DEV Community

mendapi
mendapi

Posted on

Your API provider shipped a breaking change. Here's how to find what it breaks in your code

#api #node #devtools #openapi

When Dependabot bumps a dependency, the PR is green, the tests pass, and you merge it on autopilot. Three days later something in production throws a TypeError on a code path your test suite never exercised. The upstream provider shipped a breaking change, your SDK version moved with it, and nothing in your CI caught the mismatch because your tests only cover the surface you thought to write.

This is the gap. Version bumps tell you that something changed. They do not tell you what in your code is now wrong.

The changelog is not enough

The usual advice is "read the changelog." Fine. You open the OpenAI Node SDK v3-to-v4 migration guide and it lists forty changes. Now what? You have to hold the entire diff in your head and grep your own codebase for every affected symbol, every renamed method, every reshaped response object. For one provider, on a quiet week, maybe you can. Across Stripe, Twilio, PayPal, Cloudflare, and whatever else you integrate, on a real team shipping real features, you won't. The changelog is a description of the provider's world. What you actually need is a mapping from that world onto your call sites.

That mapping is the boring, mechanical, error-prone work nobody wants to do by hand. So it doesn't get done, and you find out at runtime.

What mendapi actually does

mendapi treats this as three steps, and keeps all three local:

  1. Spec diff. It maintains a classified database of breaking changes across major API providers, pulled from SDK release feeds and official developer changelogs. Each entry is tagged breaking / deprecation / additive / fix, so you're not drowning in additive noise.
  2. Codebase scan. It reads that change database, detects which providers your repo actually uses (SDK imports, API hosts, env vars, not naive grep), and pinpoints the exact files, lines, and symbols a breaking change touches. It scores each finding for confidence so the high-signal ones surface first.
  3. Reviewable fix diff. It applies deterministic migration rule packs to draft the change as a unified diff you review before anything happens. Nothing is pushed unless you explicitly ask.

The part that matters for a lot of teams: the scanner, fixer, and review CLIs contain no network code at all. Your source never leaves your machine. That's not a promise in a privacy policy, it's enforced by a test that fails the build if a network primitive shows up in those files.

The actual commands

Zero config, zero npm dependencies, Node 22+:

# In any repo — nothing leaves your machine
npx mendapi scan
Enter fullscreen mode Exit fullscreen mode

You get every upstream breaking change that hits your code, with file, line, and symbol. Want it saved?

npx mendapi scan --repo /path/to/your/repo --out impact.json
Enter fullscreen mode Exit fullscreen mode

Medium-confidence findings can go through an optional semantic review pass:

npx mendapi review impact.json --pending
Enter fullscreen mode Exit fullscreen mode

Then draft the migration as a diff — dry-run, changes nothing on disk until you say so:

npx mendapi fix --from-report impact.json
Enter fullscreen mode Exit fullscreen mode

And when you're ready to turn that into a branch and a PR-ready description (local only; --push is required to actually push and is never implied):

npx mendapi pr --repo /path/to/your/repo --from-report impact.json
Enter fullscreen mode Exit fullscreen mode

The sync command is the one and only command that touches the network — it fetches the latest change feed. Everything downstream runs offline.

Wiring it into your AI coding agent

If you drive your work through Claude Code or Cursor, mendapi ships an MCP server so your agent can run the scan and read the findings itself:

claude mcp add mendapi -- npx mendapi mcp
Enter fullscreen mode Exit fullscreen mode

For Cursor or any JSON-configured MCP client, drop this into .cursor/mcp.json:

{
  "mcpServers": {
    "mendapi": { "command": "npx", "args": ["mendapi", "mcp"] }
  }
}
Enter fullscreen mode Exit fullscreen mode

The server runs on stdio, offline-first, zero npm dependencies. It exposes scan, deps, fix, and changes as tools that return the same structured JSON as the CLI's --json flags. So your agent can ask "what breaks if I bump Stripe" and get file-and-line answers instead of a vibes-based guess.

Where it falls short

Honesty section, because you're going to hit these:

  • Coverage is a set, not the universe. It watches around twenty major providers today. If your critical dependency is a niche API, it's not in the feed yet.
  • Rule packs are curated. The deterministic fixers exist for well-trodden migrations. For an obscure breaking change, you may get an accurate finding but no auto-generated fix — you migrate by hand, just with the exact call sites already located.
  • It's pre-1.0. Published on npm as mendapi v0.5.0. The change database and rule registry grow daily, and interfaces may still shift before 1.0.

None of that changes the core value: the scan tells you which of your lines break before your users do.

Try it

It's open source (AGPL-3.0), so your security team can read exactly what reads your code:

Run npx mendapi scan in your noisiest repo and see what a green CI has been hiding.

Top comments (0)