AI导哈

Swagger探索工具

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

  • by johnneerdael
  • TypeScript
  • 本地部署
  • 19 星标
  • 更新于
在 GitHub 查看 johnneerdael/swagger-mcp

使用说明

Swagger Explorer 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. 点击设置（齿轮图标）
  3. 选择“工具和集成”
  4. 点击“添加MCP服务器”
  5. 输入以下内容：
    Name: Swagger Explorer
Command: npx -y @johnneerdael/swagger-mcp
Arguments: --swagger-url=$SWAGGER_URL
  6. 点击“安装”

与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 would then use the MCP to fetch and analyze the Swagger documentation]

分析特定端点

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 would use the MCP to fetch specific endpoint details]

模式分析

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

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

[Claude would use the MCP to analyze the schema structure]

特性

  1. 身份验证支持

    • 承载令牌身份验证
    • 可通过环境变量进行配置

  2. 自定义响应格式

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

  3. 模式分析

    • 详细的房地产勘探
    • 响应模式分析
    • 架构关系

  4. API勘探

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

配置

环境变量：

  • BASE_URL：API的基本路径（默认值：“”）
  • AUTH_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
    }
  }'

获取架构详细信息

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": {
    // Only non-null values
  }
}

详细格式

{
  "status": "success",
  "timestamp": "2025-01-29T10:00:00.000Z",
  "data": {
    // Full response
  },
  "metadata": {
    "version": "1.0",
    "format": "detailed"
  }
}

常见用例

  1. API文件审查

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

  2. 架构验证

    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可访问
    • 检查身份验证令牌是否正确
    • 验证端口未使用

  2. 授权错误

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

  3. 未找到架构

    • 检查架构名称是否完全匹配
    • 验证Swagger规格是否正确加载

安全说明

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

发展

贡献或修改：

  1. 克隆存储库
  2. 安装依赖项：
    npm install
  3. 构建：
    npm run build
  4. 在本地运行：
    npm start

许可证

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

相关 MCP