SourceWeave Web Search

SourceWeave Web Search

ウェブ調査のための検索優先型 MCP サーバーと CLI です。

メモ

sourceweave-search-mcp はデフォルトのローカルエントリーポイントです。SOURCEWEAVE_SEARCH_* のエンドポイント変数が明示的に設定されていない場合、ローカルの Docker 管理スタックを自動的に検出または起動します。すでにサービスを自分で実行している場合は、エンドポイントを明示的に設定すると、代わりにそれらが使用されます。

概要 • はじめに • 管理対象のローカルランタイム • MCP クライアントの設定 • CLI • コンテナのデプロイ • OpenWebUI • ランタイム設定 • 開発

概要

SourceWeave Web Search は、ウェブ調査のために、MCP クライアント向けの簡潔な 3 つのツールからなるインターフェースを提供します。

• search_web(query, domains?, urls?, effort?) はソースを見つけ、安定した page_id ハンドルを持つ簡潔な結果を返します。
• read_pages(page_ids, focus?) は、page_id を使って保存済みページを読み取ります。
• read_urls(urls, focus?) は、検索を行わずに URL を直接読み取ります。

以下のコンポーネントを組み合わせています。

コンポーネント	役割
SearXNG	検索対象の発見
Crawl4AI	HTML のクリーンな抽出
Redis または Valkey	ページキャッシュと page_id ストアの永続化
MarkItDown	PDF やその他の対応ファイルのドキュメント変換

はじめに

要件

• Python 3.12+
• デフォルトの管理対象ローカルランタイムを使用する場合は、Compose に対応した Docker
• ホステッドサービスまたはセルフ管理サービスを使用する場合に限り、明示的な SOURCEWEAVE_SEARCH_* エンドポイント

管理対象のローカルランタイム

公開パッケージからサーバーを実行します。

uvx --from sourceweave-web-search sourceweave-search-mcp

または、MCP サーバーを HTTP で起動します。

uvx --from sourceweave-web-search sourceweave-search-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

エンドポイントの環境変数が設定されていない場合、sourceweave-search-mcp は次のように動作します。

モード	動作
管理対象スタックが見つかった場合	現在のランタイム状態ディレクトリにある、既存の SourceWeave 管理スタックに参加します
正常な外部スタックが見つかった場合	所有権を持たずに、標準のローカルポート 19080、19235、16379 を再利用します
再利用可能なスタックがない場合	標準ポート、または空いているローカルポートで Docker 管理スタックを起動し、監視します

管理対象の状態は ~/.sourceweave-local/managed-runtime の下に保存されます。同じマシン上の複数の MCP プロセスは、状態ディレクトリごとに 1 つの管理対象スタックを共有します。

重要

管理対象ランタイムは、最後にアクティブだった SourceWeave 管理プロセスが終了した場合にのみ、コンテナを削除します。名前付きボリュームは保持されるため、キャッシュデータは再起動後も残ります。元の所有プロセスが停止した場合、後続のプロセスは Docker プロジェクトの識別情報と永続化されたランタイム状態から、同じスタックを復元できます。

明示的なエンドポイントモード

SearXNG、Crawl4AI、Redis または Valkey をすでに自分で実行している場合、またはホステッドサービスを指定する場合は、エンドポイントを明示的に設定すると、MCP エントリーポイントは管理対象の Docker 起動を経由せずに動作します。

SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://127.0.0.1:19080/search?format=json&q=<query>" \
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://127.0.0.1:19235" \
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://127.0.0.1:16379/2" \
uvx --from sourceweave-web-search sourceweave-search-mcp

直接 CLI

sourceweave-search はツールを直接実行します。サポートするサービスがすでに利用可能な場合や、エンドポイントを指定する場合に使用してください。Docker は起動しません。

sourceweave-search --query "python programming" --read-first-pages 2
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

ヒント

直接 CLI では、--searxng-base-url、--crawl4ai-base-url、--cache-redis-url のオーバーライドも使用できます。

MCP クライアントの設定

OpenCode

opencode.json / opencode.jsonc / ~/.config/opencode/opencode.json の設定例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ],
      "enabled": true,
      "timeout": 300000
    }
  }
}

代わりに共有 HTTP エンドポイントを使用する場合：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sourceweave": {
      "type": "remote",
      "url": "http://127.0.0.1:18000/mcp",
      "enabled": true,
      "timeout": 300000
    }
  }
}

VS Code Copilot

.vscode/mcp.json の設定例：

{
  "servers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

代わりに共有 HTTP エンドポイントを使用する場合：

{
  "servers": {
    "sourceweave": {
      "type": "http",
      "url": "http://127.0.0.1:18000/mcp"
    }
  }
}

Claude Code

.mcp.json の設定例：

{
  "mcpServers": {
    "sourceweave": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "sourceweave-web-search",
        "sourceweave-search-mcp"
      ]
    }
  }
}

プロジェクト単位で共有設定を適用するには、同じブロックをリポジトリのルートにある .mcp.json に配置してください。

CLI

補助サービスにすでに接続できる状態であれば、直接 CLI が便利です。MCP ラッパーを使わずに、同じく検索を最初に行うワークフローを利用できます。

sourceweave-search --query "react useEffect cleanup example" --read-first-page
sourceweave-search --query "HTTP overview" --domain developer.mozilla.org --read-first-page
sourceweave-search --read-url "https://packaging.python.org/en/latest/"

コンテナのデプロイ

管理対象のローカルランタイムは、ホスト側で uvx または uv run を起動する場合に使用します。コンテナ化されたデプロイでは、引き続きエンドポイントを明示的に指定します。

• イメージ：ghcr.io/mrnaqa/sourceweave-web-search-mcp
• リポジトリ内の compose エントリーポイント：docker compose up -d --build mcp

コンテナの実行例：

docker run --rm -p 8000:8000 \
  -e SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://host.docker.internal:19080/search?format=json&q=<query>" \
  -e SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://host.docker.internal:19235" \
  -e SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://host.docker.internal:16379/2" \
  ghcr.io/mrnaqa/sourceweave-web-search-mcp:latest

OpenWebUI

このリポジトリには、生成済みのスタンドアロン OpenWebUI ツールファイル artifacts/sourceweave_web_search.py も含まれています。

リポジトリをチェックアウトした状態で、正規の実装と同期していることを確認します。

uv run sourceweave-build-openwebui --check

スタンドアロンのツールファイルをデプロイする場合は、この成果物を OpenWebUI に貼り付けてください。生成ファイルでは、デフォルトのエンドポイントがリポジトリ内の compose サービス名に書き換えられるため、コンテナのデプロイ方法にそのまま適合します。

ランタイム設定

任意の環境変数：

変数	用途
SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL	SearXNG の URL テンプレートです。<query> を含める必要があります。
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL	Crawl4AI のベース URL です。
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL	キャッシュに使用する Redis または Valkey の URL です。
FASTMCP_HOST	sse または streamable-http トランスポートのホストです。
FASTMCP_PORT	sse または streamable-http トランスポートのポートです。

エンドポイント変数が設定されていない場合、sourceweave-search-mcp は管理対象のローカルランタイムをデフォルトで使用します。

• 正規のホストエンドポイントは引き続き推奨されるデフォルトであり、外部再利用の確認対象でもあります。
• 正規のデフォルトがすでに使用中の場合、SourceWeave が管理するスタックでは、空いている別のホストポートを使用することがあります。
• 同じマシン上の複数の MCP プロセスは、ローカルランタイムの状態ディレクトリごとに 1 つの管理対象スタックを共有します。

デフォルトのエンドポイント値：

• SearXNG：http://127.0.0.1:19080/search?format=json&q=<query>
• Crawl4AI：http://127.0.0.1:19235
• Redis：redis://127.0.0.1:16379/2

管理対象の起動で優先されるデフォルトのホストポート：

• SearXNG：19080
• Crawl4AI：19235
• Redis：16379
• MCP：uvx で直接実行する場合は 8000、リポジトリの mcp compose サービスを使用する場合は /mcp の 18000

開発

git clone https://github.com/MRNAQA/sourceweave-web-search.git
cd sourceweave-web-search
uv sync --locked --group dev
uv run sourceweave-search-mcp

便利なチェック：

uv run sourceweave-build-openwebui --check
uv run sourceweave-search-mcp --help
uv run pytest tests/test_config.py tests/test_packaging.py tests/test_tool.py tests/test_managed_runtime.py -m "not integration"