swagger-mcp-toolkit 让 AI编辑器 更快“读懂并调用”你的接口

---

用MCP一键生成Swagger/OpenAPI 接口声明及代码：swagger-mcp-toolkit 让 AI编辑器 更快"读懂并调用"你的接口文档

在前端开发中，大概率都遇到过这类场景：

• 接口很多、模型很复杂，AI 想帮你写调用代码或封装 SDK，但它对你的 API 结构不熟，得你一遍遍过
• 内网的 Swagger文档（Spring Boot提供）只能浏览器打开，对接接口时需要一遍遍核对
• apifox-mcp只能对应单独模块，且需要等待更新，且无法导入解析Knife4j增加的swagger文档

我做了一个 MCP Server：swagger-mcp-toolkit 。它的目标很直接：把 Swagger/OpenAPI 变成 AI/客户端可探索、可生成、可直接用的 MCP 工具集合，让 AI 在 Cursor、Trae 等支持 MCP 的客户端里，能够更系统地理解接口、列出端点、识别模型，并生成完整的 MCP Tool 定义代码。

这个项目改造自上游：github.com/Vizioz/Swag...

在此基础上增强了 Swagger 2.0 支持，并补齐 Knife4j / swagger-resources 等更贴近国内常见技术栈的能力。

---

它解决了什么问题？

1）让 AI"结构化探索 API"，而不是"猜"

传统做法是把 Swagger JSON 丢给 AI，让它自己分析。但现实是：

• 文档很大，AI 容易漏字段、漏路径、漏模型
• 参数/Schema 的细节（required、enum、嵌套对象、数组）容易被简化
• 多模块（swagger-resources）时，AI 很难稳定选对模块

swagger-mcp-toolkit 做的是：先把 Swagger 下载并缓存到本地，再提供一组 MCP 工具，让 AI 可以按步骤完成"探索 → 选择 → 生成"。

2）能生成"可执行"的 MCP Tool 定义代码

它不只列接口，还能 生成 MCP tool definition 的 TypeScript 代码，并且带上更完整的 schema 信息，降低你手工维护工具定义的成本。

3）补齐 Knife4j / 网关 Header 等落地细节

这个 fork 增强了：

• Swagger 2.0 定义支持（同时保留原有能力）
• Knife4j / KnifeHeader：支持自定义 headers，以及 gatewayHeader / gatewayCode 透传
• swagger-resources：新增 listSwaggerResources、saveSwaggerResources，便于多模块场景选择/落盘

---

为什么要做成一个 npm 的 MCP Server？

我当时的考量主要是三点：

1. MCP 是"工具化接口"的标准通道

   AI 不擅长在长文本里保持一致性，但很擅长调用结构化工具。把 Swagger 转 MCP 工具，就等于给 AI 一条稳定的"读接口"的路。

2. npm 分发成本低，接入门槛低

   你可以本地 build 后 node build/index.js 跑，也可以直接 npx -y swagger-mcp-toolkit@latest ... 拉起，适合团队内部快速推广。

3. CLI 固定 Swagger URL，减少每次对话参数

   MCP 工具调用可以不再每次都传 swaggerFilePath：启动时用 --swagger-url 固定，AI 调用工具更省心，也更不容易出错。

---

安装与构建

方式 A：本地运行（适合二次开发/定制）

git clone https://github.com/ZTrainWilliams/swagger-mcp-toolkit.git
cd swagger-mcp-toolkit
npm install
npm run build
node build/index.js --swagger-url="https://petstore.swagger.io/v2/swagger.json"

方式 B：npx 直接运行（适合"拿来即用"）

npx -y swagger-mcp-toolkit@latest --swagger-url="https://petstore.swagger.io/v2/swagger.json"

在 Cursor 里接入（MCP Server 配置）

Cursor Settings → Features → MCP → "+ Add New MCP Server"：

• Transport：stdio
• Command：node
• Args（示例）：
  • 本地 build：
    • C:/projects/swagger-mcp-toolkit/build/index.js
    • --swagger-url=http://xxx.xx.xx.xx:xxxxxx

swagger-url多为swagger文档的ip（或域名）+ 端口，不需要/doc.html

对应的 MCP 配置例子（README 同款）：

{
  "mcpServers": {
    "get-swagger": {
      "command": "node",
      "args": [
        "C:/projects/swagger-mcp-toolkit/build/index.js",
        "--swagger-url=http://xxx.xx.xx.xx:xxxxxx"
      ],
      "env": {}
    }
  }
}

如果你用 npx：

{
  "mcpServers": {
    "get-swagger": {
      "command": "npx",
      "args": [
        "-y",
        "swagger-mcp-toolkit@latest",
        "--swagger-url=http://xxx.xx.xx.xx:xxxxxx"
      ],
      "env": {}
    }
  }
}

---

可用工具（AI 能调用什么）

swagger-mcp-toolkit 暴露的 MCP Tools 包括：

• getSwaggerDefinition：从 URL 下载 Swagger 定义
• listSwaggerResources：获取 Knife4j swagger-resources（多模块选择）
• saveSwaggerResources：获取并保存 swagger-resources 到本地 JSON
• listEndpoints：列出所有 endpoints（可选 swaggerFilePath）
• listEndpointModels：列出某个 endpoint 关联的模型（可选 swaggerFilePath）
• generateModelCode：生成某个 model 的 TypeScript 代码（可选 swaggerFilePath）
• generateEndpointToolCode：生成某个 endpoint 的 MCP Tool 定义 TypeScript 代码（可选 swaggerFilePath）

Swagger 定义优先级（很重要）

工具会按这个优先级选择 Swagger：

1. 启动时 CLI --swagger-url（优先级最高）
2. 工具调用参数里的 swaggerFilePath
3. 两者都没有则报错

这也是为什么我推荐：启动时就把 swagger-url 固定好。

---

使用建议：一套"AI 友好"的调用流程

在实际体验里，比较稳定的流程是：

1. 如果是多模块：先 listSwaggerResources 看有哪些模块
2. 选定模块后（必要时 saveSwaggerResources 落盘），可通过getSwaggerDefinition获取到模块中相应接口内容
3. listEndpoints 快速扫一遍你关心的路径
4. 对单个接口：listEndpointModels 看它涉及哪些模型
5. 需要强类型/工具化调用：
   • generateModelCode 生成模型 TS
   • generateEndpointToolCode 生成 MCP tool definition TS（包含 schema 信息）

这样 AI 不用"猜"，你也不用反复解释"这个接口是 POST、body 结构是什么、返回什么"。ps：最高在编辑器规划好项目规则或skill。

---

编辑器中查看swagger文档

roothub

编辑器中查看swagger文档

---

仓库地址 & 欢迎使用

• GitHub： swagger-mcp-toolkit

如果你正在用 Cursor 或任何支持 MCP 的客户端，并且你的服务已经有 Swagger/OpenAPI（尤其是 Swagger 2.0 + Knife4j + 多模块那种常见组合），或后端是用Spring Boot提供的swagger文档，这个工具会非常省时间。

欢迎试用、提 Issue / PR，一起把"AI 调接口"这件事做得更顺滑。