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

依賴項

屬性	詳情
模型類型	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)             │  → 常量
└─────────────────────────────────────┘

關鍵設計原則

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/                          # 測試文件

技術棧

技術	版本	用途
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 加載。您可以：

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 許可證