@reapi/mcp-openapi

一个 Model Context Protocol (MCP) 服务器，用于加载和提供多个 OpenAPI 规范，以实现由 LLM 支持的 IDE 集成。该服务器充当您的 OpenAPI 规范与 Cursor 等 LLM 支持的开发工具之间的桥梁。

功能

• 从目录中加载多个 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. 转到设置 > Cursor 设置 > 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 信息对象中添加 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 (字符串)：搜索查询
     • 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 协议公开代码模板
   • 提供 LLM 代码生成的参考模式

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。