能力
面向 Agent 的实时文档查询
将文档发现、接口定位、Schema 展开和来源信息统一为只读 MCP Tool
实时获取
每次 Tool 调用都从目标入口重新获取文档，不依赖快照或缓存。上游失败时明确报错，不返回过期内容。
无状态
不保存文档地址、不绑定工程、不记录历史。每次调用都必须显式传入 docsUrl。
安全只读
不调用业务 API、不读取外部引用、拒绝跨主机重定向。stdout 只承载 MCP 协议，不影响业务系统。
Schema 展开
递归展开响应字段树，标记循环引用、动态 Map、外部引用边界。同时输出 schemaTree 和可检索的 flatFields。
分步导航
识别 Knife4j 深链接，实时验证 hash 分组、分类和 operationId 线索，引导 AI 逐级定位接口，不猜测未查验的结果。
来源可追溯
每个结果都注明本次查询地址、实际 Swagger 地址、获取时间和缓存状态。降低联调时错查旧文档的风险。
三步入门
在对话中直接查询接口
-
1.
以 Claude Code 为例，运行配置命令：
npx --yes swagger-docs-mcp@latest setup claude -
2.
在 AI 对话中提供
doc.html地址和查询意图 -
3.
AI 实时获取文档，返回分类、接口详情或搜索结果
// 虚拟示例：列出接口分类 Tool: list_api_categories docsUrl: https://api.example.com/doc.html // 虚拟示例输出： account-controller 6 个接口 order-controller 4 个接口 catalog-controller 3 个接口 本次查询: api.example.com/doc.html 实际地址: api.example.com/v2/api-docs 未使用缓存
客户端
覆盖 11 类 MCP 客户端
Codex、Claude Code 和 Gemini CLI 支持自动写入配置并核验；其余客户端仅生成配置，不修改本地文件。
自动配置并核验
OpenAI Codex
Claude Code
Gemini CLI
仅生成配置
VS Code Copilot
Cursor
Windsurf
Trae
Cline
Roo Code
Kiro
OpenCode v2
交给 Agent
复制任务，让 Agent 完成接入
适用于具备本机命令和文件操作能力的 Agent。任务会要求它先核实客户端与配置契约，再安装、配置并验证。
请帮我在当前 MCP 客户端中安装并配置 swagger-docs-mcp。 要求： 1. 先确认 Node.js 版本不低于 20，并识别当前客户端的准确名称；不要猜测客户端或配置格式。 2. 运行 `npx --yes swagger-docs-mcp@latest setup list`，根据输出选择准确的客户端 ID。 3. 运行 `npx --yes swagger-docs-mcp@latest setup <client>`。 4. 如果命令自动写入配置，确认结果明确通过启动命令一致性核验。 5. 如果命令只输出 JSON，仅在核实当前客户端的官方配置文件位置和结构后，合并 `swagger-docs` 条目并保留其他配置；写入后重新解析配置，核对完整启动命令。 6. 如发现同名配置、权限错误、无法核验或外部契约不明确，立即停止并说明原因；不要覆盖、删除或猜测修复。 7. 最后运行 `npx --yes swagger-docs-mcp@latest doctor`，并报告实际使用的客户端 ID、执行命令、修改位置和核验结果。 不要保存 Swagger 文档地址、口令或 Token，也不要修改与本次接入无关的 MCP 配置。