MCP 服务器

swagger-openapi-mcp

Enables AI to scan and query local OpenAPI/Swagger documentation, listing API groups and endpoints, and generating TypeScript type definitions for specific endpoints.

README

Swagger/OpenAPI MCP Server (Streamable HTTP)

这是一个基于 MCP (Model Context Protocol) 的服务端应用，专为 AI 辅助开发设计。

它采用 Streamable HTTP 协议运行，能够扫描您本地的 OpenAPI/Swagger 文档目录，使 AI (如 Claude, Cursor) 能够理解您的后端接口结构、查询详细定义，甚至为您生成前端 TypeScript 类型代码。

🌟 核心特性

智能文档索引：AI 可以扫描指定文件夹下的所有 .yaml / .json 文件并自动聚合。
基于 Tag 分组：支持按业务 Tag (如 Auth, Users) 查看接口，跨文件聚合，更符合业务逻辑。
TypeScript 类型生成：集成 openapi-typescript，直接为特定接口生成精简的 TypeScript interface (Query/Body/Response)。
缓存热更新：支持手动刷新缓存，即时同步文档变更。

📥 下载与运行

1. 下载项目

git clone https://github.com/dreamhuan/swagger-openapi-mcp.git
cd swagger-openapi-mcp

2. 安装依赖

pnpm install

3. 环境配置

复制 .env.sample 为 .env，并修改 OPENAPI_DIR_PATH 为你本地 Swagger/OpenAPI 文件所在的绝对路径。

cp .env.sample .env

.env 示例：

OPENAPI_DIR_PATH=/Users/username/my-project/docs
PORT=3030

注意这是一个文件夹的路径，里面存放所有的xxx.yaml，有一个api.yaml作为入口

4. 启动服务

pnpm dev

服务启动后，Endpoint 地址为: http://localhost:3030/mcp

⚙️ MCP 客户端配置

{
  "mcpServers": {
    "openapi-tools": {
      "transport": "http",
      "url": "http://localhost:3030/mcp"
    }
  }
}

🤖 可用工具 (Tools)

1. `list_api_group`

功能：列出当前所有可用的 API Tags (业务分组)。
示例输出：["auth", "billing", "users"]

2. `list_api_structure`

功能：列出 API 路径概览。支持按 Tag 过滤。
参数：
- tags (可选, string[]): 指定 Tag 列表。建议先调用 list_api_group 获取 Tag，然后指定此参数以减少输出量。
- 示例: {"tags": ["auth", "files"]}

3. `get_endpoint_types`

功能：精准提取特定接口的 TypeScript 类型定义 (Query Params, Request Body, Response)。
参数：
- path (如 /users/{id})
- method (如 POST)

4. `refresh_api_cache`

功能：清除内存缓存并重新解析 OpenAPI 文件。当您修改了 YAML 文件后调用此工具。

📦 推荐的 AI 工作流

AI: "先看看有哪些 API 业务分组。" -> 调用 list_api_group。
AI: "我看有 auth 模块，列出里面的接口。" -> 调用 list_api_structure(tags=["auth"])。
AI: "需要 /auth/login 接口的类型定义。" -> 调用 get_endpoint_types(path="/auth/login", method="POST")。