Swagger 探索器 MCP 服务器

一个管理控制平面（MCP）服务器，用于通过Claude探索和分析 Swagger/OpenAPI 规范。

快速入门

使用 npx 全局安装并运行：

npx -y @johnneerdael/swagger-mcp

或者通过环境变量进行安装：

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

针对 Claude Desktop 用户的安装说明

1. 打开工具和集成菜单。
2. 点击“添加 MCP 服务器”按钮。
3. 输入以下配置：
   • 地址：localhost
   • 端口：3000
4. 完成后，MCP 服务器将自动运行。

示例交互

基本探索

Claude: 你能通过 Swagger 接口帮我列出所有可用的 API 端点吗？
你：当然可以！请提供 Swagger URL。

分析特定端点

Claude: GET /users 端点返回的数据格式是什么？
你：让我查看一下 Swagger 文档。该端点返回一个包含用户信息的对象，包括 ID、用户名和电子邮件。

功能特性

1. 认证支持：通过bearer令牌进行身份验证。
2. 自定义响应格式：支持Minimal和Detailed两种响应模式。
3. 模式分析：自动解析并展示API接口的结构。
4. API探索：提供完整的API文档浏览功能。

配置说明

1. 环境变量设置
   • BASE_URL: 服务的基础URL，默认为/api
   • AUTH_TOKEN: 访问令牌，用于身份验证
   • PORT: 服务运行的端口，默认为3000
   • SWAGGER_URL: Swagger文档的URL地址

API 端点使用说明

探索 API

curl http://localhost:3000/explore \
  -H "Authorization: Bearer your-token"

获取模式详情

curl http://localhost:3000/schema-details \
  -H "Authorization: Bearer your-token" \
  -d '{"schemaName":"User"}'

获取响应模式

curl http://localhost:3000/response-schemas \
  -H "Authorization: Bearer your-token"

响应格式

1. Minimal 模式

   {
     "status": "success",
     "data": {}
   }
   

2. Detailed 模式

   {
     "status": "success",
     "data": {},
     "description": "完整的 API 接口文档"
   }
   

常见使用场景

1. 探索和分析API端点。
2. 获取特定模式的详细信息。
3. 分析和验证响应格式。

故障排除

1. 连接问题

   • 确保 Swagger URL 可用
   • 检查令牌是否正确
   • 验证端口未被占用

2. 授权错误

   • 确认 AUTH_TOKEN 设置正确
   • 请求中包含 bearer 令牌

3. 模式未找到

   • 检查模式名称是否准确
   • 确保 Swagger 规范已正确加载

安全注意事项

1. MCP 需要认证，若设置 AUTH_TOKEN 则必须提供。
2. 所有请求都会被记录以备调试。
3. 敏感信息不会被缓存。
4. 实施速率限制以防止滥用。

开发说明

1. 克隆仓库：

   git clone [仓库地址]
   

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

4. 本地运行：

   npm start
   

许可证

MIT 许可证 - 详情请参见LICENSE文件