mcp-openapi 是一个 MCP 服务器，专为简化 LLM 驱动的 IDE 集成而设计。它充当 OpenAPI 规范与开发工具（如 Cursor）之间的桥梁，使 LLM 能够直接在 IDE 中理解和使用 API。该服务器能够加载并提供多个 OpenAPI 规范，支持 JSON 和 YAML 格式，并自动发现规范文件。

通过 mcp-openapi，开发者可以轻松地将 API 上下文传递给 LLM，从而实现智能代码补全、API 集成辅助和代码片段生成等功能。它通过 MCP 协议公开 API 操作和模式，支持取消引用的模式以获得完整的 API 上下文，并维护所有可用 API 的目录。集成的关键在于在项目或全局 Cursor 配置中启用该服务器，并指定包含 OpenAPI 规范的目录。这使得 LLM 能够理解 API，极大地提升开发效率和代码质量。

OpenAPI规范动态加载与管理

mcp-openapi能够从指定目录动态加载多个OpenAPI规范文件（JSON或YAML格式），并自动发现和处理这些文件。它通过MCP协议将这些API操作和模式暴露给LLM驱动的IDE集成工具，如Cursor。这种动态加载能力极大地简化了API集成流程，开发者无需手动配置每个API，只需将OpenAPI规范文件放入指定目录，mcp-openapi即可自动完成加载和管理。此外，它还支持通过x-spec-id自定义规范ID，解决了多个规范具有相同路径或模式名称时的冲突问题。

例如，一个团队维护多个微服务的OpenAPI规范，只需将这些规范文件放在一个目录下，并配置mcp-openapi指向该目录，Cursor等IDE即可自动识别并利用这些API，为开发者提供智能代码补全、API集成辅助等功能。

技术实现上，mcp-openapi会定期扫描指定目录，解析OpenAPI规范文件，并将其转换为内部数据结构，以便快速查询和访问。

API目录生成与维护

mcp-openapi会自动创建并维护一个包含所有可用API操作和模式的目录。这个目录充当了API的索引，使得LLM能够快速查找和理解API的功能和用法。通过MCP协议，IDE可以访问这个目录，并将其用于智能代码补全、API搜索和文档生成等功能。该目录包含每个API规范的元数据，包括规范ID、操作ID、路径、方法、参数和模式等信息。

例如，开发者可以使用Cursor的聊天面板，通过自然语言查询“Show me all available APIs in the catalog with their operations”，快速了解当前可用的API列表及其详细信息。

技术实现上，mcp-openapi使用高效的数据结构来存储API目录，并提供快速的搜索和过滤功能。

LLM驱动的IDE集成桥梁

mcp-openapi充当了OpenAPI规范和LLM驱动的开发工具之间的桥梁，使得LLM能够直接在IDE中理解和使用API。它通过MCP协议将API的上下文信息传递给LLM，包括API的操作、参数、请求体、响应体和模式等。LLM可以利用这些信息为开发者提供智能代码补全、API集成辅助、代码生成和文档生成等功能。

例如，开发者在编写代码时，可以使用Cursor的智能代码补全功能，根据OpenAPI规范自动生成API调用的代码片段，并根据API的参数和模式提供参数提示和验证。

技术实现上，mcp-openapi实现了MCP服务器端，并提供了一组标准的MCP工具，用于查询和加载API信息。

规范ID自定义与冲突解决

mcp-openapi支持通过在OpenAPI规范的info对象中添加x-spec-id字段来自定义规范ID。当多个规范具有相似或相同的端点路径、相同的模式名称或重叠的操作ID时，自定义规范ID变得至关重要。通过为每个规范分配唯一的ID，可以避免命名冲突，并允许LLM准确地识别和调用特定的API。

例如，如果两个不同的服务都定义了/users端点，可以通过设置x-spec-id分别为user-service和admin-service，从而可以通过user-service/users和admin-service/users来明确引用这两个端点。

技术实现上，mcp-openapi在加载OpenAPI规范时会检查x-spec-id字段，如果存在则使用该值作为规范ID，否则使用文件名作为默认ID。

丰富的API操作工具集

mcp-openapi提供了一系列强大的API操作工具，包括refresh-api-catalog、get-api-catalog、search-api-operations、search-api-schemas、load-api-operation-by-operationId、load-api-operation-by-path-and-method和load-api-schema-by-schemaName。这些工具使得开发者和LLM能够方便地查询、搜索和加载API信息，从而实现更智能的API集成和开发体验。

例如，开发者可以使用search-api-operations工具，通过关键词查询相关的API操作，并使用load-api-operation-by-operationId工具加载指定操作的详细信息。

技术实现上，这些工具通过MCP协议暴露给客户端，并使用高效的算法来查询和加载API信息。