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 Desktop 安装

1. 打开 Claude Desktop
2. 点击设置（齿轮图标）
3. 选择 "Tools & Integrations"（工具 & 集成）
4. 点击 "Add MCP Server"（添加 MCP 服务器）
5. 输入以下内容：

   Name: Swagger Explorer
   Command: npx -y @johnneerdael/swagger-mcp
   Arguments: --swagger-url=$SWAGGER_URL
   

6. 点击 "Install"（安装）

与 Claude 一起使用

以下是一些与 Claude 交互的示例：

基本 Swagger 探索

Human: Can you explore the Swagger documentation at http://localhost:8080/docs?

Claude: I'll help you explore that Swagger documentation using the Swagger Explorer MCP.

Let me analyze the API endpoints and schemas for you:

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

分析特定端点

Human: What are the available response schemas for the /pets POST endpoint?

Claude: I'll check the response schemas for that endpoint using the MCP.

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

Schema 分析

Human: Can you show me the detailed structure of the Pet schema?

Claude: I'll retrieve the detailed schema information using the MCP.

[Claude 会使用 MCP 分析 schema 结构]

功能

1. 身份验证支持

   • Bearer token 身份验证
   • 可通过环境变量配置

2. 自定义响应格式

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

3. Schema 分析

   • 详细的属性探索
   • 响应 schema 分析
   • Schema 关系

4. API 探索

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

配置

环境变量：

• BASE_URL: API 的基本路径（默认：''）
• AUTH_TOKEN: 用于身份验证的 Bearer token
• 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
    }
  }'

获取 Schema 详细信息

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"
  }'

获取响应 Schemas

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": {
    // 仅非 null 值
  }
}

详细格式

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

常见用例

1. API 文档审查

   Human: Can you summarize all the available endpoints and their purposes?
   

2. Schema 验证

   Human: What fields are required for creating a new pet?
   

3. 响应分析

   Human: What are the possible error responses for the login endpoint?
   

4. 集成计划

   Human: How should I structure my request to create a new order?
   

故障排除

1. 连接问题

   • 确保 Swagger URL 可访问
   • 检查身份验证 token 是否正确
   • 验证端口是否未被使用

2. 授权错误

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

3. Schema 未找到

   • 检查 schema 名称是否完全匹配
   • 验证 Swagger spec 是否已正确加载

安全说明

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

开发

要贡献或修改：

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

   npm install
   

3. 构建：

   npm run build
   

4. 在本地运行：

   npm start
   

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件