MCP开放API模式探索器
项目介绍
MCP OpenAPI Schema Explorer
一个 MCP（模型上下文协议）服务器，通过 MCP 资源 提供高效访问 OpenAPI（v3.0）和 Swagger（v2.0）规范的方式。
项目目标
该项目的主要目标是允许 MCP 客户端（如 Cline 或 Claude Desktop）无需将整个文件加载到 LLM 的上下文窗口中，即可探索大型 OpenAPI 规范的结构和细节。它通过暴露规范的部分内容来实现这一点，这些部分通过 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 镜像。
但是，如果您希望或需要明确安装服务器，有两种选项：
-
全局安装： 您可以使用 npm 全局安装该包：
npm install -g mcp-openapi-schema-explorer请参阅下面的 方法 3，了解如何配置您的 MCP 客户端以使用全局安装的服务器。
-
本地开发/安装： 您可以克隆仓库并本地构建：
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 方法）：
在您的 MCP 客户端配置文件的 mcpServers 部分添加以下 JSON 对象。这个条目指示客户端如何使用 npx 运行服务器：
{
"mcpServers": {
"我的 API 规范 (npx)": {
"command": "npx",
"args": [
"-y",
"mcp-openapi-schema-explorer@latest",
"<path-or-url-to-spec>",
"--output-format",
"yaml"
],
"env": {}
}
}
}
配置注意事项：
- 将
"我的 API 规范 (npx)"替换为您客户端中此服务器实例的唯一名称。 - 将
<path-or-url-to-spec>替换为您的规范的绝对本地文件路径或完整的远程 URL。 --output-format是可选的（json、yaml、json-minified），默认值为json。- 若要探索多个规范，请在
mcpServers中添加单独的条目，每个条目具有唯一的名称并指向不同的规范。
方法 2：Docker
您可以指示您的 MCP 客户端使用官方 Docker 镜像运行服务器：kadykov/mcp-openapi-schema-explorer。
客户端配置条目示例（Docker 方法）：
在您的 MCP 客户端配置文件的 mcpServers 部分添加以下 JSON 对象之一。这些条目指示客户端如何使用 docker run 运行服务器：
-
远程 URL： 直接将 URL 传递给
docker run。 -
使用远程 URL：
{ "mcpServers": { "我的 API 规范 (Docker 远程)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } } -
使用本地文件：（需要将文件挂载到容器中）
{ "mcpServers": { "我的 API 规范 (Docker 本地)": { "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 全局安装了该包，您可以配置客户端直接运行它。
# 在您的终端中运行一次
npm install -g mcp-openapi-schema-explorer
客户端配置条目示例（全局安装方法）：
在您的 MCP 客户端配置文件中添加以下条目。这假设 mcp-openapi-schema-explorer 命令在客户端执行环境的 PATH 中可用。
{
"mcpServers": {
"我的 API 规范 (全局)": {
"command": "mcp-openapi-schema-explorer",
"args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
"env": {}
}
}
}
- 确保
command(mcp-openapi-schema-explorer) 在 MCP 客户端使用的 PATH 环境变量中可用。
方法 4：本地开发/安装
如果已克隆仓库进行开发或运行修改后的版本，此方法很有用。
设置步骤（在您的终端中运行一次）：
- 克隆仓库：
git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git - 导航到目录：
cd mcp-openapi-schema-explorer - 安装依赖项：
npm install - 构建项目：
npm run build（或just build）
客户端配置条目示例（本地开发方法）：
在您的 MCP 客户端配置文件中添加以下条目。这指示客户端使用 node 运行本地构建的服务器。
{
"mcpServers": {
"我的 API 规范 (本地开发)": {
"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://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 - 输出：
text/plain列表用于paths和components；配置的格式（JSON/YAML/压缩的 JSON）用于其他字段。 - 补全建议： 根据实际加载的规范中的顶级键提供
{field}的动态建议。
- 描述： 访问 OpenAPI 文档的顶级字段（例如，
-
openapi://paths/{path}- 描述： 列出特定 API 路径的可用 HTTP 方法（操作）。
- 参数：
{path}- API 路径字符串。必须进行 URL 编码（例如，/users/{id}变成users%2F%7Bid%7D）。 - 示例：
openapi://paths/users%2F%7Bid%7D - 输出：
text/plain列表的方法。 - 补全建议： 根据加载的规范中的路径（URL 编码）提供
{path}的动态建议。
-
openapi://paths/{path}/{method*}- 描述： 获取特定 API 路径上一个或多个操作（HTTP 方法）的详细规范。
- 参数：
{path}- API 路径字符串。必须进行 URL 编码。{method*}- 一个或多个 HTTP 方法（例如，get、post、get,post）。大小写不敏感。
- 示例（单个）：
openapi://paths/users%2F%7Bid%7D/get - 示例（多个）：
open/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}的动态建议。仅当加载的规范中总体上只有一个组件类型（例如，只有schemas）时，才提供{name*}的动态建议。这是因为 MCP SDK 当前不支持按所选{type}提供补全建议；提供所有类型的所有名称可能会误导。
贡献
欢迎贡献！请参阅 CONTRIBUTING.md 文件，了解设置开发环境、运行测试和提交更改的指南。
发布
此项目使用 semantic-release 根据 常规提交 自动管理版本和发布包。
未来计划
（未来计划待定）