aike1202/swagger-mcp-server

Swagger MCP Server

这是一个功能强大的 MCP (Model Context Protocol) 服务器，能够将任意 Swagger/OpenAPI 文档转化为 AI 可理解、可调用的工具集。它不仅支持文档查询，还支持接口调试、代码生成和cURL 命令构建。

✨ 核心功能

🔍 智能文档查询

• list_services: 查看所有配置的 API 服务。
• list_endpoints: 列出服务中的所有接口摘要。
• search_apis: 支持智能模糊搜索（加权匹配）。例如搜索 "user create"，即使接口是 "create new user" 也能精准命中。
• get_endpoint_details: 获取接口的完整定义，包括请求参数、Body 结构和响应 Schema。

🚀 接口调试与测试

• debug_endpoint: (杀手级功能) 让 AI 直接调用真实接口。
  • 自动认证 (Auto Auth):
    • 支持在配置中预设账号密码（如 auth=admin:123456）。
    • 当接口返回 401 时，MCP 会提示 AI 使用预设凭证登录。
    • AI 调用登录接口后，MCP 自动捕获并缓存 Token，后续请求自动注入。
  • 智能参数补全: 如果你漏掉了必填参数，MCP 会根据 Schema 类型自动填充合理的默认值，防止 400 错误。
  • 网络自动纠错: 自动处理 localhost vs 127.0.0.1 的连接问题。

💻 开发者生产力

• generate_curl: 生成标准的 cURL 命令，方便在终端复现请求。
• Typescript/Client 代码生成: (V2 新特性) 不再依赖死板的工具，直接让 AI 阅读 get_endpoint_details 的 Schema，生成符合你项目规范的完美代码。

🛠 安装与使用

1. 安装依赖

npm install

2. 构建项目

npm run build

3. 配置 MCP Host (Claude Desktop / Windsurf)

编辑你的 MCP 配置文件（如 %APPDATA%/Claude/claude_desktop_config.json 或 Windsurf 配置）。

方式一：NPX 免安装模式（推荐）

直接运行最新发布的包，无需手动下载源码。

{
  "mcpServers": {
    "swagger": {
      "command": "npx",
      "args": [
        "-y",
        "@aike1202/swagger-mcp-server",
        "http://localhost:8090/v3/api-docs"
      ]
    }
  }
}

方式二：本地源码模式（开发用）

如果你 Clone 了本项目并想自己修改代码：

{
  "mcpServers": {
    "swagger": {
      "command": "node",
      "args": [
        "E:/mcp/swagger-mcp/build/index.js", // 修改为你的实际路径
        "http://localhost:8090/v3/api-docs"
      ]
    }
  }
}

进阶配置（多服务 + 自动认证）

支持同时挂载多个微服务文档，以及自动登录配置：

{
  "mcpServers": {
    "swagger": {
      "command": "npx", // 或 "node"
      "args": [
        "-y",
        "@aike1202/swagger-mcp-server",
        "user=http://localhost:8090/v3/api-docs",
        "order=http://localhost:8091/v3/api-docs",
        "auth=admin:123456"  // [可选] 预设凭证，AI 遇到 401 时会知道用这个账号去登录
      ]
    }
  }
}

📝 如何高效调用 MCP 服务

1. 让 AI 学习你的项目规则 (System Prompt / Rules)

为了让 AI 更好地配合你的工作流，建议在 Cursor/Windsurf 的 .cursorrules 或 .windsurfrules 中添加以下规则：

# Swagger MCP 使用规范

当用户要求进行 API 开发或调试时，请遵循以下 SOP：

1. **搜索先行**: 先使用 `search_apis` 找到相关接口，不要凭空猜测路径。
2. **详情确认**: 在写代码或测试前，必须调用 `get_endpoint_details` 确认参数结构。
3. **智能测试**:
    - 如果需要测试接口，直接调用 `debug_endpoint`。
    - 如果遇到 401 错误且提示有存储凭证，请自动寻找登录接口（如 `/auth/login`）进行登录，然后再重试原请求。
    - 不需要用户提供所有参数，利用 `debug_endpoint` 的自动补全功能。
4. **类型生成**: 
    - 不要自己瞎编类型。先调用 `get_endpoint_details` 获取 Schema，然后根据该 Schema 为我生成 TypeScript 接口。
    - 接口命名风格请遵循 IRequest, IResponse。

2. 常用对话指令 (Prompt 示例)

• 全自动测试流程:

  "帮我测一下创建订单接口，参数随便填，只要能跑通就行。" (AI 会自动搜索接口 -> 查详情 -> 自动补全参数 -> 调用 -> 如果 401 自动登录 -> 重试)

• 前端联调 (新玩法):

  "我要对接查询用户接口，先查一下它的定义，然后帮我生成 React Hook 和 TS 类型。" (AI 会先查文档，然后利用它的代码生成能力直接写出完美的 React 代码，比旧版 generate_interface 工具更强)

• 排查问题:

  "这个接口一直报错，帮我看看参数传得对不对，顺便生成个 curl 我在终端里试试。"

📂 项目结构

src/
├── index.ts             # 服务入口
├── services/
│   └── loader.ts        # 文档加载、多服务管理、Token 缓存、凭证管理
├── tools/
│   └── index.ts         # MCP 工具定义 (Search, Debug, Curl...)
├── utils/
│   └── schema.ts        # JSON Schema 解析
└── types/
    └── swagger.ts       # 类型定义

⚡ 常见问题 (FAQ)

• Q: 连接 localhost 报错 connect EACCES ::1:8090?

  • A: MCP Server 已内置自动纠错机制，会自动切换到 127.0.0.1 重试，无需手动修改 Host。

• Q: 登录接口的 Token 不在 data.token 字段里怎么办？

  • A: 目前支持自动识别 token, accessToken, access_token 以及 Authorization 头。如果你的结构很特殊，请修改 src/tools/index.ts 中的 heuristic 逻辑。

Enjoy your AI-powered API development! 🚀