swagger-mcp

English | 中文

用于加载和查询 OpenAPI/Swagger 文档的 MCP 服务。 支持在用户只提供部分路径或关键词时进行接口模糊匹配。

功能特性

• 加载远程 OpenAPI 3.x 文档（JSON/YAML）
• 基于内存的文档缓存（TTL）
• 按 method/tag/关键词筛选接口
• 通过不完整路径进行接口模糊解析
• 查看接口完整请求/响应结构
• 查看 components.schemas 以及被哪些接口引用

工具列表

• openapi.load
• openapi.health
• openapi.reload
• openapi.list_operations
• openapi.resolve_operation
• openapi.get_operation
• openapi.explain_operation
• openapi.get_schema

openapi.explain_operation 适合直接回答“这个接口怎么调”：会输出参数分类、请求体示例和响应示例。

省 token 默认策略：

• openapi.resolve_operation：topK 默认 3
• openapi.get_operation：默认 resolveRefs=false 且 responseFormat=compact
• openapi.explain_operation：默认 resolveRefs=false 且 detailLevel=brief

环境要求

• Node.js 18+
• pnpm 10+

快速开始

pnpm install
pnpm dev

构建并运行：

pnpm build
pnpm start

Codex MCP 配置示例

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "swaggertools-mcp", "--docPath", "http://dev.manage.zw.uav.sczlcq.com/v3/api-docs"]
    }
  }
}

如果你在本仓库本地联调，也可以继续用 pnpm dev 启动。

参数说明

• openapi.load 支持运行时入参：url、headers、forceRefresh
• url（或回退到启动参数 --docPath）必须是 OpenAPI 文档的 http/https 地址
• 启动参数 --docPath 变为可选，用于在未传 openapi.load.url 时作为默认来源
• 不再通过 .env 或其他环境变量读取默认文档地址

docId: "default" 行为

• 如果服务中已加载过文档，default 会映射到最近一次加载的 docId。
• 如果尚未加载文档，会返回错误并提示先调用 openapi.load。

常见问题

• 错误：Document not found: default
  • 先调用 openapi.load
  • 确保 MCP 启动参数中已设置 --docPath