使用说明

项目简介

ReAPI OpenAPI MCP 服务器是一个基于 Model Context Protocol (MCP) 的后端服务，旨在弥合 OpenAPI 规范与 LLM 驱动的集成开发环境 (IDE) 之间的鸿沟。它允许开发者将 OpenAPI 规范加载到服务器中，并通过 MCP 协议向 LLM 客户端（如 Cursor 编辑器）提供 API 的上下文信息，从而使 LLM 能够更好地理解和操作 API，提升开发效率。

主要功能点

加载多个 OpenAPI 规范: 从指定目录加载多个 OpenAPI 3.x 规范文件（JSON 或 YAML 格式）。
MCP 协议支持: 通过 MCP 协议标准化的暴露 API 操作和数据模型。
IDE 集成: 使 LLM 驱动的 IDE (如 Cursor) 能够直接理解和使用您的 API。
完整的 API 上下文: 支持已解除引用的 Schema，提供完整的 API 上下文信息。
API 目录管理: 维护所有可用 API 的目录，方便 LLM 客户端检索和使用。

安装步骤

安装 Node.js: 确保您的系统中已安装 Node.js (>= 16)。

全局安装 npm 包: 打开终端，运行以下命令全局安装 '@reapi/mcp-openapi' 包：

npm install -g @reapi/mcp-openapi

服务器配置

MCP 服务器主要通过命令行参数进行配置。对于 MCP 客户端（例如 Cursor），您需要在客户端的 MCP 服务器配置中指定服务器的启动命令和参数。

以下是 Cursor IDE 客户端的 'mcp.json' 配置文件示例，用于配置 'ReAPI OpenAPI MCP 服务器'：

项目专属配置 (推荐): 在您的项目根目录下创建 '.cursor/mcp.json' 文件，并添加以下内容：

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi", "--dir", "./specs"],
      "env": {}
    }
  }
}

'"@reapi/mcp-openapi"': 服务器名称，在 Cursor 设置中启用时会用到。
'"command": "npx"': 指定启动服务器的命令为 'npx'。
'"args": ["-y", "@reapi/mcp-openapi", "--dir", "./specs"]': 配置服务器启动参数。
- '"-y"': 'npx' 参数，用于自动确认安装 '@reapi/mcp-openapi' 包（如果尚未安装）。
- '"@reapi/mcp-openapi"': 指定要执行的 npm 包为 '@reapi/mcp-openapi'，即 MCP 服务器程序。
- '"--dir", "./specs"': '@reapi/mcp-openapi' 服务器的参数，'--dir' 用于指定 OpenAPI 规范文件所在的目录为当前目录下的 'specs' 文件夹。您可以根据实际情况修改为您的 OpenAPI 规范文件目录。
'"env": {}': 环境变量配置，此处为空。

全局配置: 如果您希望在所有 Cursor 项目中使用该服务器，可以将配置添加到 '~/.cursor/mcp.json' 文件中，配置内容与项目专属配置类似，但需要修改 '--dir' 参数为您的全局 OpenAPI 规范文件目录。

基本使用方法

准备 OpenAPI 规范文件: 将您的 OpenAPI 3.x 规范文件（JSON 或 YAML 格式，扩展名为 '.json', '.yaml', 或 '.yml'）放置在您在 'mcp.json' 配置文件中 '--dir' 参数指定的目录下，例如 './specs' 目录。
在 Cursor 中启用 MCP 服务器:
- 打开 Cursor IDE。
- 进入 Settings (设置) -> Cursor Settings (Cursor 设置) -> MCP。
- 找到 '@reapi/mcp-openapi' 服务器，点击开关启用它。
- 点击服务器名称旁边的刷新图标以应用更改。

刷新 API 目录: 在 Cursor 的聊天面板中，输入以下提示语之一，即可刷新 API 目录：

"Please refresh the API catalog"
"Reload the OpenAPI specifications"

使用 API: 现在您可以在 Cursor 中使用提示词与 API 进行交互，例如：

"Show me all available APIs in the catalog with their operations"
"Show me the details of the create pet API endpoint"
"Generate mock data for the Pet schema"

更多示例提示词请参考仓库 README 文档的 "Example Prompts in Cursor" 章节。

关键词