Swaggertools MCP

马大伟

英语| 中文

MCP服务器，用于加载和查询OpenAPI/Swagger文档。 当用户提供不完整的路径或关键字时，它支持模糊操作匹配。

特性

• 加载远程OpenAPI 3.x文档（JSON/YAML）
• 带TTL的内存文档缓存
• 按方法/标签/关键字列出/过滤操作
• 部分路径的模糊解析操作
• 检查完整的请求/响应详细信息
• 检查 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 是为“如何调用此API”答案而设计的，包括参数组、请求示例和响应示例。

令牌保存默认值：

• 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 回退）必须是 http/https OpenAPI文档URL
• 初创公司 --docPath 是可选的，在以下情况下充当默认源 openapi.load.url 未提供
• 没有从加载默认的OpenAPI URL .env 或其他环境源

docId: "default" 行为

• 如果文档已经被加载， default 映射到最新加载的 docId.
• 若还没有加载文档，服务器将返回错误并要求调用 openapi.load 第一。

故障排除

• 错误： Document not found: default

- 呼叫 openapi.load 第一。 - 确保MCP启动参数包括 --docPath.