openapi-md-mcp

An MCP server that exposes OpenAPI specs to markdown with progressive disclosure.

Why

• Swagger UI (/docs) is a JS shell; AI can't scrape its content

• The full /openapi.json is often tens of thousands of tokens—too expensive to stuff into context

• This tool keeps the AI's resident context to just an endpoint table of "key + summary" (~1k tokens), drilling down by key to fetch single-endpoint / single-schema markdown details—measured to save ~90% of context

Related MCP server: OpenAPI MCP Server

Tool surface (progressive disclosure, all output is markdown)

Drill-down key = METHOD /path or schema name, obtained directly from the output of the layer above.

Batch mode (select + get_batch)

Single-key drill-down can't answer horizontal questions ("all authenticated endpoints" would require dozens of individual get_endpoint calls), so the batch layer fills the gap:

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • patterns elements look like "METHOD /path/glob": method can be * (case-insensitive); path glob is case-sensitive

  • security is a scheme name; patterns are OR'd together, and AND'd with security/tag

  • Zero matches return success text (available schemes / tags + relaxation suggestions), not an error

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • Keys deduplicated preserving order, cap of 40; total rendered character cap of 100k, beyond which include_refs=False or batching is suggested

  • include_refs=True auto-merges $refs referenced during rendering into a "shared schema appendix" (each name rendered only once)

Configuration (env)

• Spec supports JSON and YAML; cached in-process for 60s after loading

• Requests are direct (trust_env=False): the target is a localhost / intranet spec, so system proxy is bypassed (macOS system proxy hijacks localhost into a 502)

• Read-only, no API-calling capability (auth headers never enter the MCP layer)

Integrate into any repository

Claude Code user-level registration (register once, available in all repositories):

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

Repositories needing a different data source can override env in their project-level .mcp.json.

Protocol compliance (MCP 2026-07-28, colloquially 2.0)

• Tool names / descriptions / inputSchema conform to spec §Tools (name character set and length, deterministic tools/list ordering)

• All five tools declare annotations.readOnlyHint: true (read-only)

• Error semantics follow spec §Tools Error Handling: spec load failure, unknown keys (with near-match suggestions), invalid filter patterns, and batch over-limit are thrown as ToolError for Tool Execution Error → surfaced online as CallToolResult(isError=true), and the client feeds suggestions back to the model for self-correction; zero matches are success text; no call (API invocation) capability

• Version negotiation: stdio uses the initialize handshake epoch (highest 2025-11-25); the stateless envelope epoch of 2026-07-28 is handled by the SDK at the HTTP transport layer (server/discover), not applicable to the stdio scenario

Development

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）