OpenAPI 到 MCP 服务器

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

概述

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

特性

• 从文件或 HTTP/HTTPS URL 动态加载 OpenAPI 规范
• 支持从文件或 HTTP/HTTPS URL 加载的 OpenAPI 叠加层
• 自定义映射 OpenAPI 操作到 MCP 工具
• 使用通配符模式对操作 ID 和 URL 路径进行高级过滤
• 完整的参数处理，保留格式和位置元数据
• API 认证处理
• 使用 OpenAPI 元数据（标题、版本、描述）配置 MCP 服务器
• 层次描述回退（操作描述 → 操作摘要 → 路径摘要）
• 通过环境变量和命令行支持自定义 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%\Claude\claude_desktop_config.json

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

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

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

自定义配置

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

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--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 需要进行调整）：

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

3. 重新启动 Cursor 或重新加载窗口

与 Vercel AI SDK 一起使用

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

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

// 初始化 Google 生成式 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: '使用 API 列出宠物店中的所有可用宠物。',
      tools, // 将 MCP 工具传递给模型
    });

    console.log('生成的文本:', text);
  } catch (error) {
    console.error('错误:', error);
  } finally {
    // 总是要关闭 MCP 客户端以释放资源
    await mcpClient.close();
  }
}

main();

配置

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

命令行选项

# 使用特定的 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 配置文件：

{
  "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 配置文件

开发

安装

# 克隆仓库
git clone <repository-url>
cd openapi-to-mcp-generator

# 安装依赖
npm install

# 构建项目
npm run build

本地测试

# 启动 MCP 服务器
npm start

# 开发模式，自动重载
npm run dev

创建并发布您自己的版本

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

分叉和定制

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

2. 添加您的 OpenAPI 规范：

   # 如果不存在，则创建 specs 目录
   mkdir -p specs
   
   # 添加您的 OpenAPI 规范
   cp path/to/your/openapi-spec.json specs/
   
   # 添加任何叠加文件
   cp path/to/your/overlay.json specs/
   

3. 配置默认设置： 创建一个将与您的包捆绑在一起的自定义配置文件：

   # 复制示例配置
   cp config.example.json config.json
   
   # 编辑配置以指向您的捆绑规范
   # 并设置任何默认设置
   

4. 更新 package.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 工作流

该仓库包括一个 GitHub Actions 工作流，用于自动发布到 npm。为了定制您的分叉仓库：

1. 更新工作流名称： 编辑 .github/workflows/publish-npm.yaml，如果需要，更新名称：

   name: 发布我的定制 MCP 包
   

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

   - 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. 创建并推送标签：

   # 更新 package.json 中的版本（可选，工作流将基于标签更新它）
   npm version 1.0.0
   
   # 推送标签
   git push --tags
   

2. GitHub Actions 将：

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

发布后使用

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

# 安装您的定制化包
npm install your-custom-mcp-server -g

# 运行它
your-custom-mcp-server

他们可以通过环境变量或命令行选项覆盖您的默认设置，如配置部分所述。

许可证

MIT