内容
# NPM 文档 MCP 服务器
一个 MCP 服务器，提供一个工具来获取 NPM 包的元数据和文档（包括 README 内容），使用本地缓存来提高性能。
## 特性
- 使用 [npms.io API](https://api.npms.io/) 获取包的元数据和 README 内容。
- 使用 SQLite (`better-sqlite3`) 在本地缓存结果。
- 提供 `getNpmPackageDocs` MCP 工具。
- 遵循标准的 MCP 服务器结构。
## 项目结构
- `/src`: 包含所有源代码。
- `/config`: 配置管理 (`ConfigurationManager`)。
- `/services`: 核心逻辑 (`NpmDocService`, `CacheService`)。
- `/tools`: MCP 工具定义 (`npmDocsTool.ts`, `npmDocsToolParams.ts`)。
- `/types`: TypeScript 接口和自定义错误 (`npmDocsTypes.ts`)。
- `/utils`: 共享的工具函数 (`logger.ts`, `errors.ts`)。
- `createServer.ts`: 服务器实例创建和工具注册。
- `server.ts`: 主应用程序入口点。
- `/dist`: 编译后的 JavaScript 输出（由 `npm run build` 生成）。包含默认的缓存数据库文件 (`npm-docs-cache.db`)。
- `package.json`: 项目元数据和依赖。
- `tsconfig.json`: TypeScript 编译器选项。
- `.eslintrc.json`: ESLint 配置。
- `.prettierrc.json`: Prettier 配置。
- `.gitignore`: Git 忽略规则。
## 安装与设置
1. **克隆仓库（如果适用）。**
2. **安装依赖：**
```bash
npm install
```
3. **构建服务器：**
```bash
npm run build
```
这会将 TypeScript 代码编译到 `dist/` 目录。
## 配置
服务器可以使用环境变量进行配置：
- `NPM_CACHE_TTL`: 缓存的生存时间（TTL），单位为秒。（默认值：`86400` - 24 小时）
- `NPM_CACHE_DB_PATH`: SQLite 数据库文件的路径。（默认值：`./dist/npm-docs-cache.db` - 相对于构建后的项目根目录）。如果设置了该值，将覆盖默认值。可以是绝对路径或相对于启动服务器的当前工作目录。
- `LOG_LEVEL`: 设置为 `debug` 以获取详细日志。（默认值：`info`）
*注意：`NPM_REGISTRY_URL` 配置变量存在，但当前被忽略，因为服务器使用的是 `npms.io` API。*
## 运行服务器
您可以直接使用 Node 运行编译后的服务器：
```bash
node dist/server.js
```
对于开发，使用 `dev` 脚本进行自动重载：
```bash
npm run dev
```
## MCP 集成
要将此服务器与 MCP 客户端（如 Cline）一起使用，请将其配置添加到您的 MCP 设置文件中（例如，`cline_mcp_settings.json`）：
```json
{
"mcpServers": {
// ... 其他服务器
"npm-docs-server": {
"command": "node",
"args": [
"/path/to/mcp-npm_docs-server/dist/server.js" // <-- 重要：使用编译后的 server.js 的绝对路径
],
"env": {
// 可选：如有需要，在此设置环境变量
// "NPM_CACHE_TTL": "3600",
// "NPM_CACHE_DB_PATH": "/path/to/your/cache.db",
// "LOG_LEVEL": "debug"
},
"disabled": false, // 确保启用
"autoApprove": [
"getNpmPackageDocs" // 可选：自动批准该工具
]
}
// ... 其他服务器
}
}
```
**将 `/path/to/mcp-npm_docs-server` 替换为您系统中此项目目录的实际绝对路径。**
## 提供的 MCP 工具
### `getNpmPackageDocs`
检索指定 NPM 包的文档和元数据。
**参数：**
- `packageName` (string, **必需**): NPM 包的确切名称（例如，'react'，'axios'，'@azure/storage-blob'）。区分大小写。
- `forceFresh` (boolean, 可选，默认值：`false`): 如果为 `true`，则绕过本地缓存，从 npms.io API 获取新数据。
**返回：**
一个符合 `NpmDocumentation` 接口的 JSON 对象，包括：
- `name`
- `version`
- `description`
- `homepage`（如果可用）
- `repository`（URL，如果可用）
- `author`（名称，如果可用）
- `license`（如果可用）
- `keywords`（如果可用）
- `dependencies`
- `devDependencies`
- `readmeContent`（包含 README markdown 的字符串，如果通过 npms.io 可用）
**示例用法（MCP 工具调用）：**
```xml
<use_mcp_tool>
<server_name>npm-docs-server</server_name>
<tool_name>getNpmPackageDocs</tool_name>
<arguments>
{
"packageName": "lodash",
"forceFresh": false
}
</arguments>
</use_mcp_tool>
```
## 代码检查与格式化
- **代码检查:** `npm run lint`
- **格式化:** `npm run format`
代码将在提交时通过 Husky 和 lint-staged 自动进行检查和格式化（如果安装了 Husky）。
MCP 市场