MCP 4get

🚀 4get MCP 服務器

這是一個 MCP 服務器，它通過 FastMCP 為大語言模型（LLM）客戶端提供無縫訪問 4get 元搜索引擎 API 的能力。

🚀 快速開始

# 安裝依賴
uv sync

# 運行服務器
uv run -m mcp_4get

# 或者使用 mise
mise run

✨ 主要特性

• 🔍 多搜索功能：支持網頁、圖像和新聞搜索，並提供全面的結果格式化。
• ⚡ 智能緩存：基於 TTL 的響應緩存，可配置緩存大小限制。
• 🔄 重試邏輯：針對速率限制和網絡錯誤採用指數退避策略。
• 🏗️ 生產就緒：具備連接池、全面的錯誤處理和驗證功能。
• 📊 豐富響應：包含特色答案、相關搜索、分頁支持等。
• 🧪 充分測試：擁有廣泛的測試套件，包括與真實 API 的集成測試、單元測試等。
• ⚙️ 高度可配置：支持 11 個以上的環境變量進行精細調整。
• 🎯 引擎簡寫：可通過 engine 參數選擇 4get 抓取器，無需記憶查詢字符串。

📦 安裝指南

環境要求

• Python 3.13+
• 使用 uv 進行依賴管理

安裝步驟

# 安裝依賴
uv sync

💻 使用示例

基礎用法

import asyncio
from mcp_4get.client import FourGetClient
from mcp_4get.config import Config

async def main() -> None:
    client = FourGetClient(Config.from_env())
    data = await client.web_search(
        "model context protocol",
        options={"scraper": "mullvad_brave"},
    )
    for result in data.get("web", []):
        print(result["title"], "->", result["url"])

asyncio.run(main())

高級用法

分頁使用示例

# 獲取第一頁
result = await client.web_search("python programming")

# 如果有下一頁，獲取下一頁
if result.get('npt'):
    next_page = await client.web_search("ignored", page_token=result['npt'])

📚 詳細文檔

⚙️ 配置

服務器可通過環境變量進行高度配置。對於公共的 https://4get.ca 實例，所有設置都有合理的默認值。

核心設置

緩存與性能

重試與彈性

🚀 運行服務器

本地開發

uv run -m mcp_4get

生產部署

# 使用自定義配置
export FOURGET_BASE_URL="https://my-4get-instance.com"
export FOURGET_PASS="my-secret-token"
export FOURGET_CACHE_TTL="300"
export FOURGET_MAX_RETRIES="5"

uv run -m mcp_4get

MCP 服務器集成

你可以將 4get MCP 服務器與流行的 IDE 和 AI 助手集成。以下是配置示例：

Cursor IDE

將以下內容添加到你的 Cursor MCP 配置文件（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "4get": {
      "command": "uvx",
      "args": [
        "mcp_4get@latest"
      ],
      "env": {
        "FOURGET_BASE_URL": "https://4get.ca"
      }
    }
  }
}

OpenAI Codex

將以下內容添加到你的 Codex MCP 配置文件（~/.codex/config.toml）中：

[mcp_servers.4get]
command = "uvx"
args = ["mcp_4get@latest"]
env = { FOURGET_BASE_URL = "https://4get.ca" }

注意：請將 /path/to/your/mcp-4get 替換為你項目目錄的實際路徑。

🔧 MCP 工具

服務器提供了三個強大的搜索工具，並具備全面的響應格式化功能：

fourget_web_search

fourget_web_search(
    query: str,
    page_token: str = None,        # 使用上一次響應中的 'npt'
    extended_search: bool = False, # 啟用擴展搜索模式
    engine: str = None,             # 從支持的引擎列表中選擇一個抓取器
    extra_params: dict = None      # 語言、地區等參數
)

響應包含：web[]、answer[]、spelling、related[]、npt

fourget_image_search

fourget_image_search(
    query: str,
    page_token: str = None,   # 使用上一次響應中的 'npt'
    engine: str = None,       # 從支持的引擎列表中選擇一個抓取器
    extra_params: dict = None # 大小、顏色、類型過濾器
)

響應包含：image[]、npt

fourget_news_search

fourget_news_search(
    query: str,
    page_token: str = None,   # 使用上一次響應中的 'npt'
    engine: str = None,       # 從支持的引擎列表中選擇一個抓取器
    extra_params: dict = None # 日期範圍、來源過濾器
)

響應包含：news[]、npt

引擎簡寫

所有 MCP 工具都接受一個可選的 engine 參數，該參數直接映射到 4get 的 scraper 查詢參數。此簡寫會覆蓋你在 extra_params 中可能包含的任何 scraper 值。

如果你需要傳遞其他 4get 查詢參數（如 country 或 language），請繼續通過 extra_params 提供。

📊 響應格式

基於真實的 4get API，響應包含豐富的元數據：

{
  "status": "ok",
  "web": [
    {
      "title": "示例結果",
      "description": "結果描述...",
      "url": "https://example.com",
      "date": 1640995200,
      "type": "web"
    }
  ],
  "answer": [
    {
      "title": "特色答案",
      "description": [{"type": "text", "value": "答案內容..."}],
      "url": "https://source.com",
      "table": {"Key": "Value"}
    }
  ],
  "spelling": {
    "type": "no_correction",
    "correction": null
  },
  "related": ["相關搜索", "術語"],
  "npt": "分頁令牌"
}

開發

本項目使用了幾個工具來簡化開發流程：

mise

mise 用於管理項目級別的依賴項和環境變量。它有助於確保不同機器上的開發環境一致。

要開始使用 mise：

1. 按照 官方網站 上的說明安裝 mise。
2. 在項目根目錄下運行 mise install 來設置開發環境。

環境變量覆蓋：你可以通過在項目根目錄下創建一個 .mise.local.toml 文件來覆蓋任何環境變量：

[env]
FOURGET_BASE_URL = "https://your-custom-4get-instance.com"
FOURGET_CACHE_TTL = "300"
# 添加你想要覆蓋的任何其他環境變量

這個文件會被 mise 自動加載，允許你自定義本地開發環境，而無需修改共享配置文件。

UV

UV 用於依賴管理和打包。它提供了一種簡潔、版本可控的方式來管理項目依賴項。

要使用 UV 設置項目：

1. 使用 mise 安裝 UV，或按照 官方網站 上的說明進行安裝。
2. 運行 uv sync 來安裝項目依賴項。

本地開發的 MCP 服務器集成

Cursor IDE

將以下內容添加到你的 Cursor MCP 配置文件（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "4get": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/your/mcp-4get",
        "-m",
        "src"
      ],
      "env": {
        "FOURGET_BASE_URL": "https://4get.ca"
      }
    }
  }
}

OpenAI Codex

將以下內容添加到你的 Codex MCP 配置文件（~/.codex/config.toml）中：

[mcp_servers.4get]
command = "uv"
args = ["run", "--project", "/path/to/your/mcp-4get", "-m", "src"]
env = { FOURGET_BASE_URL = "https://4get.ca" }

注意：請將 /path/to/your/mcp-4get 替換為你項目目錄的實際路徑。

🧪 測試

擁有全面的測試套件，包括單元測試、集成測試和性能測試：

# 運行所有測試
uv run pytest

# 僅運行快速單元測試（排除集成測試）
uv run pytest -m "not integration"

# 運行與真實 4get API 的集成測試
uv run pytest -m integration

# 運行測試並生成覆蓋率報告
uv run pytest --cov=src

# 運行特定測試類別
uv run pytest tests/test_cache.py      # 緩存行為測試
uv run pytest tests/test_client.py     # 客戶端和重試邏輯測試
uv run pytest tests/test_integration.py # 真實 API 集成測試

測試類別

• 單元測試：使用模擬傳輸進行快速、確定性的測試。
• 集成測試：對真實 API 進行測試，並驗證速率限制和彈性。
• 緩存測試：測試 TTL 過期、淘汰策略和併發訪問。
• 重試測試：測試指數退避、錯誤處理和超時場景。
• 配置測試：驗證配置邏輯和環境變量解析。

這些測試遵循 FastMCP 測試指南，具備全面的測試固件和適當的隔離。

🤝 貢獻

1. 設置環境：請參閱 開發 和 快速開始 部分。
2. 運行測試：請參閱 測試 部分。
3. 代碼檢查：運行 uv run ruff check。
4. 代碼格式化：運行 uv run ruff format。

📄 許可證

本項目採用 GPLv3 許可證，詳情請參閱 LICENSE 文件。