Mcp Npm_docs Server

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 生成）。包含默认缓存数据库文件（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": {
    // ... other servers
    "npm-docs-server": {
      "command": "node",
      "args": [
        "/path/to/mcp-npm_docs-server/dist/server.js" // <-- IMPORTANT: Use the absolute path to the compiled server.js
      ],
      "env": {
        // Optional: Set environment variables here if needed
        // "NPM_CACHE_TTL": "3600",
        // "NPM_CACHE_DB_PATH": "/path/to/your/cache.db",
        // "LOG_LEVEL": "debug"
      },
      "disabled": false, // Ensure it's enabled
      "autoApprove": [
          "getNpmPackageDocs" // Optional: Auto-approve the tool
       ]
    }
    // ... other servers
  }
}

将 /path/to/mcp-npm_docs-server 替换为系统上此项目目录的实际绝对路径。

提供的 MCP 工具

getNpmPackageDocs

获取指定 NPM 包的文档和元数据。

参数：

• packageName（字符串，必填）：NPM 包的准确名称（例如，'react'、'axios'、'@azure/storage-blob'）。区分大小写。
• forceFresh（布尔值，可选，默认值：false）：如果为 true，则绕过本地缓存，从 npms.io API 获取最新数据。

返回值：

符合 NpmDocumentation 接口的 JSON 对象，包含：

• name
• version
• description
• homepage（如果可用）
• repository（URL，如果可用）
• author（名称，如果可用）
• 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>

代码检查与格式化

• 代码检查： npm run lint
• 格式化： npm run format

提交时，Husky 和 lint-staged 会自动对代码进行检查和格式化（如果已安装 Husky）。