MCP OpenAPI Schema Explorer

MCP OpenAPI Schema Explorer

一个 MCP（Model Context Protocol）服务，通过 MCP 资源模板高效利用令牌地访问 OpenAPI（v3.0）和 Swagger（v2.0）规范。

项目目标

本项目的主要目标是让 MCP 客户端（例如 Cline 或 Claude Desktop）能够探索大型 OpenAPI 规范的结构和细节，而无需将整个文件加载到大模型的上下文窗口中。它通过 MCP 资源模板公开规范的各个部分，提供参数化访问方式，以便以只读方式探索数据。

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

注意：此服务提供的是资源模板（而非预先枚举的资源）。MCP 客户端通过 resources/templates/list 协议方法访问这些模板。有关资源模板的更多信息，请参阅 MCP 资源模板文档。

为什么使用 MCP 资源模板？

Model Context Protocol 定义了资源和工具。

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

虽然已有其他 MCP 服务通过_工具_提供 OpenAPI 规范访问方式，但本项目专注于通过_资源模板_提供访问。对于大型 API，这种方式尤其高效，因为：

• 无需预先枚举成千上万个可能的路径和组件
• 客户端可以使用模板模式动态发现可用资源
• 可以按需结构化地访问规范中的特定部分

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

各客户端快速入门指南

• Claude Code - Anthropic 的 CLI 工具，用于使用 Claude 编码
• Claude Desktop、Cline、Windsurf - 请参阅下方的安装说明

安装

对于推荐的使用方式（下文介绍的 npx 和 Docker），无需单独安装。MCP 客户端会根据你提供的配置自动下载软件包或拉取 Docker 镜像。

不过，如果你更愿意或需要显式安装服务，有两种选择：

1. **全局安装：**你可以使用 npm 全局安装软件包：

   npm install -g mcp-openapi-schema-explorer
   

   有关如何配置 MCP 客户端以使用全局安装的服务，请参阅下文的方法 3。

2. **本地开发／安装：**你可以克隆代码库并在本地构建：

   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
   cd mcp-openapi-schema-explorer
   npm install
   npm run build
   

   有关如何配置 MCP 客户端，使用 node 从本地构建运行服务，请参阅下文的方法 4。

将服务添加到 MCP 客户端

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

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

方法 1：npx（推荐）

推荐使用 npx，因为它无需全局或本地安装，并能确保客户端使用最新发布的版本。

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

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

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

配置说明：

• 将 "My API Spec (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 方法）：

将以下 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 全局安装软件包，可以配置客户端直接运行它。

# 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": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}

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

方法 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 运行本地构建的服务。

{
  "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://info、openapi://paths/{path}/{method}、openapi://components/{type}/{name}）探索 OpenAPI 规范。
• **支持 OpenAPI v3.0 和 Swagger v2.0：**可加载这两种格式，并自动将 v2.0 转换为 v3.0。
• **本地和远程文件：**可从本地文件路径或 HTTP/HTTPS URL 加载规范。
• **节省令牌：**通过提供结构化访问方式，尽可能减少大模型的令牌用量。
• **多种输出格式：**可获取 JSON（默认）、YAML 或精简 JSON 格式的详细视图（--output-format）。
• **动态服务名称：**MCP 客户端中的服务名称会反映所加载规范中的 info.title。
• **引用转换：**内部 $ref（#/components/...）会转换为可点击的 MCP URI。

可用的 MCP 资源

此服务会公开以下 MCP 资源模板，以供探索 OpenAPI 规范。

重要：此服务提供的是资源模板，而非预先枚举的资源。在使用 MCP 客户端时：

• 客户端调用 resources/templates/list，以发现可用的模板模式
• 然后，你需要通过填写模板参数来构造特定 URI（例如，将 {path} 替换为 users%2F%7Bid%7D）
• 客户端使用你构造的 URI 调用 resources/read，以获取实际内容

如果你调用 resources/list（不带“templates”），将得到空列表——这是预期行为。

了解多值参数（*）

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

资源模板：

• 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%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} 提供动态建议。_仅当_已加载的规范中总共恰好包含一种组件类型时（例如，只有 schemas），才会为 {name*} 提供动态建议。此限制是因为 MCP SDK 目前不支持根据所选 {type} 提供范围限定的补全；提供所有类型的名称可能会造成误导。

贡献

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

发布

本项目使用 semantic-release，根据 Conventional Commits 自动管理版本并发布软件包。

未来计划

（未来计划待定）