Home/Docs/For AI agents

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.

shell
# pure-JSON pipeline, no terminal parsing
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.

3. MCP server

mendapi mcp starts a Model Context Protocol server on stdio (JSON-RPC 2.0, newline-delimited). Zero npm dependencies, zero network code — every tool call runs the local CLIs and the local SQLite database only.

shell
Usage: node mcp.js

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

Client configuration

shell
{
  "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.

scan

Scan a repository for code impacted by monitored upstream API breaking changes. Runs fully locally (no network). Returns the mendapi scan report JSON (schema_version 1): impacts[] with change metadata, confidence (high/medium/low), and file:line usage sites.

arguments: repo (required) · provider · include_prereleases

deps

Inventory which provider API surfaces a repository uses (imports, endpoints, env credentials, SDK call chains), with file:line evidence. Local only. Set match=true to join the inventory against monitored breaking changes and migration packs. Returns JSON (schema_version 1).

arguments: repo (required) · match

fix

Preview (default, dry-run) or apply a deterministic migration pack against a repository. Dry-run writes nothing to the repo; it produces a unified diff patch and a fix report JSON (schema_version 1). Set apply=true only after reviewing the dry-run diff.

arguments: repo (required) · migration (required) · apply · out_dir

changes

Query the local API change database (read-only). Filter by provider and/or change type (breaking | deprecation | additive | docs-only | unknown). Returns the newest records first.

arguments: provider · change_type · limit

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.
PreviousCI & automation NextSecurity model
Pre-release documentation, generated from the mendapi codebase. Command output and pack listings reflect the shipped CLI exactly.