npm-advisor-mcp

npm-advisor-mcp

一个充当智能 npm 包顾问的模型上下文协议（MCP）服务。描述你需要的功能，它会搜索注册表、比较候选包、审计漏洞，并根据包体积、受欢迎程度、维护情况、TypeScript 支持等因素推荐最佳库。

---

功能

• 按功能搜索 — 描述你的需求（例如“日期处理”“PDF 生成”），即可获得按排名排列的结果
• 并排比较 — 以清晰的表格形式比较 2–5 个包的关键指标
• 深入了解包详情 — 查看单个包的完整信息：README、依赖项、评分、链接
• 加权推荐 — 基于算法给出推荐，并针对不同用例（浏览器、Node.js、React、CLI）动态调整权重
• 安全审计 — 检查已知 CVE，并按严重性分类显示及提供补丁情况
• 弃用检查 — 检测已弃用、已废弃或无人维护的包，并给出明确结论
• 查找替代方案 — 迁移弃用库时，发现可替代的竞争包
• 安装命令生成器 — 生成可直接复制粘贴的 npm、yarn、pnpm 和 bun 命令，并包含 peer 依赖项
• 变更日志查看器 — 从 GitHub、GitLab（云端和可自托管）或 Bitbucket 获取近期发布说明
• 技术问答 — 针对某个包提出具体问题，并根据其元数据获得相关回答
• 内存缓存 — 使用 TTL 缓存所有 API 响应，以消除重复的网络请求

---

架构

npm-advisor-mcp/
├── package.json                  # Project manifest (ESM, Node 18+)
├── tsconfig.json                 # TypeScript strict config (ES2022/Node16)
├── mcp-config.json               # Ready-to-use Kiro MCP configuration snippet
├── src/
│   ├── index.ts                  # MCP server entry point (stdio transport)
│   ├── models/
│   │   └── types.ts              # Shared interfaces and scoring weights
│   ├── services/
│   │   ├── cache.ts              # In-memory TTL cache (2/5/10 min tiers)
│   │   ├── npm-registry.ts       # registry.npmjs.org client
│   │   ├── npm-audit.ts          # npm security advisory API client
│   │   ├── bundlephobia.ts       # Bundle size data (bundlephobia.com)
│   │   ├── npms-io.ts            # Quality/maintenance/popularity scores
│   │   └── scoring.ts            # Weighted recommendation engine + license checker
│   └── tools/
│       ├── search-packages.ts
│       ├── compare-packages.ts
│       ├── package-details.ts
│       ├── recommend.ts
│       ├── resolve-doubt.ts
│       ├── audit-package.ts
│       ├── find-alternatives.ts
│       ├── check-deprecation.ts
│       ├── generate-install-command.ts
│       └── get-changelog.ts
└── dist/                         # Compiled output (generated by `npm run build`)

---

前提条件

• Node.js 18+（使用原生 fetch）
• npm 9+

无需 API 密钥 — 所有数据源均公开且免费。

---

安装

cd C:\Users\617500221\Projects\AI-Tools\npm-advisor-mcp
npm install
npm run build

---

配置（Kiro MCP）

将以下内容添加到 ~/.kiro/settings/mcp.json 中的 "mcpServers" 对象内：

"npm-advisor": {
  "command": "node",
  "args": [
    "C:\\Users\\617500221\\Projects\\AI-Tools\\npm-advisor-mcp\\dist\\index.js"
  ],
  "disabled": false,
  "autoApprove": [
    "search_packages",
    "compare_packages",
    "get_package_details",
    "recommend_package",
    "resolve_technical_doubt",
    "audit_package",
    "find_alternatives",
    "check_deprecation",
    "generate_install_command",
    "get_changelog"
  ]
}

保存后，服务将显示在 Kiro MCP 面板中，并自动重新连接。

---

工具参考

1. search_packages

在 npm 中搜索符合某项功能或关键词的包。

参数	类型	必填	描述
query	string	是	功能或关键词（例如“表单验证”“状态管理”）
limit	number	否	返回结果的最大数量（默认值：8，最大值：15）

提示词示例：

“搜索可在 Node.js 中生成 PDF 的包”

返回： 按排名排列的列表，包含描述、每周下载量、gzip 体积、质量／维护／受欢迎程度评分，以及 tree-shaking 支持情况。

---

2. compare_packages

并排比较 2–5 个包的所有关键指标。

参数	类型	必填	描述
packages	string[]	是	包名数组（2–5 个）

提示词示例：

“比较 dayjs、date-fns 和 moment 在日期处理方面的表现”

返回： Markdown 表格，包含版本、gzip 体积、压缩后体积、每周下载量、TypeScript 支持、tree-shaking、依赖项数量、维护评分、质量评分、上次发布时间和许可证。

---

3. get_package_details

深入了解单个包的完整元数据。

参数	类型	必填	描述
package_name	string	是	npm 包名

提示词示例：

“获取 zod 包的详细信息”

返回： 版本、描述、快速统计表（下载量、体积、依赖项、TypeScript 支持、许可证、发布日期）、质量评分、依赖项列表、peer 依赖项、链接、关键词和 README 摘录。

---

4. recommend_package

从候选列表中获取加权推荐结果。评分权重会根据目标环境自动调整。

Parameter	Type	Required	Description
packages	string[]	Yes	要评估的包名称数组（2–10 个）
max_size_kb	number	No	可接受的最大 gzip 大小（KB）——超过此值的包会被扣分
require_typescript	boolean	No	如果为 true，不包含 TS 类型的包会被更多扣分
use_case	string	No	browser、node、react、cli 或 general——用于调整评分权重

提示词示例：

“请从 dayjs、date-fns、moment 和 luxon 中，为浏览器应用推荐一个日期库——gzip 压缩后必须小于 10KB”

**返回：**胜出者及推荐理由、次选方案、详细的评分明细表，以及许可证兼容性列。

默认评分权重（general）

Criterion	Weight	What it measures
Bundle size (gzip)	25%	越小越好；在比较组内进行相对评估
Weekly downloads	20%	社区采用情况（按对数缩放）
Maintenance	20%	npms.io 维护评分
TypeScript support	15%	内置类型（100）> @types（60）> 无（20）
Dependency count	10%	运行时依赖越少，风险越低
Freshness	10%	发布越新越好

用例权重调整

Criterion	browser	node	react	cli
Bundle size	40%	10%	30%	5%
Downloads	15%	20%	20%	20%
Maintenance	15%	25%	15%	30%
TypeScript	15%	15%	20%	10%
Dependencies	10%	20%	10%	20%
Freshness	5%	10%	5%	15%

---

5. resolve_technical_doubt

回答有关某个包的具体技术问题。

Parameter	Type	Required	Description
package_name	string	Yes	npm 包名称
question	string	Yes	你的技术问题

提示词示例：

“dayjs 是否开箱即支持时区转换？” “lodash 是否支持 tree-shaking？” “@angular/material 的 peer 依赖有哪些？” “chalk 目前仍在积极维护吗？”

**返回：**基于元数据、包体积分析、依赖树、评分和 README 内容生成的上下文相关回答。会自动识别问题类别（体积、TypeScript、依赖、维护、tree-shaking），并提供相关数据。

---

6. audit_package

检查包是否存在已知安全漏洞。

Parameter	Type	Required	Description
package_name	string	Yes	要审计的 npm 包名称

提示词示例：

“lodash 是否存在任何已知漏洞？”

**返回：**漏洞总数、严重程度明细（严重/高/中/低）、每个 CVE 的详细信息（含受影响版本范围）、补丁可用性、公告链接，以及适用时的弃用警告。

---

7. find_alternatives

查找与指定包相似或相互竞争的替代包。

Parameter	Type	Required	Description
package_name	string	Yes	要查找替代方案的包
limit	number	No	最多返回的替代方案数量（默认值：6，最大值：10）

提示词示例：

“查找 moment.js 的替代方案” “我可以用什么来替代 request？”

**返回：**按排名排列的替代方案列表，包含描述、每周下载量、包体积、质量评分和 tree-shaking 支持情况。如果原包已弃用，也会标记。

8. check_deprecation

检测某个包是否已弃用、无人维护或可能已被放弃。

参数	类型	必填	说明
package_name	string	是	要检查的 npm 包名称

示例提示词：

"request 还在维护吗？" "moment.js 已弃用了吗？"

返回： npm 弃用标记、自上次发布以来的天数、维护评分、每周下载量，以及明确的判定结果——积极维护 / 有些过时 / 可能已被放弃 / 已正式弃用。

---

9. generate_install_command

为所有主流包管理器生成可直接粘贴的安装命令。

参数	类型	必填	说明
package_name	string	是	npm 包名称
include_peer_deps	boolean	否	包含对等依赖（默认值：true）
dev	boolean	否	作为开发依赖安装（默认值：false）

示例提示词：

"给我 @tanstack/react-query 的安装命令" "如何用 pnpm 将 eslint 安装为开发依赖？"

返回： npm、yarn、pnpm 和 bun 的安装命令。自动追加对等依赖；如果包没有内置 TypeScript 类型，还会添加一个单独的 @types/ 安装代码块。

---

10. get_changelog

从包的 Git 仓库获取近期发布说明。支持 GitHub、GitLab（云端和可自托管）以及 Bitbucket。

参数	类型	必填	说明
package_name	string	是	npm 包名称
limit	number	否	要显示的近期发布数量（默认值：5，最大值：10）

示例提示词：

"zod 最近几个版本有哪些变化？" "显示 vite 的近期发布记录" "@ATLAS/info-panel 有什么新内容？"

返回： 发布历史，包含版本标签、发布日期和格式化的发布说明（每个版本的说明截断至 800 个字符）。

Git 托管平台检测

该工具读取包 package.json 中的 repository 字段，并自动检测托管平台：

repository URL 中的模式	检测为	使用的 API
github.com/...	GitHub	GitHub Releases API
gitlab.com/...	GitLab 云端	GitLab Releases API
gitlab.yourcompany.com/...	可自托管的 GitLab	GitLab Releases API（路径相同，基础 URL 不同）
git.yourcompany.com/...	可自托管的 GitLab	GitLab Releases API
bitbucket.org/...	Bitbucket	Bitbucket Tags API
以上均不匹配	—	回退到 npm 版本页面链接

私有/内部包说明： 该工具会读取从你的注册表获取的包元数据中的 repository 字段。如果你的内部 package.json 未包含 repository 字段，或使用了无法识别主机名的 SSH URL（例如 git@internal-git:atlas/info-panel），该工具将无法检测托管平台。添加完整的 HTTPS URL 即可解决：

"repository": "https://gitlab.yourcompany.com/atlas/info-panel"

---

11. check_registry (诊断)

根据 ~/.npmrc，显示服务针对给定包名称解析出的注册表 URL 和身份验证凭据。调试私有注册表访问时，请先运行此工具。

参数	类型	必填	说明
package_name	string	是	要检查解析结果的包名称

示例提示词：

"检查 @ATLAS/info-panel 的注册表"

返回： 解析出的注册表 URL、是否找到身份验证令牌，以及当意外解析到公共注册表时的指导信息。

---

数据源

API	基础 URL	提供内容	身份验证
npm Registry	从 .npmrc 解析（默认：registry.npmjs.org）	软件包元数据、版本、README、依赖项、弃用信息	通过 .npmrc
npm Downloads	api.npmjs.org/downloads	每周下载量	无
npm Audit	从 .npmrc + /-/npm/v1/security/audits 解析	已知 CVE 和安全公告	通过 .npmrc
npms.io	api.npms.io/v2	搜索 + 质量、维护度和受欢迎度评分	无
Bundlephobia	bundlephobia.com/api	压缩后大小、gzip 大小、tree-shaking、副作用	无
GitHub API	api.github.com	发行说明和变更日志	无
GitLab API	gitlab.com/api/v4 或自托管的 /api/v4	发行说明和变更日志	无（公开）/ 私有时使用令牌
Bitbucket API	api.bitbucket.org/2.0	用作发行历史的标签	无

所有请求都设有超时（10–15s），并提供优雅的回退机制——如果某个 API 响应缓慢或不可用，工具仍会返回部分结果，而不会失败。响应会缓存在内存中，避免在同一会话中重复请求。

---

私有 Registry 支持（.npmrc）

服务会直接读取 ~/.npmrc，为每个软件包解析 Registry URL 和身份验证令牌。它不会调用 shell 子进程，而是像 npm 一样解析文件，因此无论 MCP 服务进程如何启动，都能正常工作。

这意味着，只要正确配置 .npmrc，像 @your-company/some-lib 这样的作用域私有软件包就能开箱即用，例如：

@ATLAS:registry=https://your-company-registry.example.com/
//your-company-registry.example.com/:_authToken=your-token

.npmrc 中的作用域名称不区分大小写——@ATLAS、@atlas 和 @Atlas 都会匹配同一项。

Registry 解析逻辑

每次获取软件包时，服务都会：

1. 读取 ~/.npmrc，查找与软件包作用域匹配的作用域 Registry 覆盖项（例如 @ATLAS:registry=...）
2. 如果找到，则使用该 Registry URL 及对应的身份验证令牌
3. 如果未找到，则使用 .npmrc 中的默认 registry 值（如果未设置，则使用 registry.npmjs.org）
4. 如果解析出的 Registry 请求失败，且它不是公共 Registry，则自动重试 registry.npmjs.org——因此，即使配置了自定义默认 Registry，公共软件包也始终可用

运行其他工具前，可使用 check_registry 工具验证服务为任意软件包解析出的 Registry 和身份验证信息。

公共与私有软件包支持

来源	公共软件包	私有 Registry 软件包
Registry 元数据	✅ 完整	✅ 完整（通过 .npmrc 身份验证）
每周下载量	✅	✅（npm 下载 API 是公开的）
Bundle 大小	✅	❌ Bundlephobia 仅索引公共 npm 软件包
npms.io 评分	✅	❌ npms.io 仅索引公共 npm 软件包
安全审计	✅	⚠️ 还会回退检查公共 npm 安全公告数据库
变更日志	✅ GitHub / GitLab / Bitbucket	✅ repository 字段包含完整 HTTPS URL 时可用

对于私有软件包，依赖 Bundlephobia 或 npms.io 的工具（search_packages、find_alternatives、对比中的 Bundle 大小）会在相应字段显示 N/A，但仍会正确返回所有 Registry 元数据。

---

缓存

所有 API 响应都会缓存在内存中，并采用分级 TTL：

层级	TTL	用途
短	2 min	下载量、npms.io 评分、搜索结果
中	5 min	npm Registry 元数据、GitHub 发行信息
长	10 min	Bundle 大小、安全审计结果

缓存仅在当前进程中有效——MCP 服务重启后会重置。

---

开发

# Watch mode (recompiles on save)
npm run dev

# Single build
npm run build

# Run directly
npm start

项目脚本

脚本	命令	描述
build	tsc	将 TypeScript 编译到 dist/
start	node dist/index.js	运行 MCP 服务
dev	tsc --watch	开发用监视模式

---

技术栈

技术	版本	用途
Node.js	18+	运行时（原生 fetch）
TypeScript	~5.5	类型安全
@modelcontextprotocol/sdk	^1.12	MCP 服务框架
zod	^3.23	工具输入的模式验证

除 MCP SDK 和 zod 外，没有运行时依赖。无需数据库，也无需外部身份验证。

---

工作原理

1. 用户在 Kiro 中提问（例如：“帮我找一个用于解析 CSV 的库”）
2. Kiro 根据提示词路由到相应工具
3. 工具检查内存缓存——如果数据仍然有效，则立即返回
4. 缓存未命中时，并行从 npm registry、npms.io、bundlephobia 和 GitHub 获取实时数据
5. 对结果进行评分、格式化，并以结构化 Markdown 的形式返回
6. Kiro 在聊天中展示答案，其中包含表格、评分和可执行的建议

服务以 stdio 进程运行——Kiro 按需启动该进程，并通过 stdin/stdout 使用 JSON-RPC 进行通信。

---

扩展

添加新工具：

1. 创建 src/tools/your-tool.ts，其中包含一个处理函数
2. 在 src/index.ts 中使用 server.tool(name, description, zodSchema, handler) 注册该工具
3. 将工具名称添加到 mcp-config.json 的 autoApprove 中
4. 重新构建：npm run build

添加新的数据源：

1. 创建 src/services/your-source.ts，其中包含获取数据的函数
2. 使用 services/cache.ts 中的 cache.set / cache.get 缓存响应
3. 在相关工具处理函数中导入并使用该数据源
4. 添加超时和优雅降级，以增强韧性

---

故障排除

问题	解决方案
Kiro 中未显示服务	检查 mcp.json 路径是否正确；确保 dist/index.js 存在
出现 "Cannot find module" 错误	修改任何源文件后运行 npm run build
API 超时错误	在企业代理后运行时属正常现象——结果可能不完整
Bundle size 显示 "N/A"	Bundlephobia 无法分析所有软件包（原生插件等）
Audit 未返回结果	npm advisory API 可能没有该软件包版本的数据
Changelog 未显示发布记录	软件包可能未使用 GitHub/GitLab 发布功能，或者 package.json 中缺少 repository 字段，或该字段仅使用 SSH
私有软件包返回 "not found"	运行 check_registry，确认从 ~/.npmrc 正确解析了 registry URL 和身份验证令牌
check_registry 显示了错误的 registry	检查 ~/.npmrc 中是否有 @SCOPE:registry=https://... 和 //host/:_authToken=... 条目

如果在会拦截 HTTPS 的企业代理（例如 Zscaler）后运行，请将企业 CA 证书添加到 MCP 配置中：

"env": {
  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem"
}

这是推荐的修复方法。Node 的原生 fetch 并非在所有情况下都遵循 NODE_TLS_REJECT_UNAUTHORIZED=0，而完全禁用 TLS 验证会带来安全风险。使用 NODE_EXTRA_CA_CERTS 可将企业 CA 添加到 Node 的信任存储中，而不会禁用对其他内容的验证。

如需查找企业 CA 证书路径，请咨询 IT 团队，或在系统证书存储中查找。在 Windows 上，通常可从 certmgr.msc →“受信任的根证书颁发机构”导出。

如果还需要显式代理：

"env": {
  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem",
  "HTTPS_PROXY": "http://your-proxy:8080"
}

---

许可证

ISC