Openapi MCP Gateway

OpenAPI MCP网关

一个MCP（模型上下文协议）服务器，它动态地将OpenAPI端点作为大型语言模型的工具进行暴露。

特点/特性

• 🔄 自动获取并解析OpenAPI规范
• 🛠️ 从API端点动态生成MCP工具
• 🔐 支持多种认证方法：

- 基本身份验证（用户名/密码） - 不记名令牌（或称为“承载令牌”） - API密钥（自定义头部）

• 📝 保留端点描述和参数详情
• 🚀 支持OpenAPI 3.x和Swagger 2.x规范

安装

npm install
npm run build

配置

服务器通过环境变量进行配置：

所需的环境变量

• OPENAPI_SERVER_HOST - 您的API服务器的基本URL（例如。， https://api.example.com）

可选的环境变量

• OPENAPI_ROUTE - OpenAPI 规范的路径（默认： /docs.json)
• OPENAPI_USERNAME - 基本认证的用户名
• OPENAPI_PASSWORD - 基本认证的密码
• OPENAPI_BEARER_TOKEN - 用于授权头的承载令牌
• OPENAPI_API_KEY API密钥值
• OPENAPI_API_KEY_HEADER API密钥的头部名称（默认： X-API-Key)

用法

直接运行

export OPENAPI_SERVER_HOST="https://api.example.com"
export OPENAPI_ROUTE="/api/swagger.json"
export OPENAPI_BEARER_TOKEN="your-token-here"

npm start

与Claude Desktop一起使用

在您的Claude桌面配置文件中添加：

MacOS（中文可译为“麦奥斯”或直接使用原英文名，因“MacOS”通常不直接翻译，保持原样以体现品牌特性）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openapi-gateway": {
      "command": "node",
      "args": ["/path/to/openapi-mcp-gateway/build/index.js"],
      "env": {
        "OPENAPI_SERVER_HOST": "https://api.example.com",
        "OPENAPI_ROUTE": "/swagger.json",
        "OPENAPI_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

与Cline或其他MCP客户端一起使用

添加到你的MCP设置文件中（通常 .mcp/settings.json):

{
  "mcpServers": {
    "openapi-gateway": {
      "command": "node",
      "args": ["/path/to/openapi-mcp-gateway/build/index.js"],
      "env": {
        "OPENAPI_SERVER_HOST": "https://api.example.com",
        "OPENAPI_ROUTE": "/api/docs/swagger.json"
      }
    }
  }
}

认证示例

基本身份验证

{
  "env": {
    "OPENAPI_SERVER_HOST": "https://api.example.com",
    "OPENAPI_USERNAME": "admin",
    "OPENAPI_PASSWORD": "secret"
  }
}

Bearer Token（承载令牌/持有者令牌）

{
  "env": {
    "OPENAPI_SERVER_HOST": "https://api.example.com",
    "OPENAPI_BEARER_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

API 密钥

{
  "env": {
    "OPENAPI_SERVER_HOST": "https://api.example.com",
    "OPENAPI_API_KEY": "your-api-key",
    "OPENAPI_API_KEY_HEADER": "X-API-Key"
  }
}

它是如何运作的

1. 初始化服务器从环境变量中读取配置
2. “Spec Fetching”可以翻译为“规格获取”或“规范获取”，具体取决于上下文中的使用场景。如果是指从某个来源获取产品或服务的规格说明，那么“规格获取”更为贴切；如果是指获取某种技术或标准的规范文档，则“规范获取”可能更合适。但通常情况下，“规格获取”是一个较为通用的翻译在首次请求工具列表时，它会从配置的端点获取OpenAPI规范
3. 工具生成每个API端点都成为了一个MCP工具，具备：

- 操作ID或自动生成的名称 - 来自Swagger规范的描述 - 基于参数（路径、查询、头部、主体）的输入模式

1. 工具执行当调用一个工具时：

- 参数被提取并分类 - HTTP请求已构建，包含适当的头部、查询参数和请求体 - 响应包含状态、头部信息和数据

工具命名

工具的命名方式为 operationId 来自Swagger规范，或根据HTTP方法和路径自动生成。例如：

• getUserById - 来自 operationId
• get__api_users__id_ - 自动生成自 GET /api/users/{id}

参数处理

• 路径参数直接论点（例如。， id for /users/{id})
• 查询参数以……为前缀 query_ （例如。， query_limit， query_offset)
• 头部参数以……为前缀 header_ （例如。， header_X_Custom_Header)
• 请求体单身 body POST/PUT/PATCH 请求的参数

响应格式

所有响应均以JSON格式返回，包含：

• statusHTTP状态码
• statusTextHTTP状态文本
• headers响应头
• data响应体

错误响应包括：

• error错误信息
• status， statusText， data从错误响应（如果有的话）中

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

许可证

麻省理工学院（MIT）