内容
# 通用 OpenAPI MCP 服务器
一个强大的模型上下文协议（Model Context Protocol，MCP）服务器，能够与任何符合 OpenAPI 标准的 API 一起使用。该服务器允许您通过提供其 OpenAPI 规范，轻松连接和与任何 API 进行交互，支持多个 API 和各种认证方法。
## 目录
- [功能](#features)
- [安装](#installation)
- [快速开始](#quick-start)
- [与 Claude Desktop 的使用](#usage-with-claude-desktop)
- [配置](#configuration)
- [使用 .env（环境变量）](#using-env-environment-variables)
- [使用 YAML 配置](#using-yaml-configuration)
- [可用工具](#available-tools)
- [实际案例](#real-world-examples)
- [故障排除](#troubleshooting)
- [高级功能](#advanced-features)
- [开发](#development)
- [架构文档](#architecture-documentation)
- [贡献](#contributing)
- [许可证](#license)
## 特性
- **通用API支持**：与任何符合OpenAPI 3.x或Swagger 2.0的API兼容
- **多API管理**：配置并在多个API之间切换
- **自动验证**：使用@readme/openapi-parser验证OpenAPI规范
- **灵活的身份验证**：支持API Key、Bearer Token、Basic Auth、OAuth2和自定义身份验证
- **双重配置**：环境变量或YAML配置文件
- **结构化API发现**：返回按标签分组的有组织的JSON数据
- **增强的错误报告**：提供详细的错误信息和请求信息以便调试
- **环境变量替换**：在YAML文件中使用${VAR_NAME}
- **TypeScript支持**：完全使用TypeScript进行类型定义，以提升开发体验
- **FastMCP集成**：基于FastMCP构建，以优化模型上下文协议支持
## 安装
1. 克隆代码库：
```bash
git clone https://github.com/jonsoku-dev/universal-openapi-mcp.git
cd universal-openapi-mcp
```
2. 安装依赖：
```bash
npm install
```
3. 构建项目：
```bash
npm run build
```
## 快速开始
1. **复制示例环境文件：**
```bash
cp .env.example .env
```
2. **使用您的 API 详细信息编辑 `.env` 文件：**
```bash
```
# 最小配置
API_NAME=petstore
API_BASE_URL=https://petstore.swagger.io/v2
OPENAPI_SPEC_URL=https://petstore.swagger.io/v2/swagger.json
```
3. **运行服务器：**
```bash
npm run dev
```
4. **使用 FastMCP 测试：**
```bash
npx fastmcp dev src/index.ts
```
## 与 Claude Desktop 的使用
要将此服务器与 Claude Desktop 一起使用，您需要在 `claude_desktop_config.json` 文件中注册它。
1. 找到您的 `claude_desktop_config.json` 文件。文件位置因操作系统而异：
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`
* **Linux:** `~/.config/Claude/claude_desktop_config.json`
2. 打开文件并按如下方式添加或更新 `mcpServers` 部分：
```json
{
"mcpServers": {
"universal-openapi-mcp": {
"command": "npx",
"args": [
"universal-openapi-mcp"
],
"env": {
"OPENAPI_SPEC_URL": "YOUR_OPENAPI_SPEC_URL",
"API_BASE_URL": "YOUR_API_BASE_URL",
"API_NAME": "YOUR_API_NAME",
"API_TIMEOUT": "30000" // 可选
// 添加您 API 所需的其他环境变量
// （例如，AUTH_TYPE、API_KEY 等，详见 [Configuration](#configuration) 部分）。
}
}
// 您可以在此处添加其他 MCP 服务器
}
}
```
3. **重要：** 将 `YOUR_OPENAPI_SPEC_URL`、`YOUR_API_BASE_URL` 和 `YOUR_API_NAME` 替换为您要连接的 API 的实际值。您还可以通过在服务器的 `env` 块中设置适当的环境变量（例如，`AUTH_TYPE`、`API_KEY` 等，详见 [Configuration](#configuration) 部分）来配置身份验证。
4. 保存 `claude_desktop_config.json` 文件。Claude Desktop 应该会自动识别新的服务器配置。
## 配置
### 使用 .env（环境变量）
配置的最简单方法是使用 `.env` 文件。服务器支持对 API 连接的各个方面进行全面的环境变量配置。
#### 基本配置（必需）
```bash
# API 名称 - 您的 API 的唯一标识符
API_NAME=my-api
# API 基础 URL - 您的 API 的基础 URL
API_BASE_URL=https://api.example.com
# OpenAPI 规范 URL - 从哪里获取规范
# 可以是一个 URL 或本地文件路径
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
# 或者用于本地文件：
# OPENAPI_SPEC_URL=./specs/my-api.yaml
# 请求超时时间（毫秒）（可选，默认值：30000）
API_TIMEOUT=30000
```
#### 认证方法
服务器支持多种认证方法。选择一个与您的 API 匹配的方法：
**1. API 密钥认证：**
```bash
AUTH_TYPE=apiKey
API_KEY=your-api-key-here
API_KEY_LOCATION=header # 或 'query'
API_KEY_NAME=X-API-Key # 头部/查询参数的名称
```
# 常见的 API 密钥头部名称：
# - X-API-Key: 通用API
# - 授权：某些服务使用 "Authorization: API-Key YOUR_KEY"
# - X-RapidAPI-Key: RapidAPI 服务
# - api-key: Azure 服务
# - X-Auth-Token: 一些REST API
# - access_token: 当作为查询参数传递时
```
**2. Bearer Token 认证：**
```bash
AUTH_TYPE=bearer
```
# 您可以使用 AUTH_TOKEN 或 BEARER_TOKEN
BEARER_TOKEN=your-bearer-token-here
# 令牌将作为 "Authorization: Bearer TOKEN" 发送
```
**3. 基本认证：**
```bash
AUTH_TYPE=basic
AUTH_USERNAME=your-username
AUTH_PASSWORD=your-password
```
**4. OAuth2 认证：**
```bash
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_TOKEN_URL=https://api.example.com/oauth/token
OAUTH2_SCOPE=read write # 空格分隔的权限范围
OAUTH2_GRANT_TYPE=client_credentials # 通常为 'client_credentials' 用于服务器到服务器
```
#### 自定义头部
通过在前面添加 `HEADER_` 来添加任何自定义头部。前缀将被移除，下划线将被转换为连字符：
```bash
```
# 头部转换示例：
# HEADER_USER_AGENT → 用户代理 (User-Agent)
# HEADER_X_CUSTOM_ID → X-Custom-Id
# HEADER_CONTENT_TYPE → Content-Type
HEADER_USER_AGENT=MyApp/1.0
HEADER_ACCEPT=application/json
HEADER_X_REQUEST_ID=req_123456
HEADER_X_CLIENT_VERSION=2.0
HEADER_X_TENANT_ID=tenant_abc
### 使用 YAML 配置
对于更复杂的设置或多个 API，请使用 YAML 配置。这在以下情况下特别有用：
- 需要配置多个 API
- 希望对配置进行版本控制
- 具有复杂的身份验证设置
- 需要使用环境变量替换
#### 创建 config.yaml:
```yaml
apis:
# GitHub API 示例
github:
name: github
baseUrl: https://api.github.com
openApiSpecUrl: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
authentication:
type: bearer
config:
token: ${GITHUB_TOKEN} # 使用环境变量
defaultHeaders:
User-Agent: Universal-OpenAPI-MCP/1.0
Accept: application/vnd.github.v3+json
timeout: 30000
# PetStore 示例（用于测试）
petstore:
name: petstore
baseUrl: https://petstore.swagger.io/v2
openApiSpecUrl: https://petstore.swagger.io/v2/swagger.json
timeout: 15000
# 带 API 密钥的自定义 API
myapi:
name: myapi
baseUrl: ${MY_API_URL} # 可以在任何地方使用环境变量
openApiSpecUrl: ${MY_API_URL}/openapi.json
authentication:
type: apiKey
config:
apiKey: ${MY_API_KEY}
location: header
keyName: X-API-Key
defaultHeaders:
Content-Type: application/json
timeout: 60000
# OAuth2 API 示例
oauth_api:
name: oauth_api
baseUrl: https://oauth-api.example.com
openApiSpecUrl: https://oauth-api.example.com/openapi.json
authentication:
type: oauth2
config:
clientId: ${OAUTH2_CLIENT_ID}
clientSecret: ${OAUTH2_CLIENT_SECRET}
tokenUrl: https://oauth-api.example.com/oauth/token
scope: read write
grantType: client_credentials
timeout: 30000
```
# 设置默认 API（可选）
defaultApi: github
```
#### 使用YAML配置：
```bash
```
# 选项 1：使用 CONFIG_FILE 环境变量
CONFIG_FILE=./config.yaml npm run dev
# 选项 2：使用 MCP_CONFIG_FILE 环境变量
MCP_CONFIG_FILE=./my-config.yaml npm run dev
# 选项 3：在 .env 文件中设置
echo "CONFIG_FILE=./config.yaml" >> .env
npm run dev
```
### 配置优先级
1. 如果设置了 `CONFIG_FILE` 或 `MCP_CONFIG_FILE`，则首先尝试加载 YAML
2. 如果 YAML 加载失败，则回退到环境变量
3. 如果没有使用 `API_NAME` 指定 API，则使用 YAML 中的 `defaultApi`
4. 当两者都存在时，YAML 配置优先于环境变量
## 可用工具
服务器提供了四个主要工具用于与API进行交互：
### 1. `api_request`
向配置的API发送HTTP请求，并提供详细的错误报告。
**参数：**
- `path`: API端点路径（例如，'/users' 或 '/pet/123'）
- `method`: HTTP方法（默认值：'get'）
- `data`: POST/PUT/PATCH请求的请求体
- `params`: 查询参数
- `headers`: 额外的头部信息
**示例：**
```json
{
"path": "/pet/123",
"method": "get"
}
```
**错误响应包括：**
- 完整的请求URL
- 使用的HTTP方法
- 发送的头部信息（敏感数据已被隐藏）
- 查询参数
- 请求体
- 状态码和错误信息
### 2. `api_paths_list`
返回一个结构化的 JSON 对象，包含按标签组织的所有 API 端点。
**响应格式：**
```json
{
"summary": {
"totalEndpoints": 20,
"tags": ["pet", "store", "user"]
},
"endpoints": {
"pet": [
{
"path": "/pet",
"method": "POST",
"operationId": "addPet",
"summary": "向商店添加一只新宠物",
"parameters": [],
"requestBody": {
"required": true,
"contentTypes": ["application/json", "application/xml"]
}
}
]
}
}
```
### 3. `api_paths_info`
获取特定路径的详细 OpenAPI 规范。
**参数：**
- `path_templates`: 路径模板数组（例如，["/pet", "/pet/{petId}"]）
### 4. `api_spec_info`
获取关于API的OpenAPI规范的一般信息。
**参数：**
- `include`: 要包含的信息类型数组
- `info`: API标题、版本、描述
- `servers`: 可用的服务器URL
- `tags`: 标签描述
- `paths_summary`: 所有路径及其操作的摘要
## 真实世界的示例
### 示例 1：GitHub API 设置
**.env 文件：**
```bash
API_NAME=github
API_BASE_URL=https://api.github.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
AUTH_TYPE=bearer
BEARER_TOKEN=ghp_your_github_personal_access_token_here
HEADER_ACCEPT=application/vnd.github.v3+json
HEADER_X_GITHUB_API_VERSION=2022-11-28
```
### 示例 2：Stripe API 设置
**.env 文件：**
```bash
API_NAME=stripe
API_BASE_URL=https://api.stripe.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
AUTH_TYPE=bearer
BEARER_TOKEN=sk_test_your_stripe_secret_key_here
HEADER_STRIPE_VERSION=2023-10-16
```
### 示例 3：OpenAI API 设置
**.env 文件：**
```bash
API_NAME=openai
API_BASE_URL=https://api.openai.com
OPENAPI_SPEC_URL=https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml
AUTH_TYPE=bearer
BEARER_TOKEN=sk-your-openai-api-key-here
HEADER_OPENAI_BETA=assistants=v2
```
### 示例 4：自定义内部 API
**config.yaml:**
```yaml
apis:
internal:
name: internal-api
baseUrl: https://api.internal.company.com
openApiSpecPath: ./specs/internal-api.yaml # 本地文件
authentication:
type: apiKey
config:
apiKey: ${INTERNAL_API_KEY}
location: header
keyName: X-Company-API-Key
defaultHeaders:
X-Request-ID: ${REQUEST_ID}
X-Client-Version: "2.0"
X-Tenant-ID: tenant_123
timeout: 45000
defaultApi: internal
```
## 故障排除
### 常见问题及解决方案
1. **“未提供 OpenAPI 规范 URL 或路径”**
- 确保在 .env 或 config.yaml 中设置了 `OPENAPI_SPEC_URL`
- 检查该 URL 是否可访问并返回有效的 OpenAPI/Swagger 规范
- 尝试在浏览器中打开该 URL 以进行验证
2. **请求时出现 404 错误**
- 验证 `API_BASE_URL` 是否包含完整的基础路径（例如，PetStore 的 `/v2`）
- 使用 `api_paths_list` 检查您请求的路径是否存在
- 确保路径中没有双斜杠（例如，避免使用 `//pet`）
3. **身份验证错误**
- 仔细检查您的 API 密钥/令牌是否正确且未过期
- 验证您是否使用了正确的 `AUTH_TYPE` 进行 API 访问
- 检查身份验证类型是否符合 API 要求
- 某些 API 需要特定的头部名称（请查看 API 文档）
- 对于 OAuth2，确保所有必填字段均已设置
4. **“加载配置失败”**
- 检查 YAML 语法是否有效（使用 YAML 验证器）
- 确保所有用 ${} 引用的环境变量都存在
- 如果使用 CONFIG_FILE，验证文件路径是否正确
5. **超时错误**
- 增加 `API_TIMEOUT` 值（默认值为 30000ms）
- 检查网络连接
- 某些 API 具有响应较慢的端点，需要更长的超时时间
### 调试模式
要查看详细的日志和调试信息：
```bash
```
# MCP 服务器记录请求和错误的详细信息
```bash
npm run dev
```
检查错误信息 - 它们包括：
- 被请求的确切 URL
- 发送的头部（敏感数据已被隐藏）
- 查询参数
- 请求体（对于 POST/PUT/PATCH）
- 完整的错误堆栈跟踪
## 高级功能
### 使用本地 OpenAPI 规范
您可以使用本地文件，而不是 URL：
```yaml
apis:
local:
name: local-api
baseUrl: http://localhost:3000
openApiSpecPath: ./specs/my-api.yaml # 本地文件路径
```
### 动态头部
使用环境变量来设置动态头部：
```bash
```
# 在 .env 文件中
REQUEST_ID=req_${RANDOM_ID}
SESSION_TOKEN=${DYNAMIC_TOKEN}
# 这些成为头部
HEADER_X_REQUEST_ID=${REQUEST_ID}
HEADER_AUTHORIZATION=Session ${SESSION_TOKEN}
```
### 多种认证方法
某些 API 支持多种认证方法。请配置您偏好的方法：
```yaml
# OAuth2用于写操作
authentication:
type: oauth2
config:
clientId: ${CLIENT_ID}
clientSecret: ${CLIENT_SECRET}
tokenUrl: https://api.example.com/oauth/token
scope: read write
# 或使用 API 密钥进行只读访问
# 认证:
# 类型: apiKey
# 配置:
# apiKey: ${READ_ONLY_KEY}
# location: header
# keyName: X-API-Key
```
### YAML中的环境变量替换
YAML加载器支持使用`${VAR_NAME}`语法进行环境变量替换：
```yaml
apis:
myapi:
baseUrl: ${API_BASE_URL}
authentication:
type: bearer
config:
token: ${API_TOKEN}
defaultHeaders:
X-Environment: ${ENVIRONMENT:-development} # 带默认值
```
## 开发
### 项目结构
```
src/
├── index.ts # 主 MCP 服务器
├── types.ts # TypeScript 类型定义
├── auth.ts # 认证处理程序
├── client.ts # 带错误处理的 HTTP 客户端
├── spec-utils.ts # OpenAPI 规范工具
├── validation-error.ts # 自定义错误类
└── config-loader.ts # 配置加载逻辑
```
### 可用脚本
```bash
```
# 开发模式与热重载
npm run dev
# 将 TypeScript 构建为 JavaScript
npm run build
# 运行构建版本
npm start
# 使用 FastMCP 进行测试
npm test
# 检查 MCP 功能
npm run inspect
# 清理构建目录
npm run clean
```
### 从源代码构建
```bash
```
# 安装依赖
npm install
# 以开发模式运行（带热重载）
npm run dev
# 生产环境构建
npm run build
# 运行测试
npm test
```
## 架构文档
有关服务器架构的详细说明，请参阅 [ARCHITECTURE.md](ARCHITECTURE.md) 文件。
## 贡献
1. Fork 该仓库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 进行更改
4. 如果适用，添加测试
5. 提交更改 (`git commit -m 'Add some amazing feature'`)
6. 推送到分支 (`git push origin feature/amazing-feature`)
7. 打开一个 Pull Request
## 许可证
MIT 许可证 - 详细信息请参见 LICENSE 文件
## 更新日志
### 版本 1.0.0
- 使用 @readme/openapi-parser 完成重写，以实现更好的验证
- 支持 Swagger 2.0 和 OpenAPI 3.x 规范
- 增强的错误信息，包含详细的请求信息
- 为 api_paths_list 工具提供结构化的 JSON 响应
- 改进了不同 API 结构的 URL 处理
- 在各处提供更好的 TypeScript 类型
- 全面的环境变量支持
- 支持带环境变量替换的 YAML 配置
- 多种认证方法（API Key、Bearer、Basic、OAuth2）
- 自定义头部支持
- FastMCP 集成以实现最佳的 MCP 支持
MCP 市场
