mendapi

mendapi

就像 Dependabot，但适用于你依赖的每个 API。 我们会监控上游 API 提供商的破坏性变更，扫描你的代码库以评估影响，并在集成出现问题之前创建修复 PR。

30 秒即可获得首个结果

# In any repo — zero config, zero npm dependencies
npx mendapi sync                          # one network call: fetch the change feed
npx mendapi scan --out impact.json        # local only, from here on
npx mendapi fix --from-report impact.json

sync 会将上游 API 变更源拉取到本地 SQLite 数据库。这是唯一会访问网络的命令，只需运行一次（之后可根据需要运行，以获取更新的数据）。

scan 会报告实际影响到你代码的每项上游破坏性变更，包括文件、行号和符号，并评估置信度。fix 会生成可供审核的迁移差异；在你传入 --apply 之前，它不会修改任何文件。两者都不会读取或写入你机器之外的任何内容。

在使用 AI 编码 Agent？只需一行，即可将 mendapi 接入 Claude Code，作为 MCP 服务使用（Cursor 和其他所有 MCP 客户端也都适用——详情见下文）：

claude mcp add mendapi -- npx mendapi mcp

需要 Node.js 22.13 或更高版本。所有操作都在本地运行：扫描器、修复器和审核 CLI 完全不包含网络代码。

安全模型（请先阅读）

此工具专为不能让源代码离开其机器的团队设计。安全模型本身就是产品的一部分，而不是 FAQ 条目：

1. 你的代码绝不会离开你的机器。 扫描器在本地或 CI 中运行。默认情况下不会上传任何内容——扫描器、修复器或审核 CLI 完全不包含网络代码（我们的测试套件会通过机制强制执行：这些文件中一旦出现任何网络原语，构建就会失败）。
2. 仅报告元数据，且必须主动选择。 如果你选择将结果报告到托管式仪表板，负载构建器（payload.js）会通过白名单构造负载：仅包含提供商名称、SDK 版本、文件基本名称、行号和符号名称。从结构上就不可能包含代码片段——负载架构中不存在对应字段。报告需要显式传入 --report-to 标志；默认情况下绝不会启用。
3. 全面脱敏机密信息。 每个出站负载的所有字段都会清除 15 种机密信息模式（OpenAI、Stripe、AWS、GitHub、Slack、JWT、Bearer 令牌、通用密钥赋值等），并且传输前断言会检查是否仍有禁止的键或未脱敏的机密信息；若有残留，就会抛出错误。
4. 专为审计而设计。 CLI 是开源的，安全团队可以逐行核实具体读取了哪些内容，以及发送了哪些内容（如果有）。
5. 仅需最小限度的 GitHub 权限。 修复 PR 使用 GitHub App，仅在你选择的仓库中授予 contents:read + pull_requests:write 权限。绝不授予管理员权限。
6. 支持自托管。 企业版方案可将整个技术栈（包括变更源）运行在你的防火墙内。

功能介绍

三个组件构成一个闭环：

组件	职责	运行位置
Watcher	通过 SDK 发布源和官方开发者变更日志监控 20 个主要 API 提供商（Stripe、OpenAI、Anthropic、Shopify、Twilio、Slack、GitHub、Google、AWS、Plaid、PayPal、Meta、Cloudflare、Vercel、Supabase、Firebase、Notion、HubSpot、Salesforce、SendGrid）。将每项变更分类（破坏性变更／弃用／新增／修复／仅文档），并存入结构化 SQLite 数据库。	我们的基础设施（或由你自托管）
Scanner	读取变更数据库，检测你的仓库实际使用了哪些提供商（SDK 导入、API 主机、环境变量——具备上下文感知能力，而非简单的 grep），并精确定位每项破坏性变更影响到的文件、行号和符号。三级置信度评分加上可选的大模型语义审核流程，能将误报降至接近于零。	在本地、你的机器或 CI 上
Fixer	应用确定性的迁移规则包（例如 openai-v3-to-v4、stripe-v7-to-v8），生成可供审核的差异，然后在专用分支上创建修复 PR，并在提交消息中引用官方迁移指南。	默认在本地运行；付费方案支持托管式运行

快速开始

需要 Node.js 22.13 或更高版本（使用内置的 node:sqlite）。无需 npm 依赖。

# Fetch the latest API change feed (the only command that touches the network)
mendapi sync

# Scan the current repo against the breaking-change database (zero config)
mendapi scan

# Or scan a specific repo and save the report
mendapi scan --repo /path/to/your/repo --out impact.json

# Review medium-confidence findings (optional LLM semantic pass)
mendapi review impact.json --pending

# Preview fixes (dry-run: writes a unified diff, changes nothing)
mendapi fix --from-report impact.json

# Create a fix branch + commit + PR-ready description (local only;
# --push is required to actually push, and is never implied)
mendapi pr --repo /path/to/your/repo --from-report impact.json

从代码检出目录运行？node app/cli.js <command> 的效果完全相同。

修复示例

以下是真实输出——我们的测试套件对 openai-node v3 → v4 迁移包逐字节锁定的精确差异。注意其中两行在字符串和模板字面量中提及了旧版调用：codemod 会原样保留这两行，因为规则基于语法树中的调用位置，而不是文本模式。

--- a/lib/ai.js
+++ b/lib/ai.js
@@ -1,28 +1,27 @@
 // Demo service using the legacy openai-node v3 SDK (pre-v4 breaking change).
 // Docs note: openai.createChatCompletion({...}) was the v3 entry point.
-const { Configuration, OpenAIApi } = require('openai');
+const OpenAI = require('openai');
 
 // This string mentions the legacy call and must never be rewritten by the fixer:
 const LEGACY_HINT = 'if you still call openai.createChatCompletion( upgrade to v4';
 const AUDIT_LOG_LINE = `migrating away from .createEmbedding( for tenant`;
 
-const configuration = new Configuration({ apiKey: process.env.OPENAI_API_KEY });
-const openai = new OpenAIApi(configuration);
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
 async function summarize(text) {
-  const response = await openai.createChatCompletion({
+  const response = await openai.chat.completions.create({
     model: 'gpt-4',
     messages: [{ role: 'user', content: `Summarize: ${text}` }],
   });
-  return response.data.choices[0].message.content;
+  return response.choices[0].message.content;
 }
 
 async function embed(text) {
-  const response = await openai.createEmbedding({
+  const response = await openai.embeddings.create({
     model: 'text-embedding-ada-002',
     input: text,
   });
-  return response.data.data[0].embedding;
+  return response.data[0].embedding;
 }
 
 module.exports = { summarize, embed };

每个迁移包都附带类似这样的锁定差异；如果某个包的输出与黄金证据不一致，构建就会失败。提供商指南中还有 6 个示例，同样保证逐字节匹配：OpenAI、AWS、Cloudflare、PayPal、Vercel、Stripe、Shopify。

在 AI 编码 Agent 中使用（MCP）

mendapi mcp 会通过 stdio 启动一个 Model Context Protocol 服务——离线优先，不访问网络：每次工具调用都只会运行本地 CLI 并访问本地 SQLite 数据库，而且该服务无需任何 npm 依赖。它支持当前的 MCP 修订版（2026-07-28，按请求进行 _meta 版本协商 + server/discover），同时与使用 initialize 握手的旧版客户端（2025-06-18 / 2025-03-26）完全向后兼容——这是一个跨越两个时代的服务，因为修复重大变更的工具不该只支持一个时代。

Claude Code（一行命令）：

claude mcp add mendapi -- npx mendapi mcp

Cursor（或任何使用 JSON 配置的 MCP 客户端）——添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mendapi": { "command": "npx", "args": ["mendapi", "mcp"] }
  }
}

提供的工具：scan、deps、fix、revalidate、changes——使用与 CLI --json 标志相同的、带有 schema_version 的 JSON。完整工具目录和自主维护方案，请参阅面向 AI Agent文档页面。

为什么精确性很重要

告警疲劳会让这类工具失去作用。我们的扫描器会通过以下规则筛选每条发现：

• 感知源代码的证据规则——SDK 版本发布仅影响导入该 SDK 的代码库；关于 API 端点的变更日志条目则会影响调用该主机的所有项目。
• 面向多包代码库中的提供商（Google、AWS）的子 API 过滤——youtube 的版本发布不会通知只使用 S3 的团队。
• 基于标识符边界的符号匹配——getR 永远不会匹配 getRelatedArticles。
• 感知上下文的环境变量检测——process.env.STRIPE_KEY 会被计入；名为 META_RE 的正则表达式常量则不会。

在 3 个生产代码库中进行自用测试：当前流水线报告的误报数为 0，而早期的朴素版本曾产生 27 个误报。

公开测评

我们使用真实的提供商规范语料库对变更数据库进行基准测试，并公布完整的统计结果——每项核心数据都会由网站的构建门禁根据归档证据重新计算，因此报告不会与数据脱节：

• 47 个 Stripe API 版本告诉我们的破坏性变更检测经验 — 连续 47 对规范，与 oasdiff 正面对比，没有无法解释的差异。
• 另外 3 家提供商、49 对规范、没有无法解释的差异 — 对 Twilio、PayPal 和 Vercel 进行同样的审计。
• 20 对 Twilio 规范：一个引擎发现 358 项，我们发现 142 项，每一处分歧均有说明 — 两个引擎为何相差 2.5 倍，以及每处差异的具体原因。
• 11 对 Vercel 规范：实际移除了 12 个端点，发布说明却误报了破坏性变更 — 变更日志在两个方向上都弄错了；实际传输内容没有。
• 136 项原始移除，只有 17 项确实存在：规范差异会过度报告什么 — 这些筛选规则可避免信息流中的告警疲劳。
• 821 项 OpenAI 规范变更，只有 3 项可能破坏客户端：坦诚的反面案例 — 一个能告诉你何时无需担心的工具有何价值。

状态

已作为 mendapi 发布到 npm（v0.5.6）。目前为早期版本——变更数据库和迁移包注册表每天都在扩展；在 1.0 发布前，接口仍可能调整。

许可证

CLI 使用 AGPL-3.0-only（参见 LICENSE）。选择该许可证，是为了让安全团队能够审计每一行读取代码或构建负载的内容，并确保托管分支必须共享其变更。