For AI agents

mendapi is built to be operated by AI coding agents (Claude Code, Cursor, Codex, and any MCP client), not just humans. Three interfaces, all generated from and regression-locked to the shipped code: a skill file for agents that read instructions, versioned JSON for agents that parse pipes, and an MCP server for agents that speak protocol.

1. The agent skill file

An agent-loadable SKILL.md ships in the repository under skills/mendapi/. It contains the trigger conditions, the full scan → review → fix → verify workflow, every command and flag, the JSON schemas field by field, exit-code contracts, pitfalls, and an autonomous-maintenance recipe. A dedicated regression suite mechanically verifies that every claim in the skill matches the shipped CLI — the skill cannot drift from the implementation without failing the build.

2. Versioned JSON output

Every machine-readable report carries a top-level schema_version integer (currently 1), bumped only on breaking JSON-shape changes. Agents pin to it instead of sniffing keys.

# pure-JSON pipeline, no terminal parsing
mendapi sync                                          # populates the local change database
mendapi scan --json > impact.json
mendapi deps --match --json > deps.json
mendapi fix --from-report impact.json --json > fix.json

Exit codes are part of the contract: fix returns 0 (changes made / previewed), 1 (nothing applicable), 2 (usage error), 3 (stale pack refused without --ack-stale). See CI & Automation.

The fix report also carries a verification block an agent can gate on rather than trusting the patch blind: syntax_check (passed / failed / skipped counts, plus a per-file verdict on each entry in files) (the verification.syntax_check block) proves every rewritten file parses under node --check, and repo_checks — opt-in via --run-checks with --apply — proves the repo's own test / typecheck scripts still pass after the patch lands (status is ran with per-script verdicts, or skipped with a reason, never a disguised pass). See the evidence chain.

Pack matching in deps --match

Besides joining your surfaces against recorded breaking changes, deps --match emits a pack_match section that joins your repo's endpoint surfaces against every migration pack's API-surface anchor set. A hit means a shipped pack's fix targets exactly the API surface your code calls, and the entry carries a directly runnable mendapi fix --migration <pack> suggestion with file:line evidence. The example below is the first entry produced by running the shipped CLI on the bundled demo repo at docs build time — not hand-written:

"pack_match": {
  "pack_surfaces_considered": 726,
  "pack_endpoint_matches": [
    {
      "pack": "twilio-verify-attempts-summary-servicesid",
      "provider": "twilio",
      "pack_surface": "GET /v2/Attempts/Summary",
      "repo_endpoint": "/v2/Attempts/{param}",
      "evidence": [{ "file": "lib/pyuse.py", "line": 17 }]
    }
  ]
}

SDK-release packs carry an honest empty anchor set, so they never appear in pack_endpoint_matches — their repo join is handled by the SDK call-chain matcher instead, and the two tracks never overlap. An agent can gate on pack_endpoint_matches to go from “a change hits my code” straight to a runnable fix command.

3. MCP server

mendapi mcp starts a Model Context Protocol server on stdio (JSON-RPC 2.0, newline-delimited). Offline-first, zero network — zero npm dependencies, zero network code: every tool call runs the local CLIs and the local SQLite database only. The server speaks the current MCP revision (2026-07-28: per-request _meta version negotiation, the server/discover RPC, resultType-stamped results and cacheable list results) and remains fully backward compatible with clients on the initialize-handshake revisions (2025-06-18 / 2025-03-26). A dual-era server — a tool that repairs breaking changes should not ship one.

Usage: mendapi mcp

Starts a Model Context Protocol server on stdio (JSON-RPC 2.0, newline-delimited).
Tools: scan, deps, fix, revalidate, changes. All local; no network code.

Client configuration

Claude Code, one line:

claude mcp add mendapi -- npx mendapi mcp

Cursor (or any JSON-configured MCP client) — add to .cursor/mcp.json:

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

Tools

The list below is generated by querying tools/list on the shipped server at docs build time.

Tool results return the same schema_version-stamped JSON documents as the CLI --json flags, so an agent can switch between pipe mode and protocol mode without changing its parser. Errors come back as MCP isError content (tool-level) or JSON-RPC error objects (protocol-level) — a malformed request never kills the server.

Autonomous maintenance recipe

1. sync on a schedule (the only network step).
2. scan --json each maintained repo; skip when impacts is empty.
3. deps --match --json to map hits to exact file:line sites and available packs.
4. fix as dry-run, verify the diff (syntax check, tests), then --apply.
5. pr to package the change for human review — never push without a human.