MCP OpenAPI Server

@reapi/mcp-openapi

模型上下文协议 (MCP) 服务器，可加载并提供多种 OpenAPI 规范，从而支持 LLM 驱动的 IDE 集成。该服务器充当 OpenAPI 规范与 Cursor 和其他 LLM 驱动的开发工具（例如代码编辑器）之间的桥梁。

特征

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

由ReAPI提供支持

此开源 MCP 服务器由ReAPI赞助，ReAPI 是一个简化 API 设计和测试的下一代 API 平台。此服务器不仅提供本地 OpenAPI 集成以供开发使用，还提供了两个强大的模块：

🎨 API CMS

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

🧪 API 测试

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

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

游标配置

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

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

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

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

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

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

选项 2：全局配置

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

在光标设置中启用

添加配置后：

1. 打开游标 IDE
2. 前往“设置”>“光标设置”>“MCP”
3. 启用@reapi/mcp-openapi服务器
4. 单击服务器旁边的刷新图标以应用更改

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

服务器现已可供使用。当您将新的 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 信息对象中添加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 重叠

   spec 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 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 请求。