websearch-mcp

Strataの「低コストな検索窓口」。検索文字列だけをOpenAI公式Responses APIのweb_searchへ送り、最大5件のタイトル・出典URL・主要情報・短い要約をJSONで返します。比較・考察・最終回答はStrataで行います。

Strata: 検索文字列 → HTTP MCP /mcp (Bearer認証) → websearch-mcp (NAS Docker)
                                                   ↓ 入力検証・予算予約
                                               OpenAI Responses API + web_search（1回）
                                                   ↓ 構造化JSON（最大5件）
Strata: 結果を使って比較・最終回答

MCPツールは web_search だけです。画像解析は別サーバーの vision-mcp を使います。

• 通信方式: Streamable HTTP（Docker）／stdio（ローカル開発）

• HTTPエンドポイント: /mcp、コンテナ内ポート8000固定

• 公開ツール: web_search(query: str, search_context_size="low")

• 既定モデル: gpt-5.6-luna

NASでの起動

1. NAS上にこのリポジトリを配置し、NASのSSHシェルでリポジトリのディレクトリから実行します。UGREENのDockerプロジェクト機能でも同じComposeと.envを指定できます。

2. .envを設定します。新規cloneではcp .env.example .envで作成します。既存の.envを上書きしないでください。

OPENAI_API_KEY=自分のOpenAI_APIキー
OPENAI_MODEL=gpt-5.6-luna
WEBSEARCH_MCP_TOKEN=別途生成した32文字以上のランダム文字列
MCP_BIND_IP=192.168.0.49
SERVER_IP=192.168.0.49
MCP_PORT=8101
MCP_ALLOWED_HOSTS=localhost:*,127.0.0.1:*

MCP_BIND_IPはNASホストの公開先インターフェース、SERVER_IPはHost検証に追加するNASのIPです。両方設定してください。MCP_PORTはホスト側の公開ポートだけに反映し、コンテナ内は8000番固定です。未指定時のホスト側ポートは8101です。NAS名で接続する場合はMCP_ALLOWED_HOSTSへnas-name:8101等を追加します。allowed hostsは接続元IP制限ではありません。

認証トークンの生成例（Pythonのある端末で実行）:

python -c 'import secrets; print(secrets.token_urlsafe(32))'

OpenAIキーはNASだけに置き、Strataには別のWEBSEARCH_MCP_TOKENを設定します。vision-mcpとは別の値にしてください。

docker compose config --quiet
docker compose up -d --build
docker compose ps
docker compose logs --tail=30 websearch-mcp

config --quietは展開した秘密情報を表示せずに設定を検証します。.envにキー・認証トークンが空のままだと起動しません。可能ならchmod 600 .envにします。.envはPythonに自動では読み込まれず、Composeが環境変数に展開します。

既定値のMCP_BIND_IP=127.0.0.1ではPhantom（Windows）から接続できません。LAN利用時だけNASのLAN IPへ変更します。NASのファイアウォールでも必要なLAN端末に限定し、ルーターのポート転送は設定しません。HTTPは暗号化されないため、信頼できないネットワークを通す場合はTLSのリバースプロキシやVPNを使用してください。

Related MCP server: agent-web-search-mcp

Strataへの登録

既存設定のmcp_serversのwebsearch-mcpエントリにheadersを追加してStrataを再起動します。

{
  "mcp_servers": {
    "websearch-mcp": {
      "url": "http://192.168.0.49:8101/mcp",
      "headers": {
        "Authorization": "Bearer .envのWEBSEARCH_MCP_TOKENと同じ値"
      }
    }
  }
}

設定断片なので、既存のモデル設定JSON全体を置き換えないでください。ツール定義が変わった場合はStrataを再接続してツール一覧を再取得します。

検索の使い方

web_search(
    query="DDR5 32GB 価格",
    search_context_size="low"  # low / medium / high
) -> str  # JSON: results[], limitations, usage

件数を増やすためにmedium/highへ変更しません。網羅調査・最安値保証は行いません。選択値は戻り値のusage.search_context_sizeと使用量ログに含めます。

コストと出力

モデルを変更してもreasoning.effort=noneは固定で送ります。非対応のモデルではAPIエラーになります。

サーバー全体の使用量上限

全クライアントで予算を共有し、OpenAI APIを呼ぶ前に確認します。上限に達した後はAPIを呼ばずエラーを返します。

数値は設定範囲内の正の整数のみです。0は無制限ではなく設定エラーで、サーバーは起動しません。

• API呼び出し前に回数と推定tokensを原子的に予約し、並列の呼び出しにも同じ上限を適用します。

• 応答後に予約tokensを実使用量へ置き換えます。失敗・タイムアウト・使用量不明の場合は予約を保持します。

• 入力検証で失敗した場合は予約前なので消費しません。

• 使用量DBにアクセスできない場合はAPIを呼びません。

トークン予算は厳密な課金上限ではありません。 実使用量が予約値を超えると日次予算を超過する場合があります。

使用量はComposeの名前付きボリュームwebsearch-mcp-usage（/data）にSQLiteで保存し、コンテナ再作成後も引き継ぎます。記録するのは開始時刻・日付・予約／実使用tokensだけです。通常運用でdocker compose down -vを使わないでください。

データと秘密情報

OpenAIへ送るのは検索文字列と固定指示です。Strataの会話履歴は送りません。ただし検索文字列内の個人情報は外部へ送信されます。

Responses APIにはstore=falseを指定します。これはレスポンス保存を無効化する指定であり、API全体の保持をゼロにする保証ではありません。

• APIキー・.env・使用量DBはGitに含めません。Docker build contextにも含めません（.dockerignoreは許可リスト方式）。

• SDKエラー本文は外へ返さず、キー・検索文字列・検索結果本文をログに出しません。token数などの集計値だけを記録します。

• OPENAI_BASE_URLやプロキシ環境変数を使わず、公式https://api.openai.com/v1に接続します。

• HTTP MCPは専用Bearer tokenを必須にします。allowed hostsはDNS rebinding対策であり、認証やファイアウォールの代わりではありません。

• コンテナは非root（UID 10001）、ルートFS読み取り専用、追加capabilityなし、no-new-privileges。

確認・開発

Python 3.12以上、Linux/macOS向けです。

python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m unittest discover -s tests -v

テストは実SDK + MockTransportでOpenAI通信を置き換え、外部通信・課金なしでリクエスト形状・入力検証・予算・HTTP認証・Host/Origin・本文サイズ制限を確認します。

接続確認は環境変数WEBSEARCH_MCP_TOKENを設定したシェルで:

.venv/bin/python check_mcp.py http://192.168.0.49:8101/mcp

この確認はinitializeとtools/listだけで、OpenAIを呼びません。実検索で1回だけ確認する場合（課金・使用量上限の対象）:

.venv/bin/python check_mcp.py http://192.168.0.49:8101/mcp --query "Pythonの公式サイト" --search-context-size low

ローカル開発でHTTPを起動する場合、.envの値をシェル環境に設定し、SEARCH_USAGE_DBを存在するローカル保存先へ設定してからpython server.py --httpを実行します。--httpなしはstdioです。stdioの標準出力はMCP通信専用なので、デバッグ出力を追加しないでください。

公開Strataクライアントとの任意の互換性テスト:

STRATA_SOURCE=/path/to/Strata .venv/bin/python -m unittest discover -s tests -v

1.0.0-alpha からの移行

• HTTP接続にBearer認証が必須になりました。.envにWEBSEARCH_MCP_TOKENを追加し、Strata側にheadersを追加してください。

• MCP_BIND_IPを追加しました。未設定だとループバックのみで公開されます。

• OPENAI_MODELを.envで変更できるようになりました（以前はgpt-5.6-luna固定）。

• API失敗時の例外はSDKのメッセージを含まないToolErrorに統一しました。

• 使用量DBのスキーマとボリューム名は変更していないため、履歴は引き継がれます。

• check_mcp.pyはHTTP専用になり、検索は--query指定時だけ行います。

フォルダー構成と役割

websearch-mcp/
├─ docker-compose.yaml   ← コンテナの起動・ポート・ハードニング設定
├─ Dockerfile            ← コンテナイメージのビルド定義
├─ .env / .env.example   ← 運用設定（.envはGit管理外）／ひな形
├─ .dockerignore         ← ビルドに含めるファイルの許可リスト
├─ requirements.txt      ← Pythonライブラリの依存関係
├─ server.py             ← サーバーの入口：起動・認証・MCPツール登録
├─ websearch_mcp/        ← 検索のコア処理
│  ├─ config.py          ← 環境変数から設定を読み込む
│  ├─ search.py          ← OpenAIへの検索依頼・結果の検証
│  └─ budget.py          ← 回数・トークン予算の予約と記録
├─ check_mcp.py          ← MCP接続の確認
└─ tests/                ← 自動テスト

外側のwebsearch-mcp（ハイフン）はプロジェクト全体、内側のwebsearch_mcp（アンダースコア）はPythonパッケージです。vision-mcpと同じ構成です。