Swagger Explorer MCP

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

快速开始

使用npx全局安装并运行：

npx -y @johnneerdael/swagger-mcp

或者使用环境变量进行安装：

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

Claude桌面安装

1. 打开Claude桌面
2. 点击设置（齿轮图标）
3. 选择“工具与集成”
4. 点击“添加MCP服务器”
5. 输入以下内容：

   名称: Swagger Explorer
   命令: npx -y @johnneerdael/swagger-mcp
   参数: --swagger-url=$SWAGGER_URL
   

6. 点击“安装”

使用Claude

这里是一些与Claude交互的例子：

基本Swagger探索

人类: 你能探索位于http://localhost:8080/docs的Swagger文档吗？

Claude: 我会帮助你使用Swagger Explorer MCP来探索那个Swagger文档。

让我为你分析API端点和模式：

[Claude会使用MCP获取并分析Swagger文档]

分析特定端点

人类: /pets POST端点有哪些可用的响应模式？

Claude: 我会使用MCP检查该端点的响应模式。

[Claude会使用MCP获取特定端点的详细信息]

模式分析

人类: 你能展示Pet模式的详细结构吗？

Claude: 我会使用MCP检索详细的模式信息。

[Claude会使用MCP分析模式结构]

功能

1. 认证支持

   • Bearer令牌认证
   • 通过环境变量配置

2. 自定义响应格式化

   • 最小格式：移除null/空值
   • 详细格式：包括元数据和时间戳
   • 原始格式：未修改的响应

3. 模式分析

   • 详细属性探索
   • 响应模式分析
   • 模式关系

4. API探索

   • 路径列表
   • 方法过滤
   • 响应格式分析

配置

环境变量：

• BASE_URL：API的基本路径（默认：''）
• AUTH_TOKEN：用于认证的Bearer令牌
• PORT：服务器端口（默认：3000）
• SWAGGER_URL：默认的Swagger文档URL

API端点

探索API

curl -X POST http://localhost:3000/api/explore \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "options": {
      "paths": true,
      "schemas": true
    }
  }'

获取模式详情

curl -X POST http://localhost:3000/api/schema-details \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "schemaName": "Pet"
  }'

获取响应模式

curl -X POST http://localhost:3000/api/response-schemas \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "path": "/pets",
    "method": "post"
  }'

响应格式

最小格式

{
  "status": "success",
  "data": {
    // 只有非空值
  }
}

详细格式

{
  "status": "success",
  "timestamp": "2025-01-29T10:00:00.000Z",
  "data": {
    // 完整响应
  },
  "metadata": {
    "version": "1.0",
    "format": "detailed"
  }
}

常见用例

1. API文档审查

   人类: 你能总结所有可用的端点及其用途吗？
   

2. 模式验证

   人类: 创建新宠物需要哪些字段？
   

3. 响应分析

   人类: 登录端点可能有哪些错误响应？
   

4. 集成规划

   人类: 我应该如何构建请求以创建新订单？
   

故障排除

1. 连接问题

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

2. 授权错误

   • 验证AUTH_TOKEN是否设置正确
   • 确保请求中包含bearer令牌

3. 模式未找到

   • 检查模式名称是否完全匹配
   • 验证Swagger规范是否正确加载

安全注意事项

1. 如果设置了AUTH_TOKEN，MCP需要认证
2. 所有请求都会记录以供调试
3. 敏感信息不会被缓存
4. 应用速率限制以防止滥用

开发

要贡献或修改：

1. 克隆仓库
2. 安装依赖项：

   npm install
   

3. 构建：

   npm run build
   

4. 本地运行：

   npm start
   

许可证

MIT许可证 - 查看LICENSE文件以获取详细信息