NPMJS Model Context Protocol (MCP) Server

NPMJS Model Context Protocol (MCP) 服务（v1.1.5）

1. 项目目的

本项目的主要目标是创建一个轻量级、基于 TypeScript 的 Model Context Protocol (MCP) 服务。该服务专门用于以简单、标准化的 JSON 格式提供 npmjs 软件包的结构化信息，例如版本详情、下载统计数据、发布日期、描述和许可证。此格式适用于大模型和 AI 驱动的开发工具使用。

该服务旨在通过抽象对多个 npmjs API 端点的直接交互，简化对 npm 软件包元数据的访问。

2. 设置说明

1. 克隆代码库：

   git clone https://github.com/yiannis-spyridakis/npmjs-mcp-server.git
   cd npmjs-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 运行服务

此 MCP 服务设计为由 MCP 客户端（例如大模型 Agent 或开发工具）作为子进程运行。它使用 Model Context Protocol 通过标准输入（stdin）和标准输出（stdout）与客户端通信。

开发环境

如需在开发过程中直接运行服务，并在文件发生更改时自动重启：

npm run dev

或者，如需单次运行而不监视更改：

npm run watch

（注意：npm run watch 在开发时使用 package.json 中指定的 nodemon 和 ts-node。npm run dev 直接使用 ts-node。）

服务将启动，并通过标准输入/输出监听 MCP 请求。

生产环境构建

如需将 TypeScript 代码编译为 JavaScript，以供生产环境使用：

npm run build

这将在 dist 目录中生成编译后的文件。

生产环境

如需在生产环境中运行编译后的服务：

npm start

此命令会执行 node dist/index.js。MCP 客户端负责将此命令作为子进程启动。

4. 可用的 MCP 工具

此服务提供可通过 MCP 客户端调用的工具。

工具：get_npm_package_summary

• **描述：**提供软件包的基本详情：名称、最新版本、描述、最新版本的发布日期、许可证、主页，以及仓库 URL（如果有）。
• 输入架构：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package (e.g., 'express', 'react')"
      }
    },
    "required": ["packageName"]
  }
  

工具：get_npm_package_versions

• **描述：**列出所有可用的软件包版本及其各自的发布日期。
• 输入架构：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      }
    },
    "required": ["packageName"]
  }
  

工具：get_npm_package_downloads

• **描述：**提供下载统计数据。可以获取指定时间段的数据；如果省略 period，则获取所有默认时间段（last-day、last-week、last-month）的数据。
• 输入架构：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      },
      "period": {
        "type": "string",
        "description": "Optional: 'last-day', 'last-week', 'last-month'. If omitted, all are fetched.",
        "enum": ["last-day", "last-week", "last-month"]
      }
    },
    "required": ["packageName"]
  }
  

工具：get_npm_package_details

• **描述：**提供全面的信息，包括摘要详情、维护者和关键词。
• 输入架构：

  {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "The name of the npm package"
      }
    },
    "required": ["packageName"]
  }
  

5. 可用的 MCP 提示词

除了工具，此服务还提供提示词，MCP 客户端可根据提供的变量使用这些提示词生成特定的用户请求，从而简化常见交互。

提示词：get_summary_prompt

• **描述：**生成获取指定 npm 软件包简要摘要的请求。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

提示词：get_details_prompt

• **描述：**生成获取指定 npm 软件包完整详情的请求，包括维护者和仓库 URL。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

提示词：find_homepage_prompt

• **描述：**生成查找指定 npm 软件包官方主页的请求。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

提示词：list_versions_prompt

• **描述：**生成列出指定 npm 软件包所有可用版本及其发布日期的请求。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

提示词：get_version_date_prompt

• **描述：**生成查找指定 npm 软件包特定版本发布日期的请求。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    },
    "version": {
      "type": "string",
      "description": "The specific version string (e.g., '16.8.0')"
    }
  }
  

提示词：get_downloads_prompt

• **描述：**生成请求，查询指定 npm 包在特定时间段内的下载量。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    },
    "timePeriod": {
      "type": "string",
      "enum": ["last-day", "last-week", "last-month"],
      "description": "The time period for download counts"
    }
  }
  

提示词：get_all_downloads_prompt

• **描述：**生成请求，查询指定 npm 包最近一天、一周和一个月的下载量。
• 输入架构：

  {
    "packageName": {
      "type": "string",
      "description": "The name of the npm package"
    }
  }
  

提示词：audit_project_prompt

• **描述：**生成请求，检查指定项目目录中的依赖项是否存在安全漏洞。
• 输入架构：

  {
    "projectPath": {
      "type": "string",
      "description": "The path to the project directory (e.g., '.', '../my-app')"
    }
  }
  

提示词：simulate_audit_fix_prompt

• **描述：**生成请求，模拟在指定项目目录中运行 npm audit fix。
• 输入架构：

  {
    "projectPath": {
      "type": "string",
      "description": "The path to the project directory (e.g., '.', '../my-app')"
    }
  }
  

6. 工具调用和响应示例

以下示例说明如何调用工具（概念示例，实际客户端用法可能有所不同），以及成功的 MCP CallToolResponse 中预期的 data 部分。MCP SDK 会处理完整的响应封装（版本、时间戳等）。MCP 响应中的 data 字段会包含一个 content 数组，其中第一个元素是类型为 text 的对象，其 text 属性包含下方所示结果的 JSON 字符串。

示例：调用 get_npm_package_summary

工具调用参数：

{
  "packageName": "express"
}

data.content[0].text 中预期的 JSON 字符串：

{
  "name": "express",
  "latestVersion": "4.19.2",
  "description": "Fast, unopinionated, minimalist web framework for node.",
  "publishDateLatest": "2024-03-25T14:30:36.103Z",
  "license": "MIT",
  "homepage": "http://expressjs.com/",
  "repository": "https://github.com/expressjs/express",
  "source": "https://registry.npmjs.org/express"
}

（注意：版本和日期仅为示例，实际结果将反映查询时的数据）

示例：调用 get_npm_package_versions

工具调用参数：

{
  "packageName": "express"
}

data.content[0].text 中预期的 JSON 字符串：

{
  "versions": {
    "1.0.0": "2010-12-29T19:38:25.450Z",
    "1.0.1": "2010-12-29T19:38:25.450Z",
    "4.19.2": "2024-03-25T14:30:36.103Z"
    // ... potentially many more versions
  },
  "source": "https://registry.npmjs.org/express"
}

示例：调用 get_npm_package_downloads（所有默认时间段）

工具调用参数：

{
  "packageName": "express"
}

data.content[0].text 中预期的 JSON 字符串：

{
  "downloads": {
    "last-day": 7895822,
    "last-week": 37439130,
    "last-month": 162348160
  },
  "package": "express",
  "source": "https://api.npmjs.org/downloads/point"
}

（注意：下载量仅为示例，实际结果将反映查询时的数据）

示例：调用 get_npm_package_details

工具调用参数：

{
  "packageName": "express"
}

data.content[0].text 中预期的 JSON 字符串：

{
  "name": "express",
  "latestVersion": "4.19.2",
  "description": "Fast, unopinionated, minimalist web framework for node.",
  "publishDateLatest": "2024-03-25T14:30:36.103Z",
  "license": "MIT",
  "homepage": "https://expressjs.com/",
  "repository": "https://github.com/expressjs/express",
  "maintainers": [
    { "name": "dougwilson", "email": "[email protected]" },
    { "name": "wesleytodd", "email": "[email protected]" }
    // ... other maintainers
  ],
  "keywords": [
    "express",
    "framework",
    "sinatra",
    "web",
    "rest",
    "restful",
    "router"
  ],
  "source": "https://registry.npmjs.org/express"
}

（注意：版本、日期、维护者和关键词仅为示例，实际结果将反映查询时的数据）

错误处理

如果工具调用失败（例如，未找到软件包或参数无效），MCP 服务将返回标准的 MCP 错误响应。该响应中的 result.error 对象会包含说明问题的 message。

MCP 错误响应示例（概念结构）：

{
  "version": "0.2.0", // SDK version
  "id": "response-id-string",
  "type": "CallToolResponse",
  "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
  "result": {
    "error": {
      "type": "ToolError", // Or similar error type from SDK
      "message": "Package 'nonexistent-pkg' not found on npmjs."
      // Potentially other fields like 'toolName'
    }
  }
}

如果缺少必需参数（如 packageName），工具处理程序将抛出错误，并返回类似的 MCP 错误响应。

7. 提示词使用示例

以下示例展示如何通过提供参数来使用可用的提示词。服务端将返回一个包含生成的用户消息的 GetPromptResponse。

示例：使用 get_summary_prompt

提示词调用参数：

{ "packageName": "react" }

生成的用户消息（messages[0].content.text）：

Get a quick summary of the 'react' npm package.

示例：使用 get_version_date_prompt

提示词调用参数：

{ "packageName": "lodash", "version": "4.17.21" }

生成的用户消息（messages[0].content.text）：

What was the publish date of version 4.17.21 for 'lodash'?

示例：使用 get_downloads_prompt

提示词调用参数：

{ "packageName": "axios", "timePeriod": "last-week" }

生成的用户消息（messages[0].content.text）：

How many times was 'axios' downloaded in the last-week?

示例：使用 audit_project_prompt

提示词调用参数：

{ "projectPath": "../my-frontend-app" }

生成的用户消息（messages[0].content.text）：

Audit the dependencies in the project at '../my-frontend-app' for security vulnerabilities.

示例：使用 simulate_audit_fix_prompt

提示词调用参数：

{ "projectPath": "." }

生成的用户消息（messages[0].content.text）：

Simulate running 'npm audit fix' on the project at '.' and show me what would change.