MCP Dependency Doctor

MCP Dependency Doctor

让你的 AI Agent 安全审计 npm 依赖：盘点依赖、检查漏洞、过时和已弃用的包——只读操作，绝不运行安装命令。

在本地诊断包含 package-lock.json 的 npm 项目：通过 4 个 MCP 工具读取锁文件、运行 npm audit、检查是否有新版本，并检查公开的包健康状况。无需设置，无需 API 密钥。

---

⚡ 快速安装

Cursor

点击上方徽章，或使用此深层链接：

cursor://anysphere.cursor-deeplink/mcp/install?name=dependency-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kZXBlbmRlbmN5LWRvY3RvciJdfQ==

Claude Code（推荐）

claude mcp add dependency-doctor -- npx -y mcp-dependency-doctor

如果市场中提供，也可以使用：

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

添加到 Claude Desktop 配置中（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json；Linux：~/.config/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-dependency-doctor"]
    }
  }
}

VS Code

在 VS Code 中安装

或者在项目中创建 .vscode/mcp.json：

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "npx",
      "args": ["-y", "mcp-dependency-doctor"]
    }
  }
}

任意 MCP 客户端（手动）

直接使用 npx 运行：

npx -y mcp-dependency-doctor

⭐ 为此仓库点亮星标，支持项目并获取最新动态！ → 点亮星标

---

---

📋 目录

• 为什么选择 MCP Dependency Doctor？
• 对比情况
• 使用场景
• 检查内容
• 要求
• 限制
• 安全与隐私
• 托管路径（通过控制平面实施配额）
• 路线图与商业边界
• 开发
• 贡献
• 作者的更多 MCP 服务

---

为什么选择 MCP Dependency Doctor？

AI 编码 Agent 可以帮助你维护依赖，但前提是它们知道安装了什么、哪些存在漏洞、哪些已弃用。MCP Dependency Doctor 能让它们掌握这些信息，无需运行 npm install，也无需外部账户。

适用于：

• 个人开发者：让 Claude 或 Cursor 帮你分类处理漏洞、规划升级，并审计已弃用的包——一切都在本地完成
• CI/PR 检查（即将推出）：在代码审查中提前发现有风险的依赖，避免合并
• 注重安全的团队：只读分析、明确说明网络访问情况、不收集遥测数据

这 4 个工具均为只读工具，并且专为 AI Agent 设计：它们会返回结构化 JSON 报告，供大模型解读，从而回答以下问题：

• “哪些漏洞会影响此项目？”
• “哪些包已弃用，我们应该用什么替换？”
• “显示依赖树及准确的已安装版本。”
• “我们是否在使用过时的主版本？升级路径是什么？”

---

功能对比

截至 2026 年 10 月。所有项目均采用 MIT 许可并开源。欢迎指正。

功能	MCP Dependency Doctor	qianniuspace/mcp-security-audit	tiluckdave/hound-mcp	DepsHubHQ/mcp
侧重点	npm 清单 + 审计 + 过时依赖 + 弃用情况	npm audit 漏洞	多生态安全（npm、PyPI、Go、Cargo、Maven、NuGet、RubyGems）	依赖升级助手（变更日志、破坏性变更）
本地读取锁文件	✅ 完整清单	❌	✅ 多种锁文件	❌
npm audit	✅ 完整报告 + 传递性漏洞	✅ 严重程度 + CVE + 修复建议	✅（通过 OSV）	❌
过时依赖检查	✅ npm outdated	❌	✅（通过 deps.dev）	✅（升级路径 + 发行说明）
弃用警告	✅ 按包显示健康状况	✅	✅	❌
多生态支持	❌ 仅 npm	❌ 仅 npm	✅ 7 种生态	✅ npm、Go、Cargo、RubyGems
Typosquat 检测	❌	❌	✅	❌
完全本地运行	✅（清单工具）	❌（始终使用远程服务）	✅（通过公共 API）	❌（远程服务）
零配置	✅ npx	✅ npx	✅ npx	⚠️ Docker 或远程 URL
托管选项	✅（控制平面 MVP）	❌	❌	✅

我们的差异化优势：

• 专为 AI Agent 设计：四个工具都会返回便于大模型解读的结构化 JSON，而不仅仅是命令行输出
• 本地锁文件清单：无需网络访问，即可解析确切版本和传递性依赖
• 设计上只读：绝不运行 npm install、npm audit fix 或生命周期脚本，可安全用于任何项目
• 明确说明网络访问情况：工具会清楚说明何时联系 npm 注册表；清单工具完全离线运行
• 支持控制平面：提供托管方案以支持配额和未来的团队功能（MVP）

---

使用场景

1. 重大重构前进行安全审计

让 AI 为漏洞分类并规划修复方案。

Agent: "Audit this project's dependencies. List critical and high vulnerabilities, 
        check which packages are deprecated, and suggest an upgrade order 
        that minimizes breaking changes. Do not modify files."

Agent 将：

1. 运行 dependency_audit，查找漏洞及其严重程度、CVSS 和受影响版本
2. 检查每个标记包的 package_health，以检测弃用情况
3. 使用 dependency_outdated 确定安全的升级目标
4. 根据汇总数据提出修复方案

2. 为新成员准备依赖清单

了解新代码库依赖的内容。

Agent: "Show me the full dependency tree with exact versions. 
        Highlight any packages over 2 years old."

Agent 使用 dependency_inventory（完全本地运行，无需网络）读取 package-lock.json 并报告：

• 所有声明的依赖（生产 + 开发 + 可选）
• 所有传递性依赖及其确切安装版本
• 每个包的 Node 引擎要求

3. 识别弃置包的维护信号

找出多年未更新的包。

Agent: "List all dependencies and check their last release date. 
        Flag any that haven't been updated in over two years."

Agent 会为每个包调用 package_health，报告：

• 最新版本和发布日期
• 弃用警告（如有）
• Node 引擎和对等依赖要求
• 维护信号（基于时间的自动启发式判断）

4. 拉取请求依赖快照

记录依赖更新 PR 中的变更。

Agent: "Before and after versions of all packages affected by this update. 
        Show vulnerabilities fixed and any new ones introduced."

Agent 可以分别对基分支和 PR 分支运行 dependency_audit，生成已解决和新增漏洞的差异。

---

检查内容

MCP Dependency Doctor 提供 四个只读 MCP 工具：

工具

工具	描述	网络访问
dependency_inventory	从 npm lockfile v2/v3 中读取声明的依赖项和确切的已安装版本。无网络。	❌ 完全离线
dependency_audit	运行只读的 npm audit。将软件包版本发送到已配置的 npm 注册表。绝不安装或修复软件包。	✅ npm 注册表（用户配置的注册表）
dependency_outdated	使用 npm outdated 查看可用更新。需要网络；绝不更改依赖项。	✅ npm 注册表
package_health	检查公开 npm 软件包的弃用状态、发布时间、Node 引擎和 peer 依赖要求。仅报告要求，不验证兼容性。	✅ registry.npmjs.org（无需 npm 凭据）

详细行为：

工具	功能	网络
dependency_inventory	解析 package.json + package-lock.json v2/v3，获取声明的依赖项和确切的已安装版本（包括所有传递依赖项）。返回 lockfile 版本；如果 lockfile 缺失或为旧版，则发出警告。	❌ 无网络
dependency_audit	运行 npm audit --json，获取漏洞报告，包括严重性（critical/high/moderate/low）、CVSS 分数、CVE ID、受影响版本和修复建议。绝不运行 npm audit fix 或 npm install。	✅ npm 注册表（用户配置的注册表）
dependency_outdated	运行 npm outdated --json，比较每个依赖项的当前版本、期望版本和最新版本。帮助规划升级，不会修改 package.json。	✅ npm 注册表
package_health	从 registry.npmjs.org 获取单个软件包的公开元数据：弃用状态、最新版本、发布时间、天数、Node 引擎要求、peer 依赖项、主页和代码库。	✅ registry.npmjs.org（无需 npm 凭据）

隐私默认设置：

• dependency_inventory 完全离线：仅读取本地文件
• 其他三个工具会向 npm 注册表披露软件包名称和版本
• 注册表身份验证使用用户的 npm 配置（遵循 .npmrc）
• package_health 不会发送 npm 凭据（查询公开注册表 API）
• 无遥测、无云端上传、无需外部账户

所有工具都接受 projectPath（相对于 MCP_PROJECT_ROOT）。路径会经过 realpath 验证，并限制在项目根目录内；请勿将此服务暴露给不可信的远程客户端。

Agent 提示词示例：

"Audit this project, inspect deprecated packages, and suggest an upgrade order. 
 Do not change files."

---

要求

运行此服务需要 Node.js 22+。该实现使用零依赖的 Node.js ESM。

完整清点依赖项需要 npm lockfile v2 或 v3。对于以下项目：

• 没有 package-lock.json → 清点工具会发出警告；审计和过时依赖工具仍可正常工作
• 使用 lockfile v1（旧版）→ 清点工具会发出警告；审计和过时依赖工具仍可正常工作

运行服务的系统上必须安装 npm（供 dependency_audit 和 dependency_outdated 工具使用）。

**支持的客户端：**任何支持 stdio 传输的 MCP 客户端（Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Cline、Zed、Gemini CLI 等）。

---

限制

**协议：**此 MVP 使用截至 2025-11-25 的旧版 MCP stdio 协议修订版。尚未实现 2026-07-28 的无状态协议。计划迁移到官方 SDK，并与真实客户端进行互操作性测试。

**范围：**仅支持 npm 项目。此版本不支持 pnpm、Yarn 和其他生态系统。

**Node／对等依赖要求：**仅报告，不进行解析。目前尚无完整的兼容性求解器。工具会根据包元数据显示 Node 引擎和对等依赖要求，但不会验证兼容性或解决冲突。

**维护状况信号：**较早的发布日期只是启发式指标，并不能证明项目已被弃用。package_health 工具会标记超过两年未发布新版本的包，但这并不能证明该包无人维护或不安全。

**不自动修复：**服务绝不会修改文件。它只提供诊断数据，供 Agent（或人工）采取后续操作。

**npm audit 覆盖范围：**取决于配置的注册表以及 package-lock.json 的质量。服务无法发现注册表未报告的漏洞。

**网络超时：**npm 操作会在 45 秒后超时，并明确失败。未完成的审计绝不会报告为无问题。

**测试：**开发环境中的远程注册表冒烟测试受阻；单元测试使用确定性测试夹具。

---

安全与隐私

默认只读：此服务绝不会运行 npm install、npm audit fix 或包生命周期脚本。它只会执行 npm audit --json、npm outdated --json 并读取本地 JSON 文件。

网络信息披露：

• dependency_inventory → 不联网
• dependency_audit 和 dependency_outdated → 将包名和版本发送到用户配置的 npm 注册表（遵循 .npmrc 和 npm 凭据）
• package_health → 查询 registry.npmjs.org（公共 API，不发送 npm 凭据）

**路径限制：**项目路径会通过 realpath 验证，并且必须位于 MCP_PROJECT_ROOT 内。通过检查解析后的路径来缓解符号链接攻击。

**不可信数据：**应将注册表响应和包元数据视为不可信数据，而非指令。此服务不会执行包元数据或注册表响应中的代码。

**无遥测：**没有分析数据、云端上传或外部账号。除非选择托管路径（见下文），否则所有操作都在本地运行。

威胁模型：此服务面向可信开发者在本地使用。未经额外身份验证和授权，请勿通过网络套接字向不可信的远程客户端公开此服务。

---

托管路径（通过控制平面管理配额）

无需账号，本地 stdio MCP 也能充分发挥作用。配额仅适用于单独的托管 HTTP 进程，该进程会在分析前向 mcp-control-plane 预留额度。

cp .env.example .env   # set CONTROL_PLANE_URL
npm run start:hosted   # default 127.0.0.1:3101

方法	路径	正文
GET	/health	存活检查
POST	/v1/package-health	{ "requestId", "name" }
POST	/v1/inventory	{ "requestId", "packageJson", "lockfile"? }

需要 Authorization: Bearer mcp_...（控制平面密钥）。托管版 dependency_audit／dependency_outdated 不在此 MVP 范围内。

**隐私：**清单和包名会保留在托管主机上。控制平面只能看到 product、requestId 和 units，不会看到文件内容或依赖名称。

---

路线图与商业边界

永久免费（本地）：

• 本地清单、npm audit、过时项检查和软件包健康诊断
• 无需注册、无需 API 密钥、无配额

Pro 计划（计划中，尚未上线）：

• 云端历史记录和监控
• 汇总安全状况的团队仪表板
• 面向合规的全体设备报告
• 通过控制平面提供托管配额

不在本地强制执行： 本地计数器不会用于付费计划的执行。免费本地服务始终保持完整功能。

后续步骤：

• 迁移至官方 MCP SDK
• 感知 Semver 的 Node/peer 兼容性求解器
• 升级计划生成器
• 支持 pnpm / Yarn / 多生态系统
• MCP Registry 清单（待验证仓库和 npm 的所有权后）
• 共享云端身份验证/计费

---

开发

# Run tests (Node.js built-in test runner)
npm test

# Syntax check all modules
npm run check

# Test local packaging
npm pack --dry-run

从源码运行：

git clone https://github.com/petrovicistefan/mcp-dependency-doctor.git
cd mcp-dependency-doctor
npm test
MCP_PROJECT_ROOT=/absolute/path/to/your/project node src/server.js

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "dependency-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-dependency-doctor/src/server.js"],
      "env": {"MCP_PROJECT_ROOT": "/absolute/path/to/your/project"}
    }
  }
}

协议参考： https://modelcontextprotocol.io/specification/2025-11-25
npm audit 参考： https://docs.npmjs.com/cli/v11/commands/npm-audit/

---

贡献

欢迎贡献！如果 CONTRIBUTING.md 文件存在，请参阅该文件；或者先提交问题，讨论你的想法，然后再提交拉取请求。

我们特别希望获得以下方面的帮助：

• pnpm / Yarn 锁文件解析
• 感知 Semver 的升级路径计算
• 多生态系统支持（PyPI、Go 模块、Cargo 等）
• GitHub Action 集成
• 更多针对边缘情况的测试样例

---

⭐ 支持此项目

觉得这个 MCP 有用？为此仓库点个 Star！

GitHub Star 能帮助其他开发者发现此项目，也方便你稍后再次找到它。感谢你支持开源！

---

作者的更多 MCP 服务

属于 petrovicistefan MCP 套件——为 AI 编码 Agent 提供本地优先的防护措施。

🔗 完整市场： petrovicistefan/mcp-marketplace

服务	用途
mcp-security-guard	审计 MCP 服务，检查工具投毒、rug pull 和泄露的密钥（OWASP MCP Top 10）
mcp-dependency-doctor	npm 依赖清单、漏洞、过时和弃用的软件包（你现在正在查看此项目）
mcp-cost-optimizer	分析云支出并找出节省成本的机会
mcp-database-doctor	数据库架构分析、查询优化和迁移安全检查
mcp-seo-auditor	为 Web 项目执行 SEO 审计并提供建议
mcp-api-guardian	API 安全与设计最佳实践
mcp-dealfinder	查找优惠、优惠券和折扣

---

许可证

MIT 许可证

Copyright (c) 2026 Stefan Petrovici

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或出售本软件副本的权利，并允许获得本软件的人这样做，但须遵守以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。无论是基于合同、侵权行为还是其他原因，在任何情况下，作者或版权持有人均不对因本软件或本软件的使用或其他交易而引起的任何索赔、损害或其他责任承担责任。

完整许可证文本请参阅 LICENSE。

作者： Stefan Petrovici (@petrovicistefan)