MCP OpenAPI Schema Explorer

一个提供通过MCP资源高效访问OpenAPI (v3.0) 和 Swagger (v2.0) 规范的MCP（Model Context Protocol）服务器。

项目目标

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

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

为什么使用MCP资源？

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

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

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

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

安装

对于推荐的使用方法（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 运行服务器：

{
  "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": {}
    }
  }
}

• 确保 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 运行本地构建的服务。

{
  "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/..., 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。
• 引用转换： 内部 $refs (#/components/...) 被转换为可点击的 MCP URI。

可用的 MCP 资源

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

理解多值参数 (*)

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

资源模板：

• openapi://{field}

  • Description: Accesses top-level fields of the OpenAPI document (e.g., info, servers, tags) or lists the contents of paths or components. The specific available fields depend on the loaded specification.
  • Example: openapi://info
  • Output: text/plain list for paths and components; configured format (JSON/YAML/minified JSON) for other fields.
  • Completions: Provides dynamic suggestions for {field} based on the actual top-level keys found in the loaded spec.

• openapi://paths/{path}

  • Description: Lists the available HTTP methods (operations) for a specific API path.
  • Parameter: {path} - The API path string. Must be URL-encoded (e.g., /users/{id} becomes users%2F%7Bid%7D).
  • Example: openapi://paths/users%2F%7Bid%7D
  • Output: text/plain list of methods.
  • Completions: Provides dynamic suggestions for {path} based on the paths found in the loaded spec (URL-encoded).

• openapi://paths/{path}/{method*}

  • Description: Gets the detailed specification for one or more operations (HTTP methods) on a specific API path.
  • Parameters:
    • {path} - The API path string. Must be URL-encoded.
    • {method*} - One or more HTTP methods (e.g., get, post, get,post). Case-insensitive.
  • Example (Single): openapi://paths/users%2F%7Bid%7D/get
  • Example (Multiple): openapi://paths/users%2F%7Bid%7D/get,post
  • Output: Configured format (JSON/YAML/minified JSON).
  • Completions: Provides dynamic suggestions for {path}. Provides static suggestions for {method*} (common HTTP verbs like GET, POST, PUT, DELETE, etc.).

• openapi://components/{type}

  • Description: Lists the names of all defined components of a specific type (e.g., schemas, responses, parameters). The specific available types depend on the loaded specification. Also provides a short description for each listed type.
  • Example: openapi://components/schemas
  • Output: text/plain list of component names with descriptions.
  • Completions: Provides dynamic suggestions for {type} based on the component types found in the loaded spec.

• openapi://components/{type}/{name*}

  • Description: Gets the detailed specification for one or more named components of a specific type.
  • Parameters:
    • {type} - The component type.
    • {name*} - One or more component names (e.g., User, Order, User,Order). Case-sensitive.
  • Example (Single): openapi://components/schemas/User
  • Example (Multiple): openapi://components/schemas/User,Order
  • Output: Configured format (JSON/YAML/minified JSON).
  • Completions: Provides dynamic suggestions for {type}. Provides dynamic suggestions for {name*} only if the loaded spec contains exactly one component type overall (e.g., only schemas). This limitation exists because the MCP SDK currently doesn't support providing completions scoped to the selected {type}; providing all names across all types could be misleading.

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件以获取设置开发环境、运行测试和提交更改的指南。

发布

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

未来计划

（未来计划待定）