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% 上下文

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

tool	输入	输出
list_endpoints	tag?	端点表 方法 / 路径 / 摘要（键+摘要）+ 数据源标注
get_endpoint	method, path	端点详情：鉴权、参数表、request body（$ref 只内联一层）、responses
get_schema	name	schema 属性表 + 嵌套 $ref 下钻键
select	patterns?, security?, tag?, schema_glob?	批量选中：含鉴权列的端点键表 + 匹配 schema 名（横向聚合，如「所有鉴权端点」）
get_batch	keys, include_refs?	批量下探：混合键一次取回全部详情，引用的 schema 自动整合为去重附录

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

键与 pattern 的完整文法（判定顺序、大小写 / 空白语义、可用正则独立复现， 供其他项目复用这套键）见 KEYS.md。

批量模式（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 大小写敏感
  • 路径段可含空格：首空格分隔方法与路径，其余空格归入路径（如 "GET /v1/reports/week report"）
  • security 为 scheme 名；patterns 之间 OR、与 security/tag 之间 AND
  • 零匹配返回成功文本（可用 scheme / tag + 放宽建议），不是错误
• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])
  • 键混合 "METHOD /path" 端点键与 schema 名；名字含空格的 schema 用 "schema:Credit Request" 前缀键（裸名向后兼容）
  • 键去重保序，上限 40 个；渲染总字符上限 100k，超出建议 include_refs=False 或分批
  • include_refs=True 把渲染中引用的 $ref 自动整合为「共享 schema 附录」（每名只渲染一次）

使用引导

两条路都通向同一张键表，按对路径形态的把握程度选：

• 直接筛：已知路径前缀 / tag / 鉴权 scheme → 一步 select(patterns=[...], ...) 圈键
• 先全表后筛：不确定路径形态 → 先不带 patterns 调 select()（或 list_endpoints）拿全表， 照表中「方法 + 路径」两列拼 pattern——表即素材
• 下钻键 = 表中方法 + 路径两列拼接（如 POST /v1/scoring/credit）

接入其他项目（OPENAPI_URL 指向它的 /docs 或 /openapi.json，见下方配置）后完整一轮：

select(patterns=["* /v1/scoring/*"])                 # 1. 圈键：键表 + 匹配 schema 名
get_batch(["GET /v1/scoring/credit",                 # 2. 批量下探：引用 schema 自动进附录
           "POST /v1/scoring/batch", "CreditBatchRequest"])

配置（env）

变量	默认	说明
OPENAPI_URL	http://localhost:8000/openapi.json	运行时 spec（优先）。可直接填 /docs 文档页地址：自动发现 spec（提取 Swagger UI url: / ReDoc spec-url），发现失败回退同源 /openapi.json → /openapi.yaml
OPENAPI_FILE	空	兜底 spec 文件路径（运行时不可达时使用）
OPENAPI_TIMEOUT	2.0	拉取超时（秒）

• 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 快照）