MCP 服务器

Swagger MCP Server

一个服务器，它可以通过模型上下文协议（MCP）与任何具有 Swagger/OpenAPI 规范的 API 进行交互，自动从 API 端点生成工具，并支持多种身份验证方法。

README

Swagger MCP 服务器

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

特性

加载 Swagger/OpenAPI 规范
支持多种身份验证方法：
- Basic Auth (基本认证)
- Bearer Token (Bearer 令牌)
- API Key (API 密钥) (header 或 query)
- OAuth2
从 API 端点自动生成 MCP 工具
Server-Sent Events (SSE) (服务器发送事件) 支持实时通信
TypeScript 支持

安全

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

TODO

secrets (密钥) - MCP 服务器应该能够使用来自用户的密钥来验证对 API 的请求
Comprehensive test suite (全面的测试套件)

前提条件

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

安装

克隆存储库：

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

安装依赖项：

yarn install

基于示例创建一个 .env 文件：

cp .env.example .env

配置您的 Swagger/OpenAPI 规范：
- 将您的 Swagger 文件放置在项目中（例如，swagger.json）
- 或者提供指向您的 Swagger 规范的 URL
使用您的服务器设置更新 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 文件中未指定时，配置文件设置用作回退

用法

启动开发服务器：

yarn dev

构建用于生产环境：

yarn build

启动生产服务器：

yarn start

API 端点

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

测试

运行测试套件：

# 运行测试一次
yarn test

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

# 运行测试并生成覆盖率报告
yarn test:coverage

身份验证

服务器支持各种身份验证方法。在 config.json 文件中配置它们，作为 Swagger 文件中未指定时的回退：

Basic Auth (基本认证)

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

Bearer Token (Bearer 令牌)

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

API Key (API 密钥)

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

OAuth2

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

开发

启动开发服务器：

yarn dev

<!-- 2. 对代码进行更改

运行测试以确保一切正常：

yarn test

构建项目：

yarn build
``` -->

<!-- ## 贡献

1. Fork 存储库
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开一个 Pull Request -->

## 许可证

此项目已获得 Apache 2.0 许可证的许可。

## 环境变量

- `PORT`: 服务器端口（默认：3000）
- `API_USERNAME`: API 身份验证的用户名（回退）
- `API_PASSWORD`: API 身份验证的密码（回退）
- `API_TOKEN`: API 身份验证的 API 令牌（回退）
- `DEFAULT_API_BASE_URL`: API 端点的默认基本 URL（回退）
- `DEFAULT_SWAGGER_URL`: 默认 Swagger 规范 URL