AI导哈

OpenAPI规范服务

一个加载并提供多个OpenAPI规范的服务，用于支持LLM驱动的IDE集成，作为OpenAPI规范与开发工具之间的桥梁。

  • by ReAPI-com
  • TypeScript
  • 本地部署
  • 90 星标
  • 更新于
在 GitHub 查看 ReAPI-com/mcp-openapi

使用说明

@reapi/mcp openapi

一个模型上下文协议（MCP）服务器，加载并提供多个OpenAPI规范，以实现LLM驱动的IDE集成。此服务器充当OpenAPI规范和LLM驱动的开发工具（如Cursor和其他代码编辑器）之间的桥梁。

特性

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

由...驱动 ReAPI

此开源MCP服务器由 ReAPI，下一代API平台，简化了API的设计和测试。虽然该服务器为开发提供了本地OpenAPI集成，但ReAPI提供了两个强大的模块：

🎨 API CMS

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

🧪 API测试

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

免费试用ReAPI reapi.com 网站地址 体验API未来的发展。

光标配置

要将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": {}
    }
  }
}

在光标设置中启用

添加配置后：

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

备注：默认情况下，Cursor要求对每个MCP工具执行进行确认。如果您想允许无需确认即可自动执行，可以启用 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，请添加 x-spec-id 在OpenAPI信息对象中：
    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

    规范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 （string）：搜索查询
      • specId （可选字符串）：要在其中搜索的特定API规范ID
    • 返回：API目录中的匹配操作

  4. search-api-schemas

    • 跨规范搜索模式
    • 输入：
      • query （string）：搜索查询
      • specId （可选字符串）：要搜索的特定API规范ID
    • 返回：匹配API目录中的架构

  5. load-api-operation-by-operationId

    • 按operationId加载操作
    • 输入：
      • specId （字符串）：API规范ID
      • operationId （string）：要加载的操作ID
    • 返回：完整的操作细节

  6. load-api-operation-by-path-and-method

    • 按路径和方法加载操作
    • 输入：
      • specId （字符串）：API规范ID
      • path （字符串）：API端点路径
      • method （string）：HTTP方法
    • 返回：完整的操作细节

  7. load-api-schema-by-schemaName

    • 按schemaName加载架构
    • 输入：
      • specId （字符串）：API规范ID
      • schemaName （string）：要加载的架构的名称
    • 返回：完整的架构详细信息

路线图

  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开发。您可以根据自己的具体需求调整它们，也可以将它们组合起来用于更复杂的任务。

贡献

欢迎投稿！请随时提交拉取请求。

相关 MCP