Openapi Search MCP

🚀 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

依赖项

🐳 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)             │  → 常量
└─────────────────────────────────────┘

关键设计原则

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

各层说明

• 配置层：集中管理常量和错误消息。
• 模型层：具有验证功能的类型安全数据结构。
• 存储层：内存中的文档存储，具备一致的错误处理。
• 加载器层：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/                          # 测试文件

技术栈

支持的 OpenAPI 版本

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

常见问题解答

如何加载本地 OpenAPI 文件？

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

1. 使用本地文件服务器：python -m http.server 8000
2. 通过 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。

贡献

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

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

📄 许可证

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

🙏 致谢

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

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

🔗 链接

• FastMCP 文档
• OpenAPI 规范
• 模型上下文协议

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