duckdata

duckdata

duckdata は、ホスト型の HasData DuckDuckGo MCP サーバーへの小さなローカルブリッジです。DuckDuckGo の検索結果を JSON として返します。クエリを指定すると、タイトル、URL、スニペット、表示 URL、順位、日付、サイトリンク、動画メタデータを含む、順位付けされたオーガニック検索結果が返されます。広告は別の配列に分けられ、上流サーバーが提供する場合は Search Assist AI の回答も含まれます。

このブリッジは独自の検索結果を保持しません。ライブエンドポイントから取得した上流サーバーのツール一覧を、そのままローカルで提供し、各ツール呼び出しを上流に転送して、結果を変更せずに返します。取得時に確認された機能は、読み取り専用の検索取得が 1 つだけです。書き込み、メッセージング、決済のツールはありません。

ツール

• hasdata_duckduckgo_serp_getSearchResults — DuckDuckGo の SERP を取得します。取得時のスキーマには required 配列がありません。q は検索語です（nextPageToken が指定されている場合を除き必須です。nextPageToken には次のページで継続するクエリが含まれます）。kl（us-en や de-de のような <country>-<language> コード。37 地域に対応）で地域を指定するか、代わりに cc と setLang を組み合わせて指定します。kl が優先されます。safeSearch（off、moderate、strict）で成人向けコンテンツをフィルタリングし、deviceType（desktop、mobile、tablet）でフォームファクターを選択し、前回のレスポンスで返された不透明な nextPageToken を使ってページを移動します。

設定

• HASDATA_DUCKDUCKGO_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://mcp.hasdata.com/mcp?apis=duckduckgo です。（この上書き用フックは、この再構築で独自にラベル付けした再現です。）
• HASDATA_API_KEY（任意）— 設定すると、すべての上流リクエストに、呼び出し元自身の HasData API キーを使った x-api-key: <key> ヘッダーが付加されます。設定されていない場合、キーのヘッダーは送信されません。（ヘッダー名と環境変数名は、元のレジストリレコードで固定されています。この環境変数からキーを転送する動作は、ラベル付けした再現です。元の機能はキーなしで取得されています。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name duckdata）を送信し、続いて notifications/initialized 通知を送信してから、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答した場合、その値はセッションの以降すべてのリクエストに付加されます。このセッションはプロセスの存続期間中、再利用されます。レスポンスは通常の JSON またはサーバー送信イベントとして届く場合があり、どちらも読み取られます。

成功した上流の結果は、上流が設定した isError フラグも含め、そのまま渡されます。JSON-RPC エラー、2xx 以外のステータス、読み取り不能なレスポンス、完了できないリクエストなどの失敗は、テキストが duckdata error: で始まる isError 結果として返されます（この表示方法は、この再構築で独自にラベル付けした再現です）。

CLI

このツールは、JSON 引数文字列を 1 つ受け取るサブコマンドとしても利用できます。

npx @reneturcios/duckdata hasdata_duckduckgo_serp_getSearchResults '{"q":"open source search","kl":"us-en","safeSearch":"moderate","deviceType":"desktop"}'
npx @reneturcios/duckdata --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/duckdata mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "duckdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/duckdata", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/duckdata
docker run --rm ghcr.io/cloudcorprecords/duckdata --version

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートは、スタブ化された JSON-RPC 上流サーバーのみを使って実行されます。ライブネットワークへの呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。