swagger-mcp

🚀 基于Swagger的MCP服务器

这是一个通过Model Context Protocol（MCP）处理 Swagger/OpenAPI 规范的服务器，能加载规范、支持多种认证方式，还可自动生成MCP工具，为实时通信提供支持，同时具备 TypeScript 支持。

✨ 主要特性

• 规范加载：可加载 Swagger/OpenAPI 规范。
• 多认证支持：支持基本认证、Bearer Token、API Key（头或查询）、OAuth2 等多种身份验证方法。
• 工具自动生成：能从 API 端点自动生成 MCP 工具。
• 实时通信支持：对实时通信支持 Server-Sent Events (SSE)。
• TypeScript 支持：具备 TypeScript 支持。

⚠️ 安全性提示

⚠️ 重要提示

这是一个个人服务器，请勿将其暴露到公共互联网。若底层 API 需要身份验证，同样不应将 MCP 服务器暴露到公共互联网。

📋 待办事项

• 秘密 - MCP 服务器应能够使用用户的秘密来对请求进行身份验证。
• 全面测试套件。

📦 安装指南

先决条件

• Node.js（v18 或更高）
• Yarn 包管理器
• TypeScript

安装步骤

1. 克隆仓库：

git clone https://github.com/dcolley/swagger-mcp.git
cd swagger-mcp

2. 安装依赖项：

yarn install

3. 基于示例创建.env文件：

cp .env.example .env

4. 配置你的 Swagger/OpenAPI 规范：
   • 将你的 Swagger 文件放在项目中（例如swagger.json）。
   • 或者提供到你的 Swagger 规范的 URL。
5. 在config.json中更新服务器设置：

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // 如果Swagger中未指定，则作为备用URL
    "defaultAuth": {  // 如果Swagger中未指定身份验证方案，则作为备用设置
      "type": "apiKey",
      "apiKey": "your-api-key",
      "name": "Authorization",
      "value": "Bearer ${ apiKey }"
    }
  }
}

💻 使用示例

启动开发服务器

yarn dev

构建生产环境

yarn build

📚 详细文档

API 端点

获取所有文档

GET /api-docs

根据名称获取文档

GET /api-docs/{name}

发布文档

POST /api-docs

删除文档

DELETE /api-docs/{name}

认证方法

基本认证

配置示例：

{
  "defaultAuth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Bearer Token

配置示例：

{
  "defaultAuth": {
    "type": "bearer",
    "token": "your-bearer-token"
  }
}

API Key

配置示例：

{
  "defaultAuth": {
    "type": "apiKey",
    "key": "your-api-key",
    "name": "X-API-Key",
    "value": "${ key }"
  }
}

OAuth2

配置示例：

{
  "defaultAuth": {
    "type": "oauth2",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "accessTokenUrl": "https://example.com/oauth/token",
    "authorizationUrl": "https://example.com/oauth/authorize"
  }
}

环境变量

| 属性 | 详情 | |------|------| | NEXT_PUBLIC_API_BASE_URL | 默认情况下，API 基础 URL | | NEXT_PUBLIC_SWAGGER_URL | 默认 Swagger 规范的 URL |

🧪 测试

运行测试

yarn test

按照环境运行测试

yarn test:dev

按照覆盖运行测试

yarn test:cov