@itkmoon/npm-mcp

NPM 包管理 MCP 工具 — 基于 Model Context Protocol (MCP) 构建的强大 NPM 生态工具集，为 AI 编程助手（Claude、Cursor、Trae 等）提供完整的 NPM 包搜索、查询、发布和管理能力。

✨ 功能特性

| 特性 | 描述 | |------|------| | 🔍 包搜索 | 按关键词搜索 NPM 包，支持返回数量限制 | | 📦 包详情 | 获取 NPM 包完整元数据（版本、依赖、作者、关键词等） | | 📋 版本列表 | 列出包的所有发布版本及发布时间 | | 📊 下载统计 | 查看日 / 周 / 月维度的下载量数据 | | 🌳 依赖分析 | 解析并展示完整的依赖关系树（生产/开发/同伴/可选依赖） | | 🚀 包发布 | 通过 MCP 直接执行 npm publish 发布操作 | | ⚠️ 废弃管理 | 标记指定版本的包为废弃状态 |

📥 安装方式

方式一：NPM 全局安装（推荐）

npm install -g @itkmoon/npm-mcp

方式二：从 GitHub 克隆

git clone https://github.com/ITKMUnigle/NPM-MCP-Tool.git
cd NPM-MCP-Tool
npm install
npm run build

环境要求

| 依赖项 | 版本要求 | |--------|----------| | Node.js | >= 18.0.0 | | npm | >= 9.0.0 |

⚙️ 配置指南

Claude Desktop 配置

编辑 Claude Desktop 配置文件（claude_desktop_config.json）：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "npm-mcp": {
      "command": "npm-mcp",
      "args": ["--stdio"]
    }
  }
}

Cursor 配置

在 Cursor 设置中添加 MCP Server（.cursor/mcp.json）：

{
  "mcpServers": {
    "npm-mcp": {
      "command": "npx",
      "args": ["-y", "@itkmoon/npm-mcp", "--stdio"]
    }
  }
}

Trae 配置

在 Trae 的 MCP 设置中添加配置：

{
  "servers": [
    {
      "name": "npm-mcp",
      "command": "node",
      "args": ["<your-path-to-dist>/index.js", "--stdio"],
      "env": {}
    }
  ]
}

提示： 将 <your-path-to-dist> 替换为实际的 dist/index.js 文件路径。

🔧 工具详细说明

1. npm_search — 搜索 NPM 包

按关键词搜索 NPM Registry 中的包。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | keyword | string | ✅ 是 | - | 搜索关键词（不能为空） | | limit | number | ❌ 否 | 10 | 返回结果数量限制（1-100） |

返回值示例：

{
  "success": true,
  "total": 12345,
  "results": [
    {
      "name": "react",
      "version": "18.2.0",
      "description": "React is a JavaScript library for building user interfaces.",
      "author": { "name": "React Team" },
      "links": { "npm": "https://www.npmjs.com/package/react" },
      "date": "2024-01-15T00:00:00.000Z"
    }
  ]
}

使用示例：

调用 npm_search 工具：
- keyword: "react"
- limit: 5

2. npm_info — 查看包完整详情

获取指定 NPM 包的完整元数据信息。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | ✅ 是 | - | NPM 包名（如 lodash、@types/node） |

返回值包含：

• 包名、描述、版本列表、最新版本
• 作者 / 维护者信息
• 关键词（keywords）
• 主页和仓库地址
• License 信息
• 完整的依赖声明（dependencies / devDependencies / peerDependencies）

使用示例：

调用 npm_info 工具：
- packageName: "express"

3. npm_versions — 查看所有版本列表

列出指定 NPM 包的所有已发布版本。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | ✅ 是 | - | NPM 包名 |

返回值示例：

{
  "success": true,
  "package": "express",
  "versions": [
    { "version": "4.18.2", "date": "2023-02-14T22:20:47.796Z", "latest": true },
    { "version": "4.18.1", "date": "2022-11-01T17:53:56.672Z" },
    { "version": "4.17.3", "date": "2020-06-29T19:48:36.092Z" }
  ],
  "totalVersions": 156
}

使用示例：

调用 npm_versions 工具：
- packageName: "vue"

4. npm_downloads — 查看下载统计

获取指定时间段内 NPM 包的下载量统计数据。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | ✅ 是 | - | NPM 包名 | | period | enum | ❌ 否 | last-week | 统计周期：last-day / last-week / last-month |

返回值示例：

{
  "success": true,
  "package": "lodash",
  "downloads": 15843210,
  "start": "2024-01-01",
  "end": "2024-01-08",
  "period": "last-week"
}

使用示例：

调用 npm_downloads 工具：
- packageName: "axios"
- period: "last-month"

5. npm_dependencies — 查看依赖关系树

解析并展示 NPM 包的完整依赖结构。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | ✅ 是 | - | NPM 包名 | | version | string | ❌ 否 | 最新版本 | 指定版本号（不传则使用最新版） |

返回值包含四类依赖：

• dependencies — 生产依赖
• devDependencies — 开发依赖
• peerDependencies — 同伴依赖
• optionalDependencies — 可选依赖

使用示例：

调用 npm_dependencies 工具：
- packageName: "webpack"
- version: "5.88.0"

6. npm_publish — 发布 NPM 包

通过 MCP 执行 npm publish 命令将包发布到 NPM Registry。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packagePath | string | ❌ 否 | . | 包目录路径（默认当前目录） | | access | enum | ❌ 否 | public | 访问级别：public（公开）/ restricted（受限，需付费 scope） | | tag | string | ❌ 否 | latest | 发布标签（如 next、beta、canary） |

⚠️ 注意： 执行此工具前请确保已登录 NPM 账号（npm login），且目标目录包含有效的 package.json。

返回值示例：

{
  "success": true,
  "message": "@scope/[email protected] published successfully with tag 'latest'"
}

使用示例：

调用 npm_publish 工具：
- packagePath: "./my-package"
- access: "public"
- tag: "beta"

7. npm_deprecate — 废弃包/版本

标记某个 NPM 包的特定版本为废弃状态。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | ✅ 是 | - | NPM 包名 | | version | string | ✅ 是 | - | 要废弃的版本号 | | message | string | ❌ 否 | - | 废弃原因说明（建议填写，方便用户了解迁移方案） |

⚠️ 注意： 此操作不可逆，执行后该版本将被标记为废弃。需要 NPM 登录权限。

返回值示例：

{
  "success": true,
  "message": "[email protected] has been deprecated: This version is no longer maintained, please upgrade to v2.0.0"
}

使用示例：

调用 npm_deprecate 工具：
- packageName: "my-package"
- version: "1.0.0"
- message: "此版本不再维护，请升级到 v2.0.0"

🧪 连接测试用例（Stdio 模式）

步骤一：启动 MCP Server

# 全局安装后直接运行
npm-mcp --stdio

# 或从源码运行
node dist/index.js --stdio

预期输出（stderr）：

NPM MCP Server running on stdio

步骤二：发送初始化请求

通过 stdin 发送 JSON-RPC 初始化请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "test-client", "version": "1.0.0" }
  }
}

预期响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "npm-mcp", "version": "1.0.0" }
  }
}

步骤三：发送 initialized 通知

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

步骤四：列出可用工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

预期响应应包含 7 个工具：npm_search、npm_info、npm_versions、npm_downloads、npm_dependencies、npm_publish、npm_deprecate

步骤五：调用工具测试

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "npm_search",
    "arguments": { "keyword": "react", "limit": 3 }
  }
}

预期响应包含 React 相关包的搜索结果。

🏗️ 架构图

graph TB
    subgraph Client["🤖 AI 客户端层"]
        C1[Claude Desktop]
        C2[Cursor]
        C3[Trae]
        C4[其他 MCP Client]
    end

    subgraph MCPServer["⚡ MCP Server 层"]
        S1[Server 入口<br/>index.ts]
        S2[Transport 传输层<br/>StdioServerTransport]
        S3[Tool 注册中心<br/>7 个 Tool Handler]
        S4[Zod 参数校验<br/>Schema Validation]
    end

    subgraph Tools["🔧 工具处理层"]
        T1[npm_search<br/>包搜索]
        T2[npm_info<br/>包详情]
        T3[npm_versions<br/>版本列表]
        T4[npm_downloads<br/>下载统计]
        T5[npm_dependencies<br/>依赖分析]
        T6[npm_publish<br/>包发布]
        T7[npm_deprecate<br/>废弃管理]
    end

    subgraph External["🌐 外部服务层"]
        E1[NPM Registry API<br/>registry.npmjs.org]
        E2[NPM Downloads API<br/>api.npmjs.org]
        E3[npm CLI<br/>publish/deprecate]
    end

    Client -->|"JSON-RPC over Stdio"| MCPServer
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> Tools
    T1 & T2 & T3 & T5 --> E1
    T4 --> E2
    T6 & T7 --> E3

    classDef clientStyle fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b
    classDef serverStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#e65100
    classDef toolStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef externalStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20

    class C1,C2,C3,C4 clientStyle
    class S1,S2,S3,S4 serverStyle
    class T1,T2,T3,T4,T5,T6,T7 toolStyle
    class E1,E2,E3 externalStyle

数据流时序图

sequenceDiagram
    participant AI as AI 客户端
    participant MCP as MCP Server
    participant Zod as Zod 校验器
    participant Service as NpmService
    participant API as NPM Registry API

    AI->>MCP: JSON-RPC tools/call 请求
    MCP->>Zod: 参数 Schema 校验
    alt 校验失败
        Zod-->>MCP: 返回验证错误
        MCP-->>AI: isError=true + 错误信息
    else 校验通过
        Zod->>MCP: 返回已验证参数
        MCP->>Service: 调用对应 handler
        Service->>API: HTTP GET/POST 请求
        API-->>Service: 响应数据
        Service-->>MCP: 格式化结果
        MCP-->>AI: content[] + 结果文本
    end

🔒 安全注意事项

| 项目 | 说明 | |------|------| | 🔐 认证要求 | npm_publish 和 npm_deprecate 需要有效的 NPM 登录凭证。请在宿主机上预先执行 npm login 完成认证。 | | 🛡️ 权限控制 | 发布受限访问级别（restricted）的包需要对应 scope 的付费组织成员身份。 | | ⚠️ 不可逆操作 | npm_deprecate 操作一旦执行无法撤销，废弃标记会永久显示在包页面上。 | | 📁 路径安全 | npm_publish 的 packagePath 参数仅限本地文件系统路径，不支持远程 URL。 | | 🔒 网络通信 | 所有 API 请求均通过 HTTPS 加密传输，不会明文传递敏感信息。 | | 🚫 速率限制 | NPM Registry API 有速率限制，高频调用可能触发 429 错误。内置 30 秒超时保护。 |

📊 工具总览表

| 工具名 | 描述 | 必填参数 | 可选参数 | 数据来源 | |--------|------|----------|----------|----------| | npm_search | 搜索 NPM 包 | keyword | limit | Registry Search API | | npm_info | 查看包完整详情 | packageName | - | Registry Package API | | npm_versions | 查看所有版本列表 | packageName | - | Registry Package API | | npm_downloads | 查看下载统计 | packageName | period | Downloads API | | npm_dependencies | 查看依赖关系树 | packageName | version | Registry Package API | | npm_publish | 发布 NPM 包 | - | packagePath, access, tag | npm CLI | | npm_deprecate | 废弃包/版本 | packageName, version | message | npm CLI |

📄 许可证

本项目基于 MIT License 开源发布。

MIT License

Copyright (c) 2024 unigle ([email protected])

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🔗 相关链接

| 链接 | 地址 | |------|------| | 📦 npm 包页面 | https://www.npmjs.com/package/@itkmoon/npm-mcp | | 💻 GitHub 仓库 | https://github.com/ITKMUnigle/NPM-MCP-Tool | | 📖 MCP 规范文档 | https://modelcontextprotocol.io | | 🐛 问题反馈 | https://github.com/ITKMUnigle/NPM-MCP-Tool/issues | | 👤 作者邮箱 | [email protected] |

English Version | English Documentation