Swagger MCP 服务器

一个通过模型上下文协议（MCP）摄取和提供Swagger/OpenAPI规范的服务器。

特性

• 加载 Swagger/OpenAPI 规范
• 支持多种认证方法：
  • 基本认证
  • Bearer Token
  • API 密钥（头部或查询）
  • OAuth2
• 自动从 API 端点生成 MCP 工具
• 支持服务器发送事件 (SSE) 实现实时通信
• TypeScript 支持

安全

这是一个个人服务器！！不要将其暴露在公共互联网上。
如果底层 API 需要认证，你不应该将 MCP 服务器暴露在公共互联网上。

待办事项

• 秘钥 - MCP 服务器应该能够使用用户的秘钥来认证对 API 的请求
• 全面的测试套件

先决条件

• Node.js (v18 或更高版本)
• Yarn 包管理器
• TypeScript

安装

1. 克隆仓库：

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

1. 安装依赖项：

yarn install

1. 根据示例创建一个 .env 文件：

cp .env.example .env

1. 配置你的 Swagger/OpenAPI 规范：

   • 将你的 Swagger 文件放在项目中（例如 swagger.json）
   • 或者提供一个指向你的 Swagger 规范的 URL

2. 在 config.json 中更新服务器设置：

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // Fallback if not specified in Swagger
    "defaultAuth": {  // Fallback if not specified in Swagger
      "type": "apiKey",
      "apiKey": "your-api-key",
      "apiKeyName": "api_key",
      "apiKeyIn": "header"
    }
  }
}

注意：服务器优先使用 Swagger 规范中的设置而非配置文件中的设置：

• 如果 Swagger 文件包含 servers 数组，则会使用第一个服务器 URL 作为基础 URL
• 如果 Swagger 文件定义了安全方案，它们将用于认证
• 当 Swagger 文件中未指定时，配置文件中的设置作为后备选项

使用

1. 启动开发服务器：

yarn dev

1. 构建生产环境：

yarn build

1. 启动生产服务器：

yarn start

API 端点

• GET /health - 检查服务器健康状态
• GET /sse - 建立服务器发送事件连接
• POST /messages - 向 MCP 服务器发送消息

测试

运行测试套件：

# Run tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

认证

服务器支持各种认证方法。当 Swagger 文件中未指定时，在 config.json 文件中配置这些方法作为后备选项：

基本认证

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

Bearer Token

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

API 密钥

{
  "defaultAuth": {
    "type": "apiKey",
    "apiKey": "your-api-key",
    "apiKeyName": "X-API-Key",
    "apiKeyIn": "header"
  }
}

OAuth2

{
  "defaultAuth": {
    "type": "oauth2",
    "token": "your-oauth-token"
  }
}

开发

1. 启动开发服务器：

yarn dev

许可证

此项目根据 Apache 2.0 许可证许可。

环境变量

• PORT: 服务器端口（默认：3000）
• API_USERNAME: API认证用户名（备选）
• API_PASSWORD: API认证密码（备选）
• API_TOKEN: API认证令牌（备选）
• DEFAULT_API_BASE_URL: API端点的默认基础URL（备选）
• DEFAULT_SWAGGER_URL: 默认的Swagger规范URL