Swagger MCP

🚀 Swagger MCP 服务器

Swagger MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它借助 Swagger/OpenAPI 文档，为探索和测试 API 提供了实用工具。该服务器能够自动检测多个 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"
  }
}

配置选项

🔧 技术细节

认证流程

服务器能够智能处理认证：

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

服务器会自动检测以下位置的配置文件：

• 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 文件。

贡献说明

欢迎贡献代码！请随时提交拉取请求。