JinDaGe - openapi-search-mcp MCP Details

article

README

🚀 OpenAPI Search MCP Server

OpenAPI Search MCP Server 是一个强大的模型上下文协议（MCP）服务器，用于加载、解析和查询 OpenAPI/Swagger 文档。它能让 AI 助手和其他 MCP 客户端轻松访问 OpenAPI/Swagger 文档，提供了 10 种强大的工具，可对多种格式的 API 规范进行加载、搜索和查询。

🚀 快速开始

# 1. 创建 conda 环境
conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 运行服务器
python main.py

完成以上步骤后，服务器就已启动并准备好接受 MCP 连接。

✨ 主要特性

🔄 从 URL 加载：可从任何 HTTP/HTTPS 端点获取 OpenAPI 文档。
💾 内存存储：通过结构化文档存储实现快速访问。
🔍 10 种查询工具：具备全面的 API 探索能力。
📚 多格式支持：自动检测并支持 JSON 和 YAML 格式。
🚀 版本支持：支持 OpenAPI 3.0.x、3.1.x 和 Swagger 2.0。
🏗️ 分层架构：采用模块化设计和依赖注入。
⚡ 快速索引：预建 operationId 和标签索引。
🔐 认证发现：提取安全方案和要求。
🏷️ 基于标签的导航：按功能类别浏览 API。
🎯 精确搜索：可按关键字、方法、标签或组合进行过滤。

📦 安装指南

前提条件

Python 3.12 或更高版本
Conda（推荐）或 venv

步骤 1：克隆仓库

git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

步骤 2：创建虚拟环境

使用 Conda（推荐）：

conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

使用 venv：

python3.12 -m venv .venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

步骤 3：安装依赖

pip install -r requirements.txt

依赖项

| 属性 | 详情 | |------|------| | 模型类型 | FastMCP (>=0.2.0) - MCP 服务器框架 | | 训练数据 | httpx (>=0.27.0) - 用于获取文档的异步 HTTP 客户端
PyYAML (>=6.0) - YAML 解析支持
Pydantic (>=2.0.0) - 类型安全的数据模型 |

🐳 Docker 部署

对于快速且隔离的部署，可以使用 Docker。

前提条件

已安装 Docker（获取 Docker）
Docker Compose（可选，包含在 Docker Desktop 中）

选项 1：使用 Docker Compose（推荐）

这是最简单的部署方式：

# 克隆仓库
git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

# 构建并启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

服务器将在 http://localhost:8848 可用。

选项 2：直接使用 Docker

手动构建并运行：

# 构建镜像
docker build -t openapi-search-mcp:latest .

# 运行容器
docker run -d \
  --name openapi-search-mcp \
  -p 8848:8848 \
  --restart unless-stopped \
  openapi-search-mcp:latest

# 查看日志
docker logs -f openapi-search-mcp

# 停止并移除容器
docker stop openapi-search-mcp
docker rm openapi-search-mcp

Docker 配置

Docker 设置包括：

基础镜像：python:3.12-slim（轻量级）
端口：8848（可通过环境变量配置）
健康检查：自动健康监测
资源限制：可在 docker-compose.yml 中配置
日志记录：使用 JSON 文件驱动并支持日志轮转

环境变量

可以通过设置环境变量来自定义部署：

environment:
  - DEFAULT_HTTP_PORT=8848  # 更改服务器端口
  - PYTHONUNBUFFERED=1      # 启用实时日志

从 Claude Desktop 访问

使用 Docker 时，更新 Claude Desktop 配置以指向 HTTP 端点：

{
  "mcpServers": {
    "openapi-search": {
      "url": "http://localhost:8848"
    }
  }
}

⚙️ 配置

Claude Desktop 集成

要在 Claude Desktop 中使用此 MCP 服务器，请添加以下配置：

macOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

选项 1：使用 Conda

{
  "mcpServers": {
    "openapi-search": {
      "command": "conda",
      "args": [
        "run",
        "-n",
        "openapi-search-mcp",
        "python",
        "/absolute/path/to/openapi-search-mcp/main.py"
      ]
    }
  }
}

选项 2：使用直接 Python 路径

{
  "mcpServers": {
    "openapi-search": {
      "command": "/path/to/conda/envs/openapi-search-mcp/bin/python",
      "args": ["/absolute/path/to/openapi-search-mcp/main.py"]
    }
  }
}

添加配置后，重启 Claude Desktop 以加载 MCP 服务器。

HTTP 模式（独立服务器）

默认情况下，服务器在端口 8848 以 HTTP 模式运行。要进行自定义：编辑 main.py 的第 57 行：

# STDIO 模式（用于 Claude Desktop）
mcp.run()

# 自定义端口的 HTTP 模式
mcp.run(transport="streamable-http", port=8848)

💻 使用示例

可用工具

服务器提供了 10 个 MCP 工具，用于全面的 API 探索：

1. `load_openapi`

从 URL 加载 OpenAPI 文档并保存到内存。 参数：

name（字符串，必需） - 用于后续查询的 API 标识符
url（字符串，必需） - OpenAPI 文档的 URL

示例：

{
  "name": "petstore",
  "url": "https://petstore.swagger.io/v2/swagger.json"
}

响应：

{
  "status": "success",
  "message": "API 'petstore' 加载成功",
  "info": {
    "title": "Swagger Petstore",
    "version": "1.0.0"
  },
  "paths_count": 14,
  "tags_count": 3
}

2. `list_apis`

列出所有已加载的 API 及其基本信息。 参数： 无

响应：

{
  "count": 2,
  "apis": [
    {
      "name": "petstore",
      "title": "Swagger Petstore",
      "version": "1.0.0",
      "paths_count": 14
    }
  ]
}

3. `get_path_details`

获取特定 API 路径的完整文档。 参数：

name（字符串，必需） - API 名称
path（字符串，必需） - API 路径，例如 /users/{id}

示例：

{
  "name": "petstore",
  "path": "/pet/{petId}"
}

响应：

{
  "path": "/pet/{petId}",
  "methods": {
    "get": {
      "summary": "通过 ID 查找宠物",
      "operationId": "getPetById",
      "parameters": [...],
      "responses": {...}
    }
  }
}

4. `list_all_paths`

列出 API 中的所有路径。 参数：

name（字符串，必需） - API 名称

响应：

{
  "count": 14,
  "paths": [
    {
      "path": "/pet",
      "methods": ["post", "put"]
    },
    {
      "path": "/pet/{petId}",
      "methods": ["get", "post", "delete"]
    }
  ]
}

5. `get_operation_by_id`

通过 operationId 进行快速查找。 参数：

name（字符串，必需） - API 名称
operation_id（字符串，必需） - operationId，例如 getUserById

示例：

{
  "name": "petstore",
  "operation_id": "getPetById"
}

响应：

{
  "operation_id": "getPetById",
  "path": "/pet/{petId}",
  "method": "get",
  "details": {
    "summary": "通过 ID 查找宠物",
    "parameters": [...],
    "responses": {...}
  }
}

6. `search_endpoints`

按关键字、方法、标签或组合搜索端点。 参数：

name（字符串，必需） - API 名称
keyword（字符串，可选） - 在路径、摘要、描述中搜索
method（字符串，可选） - HTTP 方法过滤器（GET、POST 等）
tag（字符串，可选） - 标签过滤器

示例：

{
  "name": "petstore",
  "keyword": "pet",
  "method": "GET"
}

响应：

{
  "count": 3,
  "results": [
    {
      "path": "/pet/{petId}",
      "method": "get",
      "operationId": "getPetById",
      "summary": "通过 ID 查找宠物"
    }
  ]
}

7. `list_tags`

列出 API 中的所有标签。 参数：

name（字符串，必需） - API 名称

响应：

{
  "count": 3,
  "tags": [
    {
      "name": "pet",
      "description": "关于您的宠物的一切"
    }
  ]
}

8. `get_endpoints_by_tag`

获取具有特定标签的所有端点（仅概述）。 参数：

name（字符串，必需） - API 名称
tag（字符串，必需） - 标签名称

示例：

{
  "name": "petstore",
  "tag": "pet"
}

响应：

{
  "tag": "pet",
  "count": 8,
  "endpoints": [
    {
      "path": "/pet",
      "method": "post",
      "operationId": "addPet",
      "summary": "添加一只新宠物"
    }
  ]
}

9. `get_schema_details`

从 components/schemas 中获取数据模型定义。 参数：

name（字符串，必需） - API 名称
schema_name（字符串，必需） - 模式名称，例如 User、Pet

示例：

{
  "name": "petstore",
  "schema_name": "Pet"
}

响应：

{
  "schema_name": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"]
}

10. `get_auth_info`

获取认证配置。 参数：

name（字符串，必需） - API 名称

响应：

{
  "security_schemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "global_security": [
    {"bearerAuth": []}
  ]
}

典型工作流

工作流 1：探索新 API

# 步骤 1：加载 API
load_openapi(name="petstore", url="https://petstore.swagger.io/v2/swagger.json")

# 步骤 2：查看存在的标签/类别
list_tags(name="petstore")

# 步骤 3：探索某个类别中的端点
get_endpoints_by_tag(name="petstore", tag="pet")

# 步骤 4：获取特定端点的详细信息
get_path_details(name="petstore", path="/pet/{petId}")

# 步骤 5：检查数据模型
get_schema_details(name="petstore", schema_name="Pet")

工作流 2：查找特定功能

# 搜索与用户相关的 POST 端点
search_endpoints(name="api", keyword="user", method="POST")

# 通过 operationId 快速查找
get_operation_by_id(name="api", operation_id="createUser")

# 获取完整的路径详细信息
get_path_details(name="api", path="/users")

工作流 3：了解认证

# 检查需要的认证方法
get_auth_info(name="api")

📚 详细文档

架构

OpenAPI Search MCP 遵循受企业模式启发的清晰分层架构：

┌─────────────────────────────────────┐
│         main.py (Entry)             │  → 应用程序初始化
├─────────────────────────────────────┤
│    Tools Layer (src/tools/)         │  → MCP 工具定义
├─────────────────────────────────────┤
│   Services Layer (src/services/)    │  → 业务逻辑
├─────────────────────────────────────┤
│  Storage Layer (src/storage.py)     │  → 数据访问
├─────────────────────────────────────┤
│ Loaders/Indexers (src/loaders/,     │  → 实用工具
│                   src/indexers/)    │
├─────────────────────────────────────┤
│  Models (src/models/)               │  → 数据结构
├─────────────────────────────────────┤
│  Config (src/config.py)             │  → 常量
└─────────────────────────────────────┘

关键设计原则

关注点分离：每个层只有单一职责。
依赖注入：服务通过构造函数接收依赖项。
类型安全：全程使用 Pydantic 模型。
面向接口：层与层之间有清晰的契约。
可测试性：每个层都可以独立进行单元测试。

各层说明

配置层：集中管理常量和错误消息。
模型层：具有验证功能的类型安全数据结构。
存储层：内存中的文档存储，具备一致的错误处理。
加载器层：HTTP 获取和格式检测（JSON/YAML）。
索引器层：构建反向索引以实现快速查找。
服务层：业务逻辑（5 个服务：API、路径、模式、搜索、标签）。
工具层：MCP 工具注册（3 个模块）。
入口层：通过依赖注入进行应用程序初始化。

项目结构

openapi-search-mcp/
├── main.py                          # 入口点 (~50 行)
├── requirements.txt                 # Python 依赖项
├── README.md                        # 本文件
├── README.zh.md                     # 中文文档
├── CLAUDE.md                        # Claude Code 指南
├── DESIGN.md                        # 详细设计文档
├── src/                             # 源代码
│   ├── config.py                   # 配置常量
│   ├── storage.py                  # 数据存储层
│   ├── models/                     # 数据模型
│   │   └── openapi_document.py    # Pydantic 模型
│   ├── loaders/                    # 文档加载器
│   │   └── openapi_loader.py      # URL 加载和格式检测
│   ├── indexers/                   # 索引构建器
│   │   └── operation_indexer.py   # operationId 和标签索引
│   ├── services/                   # 业务逻辑
│   │   ├── api_service.py         # API 加载和列表
│   │   ├── path_service.py        # 路径查询
│   │   ├── schema_service.py      # 模式和认证查询
│   │   ├── search_service.py      # 端点搜索
│   │   └── tag_service.py         # 标签查询
│   └── tools/                      # MCP 工具定义
│       ├── loading_tools.py       # load_openapi, list_apis
│       ├── query_tools.py         # 路径、操作、模式查询
│       └── search_tools.py        # 搜索、标签查询
└── tests/                          # 测试文件

技术栈

| 技术 | 版本 | 用途 | |------------|---------|---------| | Python | 3.12+ | 运行时环境 | | FastMCP | >=0.2.0 | MCP 服务器框架 | | httpx | >=0.27.0 | 用于获取文档的异步 HTTP 客户端 | | PyYAML | >=6.0 | YAML 格式解析 | | Pydantic | >=2.0.0 | 类型安全的数据模型和验证 |

支持的 OpenAPI 版本

✅ OpenAPI 3.0.x
✅ OpenAPI 3.1.x
✅ Swagger 2.0 JSON 和 YAML 格式均可自动检测和支持。

常见问题解答

如何加载本地 OpenAPI 文件？

目前仅支持通过 URL 加载。您可以：

使用本地文件服务器：python -m http.server 8000
通过 http://localhost:8000/openapi.json 访问。未来版本将支持直接使用文件路径加载。

重启后文档是否会保留？

不会，文档仅存储在内存中。服务器重启后，您需要重新加载 OpenAPI 文档。这种设计优先考虑了简单性和速度，而非持久性。

如何在 STDIO 和 HTTP 模式之间切换？

编辑 main.py 的第 57 行：

# STDIO 模式（用于 Claude Desktop）
mcp.run()

# HTTP 模式（独立服务器）
mcp.run(transport="streamable-http", port=8848)

能否加载同一 API 的多个版本？

可以，只需使用不同的名称：

load_openapi(name="petstore-v1", url="...")
load_openapi(name="petstore-v2", url="...")

如果加载具有现有名称的 API 会怎样？

新文档将覆盖现有文档。服务器将记录一条警告消息。

开发

运行测试

pytest tests/

代码结构

有关详细的架构文档和开发指南，请参阅 CLAUDE.md。

贡献

欢迎贡献代码！请按以下步骤操作：

分叉仓库
创建功能分支
进行更改
添加测试
提交拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE。

🙏 致谢

本项目在 Claude Code 的协助下开发，Claude Code 是 Anthropic 公司的 AI 编码助手。Claude Code 在以下方面提供了帮助：

架构设计和从单体结构到分层结构的重构
使用依赖注入实现服务层
文档编写和代码组织
Python 企业开发的最佳实践本项目展示了人机协作在软件开发中的强大力量。

🔗 链接

使用 Claude Code 构建 • OpenAPI Search MCP Server • MIT 许可证

openapi-search-mcp

README

🚀 OpenAPI Search MCP Server

🚀 快速开始

✨ 主要特性

📦 安装指南

前提条件

步骤 1：克隆仓库

步骤 2：创建虚拟环境

步骤 3：安装依赖

依赖项

🐳 Docker 部署

前提条件

选项 1：使用 Docker Compose（推荐）

选项 2：直接使用 Docker

Docker 配置

环境变量

从 Claude Desktop 访问

⚙️ 配置

Claude Desktop 集成

选项 1：使用 Conda

选项 2：使用直接 Python 路径

HTTP 模式（独立服务器）

💻 使用示例

可用工具

1. load_openapi

2. list_apis

3. get_path_details

4. list_all_paths

5. get_operation_by_id

6. search_endpoints

7. list_tags

8. get_endpoints_by_tag

9. get_schema_details

10. get_auth_info

典型工作流

工作流 1：探索新 API

工作流 2：查找特定功能

工作流 3：了解认证

📚 详细文档

架构

关键设计原则

各层说明

项目结构

技术栈

支持的 OpenAPI 版本

常见问题解答

如何加载本地 OpenAPI 文件？

重启后文档是否会保留？

如何在 STDIO 和 HTTP 模式之间切换？

能否加载同一 API 的多个版本？

如果加载具有现有名称的 API 会怎样？

开发

运行测试

代码结构

贡献

📄 许可证

🙏 致谢

🔗 链接

Runtime guide

Hosted runtime

Local runtime / other methods

1. `load_openapi`

2. `list_apis`

3. `get_path_details`

4. `list_all_paths`

5. `get_operation_by_id`

6. `search_endpoints`

7. `list_tags`

8. `get_endpoints_by_tag`

9. `get_schema_details`

10. `get_auth_info`