基于Swagger的MCP服务器

这是一个通过Model Context Protocol（MCP）处理 Swagger/OpenAPI 规范的服务器。

功能

• 加载 Swagger/OpenAPI 规范
• 支持多种身份验证方法：
  • 基本认证
  • Bearer Token
  • API Key（头或查询）
  • OAuth2
• 自动生成MCP工具从API端点
• 对实时通信支持Server-Sent Events (SSE)
• 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}

测试

• 运行测试：

yarn test

• 按照环境运行测试：

yarn test:dev

• 按照覆盖运行测试：

yarn test:cov

认证方法

基本认证

配置示例：

{
  "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