Swagger MCP 服务器

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

特性

• 加载 Swagger/OpenAPI 规范
• 支持多种认证方法：
  • 基本认证
  • 承载令牌
  • 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

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 中指定则作为回退
    "defaultAuth": {  // 如果未在 Swagger 中指定则作为回退
      "type": "apiKey",
      "apiKey": "your-api-key",
      "apiKeyName": "api_key",
      "apiKeyIn": "header"
    }
  }
}

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

• 如果 Swagger 文件包含 servers 数组，则第一个服务器 URL 将用作基础 URL
• 如果 Swagger 文件定义了安全方案，则将用于认证
• 配置文件中的设置仅在 Swagger 文件中未指定时作为回退

使用

1. 启动开发服务器：

yarn dev

2. 构建生产环境：

yarn build

3. 启动生产服务器：

yarn start

API 端点

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

测试

运行测试套件：

# 运行一次测试
yarn test

# 在监视模式下运行测试
yarn test:watch

# 运行带有覆盖率报告的测试
yarn test:coverage

认证

服务器支持多种认证方法。在 config.json 文件中配置它们作为回退，当 Swagger 文件中未指定时使用：

基本认证

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

承载令牌

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