serpdata

serpdata

serpdata は、ホスト型の HasData Google Search MCP サーバーへの小規模なローカルブリッジです。Google 検索 データを JSON として返します。クエリを渡すと、 オーガニック検索結果、広告、ナレッジグラフ、 他のユーザーも質問（People Also Ask）、AI Overview のフックを含む 完全な SERP、またはより低コストな 軽量レイアウトを取得できます。レスポンスで返されたトークンを使って続けると、 AI Overview ブロック、イベントの 詳細、または商品のイマーシブなポップアップを取得します。ニュース、 ショッピング、ショート動画、単一商品の検索には、 それぞれ専用のツールがあります。

このブリッジは検索データを保持しません。ライブエンドポイントから 取得したままの上流サーバーのツール一覧をローカルで提供し、 各ツール呼び出しを上流に転送して、結果を変更せずに返します。 取得できる情報は読み取り専用です。各ツールは 公開されている Google の検索結果ページを取得します。書き込み、 購入、チェックアウト、メッセージ送信、支払いを行うツールはありません。

ツール

• hasdata_google_serp_serp_getSearchResults — Google の完全な SERP。必須：q。省略可能な場所の 指定項目（location、uule、domain、gl、hl、 lr）、場所／ナレッジグラフ ID、tbs による期間と 並べ替えのフィルター、tbm による検索カテゴリ、deviceType、 およびページ指定の start／num。
• hasdata_google_serp_serp_light_getSearchResults — JavaScript を使わない軽量な SERP レイアウトです。高速で、オーガニック 検索結果に加え、AI Overview、回答ボックス、ナレッジグラフを返します。必須：q。
• hasdata_google_serp_ai_overview_getAiOverviewResponse — 遅延読み込みされる AI Overview ブロックです。必須： pageToken（SERP レスポンスから取得。1 分間有効）。
• hasdata_google_serp_ai_mode_getAiModeResponse — Gemini を活用した AI Mode の回答です。複数ターンの会話を 継続することもできます。必須：q。
• hasdata_google_serp_news_getGoogleNews — クエリ、またはトピック／セクション／出版物／記事の トークンを指定して Google ニュースを取得します。必須項目はありません。
• hasdata_google_serp_shopping_getSearchResults — クエリに対する Google ショッピングの商品一覧です。必須：q。
• hasdata_google_serp_product_getProductInformation — Google ショッピングから1つの商品について、販売情報、仕様、 またはレビューを取得します。必須：productId。
• hasdata_google_serp_immersive_product_getImmersive_e29f691177 — ショッピングのイマーシブな商品ポップアップを展開します （名前の接尾辞は上流で生成され、そのまま提供されます）。必須：pageToken。
• hasdata_google_serp_events_getEventInformation — SERP のイベント検索結果にある1件のイベントの 詳細情報を取得します。必須：pageToken。
• hasdata_google_serp_short_videos_getShortVideosSearchResults — クエリに対するショート動画のカルーセル（TikTok、Shorts、Reels） を取得します。必須：q。

設定

• HASDATA_GOOGLE_SEARCH_MCP_URL（省略可能）— 上流エンドポイントを上書きします。デフォルトは https://mcp.hasdata.com/mcp?apis=google_serp です。 （上書き用のフックは、この再構築独自のラベル付き 再現機能です。）
• HASDATA_API_KEY（省略可能）— 設定すると、すべての 上流リクエストに、呼び出し元自身の HasData API キーを含む x-api-key: <key> ヘッダーが付与されます。未設定の場合、 キーのヘッダーは送信されません。（ヘッダー名と環境変数名は、元の レジストリ記録に基づいています。この環境変数からキーを 転送する機能は、ラベル付きの再現機能です。元の 仕様はキーなしで取得されています。）

転送の仕組み

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

アップストリームからの成功した結果は、アップストリームが設定した isError フラグも含め、そのまま受け渡されます。 JSON-RPC エラー、2xx 以外のステータス、読み取れない応答、 または完了できないリクエストなどの失敗は、テキストが serpdata error: で始まる isError 結果として返されます （この表現は、この再構築版独自のラベル付き表記です）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドでもあります。

npx @reneturcios/serpdata hasdata_google_serp_serp_getSearchResults '{"q":"HasData CEO","gl":"us"}'
npx @reneturcios/serpdata hasdata_google_serp_news_getGoogleNews '{"q":"open source MCP"}'
npx @reneturcios/serpdata hasdata_google_serp_product_getProductInformation '{"productId":"1234567890","searchType":"offers"}'
npx @reneturcios/serpdata --version

終了コード：成功時は 0、isError の結果時は 1、使用法エラー時は 2 です。

MCP サーバー

npx -y @reneturcios/serpdata mcp

MCP クライアントの設定：

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

Docker

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

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

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC アップストリームに対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

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