AI导哈

OpenAPI文档查询服务

用于加载和查询OpenAPI/Swagger文档的服务器，支持模糊操作匹配和不完整路径或关键词查询。

  • by KrystalQAQ
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 KrystalQAQ/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.

相关 MCP