@reapi/mcp-openapi

@reapi/mcp-openapi

一个模型上下文协议（MCP）服务，可加载并提供多个 OpenAPI 规范，以支持由大模型驱动的 IDE 集成。此服务充当 OpenAPI 规范与 Cursor 等由大模型驱动的开发工具之间的桥梁。

功能

• 从目录加载多个 OpenAPI 规范
• 通过 MCP 协议公开 API 操作和架构
• 让大模型能够直接在 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 标签，因为我们会频繁更新服务，添加新功能并进行改进。

重要：项目专用配置有助于管理大模型上下文限制。如果将所有规范放在同一个文件夹中，合并后的元数据可能会超出大模型的上下文窗口，导致错误。按项目整理规范可以让上下文大小保持在可管理范围内。

选项 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 mode。

现在即可使用此服务。向目录添加新的 OpenAPI 规范后，可以通过以下方式刷新目录：

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

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

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  # Custom specification 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 集成随后可以利用这些信息来：
   • 为大模型提供 API 上下文
   • 实现智能代码补全
   • 辅助 API 集成
   • 生成了解 API 的代码片段

工具

1. refresh-api-catalog

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

2. get-api-catalog

   • 获取 API 目录，其中包含所有 OpenAPI 规范及其操作和架构的元数据
   • 返回：包含所有规范、操作和架构的完整 API 目录

3. search-api-operations

   • 跨规范搜索操作
   • 输入：
     • query（字符串）：搜索查询
     • specId（可选字符串）：要在其中搜索的特定 API 规范 ID
   • 返回：API 目录中匹配的操作

4. search-api-schemas

   • 跨规范搜索架构
   • 输入：
     • query（字符串）：搜索查询
     • specId（可选字符串）：要搜索的特定 API 规范 ID
   • 返回：API 目录中匹配的架构

5. load-api-operation-by-operationId

   • 根据 operationId 加载操作
   • 输入：
     • specId（字符串）：API 规范 ID
     • operationId（字符串）：要加载的操作 ID
   • 返回：完整的操作详情

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

   • 根据路径和方法加载操作
   • 输入：
     • specId（字符串）：API 规范 ID
     • path（字符串）：API 端点路径
     • method（字符串）：HTTP 方法
   • 返回：完整的操作详情

7. load-api-schema-by-schemaName

   • 根据 schemaName 加载架构
   • 输入：
     • specId（字符串）：API 规范 ID
     • schemaName（字符串）：要加载的架构名称
   • 返回：完整的架构详情

路线图

1. 语义搜索

   • 支持使用自然语言查询 API 操作和架构
   • 通过语义理解提高搜索准确性

2. 远程规范同步

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

3. 代码模板

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

4. 社区贡献

   • 提交功能请求和错误报告
   • 参与改进服务

Cursor 中的提示词示例

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

1. 探索可用的 API

   "Show me all available APIs in the catalog with their operations"
   "List all API specifications and their endpoints"
   

2. API 操作详情

   "Show me the details of the create pet API endpoint"
   "What are the required parameters for creating a new pet?"
   "Explain the response schema for the pet creation endpoint"
   

3. 架构和模拟数据

   "Generate mock data for the Pet schema"
   "Create a valid request payload for the create pet endpoint"
   "Show me examples of valid pet objects based on the schema"
   

4. 代码生成

   "Generate an Axios client for the create pet API"
   "Create a TypeScript interface for the Pet schema"
   "Write a React hook that calls the create pet endpoint"
   

5. API 集成协助

   "Help me implement error handling for the pet API endpoints"
   "Generate unit tests for the pet API client"
   "Create a service class that encapsulates all pet-related API calls"
   

6. 文档和使用方法

   "Show me example usage of the pet API with curl"
   "Generate JSDoc comments for the pet API client methods"
   "Create a README section explaining the pet API integration"
   

7. 验证和类型

   "Generate Zod validation schema for the Pet model"
   "Create TypeScript types for all pet-related API responses"
   "Help me implement request payload validation for the pet endpoints"
   

8. API 搜索与发现

   "Find all endpoints related to pet management"
   "Show me all APIs that accept file uploads"
   "List all endpoints that return paginated responses"
   

这些提示词展示了如何利用 MCP 服务的功能进行 API 开发。你可以根据具体需求调整它们，也可以组合使用，以完成更复杂的任务。

贡献

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