关键词

OpenAPISwaggerAPI ExplorerSchema Browser

项目简介

OpenAPI Schema Explorer 是一个实现了 Model Context Protocol (MCP) 的服务器，专为大语言模型（LLM）客户端设计。其主要目标是通过 MCP 标准化的 资源 (Resources) 机制，让 LLM 客户端能够高效地访问和探索大型 OpenAPI (v3.0) 或 Swagger (v2.0) 规范的结构和详细内容，而无需将整个规范文件加载到 LLM 的上下文窗口中，从而节省 Token。

它支持从本地文件路径或远程 HTTP/HTTPS URL 加载规范，并能自动将 Swagger v2.0 规范转换为 OpenAPI v3.0。

主要功能点

  • MCP 资源访问: 以结构化的方式暴露 OpenAPI/Swagger 规范的各个部分（如 'info', 'paths', 'components'）作为 MCP 资源，通过 URI 进行访问，例如 'openapi://info', 'openapi://paths', 'openapi://components/schemas'。
  • Token 高效: 允许客户端按需获取规范的特定部分，而不是加载整个文档，大幅降低 LLM 处理大规范时的 Token 消耗。
  • 格式转换: 自动识别并转换 Swagger v2.0 规范为 OpenAPI v3.0。
  • 多种来源支持: 可加载本地文件或远程 URL 的规范。
  • 输出格式定制: 支持 JSON (默认)、YAML、精简 JSON 等多种输出格式，方便客户端消费。
  • URI 引用转换: 将规范中的内部 '$ref' 引用（如 '#/components/schemas/User'）转换为可点击的 MCP URI（如 'openapi://components/schemas/User'），便于在客户端中直接跳转查看引用内容。
  • 动态服务器名称: MCP 客户端中显示的服务器名称会根据加载的规范标题 ('info.title') 动态生成。
  • 参数补全: 支持 MCP 客户端在输入资源 URI 时，对路径、方法、组件类型和名称进行动态补全提示。

安装步骤

通常情况下，您无需手动安装此服务器。大多数 MCP 客户端（如 Claude Desktop）在配置中指定使用 'npx' 或 'Docker' 启动服务器时，会自动下载并运行所需代码。

如果需要手动全局安装，可以使用 npm：

npm install -g mcp-openapi-schema-explorer

之后可以通过 'mcp-openapi-schema-explorer' 命令直接运行。

服务器配置（MCP 客户端配置）

此服务器主要由 MCP 客户端启动和管理。您需要在您的 MCP 客户端（通常在其配置文件的 'mcpServers' 部分）中添加一个条目来告诉客户端如何运行此服务器，并指定要加载的 OpenAPI/Swagger 规范路径或 URL。

以下是常见的配置结构（以 JSON 格式为例），您需要将其添加到客户端的配置中，而不是直接运行这些命令：

{
  "mcpServers": {
    "一个自定义的服务器名称": {
      // 启动服务器的命令
      "command": "...",
      // 传递给命令的参数列表
      "args": [
        // 通常第一个参数是规范文件的路径或URL
        "<您要加载的规范文件路径或URL，请替换此占位符>",
        // 可选参数：指定输出格式，默认为json
        "--output-format", "json" // 或 "yaml", "json-minified"
      ],
      // 环境变量（通常留空）
      "env": {}
    }
  }
}

常用的 'command' 和 'args' 组合示例:

  • 使用 npx (推荐): 
    // ... 在 mcpServers 下
"我的API规范 (npx)": {
  "command": "npx",
  "args": [
    "-y", // 自动确认安装
    "mcp-openapi-schema-explorer@latest", // 包名称和版本
    "<您的规范文件路径或URL>",
    "--output-format", "yaml" // 例如，指定 YAML 格式
  ],
  "env": {}
}
  • 使用 Docker: 
    // ... 在 mcpServers 下，加载远程 URL
"Petstore (Docker)": {
  "command": "docker",
  "args": [
    "run", "--rm", "-i", // Docker 参数
    "kadykov/mcp-openapi-schema-explorer:latest", // Docker 镜像名称
    "https://petstore3.swagger.io/api/v3/openapi.json" // 远程 URL
  ],
  "env": {}
},
// ... 或加载本地文件，需要挂载卷
"我的本地规范 (Docker)": {
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "/完整的本地文件路径:/spec/api.yaml", // 将本地文件挂载到容器内指定路径
    "kadykov/mcp-openapi-schema-explorer:latest",
    "/spec/api.yaml", // 使用容器内的路径
    "--output-format", "json-minified"
  ],
  "env": {}
}

请注意:

  • 您需要将 '"一个自定义的服务器名称"' 替换为一个唯一的、易于识别的名称。
  • 您需要将 '<您要加载的规范文件路径或URL>' 替换为您实际的 OpenAPI/Swagger 规范的绝对本地路径或完整 URL。
  • 如果您想探索多个规范，请在 'mcpServers' 中添加多个独立的条目，每个条目指向一个不同的规范。

基本使用方法

  1. 在您的 MCP 客户端中，找到配置文件的位置，并按照上述示例添加一个或多个 MCP 服务器配置条目，指向您要探索的 OpenAPI/Swagger 规范。
  2. 保存配置文件并重启您的 MCP 客户端。
  3. 客户端通常会在需要时（例如，您在客户端界面中选择这个服务器时）自动启动配置的 MCP 服务器进程。
  4. 在客户端的交互界面（如聊天框、资源浏览器），您可以使用特定的 MCP URI 来访问规范的内容。对于此服务器，URI 以 'openapi://' 开头。
    • 要查看规范的顶级信息（如 info, servers），使用 'openapi://<字段名>'，例如 'openapi://info' 或 'openapi://servers'。
    • 要查看所有路径列表，使用 'openapi://paths'。
    • 要查看某个具体路径有哪些方法（GET, POST 等），使用 'openapi://paths/<已编码的路径>'，例如对于 '/users/{id}' 路径，应使用 'openapi://paths/users%2F%7Bid%7D'。
    • 要查看某个路径下特定方法（操作）的详细信息，使用 'openapi://paths/<已编码的路径>/<方法>'，例如 'openapi://paths/users%2F%7Bid%7D/get'。您也可以用逗号分隔同时请求多个方法，例如 'openapi://paths/users%2F%7Bid%7D/get,post'。
    • 要查看组件类型列表（如 schemas, responses），使用 'openapi://components'。
    • 要查看某个组件类型下的所有组件名称列表，使用 'openapi://components/<组件类型>'，例如 'openapi://components/schemas'。
    • 要查看某个具体组件的详细信息，使用 'openapi://components/<组件类型>/<组件名称>'，例如 'openapi://components/schemas/User'。您也可以用逗号分隔同时请求多个组件，例如 'openapi://components/schemas/User,Order'。
  5. 客户端会向服务器发送相应的请求，服务器将返回规范中对应部分的结构化数据（根据您配置的输出格式），LLM 或客户端界面可以利用这些信息来回答关于 API 的问题、生成代码等。

信息

分类

网页与API

访问项目