Swagger MCP 服务器

一个提供工具通过 Swagger/OpenAPI 文档来探索和测试 API 的 Model Context Protocol (MCP) 服务器。此服务器能够自动检测来自多个 IDE 的配置文件，并提供全面的 API 交互能力。

功能

• 🔍 从任意 URL 获取并解析 Swagger/OpenAPI 文档
• 🧪 直接通过 MCP 接口测试 API 端点
• 📊 探索 API 架构 并理解数据结构
• 🔧 多 IDE 支持 - 自动检测来自 VS Code、Cursor、Windsurf 等 IDE 的配置
• 🌐 灵活的身份验证 - 支持 API 密钥、基本身份验证和承载令牌
• ⚡ 自动发现 - 能够自动找到文档 URL

配置

IDE 设置

在你的 IDE 配置目录中创建一个 MCP 配置文件：

• VS Code: ~/.vscode/mcp.json 或 .vscode/mcp.json（在你的项目中）
• Cursor: ~/.cursor/mcp.json 或 .cursor/mcp.json（在你的项目中）
• Windsurf: ~/.windsurf/mcp.json 或 .windsurf/mcp.json（在你的项目中）
• 任何 IDE: mcp.json（在你的项目根目录）或 .mcp/config.json

身份验证选项

选项 1：使用 API 密钥

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y",
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_KEY": "your-api-key-here"
  }
}

选项 2：使用用户名和密码

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y", 
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_USERNAME": "your-username",
    "API_PASSWORD": "your-password"
  }
}

配置选项

• API_BASE_URL - 你的 API 基础 URL（例如，https://api.example.com）[必填项]
• API_DOCS_URL - 直接指向 Swagger/OpenAPI JSON/YAML 的 URL（可选，会自动发现）
• API_KEY - 用于身份验证的 API 密钥（用作承载令牌）
• API_USERNAME - 基本身份验证的用户名
• API_PASSWORD - 基本身份验证的密码

身份验证流程

服务器智能处理身份验证：

1. 对于 API 请求：使用 API_KEY 作为承载令牌，如果失败则回退到基本身份验证
2. 对于身份验证端点：自动注入用户名/密码凭据
3. 令牌管理：自动存储并重用登录响应中的令牌
4. 自动刷新：在收到 401 未授权响应时尝试刷新令牌

可用工具

fetch_swagger_info

从给定的 URL 获取并解析 Swagger/OpenAPI 文档以发现可用的 API 端点。

list_endpoints

获取 Swagger 文档后列出所有可用的 API 端点，显示方法、路径和摘要。

get_endpoint_details

获取特定 API 端点的详细信息，包括参数、请求/响应架构和示例。

execute_api_request

执行对特定端点的 API 请求，处理认证、参数、头部和正文。

validate_api_response

根据 Swagger 文档中的模式定义验证 API 响应，确保合规性。

使用示例

一旦配置好，你可以在你的 AI 助力编辑器中使用 MCP 服务器来：

• 探索 API： "展示这个 API 中可用的端点"
• 测试端点： "测试 POST /users 端点，使用这些数据"
• 理解架构： "解释用户模型结构"
• 调试 API 请求： "帮助我解决这个 API 请求的问题"
• 验证响应： "检查这个响应是否符合 API 模式"

支持的 IDE

服务器自动检测来自以下 IDE 的配置文件：

• VS Code (.vscode/mcp.json)
• Cursor (.cursor/mcp.json)
• Windsurf (.windsurf/mcp.json)
• 根目录 (mcp.json)
• 备用位置 (.mcp/config.json)

开发

# 克隆仓库
git clone https://github.com/amrsa1/SwaggerMCP.git
cd SwaggerMCP

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 为生产构建
npm run build

许可证

MIT 许可证 - 查看 LICENSE 文件了解详情。

贡献

欢迎贡献！请随时提交 Pull Request。