JinDaGe - swagger-mcp MCP Details

article

README

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

配置选项

| 属性 | 详情 | |------|------| | API_BASE_URL | 您的 API 基础 URL（例如，https://api.example.com），[必需] | | API_DOCS_URL | Swagger/OpenAPI JSON/YAML 文件的直接 URL（可选，将自动发现） | | API_KEY | 用于认证的 API 密钥（用作令牌） | | API_USERNAME | 基本认证的用户名 | | API_PASSWORD | 基本认证的密码 |

🔧 技术细节

认证流程

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

对于 API 请求：使用 API_KEY 作为令牌，若不可用则使用基本认证。
对于认证端点：自动注入用户名/密码凭证。
令牌管理：自动存储并重用登录响应中的令牌。
自动刷新：在收到 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 文件。

贡献说明

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

swagger-mcp