NPM Context Agent MCP

npm上下文代理mcp

一个模型上下文协议（MCP）服务器，提供有关npm包的全面上下文信息，包括README文件、版本、依赖关系、下载统计信息等。

🚀 特性

核心能力

• 📦 包元数据 -获取任何npm包的详细信息
• 📖 自述文件 -使用智能分支回退从GitHub存储库自动获取README
• 🔍 程序包搜索 -按关键字搜索npm注册表，并可自定义结果限制
• 📋 版本历史 -获取带有dist标签的包的所有可用版本
• 🔗 依赖关系信息 -查看依赖关系、devDependencies和对等依赖关系
• 📊 下载统计 -跟踪软件包下载趋势（最后一天、一周或一个月）
• ℹ️ 综合信息 -获取完整的包元数据，包括关键字、许可证、维护者
• 🔀 包装比较 -并排比较两个包
• 📦 捆绑尺寸 -从bundlephobia获取包裹捆绑尺寸信息
• ⭐ 质量指标 -从npms.io获取质量分数

MCP资源

资源提供应用程序驱动的数据访问：

• 包：//｛packageName｝ -将元数据打包为JSON资源
• package://{packageName}/rereadme -README内容作为markdown资源
• 包：//｛packageName｝/依赖项 -依赖关系作为JSON资源
• 包：//｛packageName｝/版本 -JSON资源的版本历史记录

MCP提示

即用型提示模板：

• 分析包 -综合包分析提示
• 比较软件包 -比较两个包提示
• 寻找替代方案 -查找替代包提示

运输支持

• stdio运输 -传统的基于stdio的通信（默认）
• HTTP传输 -基于HTTP的远程访问通信
• 双模式 -同时支持两种传输方式

技术特性

• 🛡️ 类型安全验证 -使用Zod进行运行时模式验证
• 🏷️ 范围包支持 -处理范围包，如 @types/node
• 🎯 版本支持 -获取所有操作的特定包版本
• ⚡ 智能分支回退 -自动尝试main→ 主人→ 默认分支
• 🔄 错误处理 -优雅的错误处理，包含详细的错误消息
• 📤 结构化输出 -所有工具都返回结构化JSON以进行编程访问
• 🎨 现代MCP SDK -使用最新的MCP SDK v1.20.2以及资源和提示
• 🌐 HTTP和stdio -根据您的需求选择您的交通方式

📋 需求

• Node.js 18+（建议使用Node.js 20+）
• pnpm 10.19.0+

🛠️ 安装

来自npm（发布时）

npm install -g npm-context-agent-mcp

来源

git clone 
cd npm-context-agent-mcp
pnpm install
pnpm build

🎯 用法

作为MCP服务器

此服务器实现了模型上下文协议，可以与MCP兼容的客户端一起使用。

标准传输（默认）

添加到MCP配置中：

{
  "mcpServers": {
    "npm-context-agent": {
      "command": "node",
      "args": ["path/to/npm-context-agent-mcp/build/index.js"]
    }
  }
}

HTTP传输

要使用HTTP传输，请在启动前设置环境变量：

export TRANSPORT_MODE=http
export PORT=3000  # optional, defaults to 3000
node build/index.js

然后连接到 http://localhost:3000/mcp 来自您的MCP客户。

双模式

要同时运行stdio和HTTP传输：

export TRANSPORT_MODE=both
node build/index.js

环境变量：

• TRANSPORT_MODE -运输方式： stdio （默认）， http，或 both
• PORT -HTTP服务器端口（默认值：3000，仅用于HTTP/两种模式）

快速入门示例

工具：

获取软件包的README：

{ "packageName": "react" }

搜索包裹：

{ "query": "state management", "limit": 5 }

获取所有版本：

{ "packageName": "svelte" }

获取依赖关系：

{ "packageName": "@types/node", "version": "24.0.0" }

查看下载统计数据：

{ "packageName": "lodash", "period": "last-week" }

比较软件包：

{ "packageName1": "express", "packageName2": "fastify" }

获取捆绑包大小：

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

获取质量指标：

{ "packageName": "react" }

资源：

读取包元数据：

package://react

阅读包README：

package://react/readme

读取包依赖关系：

package://react/dependencies

读取版本历史记录：

package://react/versions

提示：

分析包：

{ "packageName": "express" }

比较两个包：

{ "packageName1": "vue", "packageName2": "react" }

寻找替代方案：

{ "packageName": "lodash", "useCase": "utility functions" }

可用工具

get_readme_data

从npm包中检索包信息和README内容。

参数：

• packageName （string，必填）：npm包的名称
• version （字符串，可选）：要获取的特定版本（默认为最新版本）

例子：

{
  "packageName": "zustand",
  "version": "5.0.0"
}

答复： 返回包名称、版本、描述、存储库URL和README内容。

______________________________________________________________________

search_packages

按关键字搜索npm注册表中的包。

参数：

• query （字符串，必填）：搜索关键字
• limit （数字，可选）：最大结果数（默认值：20）

例子：

{
  "query": "state management",
  "limit": 10
}

答复： 返回具有名称、版本、描述、作者和链接的匹配包。

______________________________________________________________________

get_package_versions

获取软件包的所有可用版本。

参数：

• packageName （string，必填）：npm包的名称

例子：

{
  "packageName": "react"
}

答复： 返回所有版本、dist标签和最新版本的列表。

______________________________________________________________________

get_package_dependencies

获取包的依赖关系和devDependencies。

参数：

• packageName （string，必填）：npm包的名称
• version （字符串，可选）：要获取的特定版本（默认为最新版本）

例子：

{
  "packageName": "@types/node",
  "version": "24.0.0"
}

答复： 返回指定版本的依赖关系、devDependencies和对等依赖关系。

______________________________________________________________________

get_download_stats

从npm获取下载统计数据。

参数：

• packageName （string，必填）：npm包的名称
• period （字符串，可选）：时间段-“最后一天”、“上周”或“上月”（默认值：“上月”）

例子：

{
  "packageName": "lodash",
  "period": "last-week"
}

答复： 返回指定时间段的下载计数和日期范围。

______________________________________________________________________

get_package_info

获取全面的包元数据。

参数：

• packageName （string，必填）：npm包的名称
• version （字符串，可选）：要获取的特定版本（默认为所有版本）

例子：

{
  "packageName": "express",
  "version": "4.18.0"
}

答复： 返回全面的包信息，包括关键字、许可证、维护者和存储库详细信息。

______________________________________________________________________

compare_packages

用详细的指标并排比较两个包。

参数：

• packageName1 （string，必填）：要比较的第一个包
• packageName2 （string，必填）：要比较的第二个包

例子：

{
  "packageName1": "express",
  "packageName2": "fastify"
}

答复： 返回并排比较，包括版本、描述、下载统计、维护者和关键字。

______________________________________________________________________

get_package_size

从bundlephobia获取包裹的捆绑大小信息。

参数：

• packageName （string，必填）：npm包的名称
• version （字符串，可选）：要检查的特定版本（默认为最新版本）

例子：

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

答复： 返回缩小的大小、gzip压缩的大小和依赖项计数。

______________________________________________________________________

get_package_quality

从npms.io获取包的质量指标。

参数：

• packageName （string，必填）：npm包的名称

例子：

{
  "packageName": "react"
}

答复： 返回质量分数、受欢迎程度分数和维护分数。

______________________________________________________________________

可用资源

可用提示

______________________________________________________________________

🏗️ 发展

项目结构

npm-context-agent-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

脚本

• pnpm build -将TypeScript编译为JavaScript
• pnpm inspect -运行MCP检查器进行测试

建筑

pnpm build

构建过程编译TypeScript并使输出可执行。

MCP检验员测试

pnpm inspect

这将运行MCP检查器，它允许您以交互方式测试服务器。

🏛️ 建筑

MCP服务器实现

服务器使用 @modelcontextprotocol/sdk v1.20.2创建一个标准化的MCP服务器，该服务器：

1. 从各种npm API获取包元数据
2. 使用Zod模式验证所有响应
3. 对于README获取：提取GitHub存储库URL，并使用分支回退获取README
4. 返回带文本和JSON输出的格式化结构化数据
5. 支持应用程序驱动的数据访问资源
6. 支持可重用分析模板的提示
7. 提供多种传输选项（stdio、HTTP或两者）

使用的API端点

• npm注册表API: https://registry.npmjs.org/ -包元数据、版本、依赖关系
• npm搜索API: https://registry.npmjs.org/-/v1/search -包搜索功能
• npm下载API: https://api.npmjs.org/downloads/point/ -下载统计数据
• GitHub原始内容: https://raw.githubusercontent.com/ -README文件获取
• 束状恐惧症API: https://bundlephobia.com/api/size -捆绑包大小信息
• npms.io API: https://api.npms.io/v2/package/ -质量指标

数据流

Client Request → MCP Server → Multiple APIs (npm, bundlephobia, npms.io, GitHub)
                                 ↓
                           Validation (Zod)
                                 ↓
                           Structured Response (Text + JSON)

错误处理

服务器实现了全面的错误处理：

• 来自所有API的HTTP错误（npm注册表、bundlephobia、npms.io、GitHub）
• 响应结构无效
• GitHub README获取失败，分支回退
• 网络错误和超时
• 包裹处理范围
• 缺少包或版本错误

所有错误都会以文本和结构化格式返回描述性消息和适当的错误标志。

README获取分支回退

服务器通过按顺序尝试多个分支来智能地获取README文件：

1. 尝试 main 分支
2. 尝试 master 分支
3. 尝试默认分支（无分支规范）

这确保了不同存储库配置之间的最大兼容性。

🔒 类型安全

该项目使用Zod对所有工具进行运行时验证：

const NpmRegistryResponseSchema = z.object({
  name: z.string(),
  version: z.string(),
  description: z.string().optional(),
  repository: z.object({
    type: z.string(),
    url: z.string(),
  }),
});

这确保了类型安全，并防止所有API终结点上的API意外响应导致运行时错误。

📦 依赖项

• @modelcontextprotocol/sdk -用于服务器实现的MCP SDK
• zod -运行时类型验证
• express -HTTP传输模式的HTTP服务器

📦 支持的包类型

此服务器可以查询任何npm包。以下是示例：

• 常规套餐: lodash, express, react
• 范围包: @types/node, @babel/core, @angular/core
• 具体版本：所有工具都支持可选版本参数

📝 版本历史

版本2.0.0（当前）

主要更新 -MCP SDK现代化和新功能

新功能：

• ✅ MCP资源支持（4个资源）
• ✅ MCP提示支持（3个提示）
• ✅ HTTP传输模式
• ✅ 双传输模式（stdio+HTTP）
• ✅ 包比较工具
• ✅ 捆绑大小工具（捆绑恐惧症集成）
• ✅ 质量指标（npms.io集成）
• ✅ 所有工具的结构化输出
• ✅ 带有注册表工具/资源/提示API的现代SDK v1.20.2

改进：

• ✅ 所有工具迁移到 registerTool() API
• ✅ 所有工具都返回结构化内容
• ✅ 更好的错误处理和类型安全
• ✅ 增强文档

注：

• 由于漏洞数据的公共API不可用，删除了安全检查工具

版本1.0.0

初始版本 -完整的npm上下文代理MCP服务器

特征：

• ✅ 使用分支回退获取README
• ✅ 包搜索功能
• ✅ 版本历史检索
• ✅ 依赖关系分析
• ✅ 下载统计数据
• ✅ 综合套餐信息
• ✅ 范围包支持
• ✅ 版本特定查询
• ✅ Zod模式验证
• ✅ 全面的错误处理

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

MIT许可证

版权所有（c）2025胡安·塞巴斯蒂安·冈萨雷斯

看 许可证.md 获取完整的许可证文本。

🙏 致谢

• 内置 模型上下文协议
• 由npm注册表API提供支持
• README内容来源于GitHub
• 质量指标由提供
• 捆绑大小数据来自 Bundlephobia