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 文件。