MCP OpenAPI Explorer

MCP OpenAPI Explorer

一个 Model Context Protocol（MCP）服务，用于分析 OpenAPI 规范，并提供与 API 交互的相关上下文。

功能

• 从各种来源（GitHub、本地文件、HTTP URL）加载 OpenAPI 规范
• 解析 API 端点并提供全面的上下文
• 通过 stdin/stdout 支持 Model Context Protocol（MCP）
• 为大模型提供关于 API 交互的智能上下文
• 支持 JSON 和 YAML 格式的 OpenAPI 规范
• 使用 Cobra CLI 构建，便于通过命令行使用
• 使用 Zap 实现结构化日志记录

开始使用

前提条件

• Go 1.24.2 或更高版本
• Docker（可选）

安装

1. 克隆仓库：

git clone https://github.com/krypticlabs/mcp-openapi-explorer.git
cd mcp-openapi-explorer

2. 安装依赖项：

go mod download

3. 构建：

go build

配置

MCP OpenAPI Explorer 可以使用 YAML 配置文件进行配置。你可以使用以下命令导出默认配置文件：

./mcp-openapi-explorer config export config.yaml

然后，根据需要修改配置文件，并使用以下命令运行服务：

./mcp-openapi-explorer --config config.yaml serve

创建 GitHub Token

如果你需要访问私有 GitHub 仓库，或希望在从 GitHub 加载 OpenAPI 规范时避免速率限制，则需要 GitHub Token：

1. 前往 GitHub 设置
2. 在左侧边栏中选择 Developer settings
3. 选择 Personal access tokens → Fine-grained tokens
4. 点击 Generate new token → Generate new token
5. 为 Token 设置一个描述性名称和说明
6. 仓库访问权限：仅选择仓库
   • 然后选择要授予此 PAT 访问权限的仓库
7. 权限：
   • 只需授予 contents 权限，并设置为只读访问
8. 点击 Generate token
9. 复制 Token（之后将无法再次查看！）

将此 Token 添加到配置文件中，或通过环境变量 MCP_OPENAPI_GITHUB_TOKEN 提供。

配置 MCP 客户端

你可以将 MCP OpenAPI Explorer 添加到 MCP 客户端配置中，以便与 MCP 客户端集成。这样，客户端就能自动启动并与 MCP 服务通信。

下载二进制文件

从 GitHub Releases 页面下载适用于你平台的二进制文件。

MCP 客户端配置

将 MCP OpenAPI Explorer 添加到 MCP 客户端配置文件中（通常为 ~/.mcp/config.json 或类似文件）：

{
  "mcpServers": {
    "openapi-explorer": {
      "command": "/path/to/mcp-openapi-explorer",
      "args": ["serve", "--config", "~/.mcp-openapi.yaml"]
    }
  }
}

将 /path/to/mcp-openapi-explorer 替换为系统中该二进制文件的实际路径。environment 部分为可选项，可用于为 MCP 服务设置环境变量。

MCP 用法

MCP 服务通过 stdin/stdout 运行，这是与大模型集成的首选方式。它可以避免网络配置的复杂性，并且适用于各种大模型集成。

启动服务

./mcp-openapi-explorer serve

选项：

• -v, --verbose - 启用详细输出
• -c, --config string - 配置文件路径

GitHub 仓库支持

你可以直接从 GitHub 仓库加载 OpenAPI 规范，也可以使用 Token 加载私有仓库中的规范：

specs:
  - "@github.com/yourOrg/yourRepo/blob/main/pathToSpec.json|yaml"

可用的 MCP 工具

MCP 服务提供以下工具：

get_api_info

获取已加载的 OpenAPI 规范中 API 端点的全面信息。

参数：

• query（字符串，必填）：关于 API 端点的查询（例如：“如何创建新用户？”、“宠物管理有哪些可用端点？”）

load_api_spec

从 URL 或文件路径加载 OpenAPI 规范。

参数：

• url（string，必需）：OpenAPI 规范的 URL 或文件路径。支持：
  • HTTP/HTTPS URL（例如：'https://petstore3.swagger.io/api/v3/openapi.json'）
  • 带有 '@' 前缀的 GitHub URL（例如：'@github.com/org/repo/blob/main/api.yaml'）
  • 本地文件路径（例如：'file:///path/to/spec.json' 或仅为 '/path/to/spec.json'）
  • 支持 JSON 和 YAML 格式

使用指定的配置文件加载新的 API 规范时，规范 URL 将自动添加到配置文件的 specs 列表中，以便持久保存。

list_api_specs

列出所有已加载的 OpenAPI 规范。

delete_api_spec

删除已加载的 OpenAPI 规范。

参数：

• spec_id（string，必需）：要删除的 API 规范 ID（使用 list_api_specs 查看可用规范）

使用指定的配置文件删除 API 规范时，规范 URL 将自动从配置文件的 specs 列表中移除，以便持久保存。

refresh_api_spec

通过从源重新下载，刷新一个或多个 OpenAPI 规范。

参数：

• spec_id（string，可选）：要刷新的 API 规范 ID。若未提供，则刷新所有已加载的规范。

获取 API 端点信息

echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_api_info","arguments":{"query":"How do I find pets by status?"}}}' | ./mcp-openapi-explorer serve

删除已加载的 API 规范

echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"delete_api_spec","arguments":{"spec_id":"Swagger Petstore - OpenAPI 3.0"}}}' | ./mcp-openapi-explorer serve

刷新所有已加载的 API 规范

echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"refresh_api_spec","arguments":{}}}' | ./mcp-openapi-explorer serve

刷新指定的 API 规范

echo '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"refresh_api_spec","arguments":{"spec_id":"Swagger Petstore - OpenAPI 3.0"}}}' | ./mcp-openapi-explorer serve

工作原理

1. 用户将 OpenAPI 规范加载到服务中（在配置文件中配置）
2. 服务解析并存储这些规范（同时支持 JSON 和 YAML 格式）
3. 用户询问 API 端点相关问题时，服务会提供所有可用端点的完整上下文
4. 大模型利用此上下文准确回答用户的问题

Docker

docker build -t mcp-openapi-explorer .

# Run the server with input from stdin
docker run -i mcp-openapi-explorer serve < your-jsonrpc-request.json

# Run the server with a configuration file
docker run -i -v $(pwd)/config.yaml:/app/config.yaml mcp-openapi-explorer --config /app/config.yaml serve

许可证

MIT