Odysseus Web MCP

Odysseus Web MCP — AI アシスタント向けの安全なウェブ検索・取得サーバー

Odysseus Web MCP は、安全な公開ウェブ検索と URL 取得のためのスタンドアロンの Model Context Protocol（MCP）サーバーです。stdio 経由でローカル実行され、MCP 対応の AI アシスタントに 2 つの情報取得ツールを提供します。web_search は情報源を見つけ、web_fetch は公開 URL を取得して内容を抽出します。

Claude Code、Cursor、Codex などのクライアント向けに構築されており、検索プロバイダーのフォールバック、読みやすい HTML／PDF／テキストの抽出、オプションの JavaScript レンダリングに加え、DNS 検証やリダイレクトの再確認を含む SSRF 対策を備えています。

機能

• プロバイダーのフォールバックと、順位付けされ情報源が明示された結果により、公開ウェブを検索します。
• 公開 URL から HTML、PDF、テキストのコンテンツを取得して抽出します。
• パブリックネットワークの確認、DNS 検証、リダイレクトの再検証により、SSRF を防ぎます。
• カーソル、品質指標、検出したリンクを含む、上限付きの証拠重視の出力を返します。
• 必要に応じて、分離された Playwright で JavaScript を多用するページをレンダリングします。

数分でインストール

要件：Python 3.11 以降と uv。

# after downloading/extracting this folder (or cloning your copy)
cd odysseus-web-mcp
uv venv .venv
uv pip install -e '.[dev]'
./run-web-mcp.sh

サーバーは stdio 経由で通信するため、ウェブポートを開かず、 ホストアプリケーションの Python 環境にインストールする必要もありません。 MCP クライアントにランチャーの絶対パスを登録します。

{
  "name": "odysseus-web-mcp",
  "command": "/absolute/path/to/odysseus-web-mcp/run-web-mcp.sh",
  "args": [],
  "cwd": "/absolute/path/to/odysseus-web-mcp"
}

ランチャーはパッケージの .venv を自動的に使用します。状態はデフォルトで ~/.local/share/odysseus-web-mcp に保存されます。別の場所に保存するには WEB_MCP_DATA_DIR を設定してください。デフォルトのフォールバック経路では API キーは不要ですが、 これらのプロバイダーを使う場合は Brave、Tavily、Serper のキーを追加できます。

2 つのツール

web_search

焦点を絞った質問の情報源を見つけるために使用します。1～3 件のクエリに加え、 任意のモード、分野、新しさの条件を指定できます。

{
  "queries": "Model Context Protocol Python SDK",
  "mode": "discovery",
  "vertical": "general"
}

レスポンスには、順位付けされた URL、タイトル、スニペット、プロバイダーの試行履歴、 キャッシュ状態、プレーンテキスト表示用の投影、evidence_id が含まれます。ホストは 返された任意の URL をそのまま web_fetch に渡せます。

web_fetch

既知の公開 URL、または件数が制限された URL のバッチを読み取るために使用します。

{
  "url": "https://example.com",
  "focus": "the page's purpose",
  "render": "auto"
}

抽出されたテキスト、タイトルとドキュメントの種類、コンテンツの品質、リンクの検出結果、 リダイレクト履歴、HTTP ステータス、切り捨て／続きのメタデータ、 evidence_id が返されます。デフォルトでは、プライベートな宛先と特殊用途の宛先は 通信前に拒否されます。

例：エージェントによる MCP の使用方法

エージェントは通常、2 段階の情報取得ループでツールを使用します。まず検索し、 次に調査したい情報源を取得します。以下のペイロードは実際の MCP インタラクションの形式を示しています。 読みやすさのため、ID と結果テキストは省略しています。

1. エージェントが情報源を検索する

{
  "name": "web_search",
  "arguments": {
    "queries": "official Model Context Protocol architecture",
    "mode": "grounding",
    "vertical": "general"
  }
}

MCP は、構造化 JSON を含むテキストコンテンツブロックを返します。

{
  "status": "ok",
  "query": "official Model Context Protocol architecture",
  "sources": [
    {
      "title": "Architecture - Model Context Protocol",
      "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
      "snippet": "Understand the architecture and communication model...",
      "provider": "duckduckgo",
      "relevance_score": 1.0
    }
  ],
  "provider_attempts": {
    "searxng": "empty",
    "duckduckgo": "ok"
  },
  "evidence_id": "a1b2c3d4...",
  "exit_code": 0
}

2. エージェントが選択した情報源を取得する

エージェントは返された URL を使って、2 つ目のツールを呼び出します。

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
    "focus": "How do clients and servers communicate?",
    "render": "auto"
  }
}

MCP は、上限付きで抽出された証拠を返します。

{
  "success": true,
  "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "final_url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "http_status": 200,
  "document_kind": "html",
  "content_quality": "good",
  "content": "The Model Context Protocol defines how clients and servers...",
  "links": [
    {
      "url": "https://modelcontextprotocol.io/docs/concepts/transports",
      "text": "Transports"
    }
  ],
  "evidence_id": "e5f6g7h8...",
  "exit_code": 0
}

エージェントは、抽出したコンテンツに基づいてユーザーに回答し、追跡可能性のために evidence_id を保持できます。また、ページが出力上限より長かった場合は、返されたカーソルを使って 別の web_fetch を実行し、取得を続けられます。

ローカルでの動作

MCP host ──stdio──▶ mcp_server.py
                       ├─ web_search → provider chain → ranked evidence
                       └─ web_fetch  → security → HTTP/extract/render → evidence

永続状態はすべて WEB_MCP_DATA_DIR 配下に保存されます。このパッケージは Odysseus から実行時インポートを行わず、その認証情報、データベース、 メモリ、ブラウザープロファイル、スケジューラー、エージェントループにもアクセスしません。

ローカルシステムの設計の詳細は docs/TECHNICAL_DESIGN.md を、GIF の記録方法は docs/INTERACTIVE_DEMO.md をご覧ください。

検索プロバイダーと設定

デフォルトのプロバイダーチェーンは次のとおりです。

SearXNG → Brave → Tavily → Serper → DuckDuckGo → Wikipedia → Bing

WEB_MCP_SEARCH_PROVIDER_CHAIN で設定します。任意の認証情報は DATA_BRAVE_API_KEY、TAVILY_API_KEY、SERPER_API_KEY です。参考として .env.example をコピーしてください。ただし、シークレットはコミットせず、 ホスト環境に保管してください。

任意のブラウザーパスは、デフォルトでは無効になっています。

uv pip install -e '.[render]'
./.venv/bin/python -m playwright install chromium
export WEB_MCP_RENDER_ENABLED=true

配布と検出

このサーバーは、io.github.AceAtDev/odysseus-web-mcp として 公式 MCP Registry で公開されています。

Claude Desktop やその他の MCPB 対応クライアントでは、 v0.1.0 GitHub Release から検証済みの MCPB リリースバンドル をダウンロードしてください。 このバンドルは uv ランタイムを使用し、マシン固有の仮想環境を同梱せずに、宣言された Python 依存関係を解決します。

自分で検証する

このプロジェクトには、目的を絞ったテストスイートとライブ検証ランナーがあります。

./.venv/bin/python -m pytest -q
./.venv/bin/python tests/live_20_cases.py --output reports/live-20-cases.json

ライブ検証では、使い捨ての状態を使い、実際の MCP ランチャー経由で検索を10回、取得を10回実行します。最新の検証記録は VERIFICATION.md にあります。

新たに実行したライブ呼び出しからターミナルのプレビューを再記録するには（ImageMagick の convert コマンドが必要です）：

./.venv/bin/python demos/record_terminal_demos.py

各 GIF は意図的に10秒未満にしてあり、静的な製品モックアップではなく、実際の MCP ハンドシェイクと結果の形式を示しています。

プロジェクトの対象範囲

このパッケージは検索・取得の基本機能であり、エージェントループ、汎用クローラー、スケジューラー、メモリーストア、ブラウザープロファイルマネージャー、認証情報保管庫ではありません。独立した MCP サーバーとしてダウンロードし、接続できるように設計されています。

ライセンスとステータス

これは Odysseus のウェブ検索・取得機能を単独で切り出した作業用ワークスペースです。ソースからモジュールへの対応については MIGRATION_MAP.md を、エビデンスに基づく現在のステータスについては VERIFICATION.md を参照してください。