Swagger MCP Server

Swagger MCP Server

通过 Model Context Protocol (MCP) 接收并提供 Swagger/OpenAPI 规范的服务。

功能

• 加载 Swagger/OpenAPI 规范
• 支持多种身份验证方式：
  • Basic Auth
  • Bearer Token
  • API Key（请求头或查询参数）
  • OAuth2
• 根据 API 端点自动生成 MCP 工具
• 支持使用 Server-Sent Events (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",  // 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 - 建立 Server-Sent Events 连接
• 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 文件中配置这些备用方式：

Basic Auth

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

Bearer Token

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

API Key

{
  "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 License 许可。

环境变量

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