mcp-openapi 是一个基于模型上下文协议（MCP）的服务器，用于加载并服务多个 OpenAPI 规范，从而支持由 LLM 驱动的 IDE 集成，充当 OpenAPI 规范与 Cursor 等 LLM 开发工具之间的桥梁。
主要能力
- 从目录加载多个 OpenAPI 规范
- 通过 MCP 协议暴露 API 操作与模式（schema）
- 让 LLM 能够直接在 IDE 中理解并使用你的 API
- 支持解引用后的模式，以获得完整的 API 上下文
- 维护所有可用 API 的目录
由 ReAPI 提供支持。该开源 MCP 服务器由 ReAPI 赞助，ReAPI 是一个简化 API 设计与测试的下一代 API 平台。本服务器提供本地 OpenAPI 集成用于开发，ReAPI 则提供两个强大模块：一是使用直观的无代码编辑器设计 API、自动生成并发布 OpenAPI 规范、与团队成员实时协作、版本控制与变更管理；二是对开发者友好的无代码 API 测试方案，包括直观界面创建和管理测试用例、强大的断言与验证能力、无服务器云测试执行器，适合 QA 团队与开发者，并支持 CI/CD 集成。可在 reapi.com 免费试用 ReAPI。
Cursor 配置 有两种配置位置可供选择。
选项 1：项目级配置（推荐）。在项目目录中创建 .cursor/mcp.json 文件。推荐此选项，因为它允许为不同项目维护不同的规范集。提示：使用类似 ./specs 的相对路径可使配置可移植，便于团队成员共享。注意：推荐使用 @latest 标签，因为服务器会频繁更新新功能和改进。重要：项目级配置有助于管理 LLM 上下文限制。当所有规范都放在单一文件夹中时，合并后的元数据可能超出 LLM 的上下文窗口，导致出错。按项目组织规范可保持上下文大小可控。
选项 2：全局配置。在主目录中创建或编辑 ~/.cursor/mcp.json，使服务器在所有项目中可用。
在 Cursor 设置中启用 添加配置后：打开 Cursor IDE；进入 Settings > Cursor Settings > MCP；启用 @reapi/mcp-openapi 服务器；点击服务器旁的刷新图标以应用更改。注意：默认情况下，Cursor 要求每次 MCP 工具执行都进行确认。若希望允许自动执行而无需确认，可在 Cursor 设置中启用 Yolo 模式。
服务器现在即可使用。当你向目录添加新的 OpenAPI 规范后，可通过打开 Cursor 的聊天面板并输入以下提示之一来刷新目录：“Please refresh the API catalog”或“Reload the OpenAPI specifications”。
OpenAPI 规范要求 将 OpenAPI 3.x 规范放入目标目录：支持 JSON 和 YAML 格式；文件应具有 .json、.yaml 或 .yml 扩展名；扫描器会自动发现并处理所有规范文件。
规范 ID 配置：默认情况下，文件名（不含扩展名）用作规范 ID。要指定自定义 ID，请在 OpenAPI info 对象中添加 x-spec-id。
重要：当处理多个具有相似或相同端点路径、相同模式名称、重叠操作 ID 的规范时，设置自定义 x-spec-id 至关重要。规范 ID 有助于区分这些相似资源并防止命名冲突。
工作方式 服务器扫描指定目录中的 OpenAPI 规范文件；处理并解引用规范以获得完整上下文；创建并维护所有 API 操作与模式的目录；通过 MCP 协议暴露此信息；IDE 集成随后可使用该信息：为 LLM 提供 API 上下文、启用智能代码补全、协助 API 集成、生成感知 API 的代码片段。
工具（MCP 工具）
- refresh-api-catalog：刷新 API 目录。返回：目录刷新成功时的成功消息。
- get-api-catalog：获取 API 目录，目录包含所有 OpenAPI 规范及其操作和模式的元数据。返回：包含所有规范、操作和模式的完整 API 目录。
- search-api-operations：跨规范搜索操作。输入：query（字符串）：搜索查询；specId（可选字符串）：要在其中搜索的特定 API 规范 ID。返回：来自 API 目录的匹配操作。
- search-api-schemas：跨规范搜索模式。输入：query（字符串）：搜索查询；specId（可选字符串）：要在其中搜索的特定 API 规范 ID。返回：来自 API 目录的匹配模式。
- load-api-operation-by-operationId：按 operationId 加载操作。输入：specId（字符串）：API 规范 ID；operationId（字符串）：要加载的操作 ID。返回：完整的操作详情。
- load-api-operation-by-path-and-method：按路径和方法加载操作。输入：specId（字符串）：API 规范 ID；path（字符串）：API 端点路径；method（字符串）：HTTP 方法。返回：完整的操作详情。
- load-api-schema-by-schemaName：按 schemaName 加载模式。输入：specId（字符串）：API 规范 ID；schemaName（字符串）：要加载的模式名称。返回：完整的模式详情。
规划中的能力（资料中列为待实现）
- 语义搜索：为 API 操作和模式启用自然语言查询；通过语义理解提升搜索准确性。
- 远程规范同步：支持从远程源同步 OpenAPI 规范。
- 代码模板：通过 MCP 协议暴露代码模板；为 LLM 代码生成提供参考模式。
- 社区贡献：提交功能请求和错误报告；参与改进服务器。
Cursor 中的示例提示词 探索可用 API：“Show me all available APIs in the catalog with their operations”“List all API specifications and their endpoints” 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” 模式与模拟数据：“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” 代码生成：“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” 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” 文档与用法：“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” 验证与类型：“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” 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。
