关键词

OpenAPI 转换API 工具化LLM 后端服务JSON-RPC 网关能力暴露

项目简介

这是一个用于将现有的 OpenAPI 规范自动转换成 Model Context Protocol (MCP) 服务器实现的工具。通过该工具，您可以快速地将任何符合 OpenAPI 3.0 规范的 RESTful API 暴露为 MCP 工具，从而让支持 MCP 的大语言模型（LLM）客户端能够发现、理解并调用这些 API 能力。它充当了 MCP 客户端与您的后端 API 之间的桥梁。

主要功能点

  • 自动化转换： 自动解析 OpenAPI 3.0 规范文件，提取 API 定义信息。
  • MCP 工具生成： 将 OpenAPI 规范中的每个操作（Operation）自动映射并生成对应的 MCP 工具 (Tool) 定义，包括工具名称、描述和输入参数 schema。
  • 请求代理与转换： 接收 MCP 客户端发起的工具调用请求，将请求参数根据 OpenAPI 规范进行转换，然后代理调用实际的后端 API，并将 API 响应结果格式化为 MCP 响应返回给客户端。
  • 参数与安全处理： 支持处理 OpenAPI 定义的各种参数位置（路径、查询、头部、请求体）和常见的安全方案（如 API Key、Basic、Bearer Token）。
  • 多传输协议支持： 生成的 MCP 服务器实例可以方便地集成到支持 Stdio, SSE, Streamable HTTP 等多种 MCP 标准传输协议的环境中。

安装步骤

  1. 确保您已安装 Node.js (版本 18 或更高) 和 TypeScript (版本 5.x 或更高)。

  2. 创建一个新的 Node.js 项目或进入您现有的项目目录。

  3. 使用 npm 安装该库：

    npm install @serverless-devs/openapi-mcp-converter @modelcontextprotocol/sdk

    （注意：'@modelcontextprotocol/sdk' 是 MCP 标准 SDK，项目依赖它来构建服务器。）

服务器配置

MCP 客户端需要知道如何启动并连接到 MCP 服务器。对于使用此转换器生成的服务器，客户端通常需要配置以下信息（以 JSON 格式表示）。请注意，您需要编写一个简短的 Node.js 脚本来使用该库并启动服务器，这里的 'command' 和 'args' 应指向您编写的脚本。

{
  "name": "github-mcp-server",
  "command": "node",
  "args": [
    "/path/to/your/server/entrypoint.js"
  ],
  "env": {
    // 如果您的后端 API 需要 API Key 或其他凭证，可以通过环境变量传递给您的脚本。
    // 您的脚本可以读取这些环境变量，并在创建 converter 实例时作为 options 传递。
    // 例如：
    // "MY_API_KEY": "your_secret_api_key",
    // "ANOTHER_CREDENTIAL": "another_value"
  },
  "options": {
    // 这里的 options 是给 MCP 客户端展示的额外信息，不是服务器启动参数。
    // 例如，可以添加服务器的功能描述。
    "description": "此服务通过转换 OpenAPI 规范提供了后端 API 能力作为 MCP 工具。"
  }
}
  • 'name': 服务器的标识名称，此处为 'github-mcp-server' (由库内部定义)。
  • 'command': 启动服务器进程的命令，通常是 'node'。
  • 'args': 传递给 command 的参数，指向您编写的启动服务器的 Node.js 脚本文件路径。您需要根据自己的项目结构替换 '/path/to/your/server/entrypoint.js' 为实际路径。
  • 'env': (可选) 需要传递给服务器进程的环境变量，常用于敏感信息如 API Keys。
  • 'options': (可选) 提供给 MCP 客户端的额外信息。

您需要编写类似如下内容的 'entrypoint.js' 脚本：

// 假设您已将 TypeScript 脚本编译到 dist 目录
import fs from 'fs';
import path from 'path';
import { OpenApiMCPSeverConverter } from '@serverless-devs/openapi-mcp-converter';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; // 选择合适的传输协议
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 加载您的 OpenAPI 规范文件
const openApiDoc = JSON.parse(fs.readFileSync(path.join(__dirname, 'your_openapi_spec.json'), 'utf8'));

// 根据需要配置 options，例如设置超时或从环境变量获取安全凭证
const options = {
  timeout: 60000, // 设置请求后端 API 的超时时间
  security: {
    // 从环境变量中获取 API Key 等信息
    // apiKey: process.env.MY_API_KEY
  }
};

// 创建转换器实例并获取 MCP 服务器对象
const converter = new OpenApiMCPSeverConverter(openApiDoc, options);
const server = converter.getServer();

// 选择并连接传输协议（例如 Stdio，适合由客户端进程启动）
async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running on stdio"); // 使用 stderr 输出非协议信息
}

runServer().catch((error) => {
  console.error("Fatal error in server:", error);
  process.exit(1);
});

将此脚本保存为 'entrypoint.js'（或您喜欢的名称），并将 'your_openapi_spec.json' 替换为您实际的 OpenAPI 规范文件路径。然后根据脚本的实际路径更新 MCP 客户端配置中的 'args'。

基本使用方法

  1. 准备 OpenAPI 规范： 拥有一个描述您的后端 API 的 OpenAPI 3.0 规范文件 ('.json' 或 '.yaml' 格式，需要在脚本中加载)。
  2. 编写启动脚本： 编写一个 Node.js 脚本，使用 'OpenApiMCPSeverConverter' 加载您的 OpenAPI 规范，并创建一个 MCP 'Server' 实例，然后选择并连接一个 MCP 传输协议（如 'StdioServerTransport'）。
  3. 配置 MCP 客户端： 在您的 MCP 客户端（如支持 MCP 的 LLM 应用）中，按照上文“服务器配置”章节提供的 JSON 格式，配置指向您编写的启动脚本的 'command' 和 'args'。同时，如果需要，配置 'env' 来传递凭证。
  4. 运行客户端： 启动 MCP 客户端。客户端会根据配置自动启动（如果使用 Stdio 等协议）或连接到（如果服务器已独立启动）您的 MCP 服务器进程。
  5. LLM 交互： LLM 客户端随后可以通过 'list_tools' 请求发现由您的 OpenAPI 规范转换而来的工具列表，并通过 'call_tool' 请求调用这些工具，从而与您的后端 API 进行交互。

信息

分类

AI与计算

访问项目