MCP OpenAPI架构浏览器
](https://badge.fury.io/js/mcp-openapi-schema-explorer) ](https://badge.fury.io/js/mcp-openapi-schema-explorer) ](https://hub.docker.com/r/kadykov/mcp-openapi-schema-explorer)     
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全局安装该包：
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方法）：
将以下JSON对象添加到 mcpServers MCP客户端配置文件的一部分。此条目指示客户端如何使用以下命令运行服务器 npx:
{
"mcpServers": {
"My API Spec (npx)": {
"command": "npx",
"args": [
"-y",
"mcp-openapi-schema-explorer@latest",
"
",
"--output-format",
"yaml"
],
"env": {}
}
}
}配置说明：
- 替换
"My API Spec (npx)"在客户端中为该服务器实例指定一个唯一的名称。 - 替换 `
` 使用您的规范的绝对本地文件路径或完整远程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：
{
"mcpServers": {
"My API Spec (Docker Remote)": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"kadykov/mcp-openapi-schema-explorer:latest",
""
],
"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，您可以配置客户端直接运行它。
# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer客户端配置条目示例（全局安装方法）：
将以下条目添加到MCP客户端的配置文件中。这假设 mcp-openapi-schema-explorer 命令可以在客户端的执行环境PATH中访问。
{
"mcpServers": {
"My API Spec (Global)": {
"command": "mcp-openapi-schema-explorer",
"args": ["
", "--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": {
"My API Spec (Local Dev)": {
"command": "node",
"args": [
"/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
"
",
"--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 有关设置开发环境、运行测试和提交更改的指南文件。
发布
未来计划
（未来计划待定）
