Swagger Explorer MCP 使用说明

项目简介

Swagger Explorer MCP 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在帮助大型语言模型 (LLM) 理解和探索 Swagger/OpenAPI API 文档。通过此 MCP 服务器，LLM 客户端可以方便地获取 API 的各种信息，例如接口路径、请求方法、请求/响应参数结构等，从而更好地理解和使用 API。

主要功能点

API 路径探索: 列出 Swagger/OpenAPI 文档中定义的所有 API 路径及其支持的 HTTP 方法。
Schema 分析: 提取和分析 API 文档中定义的 Schema (数据模型)，帮助 LLM 理解数据结构。
响应 Schema 获取: 针对特定的 API 路径和 HTTP 方法，获取其可能的响应 Schema，包括成功和错误响应。
认证支持: 支持基于 Bearer Token 的身份验证，确保 API 使用的安全性。
灵活的响应格式: 提供 Minimal、Detailed 等多种响应格式，满足不同场景的需求。

安装步骤

本 MCP 服务器可以通过 'npx' 命令快速安装和运行：

确保您的环境中已安装 Node.js 和 npm。

打开终端，运行以下命令即可安装并启动 Swagger Explorer MCP 服务器：

npx -y @johnneerdael/swagger-mcp

或者，您可以使用以下命令并设置环境变量来配置服务器：

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

服务器配置

对于 MCP 客户端（例如 Claude Desktop），您需要添加一个新的 MCP 服务器连接。配置信息如下：

{
  "serverName": "Swagger Explorer",
  "command": "npx",
  "args": ["-y", "@johnneerdael/swagger-mcp"]
}

参数说明:

serverName: 服务器名称，可以自定义，例如 "Swagger Explorer"。
command: 启动服务器的命令，这里使用 'npx' 来运行 npm 包。
args: 传递给 'npx' 命令的参数，包括 '-y' (自动确认安装) 和 '@johnneerdael/swagger-mcp' (要运行的 npm 包名)。

基本使用方法

在 MCP 客户端中成功添加并连接到 Swagger Explorer MCP 服务器后。
您可以向 LLM (例如 Claude) 发出自然语言指令，指示其使用 Swagger Explorer MCP 来探索 Swagger/OpenAPI 文档。
例如，您可以提问：
- "请探索位于 [Swagger 文档 URL] 的 Swagger 文档。"
- "'/pets' POST 接口有哪些响应 schema？"
- "请展示 Pet schema 的详细结构。"

LLM 将会调用 Swagger Explorer MCP 服务器来获取所需的信息，并返回分析结果。

注意:

确保您提供的 Swagger 文档 URL 可以被服务器访问。
如果配置了 'AUTH_TOKEN' 环境变量，则所有 API 请求都需要在 Header 中包含有效的 Bearer Token。

关键词

Swagger Explorer MCP 使用说明

信息