dep-diff-mcp 是一个 MCP（Model Context Protocol）服务器，旨在将依赖锁文件差异翻译成人类可读的升级计划。它面向使用 AI 编程助手的开发者，帮助判断依赖升级是否安全、有哪些风险。
用途
该服务器读取依赖的变更日志，告诉用户升级中哪些内容有风险。用户可以将 AI 助手（如 Cursor、Claude Desktop、Claude Code）指向 Dependabot PR、npm outdated 输出或任意一对包版本，从而获得按风险排序的升级计划。
主要能力
- 语义化版本分类：major / minor / patch / downgrade / unknown。
- 破坏性变更：从 GitHub 发布说明标题中提取。
- 安全修复：通过 OSV.dev 识别在 fromVersion 存在但在 toVersion 已解决的 CVE。
- 迁移链接：从发布说明中找到的升级指南 URL。
- 建议：单行结论及等级。
- 批量分析：analyze_packages_bulk 可并行分析最多 50 个包升级，并按风险排序：security > caution > review > likely-safe > safe，同时返回汇总计数。
- 结构化输出：两个工具均返回 JSON 文本块和符合声明 outputSchema 的 MCP 结构化内容，支持结构化输出的客户端可直接读取 recommendationLevel 或 securityFixes[]。
使用方式
安装与配置
- 用户级安装（所有项目可用）：一条命令即可。
- 项目级安装：在仓库根目录写入 .mcp.json，团队共享。
- 可显式提供 token（若已通过 gh CLI 认证则可跳过）。
- 重启 Claude Code 会话以加载服务器。
Cursor 和 Claude Desktop
添加到 MCP 客户端配置：
- Cursor: ~/.cursor/mcp.json
- Claude Desktop: macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%\Claude\claude_desktop_config.json 重启 MCP 客户端后，用自然语言提问（如“这个 Dependabot PR 有什么风险？”），工具会自动调用。
托管远程实例（无需安装）
托管实例运行在 https://dep-diff.digicatalyst.ca/mcp，通过 streamable HTTP 提供，可跳过 npm 包。也可在客户端配置中使用。托管实例使用自己的 GitHub token 进行认证，因此发布说明查询可在完整速率限制下工作，无需用户配置。仅当希望请求计入自己的 GitHub 配额时，才在 URL 上传递 ?githubToken=ghp_xxx。该实例无状态，不保留查询日志（见 PRIVACY.md）。若希望 token 不离开本机，可在本地运行 npm 包。同一实例也列在 Smithery 上，通过其网关代理。
GitHub token（可选但推荐）
服务器访问 GitHub API 读取发布说明。无 token 时每小时 60 次请求（GitHub 匿名限制），适合偶尔的单包查询，不适合批量锁文件分析。 Token 解析顺序：
- 环境变量 GITHUB_TOKEN（若设置）。
- gh auth token——若安装了 GitHub CLI 并已认证，服务器自动使用该 token，无需配置更改。
- 匿名（60 次/小时）。
推荐使用 gh CLI：若已安装 gh（brew install gh && gh auth login），无需进一步操作，服务器会使用现有认证，无需明文 token。
替代方案：环境变量。在 https://github.com/settings/tokens 创建细粒度 token：
- Token 名称：dep-diff-mcp
- 过期时间：90 天（定期轮换）
- 仓库访问：Public Repositories（只读）——不访问私有仓库
- 权限：除默认公共读取外无其他权限——不要授予 repo、workflow、user 或任何写入范围 然后在 MCP 配置中引用。配置文件以明文存储在磁盘上，保持权限严格（chmod 600），不要将 token 粘贴到 AI 聊天、issue 或共享屏幕中。Token 应为最小权限（仅公共仓库读取），即使泄露也只能读取已可读的公共数据。定期轮换 token，在 https://github.com/settings/tokens 撤销可能暴露的 token。服务器从不将 token 写入 stdout/stderr 或响应负载。
工具说明
analyze_package_change
分析单个包升级。输入：ecosystem（npm、pypi 或 github-actions）、name、fromVersion、toVersion。
analyze_packages_bulk
并行分析最多 50 个包升级。返回按风险排序的包（security > caution > review > likely-safe > safe），以及汇总计数。
支持的生态系统
- GitHub Actions：将 action 引用作为 name 传递（如 actions/checkout，或嵌套的 github/codeql-action/init）。Action 引用本身已是仓库坐标，因此发布说明和破坏性变更无需注册表查询即可解析，裸主版本标签如 4 -> 5 也能正确分类。
- npm 和 PyPI 同样支持。
适用场景
- 审查 Dependabot PR 中的风险。
- 判断单个包升级是否安全（如 lodash 从 4.17.20 到 4.17.21）。
- 批量分析锁文件差异，优先处理安全相关升级。
- 在 AI 编程助手中集成依赖升级风险评估。
限制
- 无 GitHub token 时速率限制为每小时 60 次请求，不适合批量分析。
- 托管实例无状态且不保留查询日志，但若使用自己的 token 需通过 URL 传递。
- 批量分析最多 50 个变更。
- 其他功能、收费、价格、平台、效果或使用步骤暂未提供。
