使用说明

项目简介

OpenAPI to MCP Server 生成器是一个命令行工具，它可以将现有的 OpenAPI (Swagger) 规范转换为 Model Context Protocol (MCP) 格式的服务器端实现。生成的 MCP 服务器可以方便地与 Claude Desktop 等 MCP 客户端集成，使得大型语言模型 (LLM) 能够安全、可扩展地访问和控制您的 API 资源与功能。

主要功能点

• 快速生成 MCP 服务器: 从 OpenAPI 规范一键生成可直接用于 Claude Desktop 的 MCP 服务器 TypeScript 代码。
• 自动化工具注册: 自动将 OpenAPI 中定义的 API 接口转换为 MCP 的工具 (Tools)，并注册到 MCP 服务器中。
• 状态管理: 自动提取 OpenAPI 中的状态Schema，并集成到 MCP 服务器，支持 LLM 获取当前系统状态。
• 多种输出格式: 除了 MCP 服务器代码，还支持生成 Prompt 指令、JSON Action 模板、LangChain 工具、OpenAI 插件清单等多种格式的文件，方便在不同场景下使用。
• 灵活定制: 支持生成独立的 Handler 文件，方便用户自定义业务逻辑，例如添加预处理、缓存或鉴权等。
• 模拟测试: 提供模拟模式，无需真实后端部署即可测试 AI Agent 与 API 的交互。

安装步骤

1. 确保已安装 Node.js 和 npm。

2. 全局安装 'openapi-to-mcp' 工具：

   npm install -g openapi-to-mcp
   

服务器配置

生成的 MCP 服务器文件为 'mcp-server.js' (或 'mcp-server.ts' 编译后的 js 文件)，需要配置 MCP 客户端（例如 Claude Desktop）连接到该服务器。以下是 Claude Desktop 的 MCP 工具配置示例 (JSON 格式)：

{
  "serverName": "Generated MCP Server",  // MCP 服务器名称，可自定义
  "command": "node",                     // 启动 MCP 服务器的命令，这里使用 node.js 运行环境
  "args": [                             // 启动命令的参数
    "mcp-server.js"                     // 指定要运行的 MCP 服务器 JavaScript 文件
  ]
}

注意: 请确保 'mcp-server.js' 文件与 Claude Desktop 启动命令的工作目录一致，或者在 'args' 中使用文件的绝对路径。

基本使用方法

1. 生成 MCP 服务器代码: 使用 'openapi-to-mcp' 命令行工具，指定 OpenAPI 规范文件路径，并使用 '--server' 参数生成 MCP 服务器代码。例如：

   openapi-to-mcp path/to/swagger.yaml --server --api-url https://your-api.com -o ./output-dir
   

   • 'path/to/swagger.yaml': 替换为您的 OpenAPI 规范文件路径。
   • '--server': 指定生成 MCP 服务器代码。
   • '--api-url https://your-api.com': 指定您的 API 基础 URL。
   • '-o ./output-dir': 可选参数，指定输出目录，默认为 './out'。

2. 安装依赖: 在输出目录 'output-dir' 中，安装 MCP 服务器依赖：

   cd output-dir
   npm install @modelcontextprotocol/sdk zod
   

   如果 'mcp-server.ts' 是 TypeScript 文件，还需要编译为 JavaScript:

   tsc mcp-server.ts --esModuleInterop --module nodenext
   

3. 注册 MCP 工具: 在 Claude Desktop 中，使用 'claude tools register' 命令注册生成的 MCP 服务器：

   claude tools register output-dir/mcp-server.js
   

4. 在 Claude 中使用: 在 Claude 中，您可以通过 '@工具名称' 的方式调用 API 功能，例如 '@Generated MCP Server listPets with status available'。

详细使用方法和更多功能，请参考仓库 README 文档和命令行帮助 'openapi-to-mcp --help'。