MCP 4get

🚀 4get MCP Server

FastMCP を介して、LLMクライアントに 4get Meta Search engine APIへのシームレスなアクセスを提供する MCPサーバー です。

✨ 主な機能

• 🔍 複数の検索機能：ウェブ、画像、ニュース検索が可能で、結果は包括的に整形されます。
• ⚡ スマートキャッシュ：TTLベースのレスポンスキャッシュで、サイズ制限を設定可能です。
• 🔄 リトライロジック：レート制限やネットワークエラーに対して指数バックオフを行います。
• 🏗️ 本番環境対応：コネクションプーリング、包括的なエラーハンドリング、バリデーションが備わっています。
• 📊 充実したレスポンス：注目の回答、関連検索、ページネーションサポートなどがあります。
• 🧪 十分にテスト済み：実際のAPIとの統合テスト、単体テストなど、広範なテストスイートがあります。
• ⚙️ 高度に設定可能：11以上の環境変数で微調整が可能です。
• 🎯 エンジンの省略形：engineパラメータで4getのスクレイパーを選択でき、クエリ文字列を覚える必要がありません。

📋 必要条件

• Python 3.13以上
• 依存関係管理に uv を使用

🚀 クイックスタート

# 依存関係のインストール
uv sync

# サーバーの起動
uv run -m mcp_4get

# またはmiseを使用
mise run

⚙️ 設定

サーバーは環境変数を通じて高度に設定可能です。すべての設定には、公開されている 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ツール

サーバーは、包括的なレスポンス整形を備えた3つの強力な検索ツールを公開しています。

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 を通じて提供してください。

📄 ページネーション

すべてのツールは、npt（次のページトークン）を介してページネーションをサポートしています。

# 最初のページを取得
result = await client.web_search("python programming")

# 次のページがある場合は取得
if result.get('npt'):
    next_page = await client.web_search("ignored", page_token=result['npt'])

🐍 非同期クライアントを直接使用する

MCPの外で同梱されている非同期クライアントを再利用して、直接APIにアクセスすることができます。

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())

これにより、MCPプロトコルを介さずに、4getの検索機能をPythonアプリケーションに直接統合することができます。

🛡️ エラーハンドリングと回復力

自動リトライロジック

• レート制限（429）：ジッター付きの指数バックオフを行います。
• ネットワークエラー：接続失敗やタイムアウトに対応します。
• リトライ不可：HTTP 404/500エラーは即座に失敗します。

エラータイプ

• FourGetAuthError：レート制限または無効な認証
• FourGetAPIError：APIが成功以外のステータスを返しました。
• FourGetTransportError：ネットワークまたはHTTPプロトコルエラー
• FourGetError：一般的なクライアントエラー

設定のバリデーション

すべての設定は起動時に検証され、設定ミスに対して明確なエラーメッセージが表示されます。

📊 レスポンス形式

実際の4get APIに基づいて、レスポンスには充実したメタデータが含まれています。

{
  "status": "ok",
  "web": [
    {
      "title": "Example Result",
      "description": "Result description...",
      "url": "https://example.com",
      "date": 1640995200,
      "type": "web"
    }
  ],
  "answer": [
    {
      "title": "Featured Answer",
      "description": [{"type": "text", "value": "Answer content..."}],
      "url": "https://source.com",
      "table": {"Key": "Value"}
    }
  ],
  "spelling": {
    "type": "no_correction",
    "correction": null
  },
  "related": ["related search", "terms"],
  "npt": "pagination_token_here"
}

🧪 テスト

単体テスト、統合テスト、パフォーマンステストを含む包括的なテストスイートがあります。

# すべてのテストを実行
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ファイルを参照してください。