OpenAPI 到 MCP 服务器

一个工具，可以从 OpenAPI/Swagger 规范创建 MCP（模型上下文协议）服务器，使 AI 助手能够与您的 API 进行交互。创建您自己的品牌化和定制的 MCP，以适应特定的 API 或服务。

概述

该项目创建了一个动态的 MCP 服务器，将 OpenAPI 规范转换为 MCP 工具。它通过模型上下文协议实现了 REST API 与 AI 助手之间的无缝集成，使任何 API 都可以被 AI 访问。

特性

• 从文件或 HTTP/HTTPS URL 动态加载 OpenAPI 规范
• 支持从文件或 HTTP/HTTPS URL 加载 OpenAPI 覆盖层
• 可自定义的 OpenAPI 操作到 MCP 工具的映射
• 使用 glob 模式对操作 ID 和 URL 路径进行高级过滤
• 全面的参数处理，保留格式并提供位置元数据
• API 身份验证处理
• 使用 OpenAPI 元数据（标题、版本、描述）配置 MCP 服务器
• 分层描述回退（操作描述 → 操作摘要 → 路径摘要）
• 通过环境变量和 CLI 支持自定义 HTTP 头
• X-MCP 头用于 API 请求跟踪和识别
• 支持在路径级别使用自定义 x-mcp 扩展来覆盖工具名称和描述

与 AI 助手一起使用

该工具创建了一个 MCP 服务器，允许 AI 助手与由 OpenAPI 规范定义的 API 进行交互。主要使用方式是通过配置您的 AI 助手直接将其作为 MCP 工具运行。

在 Claude Desktop 中设置

1. 确保您的计算机上已安装 Node.js

2. 打开 Claude Desktop 并导航至 设置 > 开发者

3. 编辑配置文件（如果不存在则会创建）：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json

4. 添加以下配置（根据需要自定义）：

json
{
"mcpServers": {
"api-tools": {
"command": "npx",
"args": [
"-y",
"@tyk-technologies/api-to-mcp",
"--spec",
"https://petstore3.swagger.io/api/v3/openapi.json"
],
"enabled": true
}
}
}

1. 重启 Claude Desktop
2. 您现在应该可以在聊天输入框中看到一个锤子图标。点击它即可访问您的 API 工具。

自定义配置

您可以调整 args 数组来自定义您的 MCP 服务器的各种选项：

json
{
"mcpServers": {
"my-api": {
"command": "npx",
"args": [
"-y",
"@tyk-technologies/api-to-mcp",
"--spec",
"./path/to/your/openapi.json",
"--overlays",
"./path/to/overlay.json,https://example.com/api/overlay.json",
"--whitelist",
"getPet*,POST:/users/*",
"--targetUrl",
"https://api.example.com"
],
"enabled": true
}
}
}

在 Cursor 中设置

1. 在以下位置之一创建配置文件：

   • 项目特定：项目目录中的 .cursor/mcp.json
   • 全局：主目录中的 ~/.cursor/mcp.json

2. 添加以下配置（根据您的 API 进行调整）：

json
{
"servers": [
{
"command": "npx",
"args": [
"-y",
"@tyk-technologies/api-to-mcp",
"--spec",
"./path/to/your/openapi.json"
],
"name": "My API Tools"
}
]
}

1. 重启 Cursor 或重新加载窗口

与 Vercel AI SDK 一起使用

您也可以直接在 JavaScript/TypeScript 应用程序中使用 Vercel AI SDK 的 MCP 客户端来使用此 MCP 服务器：

javascript
import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// 初始化 Google Generative AI 提供商
const google = createGoogleGenerativeAI({
apiKey: process.env.GOOGLE_API_KEY, // 在环境变量中设置您的 API 密钥
});
const model = google('gemini-2.0-flash');

// 创建带有 stdio 传输的 MCP 客户端
const mcpClient = await experimental_createMCPClient({
transport: {
type: 'stdio',
command: 'npx', // 运行 MCP 服务器的命令
args: ['-y', '@tyk-technologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI 规范
env: {
// 您可以在此处设置环境变量
// API_KEY: process.env.YOUR_API_KEY,
},
},
});

async function main() {
try {
// 从 MCP 服务器检索工具
const tools = await mcpClient.tools();

// 使用 AI SDK 和 MCP 工具生成文本
const { text } = await generateText({
  model,
  prompt: 'List all available pets in the pet store using the API.',
  tools, // 将 MCP 工具传递给模型
});

console.log('Generated text:', text);

} catch (error) {
console.error('Error:', error);
} finally {
// 始终关闭 MCP 客户端以释放资源
await mcpClient.close();
}
}

main();## 配置

配置可以通过环境变量、命令行选项或 JSON 配置文件进行管理：

命令行选项

bash

使用特定的 OpenAPI 规范文件启动

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json

应用覆盖到规范

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

仅包含特定操作（支持通配符模式）

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

指定目标 API URL

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

为所有 API 请求添加自定义头

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --headers= {"X-Api-Version":"1.0.0"}

禁用 X-MCP 头

@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

环境变量

你可以在 .env 文件中设置这些变量，或者直接在你的环境中设置：

• OPENAPI_SPEC_PATH: OpenAPI 规范文件路径
• OPENAPI_OVERLAY_PATHS: 逗号分隔的覆盖 JSON 文件路径
• TARGET_API_BASE_URL: API 调用的基础 URL（覆盖 OpenAPI 服务器）
• MCP_WHITELIST_OPERATIONS: 逗号分隔的操作 ID 或 URL 路径列表（支持通配符模式如 getPet* 或 GET:/pets/*）
• MCP_BLACKLIST_OPERATIONS: 逗号分隔的操作 ID 或 URL 路径列表（支持通配符模式，如果使用白名单则忽略）
• API_KEY: 目标 API 的 API 密钥（如果需要）
• SECURITY_SCHEME_NAME: 需要 API 密钥的安全方案名称
• SECURITY_CREDENTIALS: 包含多个安全方案凭据的 JSON 字符串
• CUSTOM_HEADERS: 包含要在所有 API 请求中包含的自定义头的 JSON 字符串
• HEADER_*: 任何以 HEADER_ 开头的环境变量都将作为自定义头添加（例如，HEADER_X_API_Version=1.0.0 添加头 X-API-Version: 1.0.0）
• DISABLE_X_MCP: 设置为 true 以禁用在所有 API 请求中添加 X-MCP: 1 头
• CONFIG_FILE: JSON 配置文件路径

JSON 配置

你也可以使用 JSON 配置文件而不是环境变量或命令行选项。MCP 服务器将按以下顺序查找配置文件：

1. 通过 --config 命令行选项指定的路径
2. 通过 CONFIG_FILE 环境变量指定的路径
3. 当前目录下的 config.json
4. 当前目录下的 openapi-mcp.json
5. 当前目录下的 .openapi-mcp.json

示例 JSON 配置文件：

json
{
"spec": "./path/to/openapi-spec.json",
"overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
"targetUrl": "https://api.example.com",
"whitelist": "getPets,createPet,/pets/",
"blacklist": "deletePet,/admin/",
"apiKey": "your-api-key",
"securitySchemeName": "ApiKeyAuth",
"securityCredentials": {
"ApiKeyAuth": "your-api-key",
"OAuth2": "your-oauth-token"
},
"headers": {
"X-Custom-Header": "custom-value",
"User-Agent": "OpenAPI-MCP-Client/1.0"
},
"disableXMcp": false
}

一个带有解释性注释的完整示例配置文件位于根目录下的 config.example.json。

配置优先级

配置设置按以下优先级顺序应用（从高到低）：

1. 命令行选项
2. 环境变量
3. JSON 配置文件

开发

安装

bash

克隆仓库

git clone
cd openapi-to-mcp-generator

安装依赖

npm install

构建项目

npm run build

本地测试

bash

启动 MCP 服务器

npm start

开发模式，带自动重载

npm run dev

自定义并发布你自己的版本您可以使用此仓库作为基础来创建自己的定制化 OpenAPI 到 MCP 服务器。本节将解释如何分叉仓库、根据您的特定 API 进行自定义，并将其发布为一个包。

分叉与自定义

1. 分叉仓库：
   在 GitHub 上分叉此仓库，以创建您自己的副本并进行自定义。

2. 添加您的 OpenAPI 规范：
   bash

   如果不存在，则创建 specs 目录

   mkdir -p specs

   添加您的 OpenAPI 规范

   cp path/to/your/openapi-spec.json specs/

   添加任何覆盖文件

   cp path/to/your/overlay.json specs/

3. 配置默认设置：
   创建一个自定义配置文件，该文件将与您的包一起打包：
   bash

   复制示例配置

   cp config.example.json config.json

   编辑配置以指向您的捆绑规范

   并设置任何默认设置

4. 更新 package.json：
   json
   {
   "name": "your-custom-mcp-server",
   "version": "1.0.0",
   "description": "针对特定 API 的定制化 MCP 服务器",
   "files": [
   "dist//*",
   "config.json",
   "specs//*",
   "README.md"
   ]
   }

5. 确保规范被打包：
   package.json 中的 files 字段（如上所示）确保您的规范和配置文件将被包含在发布的包中。

自定义 GitHub 工作流

仓库包含一个用于自动发布到 npm 的 GitHub Actions 工作流。要为您的分叉仓库自定义它：

1. 更新工作流名称：
   编辑 .github/workflows/publish-npm.yaml 以按需更新名称：
   yaml
   name: 发布我的自定义 MCP 包

2. 设置包范围（如果需要）：
   如果您希望在 npm 组织范围内发布，请取消注释并在工作流文件中修改 scope 行：
   yaml

   • name: 设置 Node.js
     uses: actions/setup-node@v4
     with:
     node-version: "18"
     registry-url: "https://registry.npmjs.org/"

     取消注释并用您的组织范围更新：

     scope: "@your-org"

3. 设置 npm 令牌：
   在您的分叉仓库设置中，将您的 npm 令牌作为名为 NPM_TOKEN 的 GitHub 密钥添加。

发布您的定制化包

一旦您完成了仓库的自定义：

1. 创建并推送标签：
   bash

   更新 package.json 中的版本（可选，工作流会根据标签更新）

   npm version 1.0.0

   推送标签

   git push --tags

2. GitHub Actions 将会：

   • 自动构建包
   • 根据标签更新 package.json 中的版本
   • 使用您的捆绑规范和配置发布到 npm

发布后的使用

您的定制化包的用户可以通过 npm 安装和使用它：

bash

安装您的定制化包

npm install your-custom-mcp-server -g

运行它

your-custom-mcp-server

他们可以通过环境变量或命令行选项覆盖您的默认设置，具体方法请参阅配置部分。

许可证

MIT