searxng-deepdive

searxng-deepdive

実際のリサーチを行う LLM エージェント向けに設計された、SearXNG 用の MCP サーバーです。エージェントが使いやすいスキーマを備えた 4 つのツール、複数ページにわたる結果の集約、軽量な URL→Markdown 読み込み、そして お使いの SearXNG インスタンスの実際のエンジンプールから動的に生成されるツールの説明を提供します。

なぜ別の mcp-searxng が必要なのですか？

既存のパッケージは最小限の機能しかなく、ほとんどが単一の search(query) ツールを公開するだけで、モデルが追加の結果を要求したり、特定のエンジンを対象にしたり、カテゴリで絞り込んだりする方法がありません。機能がより豊富なものでも、静的な説明が組み込まれているため、LLM は この インスタンスで実際に有効になっている機能を知ることができません。エージェントによるツール選択の使いやすさを設計上の優先事項としているものもありません。

searxng-deepdive では、こうした設定を利用できます。

機能	本パッケージ	npm mcp-searxng（ihor-sokoliuk）	PyPI mcp-searxng（SecretiveShell）
エンジンの指定	✅ search_on_engines で対応	❌	❌
カテゴリの指定	✅ search_by_category で対応	❌	❌
1 回の呼び出しで複数ページの結果を集約	✅ pages: N で対応	❌（1 回の呼び出しにつき 1 ページ）	❌
ページネーション	✅ pageno	✅	❌
コンパクトなレスポンスへの整形	✅ format: "compact"	❌	❌
インスタンスごとの動的な説明	✅ 実際のエンジン一覧を挿入	❌ 静的	❌ 静的
ツール間のヒントを含む検証	✅ エンジンとカテゴリの判別、大文字と小文字を区別しない	❌	❌
結果が 0 件の場合のヒント	✅ time_range／応答しないエンジン／単一エンジン	❌	❌
URL リーダー（HTML→Markdown）	✅ 目次のスキャンとセクションの抽出に対応	✅ 基本機能	❌
テストスイート	✅ 単体テストと統合テストを 102 件	最小限	❌

クイックスタート

任意の MCP クライアントから npx -y でインストールします。

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "searxng-deepdive"],
      "env": { "SEARXNG_URL": "http://127.0.0.1:7979/" }
    }
  }
}

SEARXNG_URL には、稼働中の SearXNG インスタンスを指定してください。まだお持ちでない場合は、関連リポジトリの SearXNG-Compose に、LLM での利用に最適化された、すぐに使える Docker スタックが用意されています。

要件： Node.js 22 以降。

ツール

このサーバーは 4 つのツールを登録します。LLM は以下の説明に基づいてツールを選択します。説明には、起動時にお使いのインスタンスから取得した実際のエンジンとカテゴリの一覧も追加されます。

search(query, [...])

有効になっているすべてのエンジンプールを対象にした、広範なウェブ検索です。特定の情報源を優先する必要がない場合に使用します。応答したエンジンの数にかかわらず、結果を統合し、重複を除いて返します。

search_on_engines(query, engines, [...])

指定したエンジンのみを使って検索します（例：["arxiv", "pubmed", "semantic scholar"]）。MCP クライアントに登録されるツールの説明には、お使いのインスタンスで有効な実際のエンジン一覧が含まれるため、エージェントが名前を推測する必要はありません。無効な名前がカテゴリのように見える場合は、「もしかして」ヒントを添えて検証エラーを返します。

search_by_category(query, categories, [...])

特定のカテゴリ内を検索します。各カテゴリに属するすべてのエンジンが実行されます。説明には、実際のカテゴリ一覧と、それぞれに属するエンジンが含まれます。検証方法も同じです。無効なカテゴリ名が指定され、その値が実際にはエンジン名である場合は、search_on_engines を案内する明確なエラーを返します。

web_url_read(url, [readHeadings, section, paragraphRange, startChar, maxLength])

URL を取得し、HTML を整った Markdown に変換します。軽量な HTTP + HTML→Markdown（ヘッドレスブラウザーは不要）で、静的 HTML の ウェブサイトの約 80％（Wikipedia、ドキュメントサイト、ブログ、ニュース、GitHub の README）に対応します。

トークン効率の高い抽出モード（優先順位順。最初に設定されたものが適用されます）：

• readHeadings: true — 見出し一覧のみを階層的な目次として返します
• section: "Installation" — 一致する見出しの下にあるコンテンツを返します
• paragraphRange: "3-7" — 段落を 1 から数えて指定範囲で切り出します
• startChar + maxLength — 文字単位で範囲を指定してページ分割します

長いページで推奨されるワークフロー：まず目次を確認し（readHeadings）、次に対象を絞って読み込みます（section）。ページ全体を最初に取得するより、はるかにトークン効率が高くなります。

readHeadings の結果に項目がない場合（Reddit のスレッド、コメント欄、<h*> タグの代わりに太字の段落を使っているブログ記事など）、ページの構造はフラットです。paragraphRange で順にサンプリングするか、抽出モードを指定せずに取得してください。

web_url_read は JSON、YAML、TOML のコンテンツタイプも直接受け付けるため（仕様ファイル、パッケージマニフェスト、レジストリー API の応答、CI ワークフローの YAML など）、リサーチエージェントは HTML 専用のスタブを介さずにこれらを読み取れます。

JavaScript でレンダリングされる SPA やボット対策されたサイトでは、このツールが最小限または空のコンテンツを返します。その場合は、Chromium ベースのリーダー（Crawl4AI など）に切り替えてください。

すべての検索ツールに共通するパラメーター

• pageno — 開始ページ（1 から数えます。デフォルトは 1）
• pages — 1 回の呼び出しで複数ページを取得します（1～5。デフォルトは 1）
• time_range — day / week / month / year（警告：すべてのエンジンが対応しているわけではなく、設定すると空の結果を返すものもあります）
• language — BCP-47 コード、または all
• safe_search — 0 / 1 / 2
• format — compact（デフォルト）または full

設定

環境変数	デフォルト	説明
SEARXNG_URL	http://127.0.0.1:8080	SearXNG インスタンスのベース URL

開発

git clone <this repo>
cd searxng-deepdive          # or wherever you cloned to
npm install
npm run build                # tsc
npm test                     # vitest
SEARXNG_URL=http://127.0.0.1:7979 npm run probe    # exercise the SearXNG client
SEARXNG_URL=http://127.0.0.1:7979 npm run dev      # start the MCP stdio server

開発中にソースを MCP クライアントに指定する

編集のたびに再ビルドする必要がないよう、tsx を使って src/ から直接実行します。

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/searxng-deepdive/src/index.ts"],
      "env": { "SEARXNG_URL": "http://127.0.0.1:7979/" }
    }
  }
}

MCP クライアントはサブプロセスをキャッシュします。 コードを編集しても、実行中の サーバーはサブプロセスが終了して再起動されるまで古い動作を維持します。ホスト（LM Studio、Claude Desktop など）を完全に終了してから 再度開いてください。チャットウィンドウを閉じるだけでは通常不十分です。これを行わなかった場合の症状： 直前に反映した修正が適用されません。

テスト

npm test

テストカバレッジは 7 つのファイルにわたります。

• normalize-name — 大文字と小文字を区別しない名前の処理
• validators — 相互参照のヒントを含むエンジン／カテゴリの検証
• zero-result-hint — すべてのヒントのトリガーと、その逆のケース
• trim-to-compact — 応答のトリミングとヒントの追加
• descriptions — 以前のバージョンで実際のモデルを誤解させた説明文（「エンジンでは無視されます」、「デフォルトは 'auto'」など）に対するアンチパターン正規表現チェック。再発した場合はビルドが失敗します
• searxng-client — MockAgent を使った HTTP クライアント。不正な JSON、HTML の 502 ページ、429 レート制限の処理、複数ページ取得時の重複排除、全ページの取得失敗時の例外をテストします
• url-reader — 抽出モードと HTTP 統合

設計上のメモ

• 省略可能な engine/category パラメーターを持つツールを1つにせず、4つに分けているのはなぜですか？ エージェントの判断がより明確になります。ツールを分けると、LLM にはそれぞれの目的が明示されます。一方、1つの大きなツールでは、どの省略可能なフラグをいつ設定するかを覚えておく必要があります。その代わり、MCP ツールリストの項目数は増え、ハンドラーコードの大部分が同一になります。総合的には、特に小規模なモデルでエージェントの使い勝手が向上します。

• デフォルトを format: "compact" にしているのはなぜですか？ SearXNG の完全な結果オブジェクトは、url＋title＋content＋engine だけの場合と比べて数倍も大きくなります。一般的なエージェントのワークフロー（候補を順位付けし、いくつかを選んで詳細を取得する）では、LLM が実際に使うのは compact 形式です。スコア、日付、著者、DOI が必要な場合も、パラメーターを1つ変更するだけで format: "full" を指定できます。

• 説明を動的にしているのはなぜですか？ 静的な説明では、すべての上流エンジンを列挙すると（特定のインスタンスで有効になっていないものがほとんどで、コンテキストを無駄にします）、または何も列挙しないと（LLM は engines に何を指定すればよいかわかりません）、どちらの場合も問題があります。サーバー起動時に /config をリアルタイムで調べることで、このインスタンスにぴったりのヒントを LLM に提示できます。

• 誤りを黙って返すのではなく、原因がわかる形で誤りを返すのはなぜですか？ 実際の LM Studio でのテストでは、失敗した検索が成功したように見えてしまうため、エージェントが再試行ループから抜け出せなくなるケースが繰り返し確認されました（結果が0件で「一致なし」のように見える、または無関係な結果が60件表示されて検索が実行されたように見える）。バリデーションとゼロ件結果のヒントを組み合わせることで、毎回、実際の原因が明らかになります。説明のアンチパターンを検証するテストスイートでは、モデルを誤解させることが実証された文言を使用しないようにしています。

セキュリティに関する注意事項

このパッケージは、MCP 対応の LLM クライアント（Claude Desktop、LM Studio、 Cursor など）とともに、ユーザーの信頼境界内でローカルに実行するよう 設計されています。信頼モデルでは、次のことを前提としています。

• LLM はユーザーの代理として動作します
• サーバーに接続するモデルはユーザーが管理します
• MCP トランスポートは stdio であり、リモートの呼び出し元には公開されません

この境界内で、把握しておくべき点が 2 つあります。

• web_url_read はモデルから渡された任意の HTTP(S) URL を、最大 5 回のリダイレクトを経て取得します。 プライベートネットワークにルーティングできるホストでは、モデルがイントラネットサービス、リンクローカルアドレス、クラウドインスタンスのメタデータエンドポイント（169.254.169.254 など）にアクセスできる可能性があります。これはローカル調査ツールとして意図した動作ですが、信頼できない第三者が URL を指定できる構成（たとえば、パブリックインターネットに公開されたホスト型 MCP ゲートウェイ）では、この MCP サーバーを実行しないでください。制限する場合は、SEARXNG_DEEPDIVE_BLOCK_PRIVATE=1 を設定すると、プライベート、ループバック、リンクローカル、メタデータの各宛先へのアクセスを拒否できます。この設定はリダイレクトの各段階で、実際に接続する IP アドレスに対して適用されるため、DNS リバインディングで回避することはできません。また、SEARXNG_DEEPDIVE_ALLOWED_HOSTS を使って、特定の内部ホストを許可リストに追加できます。file:// を含む HTTP(S) 以外のスキームは常に拒否されるため、このツールがローカルファイルを読み取ることはありません。本文サイズは 10 MB に制限され、1 回のリクエストの合計時間は 45 秒までです。また、返される Markdown の長さにも上限が設けられています（startChar／maxLength を使ってページ分割してください）。そのため、不正な形式または過大な応答を返す上流サービスによって、メモリや呼び出し元のコンテキストウィンドウが容易に枯渇することはありません。

• search ツールは、モデルのクエリをそのまま SearXNG に転送します。 上流エンジンへのトラフィックに関する信頼境界は SearXNG であり、このパッケージでは追加のレート制限やクエリの書き換えは行いません。

• ツールの出力は敵対的な入力であり、プロンプトインジェクションの可能性があります。 検索結果のスニペットと web_url_read が返す Markdown には、モデルが作業コンテキストの一部として読むテキストが含まれます。管理していないページやスニペットには、「以前の指示を無視して……」などの指示が含まれている可能性があります。これはこの MCP サーバーの欠陥ではなく、外部テキストを返すあらゆるツールに固有の問題です。ただし、人間による確認なしにツールの出力に基づいて自動で動作するエージェントのループは、脅威モデルに含まれます。特に、ユーザーではなくモデルが選んだ URL に対する web_url_read では、ツールの出力を信頼できない入力として扱ってください。

このパッケージは、無保証で、損害に対する責任を負わない現状有姿の状態で MIT ライセンスに基づき提供されます。LICENSE をご覧ください。脆弱性の疑いを報告する場合は、公開の issue を作成するのではなく、GitHub Security Advisories から非公開で報告してください。SECURITY.md もご覧ください。

ライセンス

MIT — LICENSE をご覧ください。