openapi-md-mcp

把 OpenAPI spec 渐进披露（progressive disclosure）为 markdown 的 MCP server。

为什么

• Swagger UI（/docs）是 JS 壳，AI 抓不到内容

• /openapi.json 全量动辄几十 K tokens，整塞上下文太贵

• 本工具让 AI 常驻上下文只有「键 + 摘要」端点表（~1k tokens）， 按键下钻取单端点 / 单 schema 的 markdown 详情，实测省 ~90% 上下文

Related MCP server: OpenAPI MCP Server

工具面（渐进披露，输出均为 markdown）

下钻键 = METHOD /path 或 schema 名，从上层输出直接获得。

批量模式（select + get_batch）

单键下钻回答不了横向问题（「所有鉴权端点」得逐个 get_endpoint 几十次）， 批量层补齐：

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

  • patterns 元素形如 "METHOD /path/glob"：方法可为 *（大小写不敏感）；路径 glob 大小写敏感

  • security 为 scheme 名；patterns 之间 OR、与 security/tag 之间 AND

  • 零匹配返回成功文本（可用 scheme / tag + 放宽建议），不是错误

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

  • 键去重保序，上限 40 个；渲染总字符上限 100k，超出建议 include_refs=False 或分批

  • include_refs=True 把渲染中引用的 $ref 自动整合为「共享 schema 附录」（每名只渲染一次）

配置（env）

• spec 支持 JSON 与 YAML；加载后进程内缓存 60s

• 请求直连（trust_env=False）：目标是 localhost / 内网 spec，不走系统代理（macOS 系统代理会把 localhost 劫持成 502）

• 只读，不提供调用 API 能力（鉴权头不进 MCP 层）

接入任意仓库

Claude Code 用户级注册（一次注册，所有仓库可用）：

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

需要不同数据源的仓库，在各自项目级 .mcp.json 覆盖 env 即可。

协议合规（MCP 2026-07-28，俗称 2.0）

• 工具名 / 描述 / inputSchema 符合规范 §Tools（名称字符集与长度、确定性 tools/list 顺序）

• 五工具均声明 annotations.readOnlyHint: true（只读）

• 错误语义按规范 §Tools Error Handling：spec 加载失败、未知键（含相近键建议）、 非法筛选模式与批量超限作为 Tool Execution Error 抛 ToolError → 线上表现为 CallToolResult(isError=true)，客户端会把建议喂回模型自纠；零匹配是成功文本； 不做 call（调 API）能力

• 版本协商：stdio 走 initialize 握手纪元（最高 2025-11-25）；2026-07-28 的无状态 信封纪元由 SDK 在 HTTP 传输层处理（server/discover），stdio 场景不涉及

开发

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