NPM 文档 MCP 服务器

一个 MCP 服务器，提供一个工具来获取 NPM 包的元数据和文档（包括 README 内容），使用本地缓存来提高性能。

特性

• 使用 npms.io API 获取包元数据和 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 生成）。包含默认的缓存 DB 文件 (npm-docs-cache.db)。
• package.json: 项目元数据和依赖项。
• tsconfig.json: TypeScript 编译器选项。
• .eslintrc.json: ESLint 配置。
• .prettierrc.json: Prettier 配置。
• .gitignore: Git 忽略规则。

安装 & 设置

1. 克隆存储库（如果适用）。

2. 安装依赖项：

   npm install
   

3. 构建服务器：

   npm run build
   

   这会将 TypeScript 代码编译到 dist/ 目录中。

配置

可以使用环境变量配置服务器：

• NPM_CACHE_TTL: 缓存生存时间（以秒为单位）。（默认值：86400 - 24 小时）
• NPM_CACHE_DB_PATH: SQLite 数据库文件的路径。（默认值：./dist/npm-docs-cache.db - 相对于构建后的项目根目录）。如果设置，则覆盖默认值。可以是绝对路径或相对于服务器启动的当前工作目录的相对路径。
• LOG_LEVEL: 设置为 debug 以进行详细日志记录。（默认值：info） 注意：NPM_REGISTRY_URL 配置变量存在，但由于服务器使用 npms.io API，因此当前被忽略。

运行服务器

您可以使用 Node 直接运行编译后的服务器：

node dist/server.js

对于开发，请使用 dev 脚本进行自动重新加载：

npm run dev

MCP 集成

要将此服务器与 MCP 客户端（如 Cline）一起使用，请将其配置添加到您的 MCP 设置文件（例如，cline_mcp_settings.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 (name, 如果可用)
• license (如果可用)
• keywords (如果可用)
• dependencies
• devDependencies
• readmeContent (包含 README markdown 的字符串，如果可以通过 npms.io 获得)

用法示例 (MCP 工具调用):

<use_mcp_tool>
  <server_name>npm-docs-server</server_name>
  <tool_name>getNpmPackageDocs</tool_name>
  <arguments>
  {
    "packageName": "lodash",
    "forceFresh": false
  }
  </arguments>
</use_mcp_tool>

Linting 和格式化

• Lint: npm run lint
• 格式化: npm run format

代码将在提交时通过 Husky 和 lint-staged 自动进行 linting 和格式化（如果已安装 Husky）。