@jharding/mcp Server Searxng

SearXNG MCP サーバー（エラーハンドリング強化フォーク）

kevinwatt/mcp-server-searxng のフォークで、AI エージェントで使用する際の体験を向上させるため、エラーメッセージとパラメーター検証を強化しています。

この MCP サーバーの実装は SearXNG と連携し、LLM エージェントへのフィードバックを改善した、プライバシー重視のメタ検索機能を提供します。

LLM と初心者向け

特定の範囲の検索結果を取得する方法：

• 結果 1～10 を取得するには：offset=0、max_results=10 を設定します
• 結果 11～20 を取得するには：offset=10、max_results=10 を設定します
• 結果 40～43 を取得するには：offset=39、max_results=4 を設定します

重要：

• ページネーションに page を使用しないでください。offset と max_results を使用してください。
• offset は 0 から始まります。offset=0 は最初の結果から開始することを意味します。
• max_results は取得したい結果の件数です（最後の結果番号ではありません）。

よく使われるパターンの表：

取得したい結果	offset	max_results
1-10	0	10
11-20	10	10
21-30	20	10
40-43	39	4

例：

{ "offset": 39, "max_results": 4 }

機能

• メタ検索：複数の検索エンジンの結果を統合します
• プライバシー重視：トラッキングやユーザープロファイリングは行いません
• 複数のカテゴリ：一般、ニュース、科学、ファイル、画像、動画などに対応します
• 言語サポート：特定の言語またはすべての言語で検索できます
• 期間フィルター：日、週、月、年で結果を絞り込めます
• セーフサーチ：3 段階のセーフサーチフィルタリング
• フォールバックサポート：信頼性を高めるため、複数の SearXNG インスタンスに対応します
• 構造化 JSON レスポンス：検索結果にプログラムからアクセスするための構造化形式

エラーハンドリング強化機能

• パラメーター検証の改善：すべてのパラメーターについて、有効な形式を明確に示します
• 状況に応じたエラーメッセージ：入力内容と期待される内容を示す詳細なフィードバックを提供します
• LLM 向けの説明：LLM が理解しやすいように最適化されたスキーマの説明
• 例に基づくフィードバック：エラーメッセージに正しい形式の例を含めます
• デバッグログの強化：パラメーター検証の問題をより詳しく記録します

このフォークの理由

このフォークは、AI エージェント（特に qwen3 などのモデル）が MCP ツールを使用する際に発生する特定の問題に対処するために作成されました。主な改善点は次のとおりです。

1. LLM 向けのエラーメッセージの改善：何が問題だったのかを LLM が理解し、修正しやすい形で明確に説明するエラーレスポンスを強化しました。

2. 形式要件の明確化：より詳細なスキーマ定義により、「3d」のような日付形式の省略表記ではなく「day」を使用するといった、よくある間違いを防ぎます。

3. 比較形式のエラーフィードバック：検証に失敗した場合、受け取った内容と期待される内容の両方をエラーに表示するため、エージェントが間違いから学びやすくなります。

4. 例に基づく学習：エラーメッセージに有効な値の具体例を含め、避けるべき無効な形式も明示します。

5. 構造化 JSON レスポンス：web_search ツールは検索結果を構造化 JSON 形式で返します。適切なメタデータ、スコア、分類情報とともに、アプリケーションから検索結果をプログラムで処理しやすくなります。

これらの変更により、AI エージェントが MCP プロトコルを通じてこのツールを使用する際の障壁を減らし、エラーを減らして全体的なユーザー体験を向上させることを目指しています。

インストール

手動インストール

npm install -g @jharding_npm/mcp-server-searxng

ソースからインストール

git clone https://github.com/jhstatewide/mcp-server-searxng.git
cd mcp-server-searxng
npm install
npm run build

使用方法

直接実行

mcp-server-searxng

Dive Desktop で使用する場合

1. Dive Desktop で「+ Add MCP Server」をクリックします
2. 次の設定をコピーして貼り付けます。

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "@jharding_npm/mcp-server-searxng"
      ]
    }
  }
}

3. 「Save」をクリックして MCP サーバーをインストールします

使用例

基本的な検索：

# Returns structured JSON results
web_search("artificial intelligence news")

フィルターを使った高度な検索：

# Search with specific parameters
web_search("climate change", {
  "time_range": "week",
  "language": "en",
  "safesearch": 1
})

パラメーター制御の例：

# Pagination: Get results 21-30 with custom content length
web_search("artificial intelligence", {
  "max_results": 10,
  "offset": 20,
  "content_length": 300
})

# Large batch: Get 50 results with short snippets
web_search("machine learning", {
  "max_results": 50,
  "offset": 0,
  "content_length": 100
})

ツールのドキュメント

web_search

複数のエンジンでメタ検索を実行し、構造化された JSON の結果を返します。

入力：

• query（文字列、必須）：検索するテキスト
• max_results（数値、任意、デフォルト 10）：返す結果の最大数（1～100）
• offset（数値、任意、デフォルト 0）：スキップする結果の数（0 始まり）
• content_length（数値、任意、デフォルト 200）：結果のコンテンツスニペットあたりの最大文字数（50～1000）
• page（数値、任意、デフォルト 1）：ページ番号（上級者向け。代わりに offset/max_results を使用してください）
• language（文字列、任意、デフォルト 'all'）：言語コード（例：'en'、'all'）
• time_range（文字列、任意、デフォルト 'all_time'）：'all_time'、'day'、'week'、'month'、または 'year'
• safesearch（数値、任意、デフォルト 1）：0 = なし、1 = 中程度、2 = 厳格

**出力：**以下の形式の構造化 JSON レスポンス：

{
  "results": [
    {
      "title": "Title of the search result",
      "url": "https://www.example.com",
      "content": "Content of the search result (truncated to 2 sentences if long)",
      "score": 0.85,
      "category": "news",
      "engine": "google",
      "publishedDate": "2023-01-01"
    }
  ],
  "metadata": {
    "total_results": 100,
    "time_taken": 0.123,
    "query": "original search query"
  }
}

機能：

• 利用可能なすべてのフィールドを含む個別の結果オブジェクト
• 読みやすさのためのコンテンツの自動切り詰め
• 処理時間や結果数などの検索メタデータ
• 検索エンジンから取得できる場合は関連性スコア
• 各結果のエンジンおよびカテゴリ情報
• offset と max_results パラメーターを使った高度なページネーション

開発

git clone https://github.com/jhstatewide/mcp-server-searxng.git
cd mcp-server-searxng
npm install
npm run build
npm start

ライセンス

この MCP サーバーは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

前提条件

ローカルで SearXNG インスタンスを実行している必要があります。セットアップ方法：

Docker で SearXNG を実行する

クイックスタート

# Create config directory
mkdir -p searxng

# Create config file
tee searxng/settings.yml << EOF
use_default_settings: true

server:
  bind_address: "0.0.0.0"
  secret_key: "CHANGE_THIS_TO_SOMETHING_SECURE"  # Generate a random key
  port: 8080

search:
  safe_search: 0
  formats:
    - html
    - json

engines:
  - name: google
    engine: google
    shortcut: g

  - name: duckduckgo
    engine: duckduckgo
    shortcut: d

  - name: bing
    engine: bing
    shortcut: b

server.limiter: false
EOF

# Start container
docker run -d \
  --name searxng \
  -p 8080:8080 \
  -v "$(pwd)/searxng:/etc/searxng" \
  searxng/searxng

検索関数のテスト

# Test JSON API with curl
curl -v 'http://localhost:8080/search?q=test&format=json'

# Or visit in browser
http://localhost:8080/search?q=test

コンテナ管理

# Stop container
docker stop searxng

# Remove container
docker rm searxng

# View container logs
docker logs searxng

# Enable auto-start on boot
docker update --restart always searxng

--restart always フラグにより、次の動作が保証されます：

• Docker デーモンの起動時にコンテナが自動的に起動します
• クラッシュした場合、コンテナが自動的に再起動します
• ユーザーが明示的に停止しない限り、停止した場合もコンテナが自動的に再起動します

カスタム設定

searxng/settings.yml を編集して、次の項目を設定します：

• 検索エンジンのリストを変更する
• セキュリティ設定を調整する
• UI の言語を設定する
• API の制限を変更する

設定オプションの詳細については、SearXNG ドキュメントを参照してください。

環境変数

• SEARXNG_INSTANCES：SearXNG インスタンス URL のカンマ区切りリスト デフォルト：http://localhost:8080

• SEARXNG_USER_AGENT：リクエストに使用するカスタム User-Agent ヘッダー デフォルト：MCP-SearXNG/1.0

• SEARXNG_MAX_ATTEMPTS：インスタンスごとの合計試行回数（初回リクエスト＋再試行） デフォルト：4（初回試行 1 回＋再試行 3 回）

• SEARXNG_RETRY_BASE_DELAY_MS：再試行時の基本待機時間（ミリ秒、指数バックオフ） デフォルト：300

• SEARXNG_RETRY_JITTER_MS：各再試行の待機時間に加えるランダムなゆらぎ（ミリ秒） デフォルト：100

• SEARXNG_REQUEST_TIMEOUT_MS：1 回の試行に対するリクエストのタイムアウト（ミリ秒） デフォルト：10000

• SEARXNG_RETRY_SOFT_FAILURES：結果が空、JSON が不正、CAPTCHA／チャレンジページが検出された場合など、レスポンスレベルのソフト失敗を再試行するかどうか デフォルト：true

• SEARXNG_RETRY_MAX_DELAY_MS：サーバーから指定された Retry-After を含む、個々の再試行における最大待機時間 デフォルト：10000

• SEARXNG_RETRY_BUDGET_MS：SearXNG インスタンスごとの再試行待機時間の最大合計 デフォルト：30000

• SEARXNG_CACHE_TTL_MS：成功した生の検索レスポンスをメモリー内キャッシュで有効な状態に保つ期間 デフォルト：300000（5 分）

• SEARXNG_STALE_IF_ERROR_MS：上流が利用できない場合に、期限切れのキャッシュ済みレスポンスを提供できる期間 デフォルト：3600000（1 時間）

• SEARXNG_CIRCUIT_COOLDOWN_MS：上流への接続が失敗し、再試行を使い切った後にインスタンスを抑制する期間 デフォルト：30000（30 秒）

キャッシュからのフォールバックレスポンスには、metadata.stale: true、metadata.stale_reason、metadata.cached_at が設定されます。チャレンジおよび不正なレスポンスによる失敗では、サーキットが直ちに開きます。一時的な HTTP 失敗では、上限付きの再試行ポリシーを使い切った後にサーキットが開きます。成功したレスポンスを受け取ると、サーキットは閉じます。

• NODE_TLS_REJECT_UNAUTHORIZED：自己署名証明書を使用した開発環境で SSL 証明書の検証を回避するには、'0' に設定します デフォルト：undefined（SSL 検証は有効）

すべてのオプションを使用した設定例：

{
  "mcpServers": {
    "searxng": {
      "name": "searxng",
      "command": "npx",
      "args": [
        "-y",
        "@jharding_npm/mcp-server-searxng"
      ],
      "env": {
        "SEARXNG_INSTANCES": "http://localhost:8080,https://searx.example.com",
        "SEARXNG_USER_AGENT": "CustomBot/1.0",
        "SEARXNG_MAX_ATTEMPTS": "4",
        "SEARXNG_RETRY_BASE_DELAY_MS": "300",
        "SEARXNG_RETRY_JITTER_MS": "100",
        "SEARXNG_REQUEST_TIMEOUT_MS": "10000",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

NODE_ENV=test の場合、再試行のデフォルト値は、決定性の高い高速なテストに適した値になります。

• SEARXNG_RETRY_BASE_DELAY_MS=1
• SEARXNG_RETRY_JITTER_MS=0
• SEARXNG_REQUEST_TIMEOUT_MS=1000

⚠️ 警告：本番環境で SSL 証明書の検証を無効にすることは推奨されません。

デフォルトではセーフサーチは OFF（0）で、最も網羅的な結果が返されます。セーフサーチを有効にすると関連情報が除外される場合があるため、調査や一般的な用途ではこの設定が推奨されます。

スキーマとデフォルト値を簡素化することで、このツールは小規模な LLM（7b モデル）での使用に最適化されています。

メンテナー向け：ビルド、パッケージ化、リリース手順

npm に新しいバージョンをリリースするには：

1. package.json のバージョンを更新します（例：0.5.4 に更新）：

   # Edit package.json and update the "version" field
   

2. プロジェクトをビルドします：

   npm run build
   # or
   yarn build
   

3. プロジェクトをパッケージ化します（任意。内容の確認に使用）：

   npm pack
   # This creates a tarball like jharding_npm-mcp-server-searxng-0.5.4.tgz
   # You can inspect it with:
   tar -tzf jharding_npm-mcp-server-searxng-0.5.4.tgz
   

4. パッケージ化した tarball をローカルでテストします（任意）：

   npx -y ./jharding_npm-mcp-server-searxng-0.5.4.tgz --help
   # Should show CLI help and not hang
   

5. npm に公開します：

   npm publish --access public
   

6. 公開した CLI を確認します：

   npx @jharding_npm/mcp-server-searxng@latest --help
   

注： npm に公開する適切な権限があること、および npm アカウントにログインしていることを確認してください。

バージョン管理に関する注記

新しいリリースを作成する際は、次の両方でバージョン番号を更新する必要があります。

• package.json
• src/index.ts（version 定数）

これにより、CLI に表示されるバージョンと公開されたパッケージのバージョンが一致します。