swagger-mcp-tool

基于 Bun 的 Swagger MCP Server，用于解析和查询 Swagger/OpenAPI 文档。为 AI 模型提供 Swagger 文档查询工具，辅助生成接口代码。例如：AI 可以查询 Swagger 文档获取接口定义，然后生成对应的 TypeScript 接口代码。

功能

提供 Swagger/OpenAPI 文档的查询工具，支持从本地文件或远程 URL 加载文档。AI 可以通过这些工具查询接口定义、Schema 等信息，用于生成 TypeScript 类型定义和 API 调用代码。

前置使用条件

1. 安装 Bun 运行时

项目依赖 Bun 运行时环境，使用前需要先安装 Bun：

curl -fsSL https://bun.sh/install | bash

2. 准备 Swagger 文档

确保你有可用的 Swagger/OpenAPI 文档（本地文件路径或远程 URL）

使用方式

通过 npx 使用（推荐）

# 使用远程 URL
npx swagger-mcp-tool http://example.com/api/swagger.json

# 使用本地文件路径
npx swagger-mcp-tool ./docs/swagger.json

注意：必须提供 Swagger 文档地址作为命令行参数，否则程序会报错退出。

通过 bunx 使用

# 使用远程 URL
bunx swagger-mcp-tool http://example.com/api/swagger.json

# 使用本地文件路径
bunx swagger-mcp-tool ./docs/swagger.json

参数说明

• 第一个参数（必需）：Swagger 文档的 URL 或本地文件路径
  • 支持 HTTP/HTTPS URL（远程文档）
  • 支持本地文件路径（相对路径或绝对路径）
  • 必须提供此参数，如果不提供，程序会报错并退出

MCP 客户端配置

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中（通常是 ~/.cursor/mcp.json 或项目中的 .cursorrules），添加以下配置：

使用远程 URL

{
  "mcpServers": {
    "swagger-tools": {
      "command": "npx",
      "args": ["swagger-mcp-tool", "http://example.com/api/swagger.json"]
    }
  }
}

使用本地文件

{
  "mcpServers": {
    "swagger-tools": {
      "command": "npx",
      "args": ["swagger-mcp-tool", "/path/to/your/swagger.json"]
    }
  }
}

使用 bunx（如果已安装 Bun）

{
  "mcpServers": {
    "swagger-tools": {
      "command": "bunx",
      "args": ["swagger-mcp-tool", "http://example.com/api/swagger.json"]
    }
  }
}

注意：

• 使用绝对路径更可靠
• 配置后需要重启 Cursor 才能生效

可用工具

1. list_api_groups

功能：列出所有 API 分组（标签）

描述：从 Swagger 文档中获取所有 API 分组信息。如果文档中没有定义顶层标签，会自动从路径中收集所有使用的标签。

使用场景：

• 查看 API 文档中有哪些功能模块
• 了解 API 的组织结构

2. search_apis

功能：搜索 API（支持按标签或关键词）

描述：根据标签或关键词搜索匹配的 API。支持在路径、摘要、描述和操作 ID 中进行搜索。

参数：

• tag（可选）：按标签过滤 API
• keyword（可选）：在路径、摘要或描述中搜索关键词

使用场景：

• 查找特定功能模块的 API
• 根据关键词快速定位相关接口

3. get_api_detail

功能：获取 API 详细信息

描述：获取指定路径和方法的完整 API 定义，包括请求参数、响应结构、描述等详细信息。会自动合并路径级别的参数。

参数：

• path：API 路径，如 /user/v1/account/unbind
• method：HTTP 方法，如 get、post、put、delete

使用场景：

• 查看特定接口的完整定义
• 生成 API 调用代码
• 了解接口的请求和响应结构

4. get_schema

功能：获取 Schema 定义

描述：通过引用或名称获取数据模型的 Schema 定义。支持完整的 Schema 引用格式（如 #/components/schemas/UserSetupParam）或简化的名称格式（如 UserSetupParam）。

参数：

• ref：Schema 引用或名称，如 #/components/schemas/UserSetupParam 或 UserSetupParam

使用场景：

• 查看数据模型的定义
• 生成 TypeScript 类型定义
• 了解请求/响应的数据结构

许可证

MIT License