OpenAPI Schema Explorer

MCP OpenAPI 模式资源管理器

MCP（模型上下文协议）服务器，通过MCP 资源提供对 OpenAPI（v3.0）和 Swagger（v2.0）规范的令牌高效访问。

项目目标

该项目的主要目标是允许 MCP 客户端（例如 Cline 或 Claude Desktop）探索大型 OpenAPI 规范的结构和细节，而无需将整个文件加载到 LLM 的上下文窗口中。它通过 MCP 资源公开规范的各个部分来实现这一点，这些资源非常适合只读数据探索。

此服务器支持从本地文件路径和远程 HTTP/HTTPS URL 加载规范。Swagger v2.0 规范在加载时会自动转换为 OpenAPI v3.0。

为什么选择 MCP 资源？

模型上下文协议定义了资源和工具。

• **资源：**表示数据源（例如文件、API 响应）。它们非常适合 MCP 客户端进行只读访问和探索（例如，在 Claude Desktop 中浏览 API 路径）。
• **工具：**表示可执行的操作或功能，通常由 LLM 用来执行任务或与外部系统交互。

虽然其他 MCP 服务器可以通过工具访问 OpenAPI 规范，但本项目专注于通过资源提供访问。这使得它对于在 MCP 客户端应用程序中直接探索特别有用。

有关 MCP 客户端及其功能的更多详细信息，请参阅MCP 客户端文档。

安装

对于推荐的使用方法（ npx和 Docker，如下所述），无需单独的安装步骤。您的 MCP 客户端将根据您提供的配置自动下载软件包或拉取 Docker 镜像。

但是，如果您更喜欢或需要明确安装服务器，则有两个选择：

1. **全局安装：**您可以使用 npm 全局安装该包：
   npm install -g mcp-openapi-schema-explorer
   请参阅下面的**方法 3，**了解如何配置 MCP 客户端以使用全局安装的服务器。
2. **本地开发/安装：**您可以克隆存储库并在本地构建它：
   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build
   请参阅下面的**方法 4，**了解如何配置 MCP 客户端以使用node从本地构建运行服务器。

将服务器添加到您的 MCP 客户端

此服务器设计为由 MCP 客户端（例如 Claude Desktop、Windsurf、Cline 等）运行。要使用它，您需要在客户端的设置文件（通常是 JSON 文件）中添加一个配置条目。此条目告诉客户端如何执行服务器进程（例如，使用npx 、 docker或node ）。除了客户端设置条目中指定的命令行参数外，服务器本身不需要单独的配置。

以下是将服务器条目添加到客户端配置的常用方法。

方法 1：npx（推荐）

建议使用npx ，因为它可以避免全局/本地安装并确保客户端使用最新发布的版本。

客户端配置条目示例（npx 方法）：

将以下 JSON 对象添加到 MCP 客户端配置文件的mcpServers部分。此条目指示客户端如何使用npx运行服务器：

配置说明：

• 将"My API Spec (npx)"替换为客户端中此服务器实例的唯一名称。
• 将<path-or-url-to-spec>替换为您指定的绝对本地文件路径或完整远程 URL。
• --output-format是可选的（ json ， yaml ， json-minified ），默认为json 。
• 要探索多个规范，请在mcpServers中添加单独的条目，每个条目都有唯一的名称并指向不同的规范。

方法二：Docker

您可以指示您的 MCP 客户端使用官方 Docker 镜像运行服务器： kadykov/mcp-openapi-schema-explorer 。

客户端配置条目示例（Docker 方法）：

将以下 JSON 对象之一添加到 MCP 客户端配置文件的mcpServers部分。这些条目指示客户端如何使用docker run运行服务器：

• **远程 URL：**将 URL 直接传递给docker run 。
• 使用远程 URL：
  { "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } }
• **使用本地文件：（**需要将文件挂载到容器中）
  { "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }
  **重要提示：**请将/full/host/path/to/spec.yaml替换为主机上正确的绝对路径。路径/spec/api.yaml是容器内的对应路径。

方法 3：全局安装（不太常见）

如果您已经使用npm install -g全局安装了该包，则可以配置您的客户端以直接运行它。

客户端配置条目示例（全局安装方法）：

将以下条目添加到 MCP 客户端的配置文件中。此操作假设mcp-openapi-schema-explorer命令在客户端的执行环境变量 PATH 中可访问。

• 确保command （ mcp-openapi-schema-explorer ）可在 MCP 客户端使用的 PATH 环境变量中访问。

方法四：本地开发/安装

如果您已在本地克隆存储库以进行开发或运行修改后的版本，则此方法很有用。

设置步骤（在终端运行一次）：

1. 克隆存储库： git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. 导航到目录： cd mcp-openapi-schema-explorer
3. 安装依赖项： npm install
4. 构建项目： npm run build （或者just build ）

客户端配置条目示例（本地开发方法）：

将以下条目添加到 MCP 客户端的配置文件中。这将指示客户端使用node运行本地构建的服务器。

**重要提示：**将/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js替换为克隆存储库中构建的index.js文件的正确绝对路径。

特征

• **MCP 资源访问：**通过直观的 URI（ openapi://info 、 openapi://paths/...``openapi://components/... ）探索 OpenAPI 规范。
• **OpenAPI v3.0 和 Swagger v2.0 支持：**加载两种格式，自动将 v2.0 转换为 v3.0。
• **本地和远程文件：**从本地文件路径或 HTTP/HTTPS URL 加载规范。
• **令牌高效：**旨在通过提供结构化访问来最大限度地减少 LLM 的令牌使用。
• **多种输出格式：**以 JSON（默认）、YAML 或最小化 JSON（ --output-format ）获取详细视图。
• 动态服务器名称： MCP 客户端中的服务器名称反映了已加载规范的info.title 。
• **引用转换：**内部$ref ( #/components/... ) 转换为可点击的 MCP URI。

可用的 MCP 资源

该服务器公开以下 MCP 资源模板，用于探索 OpenAPI 规范。

了解多值参数 ( * )

一些资源模板包含以星号 ( * ) 结尾的参数，例如{method*}或{name*} 。这表示该参数接受多个逗号分隔的值。例如，要请求路径的GET和POST方法的详细信息，可以使用类似openapi://paths/users/get,post URI。这样可以在单个请求中获取多个项目的详细信息。

资源模板：

• openapi://{field}
  • **描述：**访问 OpenAPI 文档的顶级字段（例如， info 、 servers 、 tags ），或列出paths或components的内容。具体可用字段取决于加载的规范。
  • 例如： openapi://info
  • 输出： paths和components的text/plain列表；其他字段的配置格式（JSON/YAML/最小化 JSON）。
  • **完成：**根据加载的规范中找到的实际顶级键为{field}提供动态建议。
• openapi://paths/{path}
  • **描述：**列出特定 API 路径可用的 HTTP 方法（操作）。
  • 参数： {path} - API 路径字符串。必须进行 URL 编码（例如， /users/{id}变为users/{id} ）。
  • 例如： openapi://paths/users/{id}
  • 输出： text/plain方法列表。
  • **完成：**根据加载的规范（URL 编码）中找到的路径，为{path}提供动态建议。
• openapi://paths/{path}/{method*}
  • **描述：**获取特定 API 路径上的一个或多个操作（HTTP 方法）的详细规范。
  • 参数：
    • {path} - API 路径字符串。必须经过 URL 编码。
    • {method*} - 一个或多个 HTTP 方法 (例如get 、 post 、 get,post )。不区分大小写。
  • 示例（单个）： openapi://paths/users/{id}/get
  • 示例（多个）： openapi://paths/users/{id}/get,post
  • **输出：**配置格式（JSON/YAML/最小化 JSON）。
  • **补全：**为{path}提供动态建议。为{method*}提供静态建议（常见的 HTTP 动词，如 GET、POST、PUT、DELETE 等）。
• openapi://components/{type}
  • **描述：**列出特定类型（例如， schemas 、 responses 、 parameters ）的所有已定义组件的名称。具体可用的类型取决于加载的规范。此外，还提供了每种列出类型的简短描述。
  • 例如： openapi://components/schemas
  • **输出：**带有描述的组件名称的text/plain列表。
  • **完成：**根据在加载的规范中找到的组件类型为{type}提供动态建议。
• openapi://components/{type}/{name*}
  • **描述：**获取特定类型的一个或多个命名组件的详细规范。
  • 参数：
    • {type} - 组件类型。
    • {name*} - 一个或多个组件名称（例如， User 、 Order 、 User,Order ）。区分大小写。
  • 示例（单个）： openapi://components/schemas/User
  • 示例（多个）： openapi://components/schemas/User,Order
  • **输出：**配置格式（JSON/YAML/最小化 JSON）。
  • **补全：**提供针对{type}的动态建议。仅当加载的规范整体上只包含一种组件类型（例如，仅包含schemas ）时，才会提供针对{name*}的动态建议。存在此限制是因为 MCP SDK 目前不支持提供针对所选{type}范围的补全；提供所有类型的所有名称可能会产生误导。

贡献

欢迎贡献代码！请参阅CONTRIBUTING.md文件，了解如何设置开发环境、运行测试以及提交更改。

发布

该项目使用semantic-release进行基于Conventional Commits 的自动化版本管理和包发布。

未来计划

（未来计划待定）