Swagger MCP 服务器

通过模型上下文协议 (MCP) 提取并提供 Swagger/OpenAPI 规范的服务器。

特征

• 加载 Swagger/OpenAPI 规范

• 支持多种认证方式：

  • 基本身份验证

  • 持有者令牌

  • API 密钥（标头或查询）

  • OAuth2

• 从 API 端点自动生成 MCP 工具

• 服务器发送事件 (SSE) 支持实时通信

• TypeScript 支持

Related MCP server: OpenAPI to MCP Server

安全

这是个人服务器！请勿将其暴露在公共互联网上。如果底层 API 需要身份验证，则不应将 MCP 服务器暴露在公共互联网上。

待办事项

• secrets - MCP 服务器应该能够使用用户的 secrets 来验证 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",  // 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

2. 为生产而构建：

yarn build

3. 启动生产服务器：

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

持有者令牌

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