MCP开放API服务器
项目介绍
@reapi/mcp-openapi
一个模型上下文协议（MCP）服务器，用于加载并提供多个OpenAPI规范，以支持LLM驱动的IDE集成。此服务器作为您的OpenAPI规范与LLM驱动的开发工具（如Cursor和其他代码编辑器）之间的桥梁。
功能
- 从目录中加载多个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设置中启用
添加配置后：
- 打开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规范IDoperationId（字符串）：要加载的操作ID
- 返回：完整操作详情
-
load-api-operation-by-path-and-method- 通过路径和方法加载操作
- 输入：
specId（字符串）：API规范IDpath（字符串）：API端点路径method（字符串）：HTTP方法
- 返回：完整操作详情
-
load-api-schema-by-schemaName- 通过schemaName加载模式
- 输入：
specId（字符串）：API规范IDschemaName（字符串）：要加载的模式名称
- 返回：完整模式详情
发展路线图
-
语义搜索
- 启用对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注释" "创建一个README部分，解释宠物API集成" -
验证和类型
"为Pet模型生成Zod验证模式" "为所有与宠物相关的API响应创建TypeScript类型" "帮助我实现宠物端点的请求负载验证" -
API搜索和发现
"查找所有与宠物管理相关的端点" "显示接受文件上传的所有API" "列出返回分页响应的所有端点"
这些提示展示了如何利用MCP服务器的能力进行API开发。请根据您的具体需求自由调整它们或组合它们以完成更复杂的任务。
贡献
欢迎贡献！请随时提交Pull Request。