@reapi/mcp-openapi

一个模型上下文协议 (MCP) 服务器，用于加载和提供多个 OpenAPI 规范，以支持 LLM 驱动的 IDE 集成。此服务器充当您的 OpenAPI 规范与 LLM 驱动的开发工具（如 Cursor 和其他代码编辑器）之间的桥梁。

特性

• 从目录加载多个 OpenAPI 规范
• 通过 MCP 协议公开 API 操作和模式
• 使 LLM 能够直接在您的 IDE 中理解和使用您的 API
• 支持取消引用的模式以获得完整的 API 上下文
• 维护所有可用 API 的目录

由 ReAPI 提供支持

此开源 MCP 服务器由 ReAPI 赞助，ReAPI 是一个下一代 API 平台，可简化 API 设计和测试。虽然此服务器为开发提供本地 OpenAPI 集成，但 ReAPI 提供两个强大的模块：

🎨 API CMS

• 使用直观的无代码编辑器设计 API
• 自动生成和发布 OpenAPI 规范
• 与团队成员实时协作
• 版本控制和变更管理

🧪 API 测试

• 最适合开发人员的无代码 API 测试解决方案
• 使用直观的界面创建和管理测试用例
• 强大的断言和验证功能
• 无服务器云测试执行器
• 非常适合 QA 团队和开发人员
• 随时可以进行 CI/CD 集成

在 reapi.com 免费试用 ReAPI，体验 API 开发的未来。

Cursor 配置

要将 MCP OpenAPI 服务器与 Cursor IDE 集成，您有两种配置位置选择：

选项 1：项目特定配置（推荐）

在您的项目目录中创建一个 .cursor/mcp.json 文件。 建议使用此选项，因为它允许您为不同的项目维护不同的规范集。

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

提示: 使用像 ./specs 这样的相对路径使配置可移植，并且更易于在团队成员之间共享。

注意: 我们建议使用 @latest 标签，因为我们会经常更新服务器，添加新功能和改进。

重要: 项目特定的配置有助于管理 LLM 上下文限制。 当所有规范都放在一个文件夹中时，组合的元数据可能会超过 LLM 的上下文窗口，从而导致错误。 按项目组织规范可以使上下文大小易于管理。

选项 2：全局配置

在您的主目录中创建或编辑 ~/.cursor/mcp.json，以使服务器在所有项目中可用：

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

在 Cursor 设置中启用

添加配置后：

1. 打开 Cursor IDE
2. 转到 Settings > Cursor Settings > MCP
3. 启用 @reapi/mcp-openapi 服务器
4. 单击服务器旁边的刷新图标以应用更改

注意: 默认情况下，Cursor 需要确认每次 MCP 工具的执行。 如果您想允许自动执行而无需确认，则可以在 Cursor 设置中启用 Yolo 模式。

服务器现在可以使用了。 当您向目录中添加新的 OpenAPI 规范时，可以通过以下方式刷新目录：

1. 打开 Cursor 的聊天面板
2. 键入以下提示之一：

   "请刷新 API 目录"
   "重新加载 OpenAPI 规范"
   

OpenAPI 规范要求

1. 将您的 OpenAPI 3.x 规范放在目标目录中：

   • 支持 JSON 和 YAML 格式
   • 文件应具有 .json、.yaml 或 .yml 扩展名
   • 扫描程序将自动发现和处理所有规范文件

2. 规范 ID 配置：

   • 默认情况下，文件名（不带扩展名）用作规范 ID
   • 要指定自定义 ID，请在 OpenAPI info 对象中添加 x-spec-id：

   openapi: 3.0.0
   info:
     title: My API
     version: 1.0.0
     x-spec-id: my-custom-api-id  # 自定义规范 ID
   

   重要: 当使用具有以下特征的多个规范时，设置自定义 x-spec-id 至关重要：

   • 相似或相同的端点路径
   • 相同的模式名称
   • 重叠的操作 ID

   规范 ID 有助于区分这些相似的资源并防止命名冲突。 例如：

   # user-service.yaml
   info:
     x-spec-id: user-service
   paths:
     /users:
       get: ...
   
   # admin-service.yaml
   info:
     x-spec-id: admin-service
   paths:
     /users:
       get: ...
   

   现在，您可以将这些端点专门引用为 user-service/users 和 admin-service/users

工作原理

1. 服务器扫描指定目录中的 OpenAPI 规范文件
2. 它处理并取消引用规范以获得完整的上下文
3. 创建并维护所有 API 操作和模式的目录
4. 通过 MCP 协议公开此信息
5. IDE 集成然后可以使用此信息来：
   • 向 LLM 提供 API 上下文
   • 启用智能代码完成
   • 协助 API 集成
   • 生成 API 感知的代码片段

工具

1. refresh-api-catalog

   • 刷新 API 目录
   • 返回：刷新目录时的成功消息

2. get-api-catalog

   • 获取 API 目录，该目录包含有关所有 openapi 规范、其操作和模式的元数据
   • 返回：包含所有规范、操作和模式的完整 API 目录

3. search-api-operations

   • 跨规范搜索操作
   • 输入：
     • query (string): 搜索查询
     • specId (optional string): 要在其中搜索的特定 API 规范 ID
   • 返回：来自 API 目录的匹配操作

4. search-api-schemas

   • 跨规范搜索模式
   • 输入：
     • query (string): 搜索查询
     • specId (optional string): 要在其中搜索的特定 API 规范 ID
   • 返回：来自 API 目录的匹配模式

5. load-api-operation-by-operationId

   • 按 operationId 加载操作
   • 输入：
     • specId (string): API 规范 ID
     • operationId (string): 要加载的操作 ID
   • 返回：完整的操作详细信息

6. load-api-operation-by-path-and-method

   • 按路径和方法加载操作
   • 输入：
     • specId (string): API 规范 ID
     • path (string): API 端点路径
     • method (string): HTTP 方法
   • 返回：完整的操作详细信息

7. load-api-schema-by-schemaName

   • 按 schemaName 加载模式
   • 输入：
     • specId (string): API 规范 ID
     • schemaName (string): 要加载的模式的名称
   • 返回：完整的模式详细信息

路线图

1. 语义搜索

   • 启用 API 操作和模式的自然语言查询
   • 通过语义理解提高搜索准确性

2. 远程规范同步

   • 支持从远程源同步 OpenAPI 规范

3. 代码模板

   • 通过 MCP 协议公开代码模板
   • 为 LLM 代码生成提供参考模式

4. 社区贡献

   • 提交功能请求和错误报告
   • 贡献以改进服务器

Cursor 中的示例提示

以下是一些您可以在 Cursor IDE 中使用的示例提示，以与您的 API 交互：

1. 浏览可用 API

   "显示目录中所有可用的 API 及其操作"
   "列出所有 API 规范及其端点"
   

2. API 操作详细信息

   "显示创建宠物 API 端点的详细信息"
   "创建新宠物需要哪些参数？"
   "解释宠物创建端点的响应模式"
   

3. 模式和模拟数据

   "为 Pet 模式生成模拟数据"
   "为创建宠物端点创建一个有效的请求负载"
   "根据模式显示有效宠物对象的示例"
   

4. 代码生成

   "为创建宠物 API 生成一个 Axios 客户端"
   "为 Pet 模式创建一个 TypeScript 接口"
   "编写一个调用创建宠物端点的 React hook"
   

5. API 集成协助

   "帮助我为宠物 API 端点实现错误处理"
   "为宠物 API 客户端生成单元测试"
   "创建一个封装所有与宠物相关的 API 调用的服务类"
   

6. 文档和用法

   "显示使用 curl 的宠物 API 的示例用法"
   "为宠物 API 客户端方法生成 JSDoc 注释"
   "创建一个 README 部分，解释宠物 API 集成"
   

7. 验证和类型

   "为 Pet 模型生成 Zod 验证模式"
   "为所有与宠物相关的 API 响应创建 TypeScript 类型"
   "帮助我为宠物端点实现请求负载验证"
   

8. API 搜索和发现

   "查找所有与宠物管理相关的端点"
   "显示所有接受文件上传的 API"
   "列出所有返回分页响应的端点"
   

这些提示演示了如何利用 MCP 服务器的功能进行 API 开发。 随意根据您的特定需求进行调整或将它们组合起来以完成更复杂的任务。

贡献

欢迎贡献！ 请随时提交 Pull Request。