# 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、responses |
| `get_schema` | `name` | schema 属性表 + 嵌套 `$ref` 下钻键 |
| `select` | `patterns?, security?, tag?, schema_glob?` | 批量圈键（横向聚合，如「所有鉴权端点」） |
| `get_batch` | `keys, include_refs?` | 批量下探，引用的 schema 整合为去重附录 |

单键下钻用 `get_endpoint` / `get_schema`；横向问题先 `select` 圈键再 `get_batch` 一次取回。
下钻键 = `METHOD /path` 或 schema 名，从上层输出直接获得；键与 pattern 的完整文法见 [KEYS.md](KEYS.md)。

## 快速开始

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

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

`OPENAPI_URL` 指向目标项目的 `/docs` 或 `/openapi.json`（其他数据源在各自项目级 `.mcp.json` 覆盖），完整一轮：

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

不确定路径形态就先不带 patterns 调 `select()` 拿全表，照表中「方法 + 路径」两列拼 pattern——**表即素材，照抄必中**。

## 配置（env）

| 变量 | 默认 | 说明 |
|---|---|---|
| `OPENAPI_URL` | `http://localhost:8000/openapi.json` | 运行时 spec；可直接填 `/docs` 文档页地址，自动发现 spec |
| `OPENAPI_FILE` | 空 | 兜底 spec 文件路径（运行时不可达时使用） |
| `OPENAPI_TIMEOUT` | `2.0` | 拉取超时（秒） |

spec 支持 JSON 与 YAML，进程内缓存 60s；请求直连不走系统代理（目标是 localhost / 内网 spec）；只读，不提供调用 API 的能力。

## 开发

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

协议合规（MCP 2026-07-28）：五工具均声明 `readOnlyHint: true`；错误按规范 §Tools Error Handling 抛 `isError=true` 并附自纠建议，零匹配是成功文本。