serpdata

serpdata

serpdata 是一个小型本地桥接服务，用于连接托管的 HasData Google Search MCP 服务，该服务以 JSON 格式返回 Google 搜索 数据。向它发送查询，它就会返回完整的 SERP——自然搜索结果、广告、知识图谱、 “其他人也在问”、AI Overview 入口——也可以返回更轻量的 布局；使用这些响应返回的令牌，即可获取 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 — 轻量级、无 JS 的 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 News。无必需字段。
• hasdata_google_serp_shopping_getSearchResults — 查询对应的 Google Shopping 商品列表。必需：q。
• hasdata_google_serp_product_getProductInformation — 从 Google Shopping 获取一件商品的报价、规格或评价。 必需：productId。
• hasdata_google_serp_immersive_product_getImmersive_e29f691177 — 展开 Shopping 沉浸式商品弹窗 （名称后缀由上游生成，并按原样提供）。必需：pageToken。
• hasdata_google_serp_events_getEventInformation — 获取 SERP 活动搜索结果中某项活动的完整详情。 必需：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（可选）— 设置后，每个上游 请求都会携带 x-api-key: <key> 请求头，使用调用方自己的 HasData API 密钥。未设置时， 不会发送密钥请求头。（请求头名称和环境变量名称依据原始 注册记录固定；从此环境变量转发密钥是特别标注的重建内容——原始 功能界面是在无密钥状态下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（协议版本 2025-03-26， clientInfo 名称为 serpdata），然后发送 notifications/initialized 通知，接着发送 tools/call 请求，并原样携带调用方的参数。当上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会随 此会话的后续每个请求一起发送；该会话在进程的整个生命周期内复用。 响应可能是纯 JSON，也可能是服务器发送的事件；两种形式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，文本以 serpdata error: 开头（这种呈现方式是本次重建自行标注的还原结果）。

CLI

每个工具也都是一个子命令，接受一个 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。