@reapi/mcp-openapi

一个模型上下文协议（MCP）服务器，用于加载并服务多个OpenAPI规范，以实现基于LLM的IDE集成。该服务器充当您的OpenAPI规范与Cursor等基于LLM的开发工具以及其他代码编辑器之间的桥梁。

功能

从目录加载多个OpenAPI规范
通过MCP协议暴露API操作和模式
使LLM能够直接在您的IDE中理解和处理您的API
支持引用的schema以获取完整的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设置中启用

添加配置后：

打开Cursor IDE
转到设置 > Cursor设置 > MCP
启用 @reapi/mcp-openapi 服务器
点击服务器旁边的刷新图标以应用更改

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

服务器现在已准备就绪。当您将新的OpenAPI规范添加到目录中时，可以通过以下方式刷新目录：

打开Cursor的聊天面板

输入以下提示之一：

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

OpenAPI规范要求

将您的OpenAPI 3.x规范放在目标目录中：
- 支持JSON和YAML格式
- 文件名应为 .json、.yaml 或 .yml 扩展名
- 扫描器将自动发现和处理所有规范文件
规范ID配置：
- 默认情况下，文件名（不含扩展名）用作规范ID
- 要指定自定义ID，请在OpenAPI info对象中添加 x-spec-id：
```
openapi: 3.0.0
info:
  title: 我的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

工作原理

服务器扫描指定的目录以查找OpenAPI规范文件
它处理并引用规范以获取完整上下文
创建并维护所有API操作和模式的目录
通过MCP协议暴露此信息
IDE集成然后可以使用此信息：
- 向LLM提供API上下文
- 启用智能代码补全
- 协助API集成
- 生成API感知的代码片段

工具

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中的示例提示

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

探索可用API

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

API操作详情

"显示创建宠物API端点的详细信息"
"创建新宠物所需的参数是什么？"
"解释宠物创建端点的响应模式"

模式和模拟数据

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

代码生成

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

API集成协助

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

文档和使用

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

验证和类型

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

API搜索和发现

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

这些提示展示了如何利用MCP服务器的功能进行API开发。请随意根据您的具体需求调整它们，或将它们组合用于更复杂的任务。

贡献

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

ReAPI-com/mcp-openapi

星标增长

证据时间轴