Swagger MCP Server

用于 Swagger / OpenAPI 文档查询的 MCP Server，支持多系统、多模块懒加载、URL 解析、缓存管理与 TypeScript 代码生成。

特性

• 多系统支持：kunpeng / like
• 多模块懒加载：首次访问模块时加载，后续复用缓存
• 缓存可控：支持 TTL 自动过期 + 手动刷新 + 状态查看
• URL 解析：支持 doc.html#/xxx-server/... 直接定位接口
• 查询能力：关键词、路径、标签、详情、Schema、批量搜索
• 代码生成：生成单接口 / 路径前缀的 TypeScript 代码

环境变量

至少配置以下之一：

• SWAGGER_BASE_URL_KUNPENG
• SWAGGER_BASE_URL_LIKE

可选配置：

• SWAGGER_BASE_URL_KUNPENG_ALIASES：kunpeng 的 host 别名（逗号分隔，不带协议）
• SWAGGER_BASE_URL_LIKE_ALIASES：like 的 host 别名（逗号分隔，不带协议）
• SWAGGER_CACHE_TTL_MS：缓存 TTL，默认 600000（10 分钟）

示例：

{
  "mcpServers": {
    "swagger-mcp-server-x": {
      "command": "npx",
      "args": ["-y", "swagger-mcp-server-x"],
      "type": "stdio",
      "disabled": false,
      "env": {
        "SWAGGER_BASE_URL_KUNPENG": "https://your-swagger-domain.com",
        "SWAGGER_BASE_URL_LIKE": "https://your-swagger-domain.com",
        "SWAGGER_BASE_URL_LIKE_ALIASES": "ip:port",
        "SWAGGER_CACHE_TTL_MS": "600000"
      }
    }
  }
}

工具列表

所有工具均支持可选参数 system（kunpeng / like）。不传时会按 URL host 或默认系统推断。

1. swagger_search_by_keyword

   • 参数：keyword(必填), module(可选), system(可选)
   • 功能：关键词搜索接口

2. swagger_search_by_path

   • 参数：path(必填), method(可选), module(可选), system(可选)
   • 功能：按路径精确查找接口

3. swagger_get_details

   • 参数：path(必填), method(可选), module(可选), system(可选)
   • 功能：获取完整接口详情

4. swagger_get_schema

   • 参数：schemaRef(必填), module(可选), system(可选)
   • 功能：获取 Schema 定义

5. swagger_list_all

   • 参数：module(可选), system(可选)
   • 功能：列出接口（按标签分组）

6. swagger_list_by_tag

   • 参数：tag(必填), module(可选), system(可选)
   • 功能：按标签列出接口

7. swagger_batch_search

   • 参数：keywords(必填), module(可选), system(可选)
   • 功能：多关键词批量搜索

8. swagger_parse_url

   • 参数：url(必填), system(可选)
   • 功能：解析 Swagger UI URL 并返回目标接口详情

9. swagger_generate_typescript

   • 参数：path(必填), rootModule(必填), apiName(必填), interfaceName(必填), method(可选)
   • 功能：生成单接口 TypeScript 代码

10. swagger_generate_module_typescript

    • 参数：rootModule(必填), pathPrefix(必填), apiName(必填), interfaceName(可选)
    • 功能：按路径前缀生成 TypeScript 代码

11. swagger_get_doc_url

    • 参数：path(必填), method(可选), module(可选), system(可选)
    • 功能：根据接口信息反推 Swagger UI 文档 URL

12. swagger_reload_module

    • 参数：module(必填), system(可选)
    • 功能：手动强制刷新模块缓存（忽略 TTL）

13. swagger_cache_status

    • 参数：system(可选), module(可选)
    • 功能：查看缓存状态（是否过期、剩余 TTL、swaggerUrl、接口数量）

URL 与模块名规则

• 默认从 URL hash 提取模块：#/xxx-server/... -> xxx
• 默认拼接文档地址：{BASE_URL}/admin-api/{module}/v3/api-docs
• like 系统兼容映射：like-xxx-server 会映射到 admin-api/xxx/v3/api-docs（例如 like-like-server -> admin-api/like/v3/api-docs）

缓存机制

• 按 system 分别维护模块缓存
• 每个模块记录加载时间
• getOrLoadModule 在缓存过期时自动重载
• 可用 swagger_reload_module 手动刷新
• 可用 swagger_cache_status 观察缓存健康度

开发命令

• 构建：npm run build
• Swagger 测试：npm run test:swagger
• Doc URL 测试：npm run test:swagger:get-doc-url

License

MIT