my-websearch

---

1 つのサーバーを 4 つの方法で利用できます： MCP 経由で AI クライアントに接続する、単発の CLI クエリを実行する、ローカルデーモンを常時起動しておく、または稼働前に組み込みの診断機能を使用することができます。

目次： クイックスタート · MCP ツール · CLI · 設定 · 診断 · 開発

✨ 特長

my-websearch は、AI コーディングエージェント（Claude Desktop、Cursor、Cherry Studio、Windsurf、Cline、ZCode など）専用に構築された、フルスタックの検索・技術ドキュメントエンジンです。主要な AI クライアントにすぐに対応できます：

• 🌐 16エンジンのフェデレーション検索とスマートルーティング
  国内の検索エンジン（Bing、Baidu、CSDN、Juejin、Sogou）、グローバル検索エンジン（DuckDuckGo、Brave、Startpage、Yahoo、Exa、Bing News）、開発者向けの専門プラットフォーム（GitHub、StackOverflow、Hacker News、arXiv）を集約します。言語を認識した自動ルーティング（auto）、複数クエリの並列実行（queries: string[]）、URLの重複排除、自動的なminResults段階的フォールバックに対応しています。DuckDuckGoが不調な場合、フォールバックプールからYahooが英語の優先グループに自動的に加わります。
• ⚡ ネイティブWebプロトコルとProof-of-Workソルバー（ブラウザーを使わない高速パス）
  wreq-jsを基盤とし、最新のTLS／HTTP2ハンドシェイクのネイティブエミュレーションとセッションCookieの永続化に対応しています。StartpageのAnubis SHA-256 PoWチャレンジとDuckDuckGoのd.js（isJsaChallenge）HTML5／算術チャレンジを解決する純粋なJS／Rustソルバーを搭載し、4GBではなく400MBのブラウザーを起動することなく、構造化されたチャレンジレスポンスを数ミリ秒で解決します。リクエストスタックは検索エンジンごとに異なります。DuckDuckGoではGETによるwreqのChromeプロファイルが必須です（axiosのPOSTはHTTP 202でチャレンジされます）。一方、Braveでは意図的に通常のHTTP/1.1（axios）を使用します。CloudFrontがHTTP/2の偽装に対して429を返すためです。これらを統一しないでください。注：DuckDuckGoのページレベルのHTTP 202異常CAPTCHA（「アヒルが含まれるマス目をすべて選択してください」）は人による確認であり、意図的に回避しません。この場合はbot_challengeとして報告されます。Sogouのリダイレクトリンク、BaiduのLocation、BingのBase64リンクの実際のURL解決にも対応しています。
• 📄 高精度なMarkdown記事抽出とサイト専用のフィルター
  Mozilla Readabilityと、インテリジェントなページノイズ除去を組み合わせています。WeChat公式アカウント（mp.weixin.qq.com）、StackOverflowの質問と承認済み回答に特化したフィルタールールに加え、CSDNとJuejinへの透過的な内部ルーティングを備えています。記事タイトル、コードブロック、GFMテーブルを忠実に保持しながら、<nav>、<aside>、<footer>、パンくずリストを削除します。シームレスなページネーション（startIndex）に加えて、トークンを節約する3つのモードに対応しています。BM25で関連度順に並べるfocus、LLMを使わずCSSセレクターでJSONに抽出するextract、**番号付きのcitations**です。
• 📚 Context7ライブラリドキュメントの統合検索（queryDocs）
  個別の解決手順を必要とせず、自然なパッケージ名（例："next.js"、"vue"）またはContext7 IDで公式ドキュメントを直接検索できます。候補の自動ランキング、推測に基づく検索で404が発生した場合の自動復旧、関連する代替候補の検出に対応しています。
• 🐙 GitHub／Giteeリソース取得機能の拡張
  fetchGithubContent（旧fetchGithubReadme）は、GitHubとGiteeの両方に対応しています。リポジトリのREADME、任意のソースファイル（/blob/...。lines／#L120-L180による範囲指定が可能）、ディレクトリツリー（/tree/...）、イシュー／PRのディスカッション全体、コミット（/commit/<sha>）、比較ビュー（/compare/a...b）、リリース（/releases、/releases/tag/<tag>）を取得できます。
• 🌏 設定不要のネットワーク検出とFake-IP対応
  OSのシステムプロキシを自動検出します（Windows Registry／macOS scutil／Linux env）。国内の検索エンジンには高速な直接接続を維持しながら、海外の検索エンジンにはプロキシ経由で自動的に接続します。TUN／Fake-IPとの互換性のために198.18.0.0/15を事前にホワイトリストへ追加しつつ、厳格なSSRFセキュリティ制限を適用します。
  プロキシなしがサポート対象のデフォルト設定です。中国本土以外ではPROXY_URLを未設定のままにしてください。すべての検索エンジンに直接問い合わせるため、このサーバーの利用にClash／v2rayは必要ありません。
• 🔌 柔軟なデプロイモード
  MCP STDIO（Claude Desktop／Cursor）、Streamable HTTP／SSE（Cherry Studio／リモートクライアント）、CLIの単発コマンド、接続プールの再利用とPrometheusの/metricsモニタリングに対応したローカルHTTPデーモンでシームレスに動作します。

---

🌍 16 個の検索エンジン

エンジン	中国本土からの接続性	API キー	コア技術	最適な用途
bing	🇨🇳 直接接続	なし	Chrome TLS の偽装 ＋ Base64 による実 URL の解決 ＋ ステルスフォールバック	一般的な技術検索、英語と中国語が混在するクエリ
bing-news	🌐 中国ではプロキシ経由	なし	Bing News RSS ＋ pubDate による過去 24 時間のフィルタリング ＋ apiclick.aspx?url= のデコード。直接接続では HTML ページに 302 リダイレクトされることがあるため、デフォルトでプロキシ対象です。オプトイン型の専門エンジンです	最新ニュース、過去 24 時間の更新情報
baidu	🇨🇳 直接接続	なし	Location リダイレクトの並行解決 ＋ チャレンジ検出	中国語のニュース、ドキュメント、国内フォーラム
csdn	🇨🇳 直接接続	なし	WAF Cookie jar の永続化 ＋ 空のレスポンスの自動再試行	中国語のエラーログ、デバッグチュートリアル
juejin	🇨🇳 直接接続	なし	クリーンな長文記事を取得するための公式 API への直接クエリ	最新のフロントエンド／バックエンド技術ブログ
sogou	🇨🇳 直接接続	なし	デスクトップ版とモバイル版の二重解析 ＋ リダイレクトリンクのデコード ＋ 広告の除去	WeChat エコシステムのリンク、ロングテールクエリ
duckduckgo	🌐 中国ではプロキシ経由	なし	wreq による HTML エンドポイントへの Chrome プロファイル GET リクエスト（202 の CAPTCHA 異常は axios フォールバック時のみ）。プリロードフォールバック用に d.js ソルバーを維持	英語の技術検索、オープンソースに関する議論
startpage	🌐 中国ではプロキシ経由	なし	マルチワーカーの Anubis SHA-256 PoW ソルバー（難易度 ≤ 6）＋ Cookie セッション（ブラウザー不要）	Google を基盤とする高プライバシーの検索結果
yahoo	🌐 中国ではプロキシ経由	なし	SSR HTML ＋ ホームページでの Cookie ウォームアップ ＋ RU= リダイレクトのデコード。英語のフォールバックプール（DuckDuckGo が不調な場合に自動で切り替え）	安定した Bing インデックスの英語検索フォールバック
brave	🌐 中国ではプロキシ経由	なし	プレーンな HTTP/1.1（axios）リクエスト経路（wreq／HTTP2 の偽装は CloudFront から 429 を受け取ります）＋スポンサー広告の厳格な除去	独立系の英語インデックス、技術ブログ
exa	🌐 プロキシ推奨	無料キー（任意）	公式のセマンティック検索 API（キーが未設定の場合はスキップ）。直接接続も可能ですが、実測値はプロキシ経由で約 0.77 秒、直接接続で約 1.17 秒です	意味的類似性、AI 研究、論文
github	🌐 直接 API 接続	なし	公式 GitHub Search REST API ＋ 正確な owner/repo の高速処理（issues と repositories）	GitHub の issue、バグレポート、リポジトリ、正確なリポジトリ検索
stackoverflow	🌐 直接 API 接続	なし	HTML エンティティのデコードに対応した公式 StackExchange 2.3 API	開発者向けの問題解決、スタックトレース、回答
hackernews	🌐 直接 API 接続	なし	ポイント、コメント、投稿者メタデータに対応した Algolia HN Search API	技術に関する議論、スタートアップの発表、エンジニアリング関連ニュース
arxiv	🌐 直接 API 接続	なし	タイトル、著者、要旨を解析する公式 arXiv Atom XML API	科学論文、機械学習、AI 研究
code	🌐 中国ではプロキシ経由	なし	grep.app API による GitHub 全体のコード検索。リポジトリ、パス、正確な行番号に対応	ソースコードの実装、API の使用パターン

バージョンに関する注意：この README は現在のソースツリー（1.3.10）に対応しています。Yahoo、Bing News、DDG wreq-GET 経路、Brave HTTP/1.1 経路、raw-CDP ブラウザーフォールバックは 1.3.10 に含まれています。パッケージが公開されるまでは、npm の最新バージョンに反映されていない場合があります。

---

🛠️ 4 つのコア MCP ツール（最小限・トークン効率重視）

💡 トークン予算とスリム化：すべてのツールの説明は 250 文字以内（説明の合計文字数 ≤ 1000）に厳密に収めています。詳細なルーティングガイダンスは McpServer({ instructions }) に委ねることで、LLM のコンテキスト消費を大幅に削減します。

ツール名	目的	主な特長
search	ウェブとコードの横断検索（16 エンジン）	並列クエリ、timeRange: day|week|month|year による日付フィルター、site: string[] フィルター、fetchTop によるプレビュー挿入、code エンジン（grep.app）に対応。engines を明示するとデフォルトで minResults=0（制約のないカスケード検索は行いません）。失敗時は diagnostics をインラインで返します
fetchWebContent	ウェブページの抽出、Markdown および透過的な PDF 解析	オールインワンのコンテンツ抽出ツール：ディスクレベルの Markdown キャッシュを内蔵（Node 22 node:sqlite／パーティション分割 JSON フォールバック、200MB LRU、cache: default|reload）。透過的な PDF 解析（最大 20MB／50 ページ、[page N] タグ、スキャン文書の検出）。ページネーションと focus キーワード指定（デフォルトで関連度順にランク付けされた bm25 ブロック、従来の固定ウィンドウには window を使用）。CSS サブツリーに抽出範囲を限定する selector（ページ全体を黙って返す代わりにエラーを返します）。LLM を使わない CSS セレクターによる JSON 抽出の extract。番号付き参照の citations。URL を削除する retainLinks（インデックスページで -50%）
fetchGithubContent	GitHub／Gitee コンテンツの総合リーダー	README、単一のソースファイル（/blob/<ref>/<path>、任意の lines／#L120-L180 による範囲指定、上限 400 行）、ディレクトリツリー（/tree/）、Issue／PR の議論、コミット（/commit/<sha>）、比較（/compare/a...b、パッチの上限設定とロックファイルのフィルタリング）、リリース（/releases[/tag/<tag>]）を取得します。ref にはブランチ、タグ、コミットを指定できます。Gitee も API 経由で同等に対応（GITEE_TOKEN は任意）。warnings を返します
queryDocs	公式ライブラリドキュメントを一括取得	ライブラリ名または Context7 ID を解決します。任意の version で Context7／npm／PyPI のバージョンを固定できます。24 時間のローカルキャッシュ（cache: reload で無効化）。npm → PyPI → crates.io → Go モジュールプロキシ → GitHub README の順にフォールバックします。source、confidence、warnings を返します

💡 後方互換性：従来の fetchCsdnArticle と fetchJuejinArticle は自動的に fetchWebContent にルーティングされます。従来の resolveLibraryId は queryDocs に統合されており、library 名または従来の libraryId エイリアスを受け付けます。個別の従来ツールは削除されました。未登録のハンドラーを 3 つ維持してもツール説明の予算を無駄に消費するため、REGISTER_LEGACY_ARTICLE_TOOLS スイッチは廃止されています。

---

🚀 クイックスタート

1. NPX で実行（設定不要）

インストールは不要です：

npx -y my-websearch@latest

💡 プロキシの自動検出：サーバーはオペレーティングシステムのプロキシ設定を自動的に検出します。ローカルプロキシ環境が有効な場合、海外のエンジンは自動的にプロキシを使用し、国内のエンジンは高速な直接接続を維持します。198.18.0.0/15 は Fake-IP 環境向けに標準でホワイトリストに登録されています。

2. AI クライアントで設定する

🔹 自動セットアップ（推奨）

init はインストール済みの MCP クライアントを検出し、サーバーのエントリを設定ファイルに書き込み、.bak バックアップを保持します：

npx -y my-websearch@latest init                      # auto-detect and write
npx -y my-websearch@latest init --dry-run            # preview the diff, write nothing
npx -y my-websearch@latest init --client cursor,code # target specific clients

標準で対応しているのは Claude Desktop、Cursor、VS Code（ワークスペースの .vscode/mcp.json）です。既存のエントリは --force を指定しない限り上書きされず、破損した設定ファイルには手を加えません。また、Windows では cmd /c npx を自動的に設定します。クライアントを再起動し、my-websearch doctor を実行して確認してください。

🔹 手動設定

Claude Desktop／Cursor／Windsurf／Cline（STDIO モード）

MCP 設定ファイルに追加します：

{
  "mcpServers": {
    "my-websearch": {
      "command": "npx",
      "args": ["-y", "my-websearch@latest"],
      "env": {
        "MODE": "stdio"
      }
    }
  }
}

(Windows の場合：init がこの設定を自動的に処理します。手動で設定する場合、npx がシステムパスにないときは、command を cmd に、args を ["/c", "npx", "-y", "my-websearch@latest"] に設定してください)

🔹 Cherry Studio（Streamable HTTP モード）

ターミナルで npx my-websearch@latest（デフォルトポートは 3211）を実行してサーバーを起動し、次のように設定します。

{
  "mcpServers": {
    "web-search": {
      "name": "MyWebSearch",
      "type": "streamableHttp",
      "baseUrl": "http://localhost:3211/mcp"
    }
  }
}

---

💻 CLI とローカルデーモン

my-websearch は、スタンドアロンの CLI ツールまたは常駐デーモンとして、ターミナルから直接使用できます。自動化では --json を使用し、リモートアクセスが明示的に必要な場合を除き、デーモンは 127.0.0.1 で実行してください。

# Global install
npm install -g my-websearch

# Detect installed MCP clients and write their config (--dry-run to preview)
my-websearch init

# Start persistent local HTTP daemon (port 3210 by default)
my-websearch serve

# One-shot terminal search (reuses running daemon automatically)
my-websearch search "Model Context Protocol best practices" --limit 5 --min-results 5 --json

# Only results published within the last week (day|week|month|year)
my-websearch search "typescript 5.9 release" --time-range week --json

# Extract web page as clean Markdown
my-websearch fetch-web "https://blog.vuejs.org/posts/vue-3-5" --max-chars 15000 --json

# View daemon status and Prometheus metrics (/health, /status, /metrics)
my-websearch status --json

# Clear in-memory search cache
my-websearch cache-clear

---

🩺 診断

プロキシ、ブラウザー、またはエンジンのトラブルシューティングを行う前に、組み込みの doctor コマンドを使用してください。

# Local configuration and browser checks
my-websearch doctor

# Real proxy/engine probes (may contact upstream services)
my-websearch doctor --network

# Limit network probes to selected engines
my-websearch doctor --network --engine bing,duckduckgo --json

# Reset and clear cached engine circuit breaker / health state
my-websearch doctor --reset-health

レポートでは、設定、プロキシの TCP 到達性、HTTP 到達性、アプリケーションによる解析、ブラウザーの起動、チャレンジの検証ステータスが個別に示されます。ネットワークモードでは実際のリクエストが行われるため、高頻度のヘルスチェックには使用しないでください。

🌐 プロキシのトラブルシューティングと上流のレート制限

プロキシ接続を設定または診断する際は、次のような一般的な例外ケースを確認してください。

1. proxy.url が設定されているのに、起動ログに 🌐 Proxy: disabled と表示されますか？
   • useProxy フラグを確認する：~/.my-websearch/config.json で "useProxy": false を設定すると、これが優先され、url が明示的に上書きされて無効になります（PROXY_URL='false' を設定した場合と同じです）。"useProxy": true に変更するか、このフィールドを省略してください（有効な url を指定するとプロキシは自動的に有効になります）。
   • システムプロキシは自動検出されます：明示的なプロキシが設定されていない場合、海外向けエンジンおよび汎用フェッチでは、OS のシステムプロキシ（Windows レジストリ／macOS scutil／HTTPS_PROXY）が使用されます。プロキシクライアントが起動しているという理由だけで、PROXY_URL を設定する必要はありません。検出に失敗する場合や、特定のプロキシを固定したい場合は、PROXY_URL を設定してください（例：http://127.0.0.1:7897）。
   • クライアントの env より ~/.my-websearch/config.json を優先する：proxy.url と API キーは設定ファイルに記述してください。一部の MCP クライアント（WorkBuddy など）は、command + args + env key names + cwd に基づいてサーバーのフィンガープリントを作成するため、PROXY_URL の環境変数エントリーを追加すると信頼フィンガープリントが変わり、サーバーがセッションから予告なく外れる場合があります。設定ファイルの値は起動時に読み込まれ、これを回避できます。
   • プロキシの設定場所（エラーメッセージには以前「MCP クライアント設定」とだけ表示されており、曖昧でした）：

     場所	使用する場合
     ~/.my-websearch/config.json → "proxy": { "url": "http://127.0.0.1:7897" }	推奨。 すべてのクライアント（CLI、デーモン、MCP）に適用され、クライアントの信頼フィンガープリントも変わりません。
     MCP クライアントの env → PROXY_URL	クライアントごとの上書き。クライアントを再起動してください。一部のクライアントは、信頼フィンガープリントに環境変数のキーを含めます。
     プロキシクライアントの「システムプロキシ」スイッチ	設定が一切不要です。1.3.8 以降、海外向けエンジンおよび汎用フェッチで自動検出されます。

2. プロキシは動作しているのに、海外のエンジンで失敗やタイムアウトが発生しますか？（設定エラーではなく、エンジンごとの診断）
   • DuckDuckGo が HTTP 202／チャレンジを返す場合：202 のレスポンス本文は、単純な IP ごとのレート制限ではなく、DDG の異常検知 CAPTCHA（人間による認証）です。d.js の算術問題ソルバーでは回避できません。エンジンはまず wreq の Chrome プロファイルを使った GET で HTML エンドポイントにリクエストします。この方法では、axios の POST 経路が 202 のチャレンジを受けても、通常は 200 が返ります。そのため、現在 202 が表示されるのは、その経路に失敗して axios のフォールバックが使われた場合のみです。それでも 202 が表示される場合は、ビルドに wreq の GET 経路が含まれていることを確認してください（1.3.8 以前には含まれていません）。そのうえで再試行するか、プロキシが適用されていることを確認してください。DDG は引き続きベストエフォートです。同じ出口 IP でも断続的にチャレンジが発生する可能性があるため、SLA として扱わないでください。安定性を重視する場合は、Bing／Startpage を使うか、BRAVE_API_KEY／EXA_API_KEY を設定してください。注：SEARCH_MODE=playwright:duckduckgo はサポートされていません（DDG にはブラウザー描画経路がないため）。そのため、HTTP にフォールバックします。
   • Bing が HTTP 200 を返すのに結果が 0 件の場合：wreq の偽装経路では、空のページを解析した場合に axios の SERP 経路へ自動的にフォールバックするようになりました。両方の経路で引き続き結果が空の場合は、クエリ／IP がレート制限されている可能性があります。
   • Brave が HTTP 429 Too Many Requests を返す場合：CloudFront が出口 IP を数分間にわたってスロットリングします。恒久的なものではありません。クールダウン後のリクエストでは 200 が返る場合があります（検証済み：同じノードで 429 → その後 6/6 回 200）。ただし、短時間にリクエストを集中させると再び発生します。同じノードでの測定結果では、wreq（HTTP/2 Chrome フィンガープリント）→ 429、axios/curl（HTTP/1.1）→ 200 でした。そのため、現在の main では意図的に axios を使用しています。安定した経路を使うには、BRAVE_API_KEY（公式 API、無料枠）を設定して WAF を完全に回避してください。
   • Startpage がタイムアウトする、または Anubis PoW の難易度が急上昇する場合：難易度 6 は最大 4 つのワーカースレッドでインライン処理するようになりました（約 3～12 秒）。難易度が 6 を超える場合はスキップします。チャレンジ通過後のソケットエラーや一時的な 5xx は自動的に再試行されます。
   • 💡 対処方法：これらは上流側のボット対策／レート制限の動作であり、MCP の設定が壊れているわけではありません。エンジンごとに対処してください。DDG 202 → アップグレード／再試行（wreq の GET 経路。auto モードでは、正常に動作しない DDG がフォールバックプールから Yahoo に置き換えられる場合もあります）。Brave 429 → 数分間のクールダウンを待つか、BRAVE_API_KEY を設定。Bing の結果が 0 件 → 再試行するか、クエリを調整。Startpage PoW → 再試行。エンジンごとの対処に失敗した場合にのみ、出口 IP を切り替えてください。最後の手段として engines: ["bing", "baidu"] を使用するか、SLA 対応の経路として公式キー（BRAVE_API_KEY／EXA_API_KEY）を設定してください。

🔐 セキュリティモデル（サーバーを公開する前にお読みください）

デフォルト設定はパッケージとして安全であり、それぞれが重要な役割を果たします。

デフォルト設定	保護する内容
127.0.0.1 にバインド	マシン外からポートにアクセスできません
認証なし	ループバックバインドの場合に限り許容されます
Host ヘッダーの検証	同じマシン上のブラウザーを利用した DNS リバインディング攻撃をブロックします
CORS 無効	クロスオリジンのブラウザーアクセスを防ぎます

ほかの設定を変更せずに 1 つでも緩めると、保護が気付かないうちに失われます。

• HOST=0.0.0.0（Docker）→ Host の許可リストはバインドアドレスに自動的に追従します。公開ドメインも使用する場合は、OPEN_WEBSEARCH_ALLOWED_HOSTS で追加してください（カンマ区切り）。
• パブリックインターネットに公開する場合 → 認証機能付きのリバースプロキシ（または SSH トンネル）の背後に配置してください。ループバック以外のアドレスにバインドすると、デーモンが警告を出力します。
• MCP セッション ID は識別子であり、認証情報ではありません。ポートにアクセスできる人は誰でもセッションを再開できます。
• FETCH_WEB_INSECURE_TLS=true は、ユーザー指定の URL に対する証明書検証を無効にします。信頼できるネットワークでのみ有効にしてください。
• アプリは初回実行時に、~/.gemini/config/mcp_config.json／~/.workbuddy/mcp.json で見つかった API キーを ~/.my-websearch/config.json（モード 0600）にコピーします。my-websearch doctor を実行すると、各キーの取得元を確認できます。コピーを無効にするには MYWEBSEARCH_NO_AUTO_BOOTSTRAP=1 を設定してください。

⚙️ 設定と環境変数

グローバル設定（~/.my-websearch/config.json）

重複した設定をせずに、すべての MCP クライアントで設定を共有できます。

{
  "apiKeys": {
    "context7": "ctx7sk-...",
    "exa": "..."
  },
  "proxy": {
    "url": "http://127.0.0.1:7897",
    "useProxy": true,
    "engines": ["duckduckgo", "exa", "brave", "startpage"]
  }
}

⚠️ useProxy に関する注意："url" が設定されている場合、プロキシは自動的に有効になります。"useProxy": false を設定すると、url は明示的に上書きされ、無効になります。プロキシを有効にするには、"useProxy": true を設定するか、このフィールドを省略してください。

📋 環境変数の詳細リファレンス

グローバル設定ファイル（~/.my-websearch/config.json）、ローカルの .env、またはシステム環境変数で設定できます。

優先順位（高い順）：プロセス環境変数 → プロジェクトの .env → プロジェクトの .my-websearch.json → ~/.my-websearch/config.json → 組み込みのデフォルト値。

0. 🖥️ サーバーとランタイム

変数	デフォルト	許可される値／説明
MODE	both	both ／ http ／ stdio。http は Streamable HTTP と SSE を有効にします。
HOST / OPEN_WEBSEARCH_HOST	127.0.0.1	MCP HTTP のバインドアドレス。ループバック以外のアドレスにバインドすると、そのホストも Host 許可リストに登録され、認証がないことを示す警告が表示されます。
PORT	3211	MCP HTTP ポート
OPEN_WEBSEARCH_ALLOWED_HOSTS	空	Host ヘッダーの許可リストに追加するエントリ（カンマ区切り）。パブリックドメイン／リバースプロキシ経由で提供する場合に必要です。
OPEN_WEBSEARCH_DAEMON_HOST / OPEN_WEBSEARCH_DAEMON_PORT	127.0.0.1 / 3210	ローカル REST デーモンのバインドアドレス（認証なし。ループバックに限定してください）。
METRICS_ENABLED	false	プロセス内カウンターとデーモンの /metrics エンドポイントを有効にします。
FETCH_WEB_DEADLINE_MS	45000	1 回の fetchWebContent 呼び出しに対するハードデッドライン（Cookie、ブラウザー、リトライを含む）
GITHUB_CONTENT_CDN_FIRST	false	README とソースファイルに対して、raw.githubusercontent.com より jsDelivr を優先します（パブリックリポジトリのみ）。従来の別名 GITHUB_README_CDN_FIRST も引き続き使用できます。
GITHUB_CONTENT_BUDGET_MS	12000（CDN 優先時は 6000）	1 回の fetchGithubContent 呼び出しに対する合計時間の上限。各試行のタイムアウトは最大 4.5 秒です。
BING_PLAYWRIGHT_BUDGET_MS	6000	互換性のために従来の名前を維持しています。HTTP の結果を保持する前に、Bing のブラウザー代替処理（現在は raw CDP を使用）に割り当てる時間の上限です。
MYWEBSEARCH_NO_AUTO_BOOTSTRAP	未設定	1 を設定すると、初回実行時に他のアプリの MCP 設定から API キーをコピーしないようにします。

1. 🔍 検索とルーティングのオーケストレーション

変数	デフォルト	許可される値／説明
DEFAULT_SEARCH_ENGINE	auto	デフォルトのエンジン：auto（スマートなクエリルーティング：中国語は baidu,sogou、英語／その他の言語は bing,duckduckgo）。16 個すべてのエンジンに対応：auto、bing、bing-news、baidu、sogou、duckduckgo、brave、csdn、juejin、startpage、yahoo、exa、github、stackoverflow、hackernews、arxiv、code（開発者向けの専門エンジンをデフォルトに設定できますが、グローバルなデフォルトには auto または一般的なウェブエンジンを推奨します）
ALLOWED_SEARCH_ENGINES	all	使用を許可する検索エンジンのカンマ区切りのホワイトリスト（例：bing,baidu,duckduckgo）
BING_BASE_URL	https://cn.bing.com/search	Bing クエリのベース URL。海外のユーザーまたはリバースプロキシノードでは、https://www.bing.com/search に設定できます（従来の別名 OPEN_WEBSEARCH_BING_HOST にも対応）
DEFAULT_MIN_RESULTS	5	カスケードのしきい値：使用可能な検索結果がこの値を下回ると、フォールバックエンジンを起動します
DEFAULT_SEARCH_LIMIT	10	ツール呼び出しで明示的に指定されていない場合のデフォルトの結果数上限（最大 50）
SEARCH_DEADLINE_MS	30000	複数エンジンによる検索の実行に対するグローバルな絶対期限（ミリ秒）
SEARCH_FUSION	legacy	結果の統合モード：legacy（エンジンごとのヒット数＋到着順）または rrf（エンジンごとの順位に基づく Reciprocal Rank Fusion。再ランキングの順位／合意度の要素も置き換えます）。より大規模な評価が行われるまでは、RRF はオプトイン方式です。
SEARCH_FUSION_RRF_K	20	RRF の定数 k。値が小さいほど順位の差が強調されます。SEARCH_FUSION=rrf の場合のみ使用されます。
ENGINE_CIRCUIT_BASE_COOLDOWN_MS	30000	エンジンのサーキットブレーカーが最初に適用するクールダウン時間（429／202／bot_challenge）。失敗が続くと指数関数的に延長されます（30 秒 → 60 秒 → 120 秒…）。
ENGINE_CIRCUIT_MAX_COOLDOWN_MS	300000	サーキットブレーカーの指数関数的な延長時間の上限（デフォルトは 5 分）。
SEARCH_AUTHORITY_DOMAINS	empty	結果の再ランキングに使用する追加の権威あるドメインのホワイトリスト（カンマ区切り。組み込みリストに追加されます）
SEARCH_MODE	auto	検索モードとブラウザーポリシー。単一モード、モードごとの複数エンジン、複数モードを組み合わせた設定に対応します： • グローバルモード：auto（デフォルトのフォールバック）、request／none（HTTP のみ）、playwright（ブラウザーを強制。従来の値名ですが、現在は CDP によって動作します） • 単一モード、複数エンジン：playwright:bing,startpage、auto:bing,startpage、bing,startpage • 複数モードの組み合わせ：playwright:bing;auto:startpage（bing はブラウザーを強制し、startpage は auto フォールバックを使用）、auto;request:startpage（グローバル設定は auto ですが、startpage は HTTP のみを使用）
AUTO_ROUTE_EN_ENGINES	bing,duckduckgo	英語のデフォルトの自動ルーティングに使用するエンジンのカンマ区切りリスト
AUTO_ROUTE_ZH_ENGINES	baidu,sogou	中国語のデフォルトの自動ルーティングに使用するエンジンのカンマ区切りリスト

2. 🌐 プロキシとネットワークセキュリティ

変数	デフォルト	許可される値／説明
PROXY_URL	empty (off)	上流プロキシの統合設定（以前の USE_PROXY と PROXY_ENGINES を統合します）。TUN モードでは不要です。 • デフォルトのプロキシ：空の PROXY_URL="" または PROXY_URL=true を指定すると、デフォルトの http://127.0.0.1:7897 が有効になります（一般的なローカルプロキシのポートは 7897、7890、10809 です。海外のエンジンはプロキシを使用し、国内のエンジンは直接接続します） • カスタムアドレス：PROXY_URL=http://127.0.0.1:10809 • カスタムエンジン：PROXY_URL="http://127.0.0.1:7897;duckduckgo,brave" またはすべてのエンジン：PROXY_URL=";all"
FAKE_IP_CIDRS	198.18.0.0/15	Fake-IP／TUN モードで SSRF の誤検知によるブロックを回避するためのホワイトリスト登録済み CIDR
IMPERSONATE_BROWSER	chrome_149	wreq-js のブラウザー TLS／H2 フィンガープリントプロファイル（例：chrome_149、safari_18）
IMPERSONATE_OS	windows	フィンガープリント偽装に使用するオペレーティングシステムのプラットフォーム（windows、macos、linux）
BING_IMPERSONATE	true	Bing の HTTP モードで Chrome TLS 偽装を切り替えます（連続して空の結果が返された場合は、サーキットブレーカーが自動的に作動します）
ANUBIS_MAX_POW_DIFFICULTY	6	Startpage Anubis PoW ソルバーの最大難易度しきい値。この値を超える場合はスキップまたはフォールバックします
DIRECT_FIRST_PROBE_TIMEOUT_MS	3500	プロキシにフォールバックする前に、直接接続を優先してプローブする際のタイムアウト（ミリ秒）
FETCH_WEB_INSECURE_TLS	false	fetchWebContent のみ TLS 証明書の検証を無効にします（問題のある古いサイト証明書向け）
GITHUB_README_CDN_FIRST	false	true の場合、raw.githubusercontent.com への直接接続プローブをスキップし、先に jsDelivr CDN に問い合わせます（国内ネットワークの高速化）

カスタムプロキシエンジンリスト：~/.my-websearch/config.json で proxy.engines を設定する場合、または PROXY_URL に ;engine1,engine2 サフィックスを使用する場合は、yahoo を含めてください。古い 1.3.7 時代のリスト（8 エンジンで yahoo を含まないもの）では、Yahoo が直接接続のままになります。中国からの測定では、直接接続は 15～20 秒後にタイムアウトしますが、プロキシ経由なら 約 2 秒で応答します。リストを完全に削除することをおすすめします。現在のデフォルトには Yahoo が含まれ、直接 API を使用するエンジン（GitHub／Stack Overflow／Hacker News／arXiv）はプロキシを経由しません。

3. 🔐 認証情報と API キー

変数	デフォルト	許可される値／説明
CONTEXT7_API_KEY	empty	Context7 API キー（プロキシ／TUN ユーザーには、共有 IP のクォータを避けるため強くおすすめします）
EXA_API_KEY	empty	Exa 無料 API キー（exa セマンティック検索エンジンを使用する場合にのみ必要です）
BRAVE_API_KEY	empty	Brave Search API キー（任意。設定すると、信頼性の高い公式 API を使用します）
GITHUB_TOKEN	empty	GitHub パーソナルアクセストークン（任意。レート制限が 5,000 リクエスト／時に引き上げられます）
GITEE_TOKEN	empty	Gitee パーソナルアクセストークン（任意。Gitee API のレート制限が引き上げられ、プライベートリポジトリが利用可能になります）
STACKOVERFLOW_API_KEY	empty	Stack Apps キー（任意。クォータが 10,000 リクエスト／日に引き上げられます）

4. 🖥️ サーバーモード、並行処理、セッションリーパー

変数	デフォルト	許可される値／説明
MODE	both	MCP トランスポートモード：stdio（stdin/stdout のみ）、http（HTTP/SSE のみ）、both（並行動作）
PORT	3211	MCP HTTP/SSE リッスンポート（ローカルの永続デーモンでは、デフォルトで 3210 を使用）
MAX_CONCURRENT_SEARCHES	20	デーモンモードでの最大同時検索数（無制限にする場合は 0）
MCP_MAX_SESSIONS	100	HTTP 429 Too Many Requests を返す前に保持できる MCP HTTP セッションの最大数
MCP_SESSION_TTL_MS	1800000	セッションを回収するまでのアイドル状態の有効期間（デフォルトは 30 分）
MCP_SESSION_REAPER_MS	300000	セッションリーパーのスキャン間隔（デフォルトは 5 分）
LOG_LEVEL	info	ログレベル：quiet（完全に無音）、debug、info、warn、error
SECURITY_AUDIT	false	SSRF ブロックと Host ヘッダーのセキュリティ監査ログを有効にします
OPEN_WEBSEARCH_ALLOWED_HOSTS	loopback	HTTP サーバーの Host ヘッダー許可リスト（DNS リバインディング対策、カンマ区切り）

5. 🧭 CDP ブラウザーとステルス制御（旧 Playwright 環境変数名を維持）

メモ

ブラウザーのフォールバックでは、chrome-remote-interface 経由で 生の Chrome DevTools Protocol を使用するようになりました。システムにインストール済みの Chrome／Edge を起動します。PLAYWRIGHT_* 環境変数名と SEARCH_MODE=playwright の値は、後方互換性のためだけに維持されています。BING_PLAYWRIGHT_FALLBACK と STARTPAGE_PLAYWRIGHT_FALLBACK は SEARCH_MODE に統合されました。

変数	デフォルト	許可される値／説明
BROWSER_DRIVER	cdp	ブラウザーバックエンド。cdp（デフォルト、生の CDP）。playwright は旧式の代替手段で、playwright-core を手動でインストールする必要があります。現在は同梱されていません。
PLAYWRIGHT_CDP_ENDPOINT	empty	リモート Chrome／Edge の CDP エンドポイント URL（例：http://127.0.0.1:9222 または ws://...）。旧名称ですが、CDP ドライバーで使用されます
PLAYWRIGHT_EXECUTABLE_PATH	auto	ブラウザー実行ファイルの絶対パス（デフォルトではシステムの Edge／Chrome を自動検出）。旧名称
PLAYWRIGHT_HEADLESS	true	ヘッドレスで実行します（Windows では、分離された非表示のデスクトップウィンドウを使用）。旧名称
PLAYWRIGHT_NAVIGATION_TIMEOUT_MS	20000	ページ遷移のタイムアウト上限（ミリ秒）。旧名称ですが、CDP のページ遷移に適用されます

6. 🛠️ アプリケーションディレクトリとツールのカスタマイズ

変数	デフォルト	許可される値／説明
MYWEBSEARCH_DATA_DIR	~/.my-websearch	設定ファイルと永続化される Cookie ファイルのルートディレクトリ
OPEN_WEBSEARCH_RESPONSE_CAP_BYTES	60000	プロンプトのコンテキストが過剰に拡大しないよう、LLM に返す文字数の上限
MCP_TOOL_SEARCH_NAME	search	MCP の検索ツールに付けるカスタム登録名
MCP_TOOL_FETCH_WEB_NAME	fetchWebContent	コンテンツ抽出ツールに付けるカスタム登録名
MCP_TOOL_FETCH_GITHUB_NAME	fetchGithubContent	GitHub／Gitee コンテンツツールに付けるカスタム登録名（後方互換性のため fetchGithubReadme に設定できます）

💡 設定不要のアップグレード（重複した変数を削除）：

• CORS の切り替え（ENABLE_CORS／CORS_ORIGIN）：CORS はデフォルトで無効です。ブラウザークライアントでオリジン間アクセスが必要な場合は、明示的に有効にし、許可するオリジンを制限してください。
• ブラウザーバックエンド：chrome-remote-interface 経由の生の CDP を使用します。playwright-core は同梱されなくなりました。PLAYWRIGHT_* 名と SEARCH_MODE=playwright は、互換性エイリアスとして引き続き使用できます。
• 絵文字の切り替え（OPEN_WEBSEARCH_NO_EMOJI）：コンソールのコードページを自動検出し、古いターミナルでは ASCII タグにスムーズにフォールバックします。
• 分散していたデバッグフラグ（OPEN_WEBSEARCH_DEBUG）：標準の LOG_LEVEL=debug に統合されました。
• Cookie の永続化 TTL（MYWEBSEARCH_COOKIE_TTL_DAYS）：自動スライド更新により、30 日に固定されました。

---

🤝 コントリビューションとテスト

プルリクエストやイシューを歓迎します！ローカルでテストスイートを実行するには、次の手順に従ってください。

npm install
npm run build
npm test              # Run the Vitest suite (88 files, 684 tests at the current baseline)
npm run test:live     # Run bounded-concurrency live integration tests
npm run eval:live     # Run 23-case live STDIO JSON-RPC evaluation suite

謝辞

作者：wtznicy

このプロジェクトは、Aas-ee が作成した Open-WebSearch を発展させたものです。元の作者に特別な感謝を申し上げます。また、以下の皆さんにも感謝します。

• ネイティブな Chrome の TLS／HTTP2 フィンガープリント偽装を提供する wreq-js
• 公式ドキュメントの取得を支える Context7
• コンテンツ抽出と GFM Markdown のフォーマットに貢献する Mozilla Readability & Turndown