⚙

OpenAPI规范探索器

一个通过MCP资源模板提供对OpenAPI和Swagger规范高效访问的服务，支持本地和远程文件加载，并自动转换Swagger v2.0到OpenAPI v3.0。

作者 By kadykov

本地部署 OpenAPI Swagger

MCP OpenAPI架构浏览器

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

项目目标

该项目的主要目标是允许MCP客户端（如Cline或Claude Desktop）探索大型OpenAPI规范的结构和细节，而无需将整个文件加载到LLM的上下文窗口中。它通过以下方式公开规范的部分内容来实现这一点 MCP资源模板，为只读数据探索提供参数化访问模式。

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

注：此服务器提供 资源模板 （不是预先列出的资源）。MCP客户端通过以下方式访问这些模板 resources/templates/list 协议方法。有关资源模板的更多信息，请参阅 MCP资源模板文档.

为什么选择MCP资源模板？

模型上下文协议定义了两者资源和工具.

资源： 表示数据源（如文件、API响应）。它们非常适合MCP客户端的只读访问和探索。
资源模板： 一种使用参数化URI的特殊类型的资源（例如。， openapi://paths/{path}/{method})，允许动态访问，而无需预先枚举所有可能的值。
工具： 表示可执行的动作或功能，通常由LLM用于执行任务或与外部系统交互。

虽然存在其他MCP服务器，它们通过以下方式提供对OpenAPI规范的访问工具，该项目特别侧重于通过以下方式提供访问权限 _资源模板_这种方法对于大型API特别有效，因为：

它不需要预先枚举数千个潜在的路径和组件
客户端可以使用模板模式动态发现可用资源
它提供了对规范特定部分的结构化、按需访问

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

客户快速入门指南

克劳德代码 -Anthropic的CLI工具，用于使用Claude进行编码
克劳德桌面，克莱恩，风帆 -请参阅下面的安装说明

安装

关于推荐的使用方法(npx 以及下文所述的Docker）， 不需要单独的安装步骤。您的MCP客户端将根据您提供的配置自动下载包或拉取Docker映像。

但是，如果您更喜欢或需要显式安装服务器，您有两个选项：

全球安装： 您可以使用npm全局安装该包：

BASH``` 1npm install -g mcp-openapi-schema-explorer


看 **方法3** 下面介绍如何配置MCP客户端以使用全局安装的服务器。
2. **本地开发/安装：** 您可以克隆存储库并在本地构建：


BASH```
1
2
3
4git 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对象添加到 mcpServers MCP客户端配置文件的一部分。此条目指示客户端如何使用以下命令运行服务器 npx:

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15{ “mcpServers”: { “My API Spec (npx)”: { “command”: “npx”, “args”: [ “-y”, “mcp-openapi-schema-explorer@latest”, "", “—output-format”, “yaml” ], “env”: {} } } }


**配置说明：**


- 替换 `"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对象之一添加到 `mcpServers` MCP客户端配置文件的一部分。这些条目指导客户端如何使用以下命令运行服务器 `docker run`:


- **远程URL:** 将URL直接传递给 `docker run`.
- **使用远程URL：**


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "mcpServers": {
    "My API Spec (Docker Remote)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "kadykov/mcp-openapi-schema-explorer:latest",
        "<remote-url-to-spec>"
      ],
      "env": {}
    }
  }
}

使用本地文件： （需要将文件装载到容器中）

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19{ “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`，您可以配置客户端直接运行它。


BASH```
1
2# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer

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

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

JSON``` 1 2 3 4 5 6 7 8 9{ “mcpServers”: { “My API Spec (Global)”: { “command”: “mcp-openapi-schema-explorer”, “args”: ["", “—output-format”, “yaml”], “env”: {} } } }


- 确保 `command` (`mcp-openapi-schema-explorer`)可以在MCP客户端使用的PATH环境变量中访问。


### 方法4：本地开发/安装


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


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


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`.


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

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

特性

MCP资源模板访问： 通过参数化URI模板探索OpenAPI规范(openapi://info, openapi://paths/{path}/{method}, openapi://components/{type}/{name}).
OpenAPI v3.0和Swagger v2.0支持： 加载这两种格式，自动将v2.0转换为v3.0。
本地和远程文件： 从本地文件路径或HTTP/HTTPS URL加载规范。
令牌效率： 旨在通过提供结构化访问来最大限度地减少LLM的令牌使用。
多种输出格式： 获取JSON（默认）、YAML或压缩JSON格式的详细视图(--output-format).
动态服务器名称： MCP客户端中的服务器名称反映了 info.title 根据加载的规格。
参考转换： 内部 $refs#/components/...)被转换为可点击的MCP URI。

可用MCP资源

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

重要提示： 此服务器提供 资源模板，而不是预先列出的资源。当您使用MCP客户端时：

客户来电 resources/templates/list 发现可用的模板模式

然后，通过填写模板参数（例如，替换 {path} 和 users%2F%7Bid%7D)

客户使用 resources/read 使用构造的URI获取实际内容

如果你打电话 resources/list （没有“模板”），您将得到一个空列表——这是预期的行为。

了解多值参数(*)

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

资源模板：

openapi://{field}
说明： 访问OpenAPI文档的顶级字段（例如。， info, servers, tags)或列出以下内容 paths 或 components具体的可用字段取决于加载的规格。
例子： openapi://info
输出： text/plain 列出 paths 和 components；其他字段的配置格式（JSON/YAML/压缩JSON）。
完工情况： 为以下内容提供动态建议 {field} 基于加载的规范中发现的实际顶级密钥。
openapi://paths/{path}
说明： 列出特定API路径的可用HTTP方法（操作）。
参数： {path} -API路径字符串。 必须进行URL编码 （例如。， /users/{id} 成为 users%2F%7Bid%7D).
例子： openapi://paths/users%2F%7Bid%7D
输出： text/plain 方法列表。
完工情况： 为以下内容提供动态建议 {path} 基于加载的规范中找到的路径（URL编码）。
openapi://paths/{path}/{method*}
说明： 获取特定API路径上的一个或多个操作（HTTP方法）的详细规范。
参数：
{path} -API路径字符串。 必须进行URL编码.
{method*} -一个或多个HTTP方法（例如。， get, post, get,post).不区分大小写
示例（单个）： openapi://paths/users%2F%7Bid%7D/get
示例（多个）： openapi://paths/users%2F%7Bid%7D/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}。为以下内容提供动态建议 {name*} 只有当 加载的规范总共只包含一种组件类型（例如，仅 schemas).存在此限制是因为MCP SDK目前不支持提供所选范围内的完成 {type}；提供所有类型的所有名称可能会产生误导。

贡献

欢迎投稿！请查看贡献.md 有关设置开发环境、运行测试和提交更改的指南文件。

发布

此项目使用 semantic-release 基于.NET的自动化版本管理和包发布常规提交.

未来计划

（未来计划待定）