Skip to main content
Glama
dsh-google-chrome-search

dsh-google-chrome-search

dsh-google-chrome-search

CI license: MIT node: >=18

一个 DeepSeek Harness (DSH) 插件,让 AI 代理 通过 CDP(Chrome DevTools 协议)驱动 本地 Chrome 浏览器,执行真实的 Google 网页搜索,并 渲染任意页面以提取其内容。无需搜索 API 密钥 —— 它使用机器上已安装的 Chrome 即可工作。

Google 经常为自动化流量和数据中心流量提供人工验证页面(CAPTCHA / “异常流量”)。发生这种情况时,此插件会打开一个可见的 Chrome 窗口,指向验证页面,等待人工完成验证,然后从现已受信任的会话中提取结果。这就是“询问人工”的步骤——按照设计,代理永远不会尝试自行解决 CAPTCHA。

Google's verification page, as shown to the human

功能一览

组件

路径

用途

核心引擎

src/search.mjs

Chrome/CDP Google 搜索 + CAPTCHA 验证 + 结果提取

页面引擎

src/fetch.mjs

渲染任意 URL + 提取可读内容(Mozilla Readability)+ search_and_fetch

MCP 服务器

src/server.mjs

通过 stdio 暴露 search、fetch、search_and_fetch → DSH 中的原生 mcp__google__*

CLI

bin/google-search.mjs

dsh-google-search "<query>" 和 dsh-google-search fetch "<url>" 用于直接使用

技能

skill/SKILL.md

教代理如何使用它 + 人工验证工作流程

Related MCP server: browser-search-mcp

要求

  • Node.js ≥ 18(在 Node 22 上测试)

  • 本地 Chrome/Chromium 可执行文件(例如 google-chrome、chromium)。从常见路径自动检测;可通过 CHROME_PATH 或 --chrome 覆盖。

  • 对于可见验证步骤,需要带有显示器的桌面会话(以便向人工显示 Chrome 窗口)。无头/SSH 环境仍可检测 CAPTCHA 并报告(附截图)。

安装

git clone https://github.com/davidcastilloalvarado/dsh-google-chrome-search.git
cd dsh-google-chrome-search
npm install

依赖项:puppeteer-core(驱动你的 Chrome——它不会下载浏览器)、@modelcontextprotocol/sdk(用于 MCP 服务器)、@mozilla/readability(内容提取)和 zod(模式验证)。

可选地全局链接 CLI,使其位于 PATH 中:

npm link        # gives you: dsh-google-search "<query>"

使用 CLI

# Search:
node bin/google-search.mjs "nodejs streams" --max 8
# or, after npm install / npm link:
npm run search -- "nodejs streams" --json

# Search, then render + extract the top 3 result pages:
node bin/google-search.mjs "nodejs streams" --max 8 --fetch-top 3 --fetch-max-chars 8000

# Fetch one URL directly (render + extract readable content):
node bin/google-search.mjs fetch "https://nodejs.org/api/stream.html" --max-chars 8000

退出码:0 = 成功(结果 / 获取的内容),2 = 需要验证(CAPTCHA),3 = 无结果 / 获取被阻止或失败,1 = 错误,64 = 用法错误。

获取页面(渲染 + 提取)

该插件还可以渲染任意 URL 并提取其可读的主要内容:

  • 在同一个专用 Chrome 配置文件中运行页面(因此,看到一致、可信指纹的网站表现更好)。

  • 等待页面完全加载(包括较晚的 SPA 内容)。

  • 使用Mozilla Readability 在实时页面内提取文章。如果页面没有明显的文章,则回退到整页文本。

  • 输出有上限(默认每页 8,000 字符),以保持对代理上下文友好。

  • 检测反机器人墙并报告 blocked,而不是返回垃圾内容。当网站提供人工验证挑战(例如 DataDome 的“滑动继续”墙)时,它会打开一个可见的 Chrome 窗口显示该页面,等待最多 verifyTimeoutMs 让人工通过,然后提取真实内容——与 Google CAPTCHA 流程相同的人工交接理念。受信任的会话 cookie 会保留在配置文件中,因此该网站的后续页面通常可以无头通过。使用 --no-verify / autoVerify: false 则仅报告 blocked。

dsh-google-search fetch "https://example.com/article" --max-chars 10000
dsh-google-search fetch "https://example.com/article" --html --screenshot

两种组合搜索和阅读的方式:

方式

如何操作

搜索,然后一次调用读取前 N 个页面

search_and_fetch(MCP)/ --fetch-top N(CLI)

搜索,然后读取特定结果

search,然后使用所选 URL 进行 fetch

页面按顺序渲染(一个浏览器,一次一个页面)——预计每页约 1–3 秒。

作为原生 DSH 工具使用(MCP)

在您的配置文件配置中,使用 DSH 的 @deepseek-ai/dsh-mcp-client 注册 MCP 服务器(示例——请根据您的环境调整 command 和 args 路径):

- insert:
    - id: mcp-google
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: google
        transport: stdio
        command: /path/to/node
        args: [ /path/to/dsh-google-chrome-search/src/server.mjs ]
        env:
          CHROME_PATH: /usr/bin/google-chrome   # optional — auto-detected if unset
        toolCallTimeoutMs: 300000

DSH 重启后,代理将获得三个原生工具:

工具

功能

mcp__google__search

Google 网页搜索 → 链接 + 摘要

mcp__google__fetch

渲染一个 URL → 提取可读内容(标题、署名、文本、可选的 HTML/截图)

mcp__google__search_and_fetch

搜索 → 渲染前 N 个页面 → 一次调用中每页提取的内容

注意:

  • 调用是串行化的(Chrome 每个配置文件只允许一个进程),因此并发工具调用会排队而不是并行运行。

  • search_and_fetch 比普通搜索慢:请将 toolCallTimeoutMs 保持为 300000(5 分钟),如上所示。

  • 人工验证流程适用于两者:Google 搜索(CAPTCHA)和阻止浏览器的结果页面(反机器人滑块):会为人工打开一个可见的 Chrome 窗口,之后会话会保留在配置文件中。

作为 DSH 技能使用

skill/SKILL.md 教代理如何运行搜索以及如何处理将 CAPTCHA 移交给人工。要安装它,请将其复制到您的 DSH 技能目录,例如:

mkdir -p ~/.dsh/skills/google-chrome-search
cp skill/SKILL.md ~/.dsh/skills/google-chrome-search/

在另一台机器上共享/使用之前,请编辑 SKILL.md 中的 <INSTALL_DIR> 占位符,使其指向您克隆此仓库的位置(或者将 npm link CLI 放在 PATH 中,它就可以直接工作)。

配置(环境变量 / 选项)

选项 / 环境变量

默认值

含义

chromePath / CHROME_PATH

自动检测

Chrome 可执行文件

profileDir / GSEARCH_PROFILE

~/.dsh-chrome-google

持久化的专用 Chrome 配置文件(保留“已验证”的 cookie)

maxResults

8

要返回的自然结果数(最多 20)

verifyTimeoutMs

150000

等待人工解决 CAPTCHA 的时间

autoVerify

true

如果为 false,绝不打开可见窗口——仅报告

gl / hl

us / en

地区 / 语言

maxChars

8000

每个获取页面的最大提取字符数(fetch / search_and_fetch)

fetchTop

3

在 search_and_fetch 中渲染的结果页数量(最多 5)

includeHtml / screenshot

false

fetch 选项:同时返回提取的 HTML / 页面截图

timeoutMs

20000

每个获取页面的导航超时时间

人工验证流程,逐步说明

  1. Chrome 以无头模式运行搜索(一个专用的、隔离的配置文件——绝不是您的真实浏览器)。

  2. 如果存在结果 → 返回它们(status: ok)。

  3. 如果 Google 提供 CAPTCHA:

    • 截图。

    • 在验证页面上打开一个可见的 Chrome 窗口(同一配置文件)。

    • 等待最多 verifyTimeoutMs 让人工解决,轮询页面。

    • 如果已解决 → 提取并返回结果(标记为 verifiedViaHuman: true)。如果超时 → 返回 status: verification_required 并附上最新截图。

  4. 已验证的会话保留在配置文件中,因此下一次搜索通常可以无头成功。

测试

npm test

启动 MCP 服务器,检查 search、fetch 和 search_and_fetch 工具是否列出,并且——如果机器上有 Chrome 可执行文件——使用 autoVerify: false 执行实时搜索。在没有浏览器的环境(例如 CI)中,实时调用会被优雅地跳过。

故障排除

症状

修复

Could not find Chrome / 启动错误

安装 Chrome/Chromium 或设置 CHROME_PATH / --chrome

在容器中以 root 运行,沙箱错误

默认是 --no-sandbox(用于隔离);如果您想启用沙箱,请传递 noSandbox: false

每次搜索都出现 CAPTCHA

保留专用配置文件(~/.dsh-chrome-google)——删除它会重置“已验证”的 cookie。数据中心 IP 更常遇到 CAPTCHA。

SSH 上不出现可见窗口

使用带有显示器的机器,或设置 autoVerify: false 并在打印的截图的浏览器上下文中手动解决 CAPTCHA。

ECONNREFUSED / 配置文件中的陈旧锁

关闭使用该配置文件的所有 Chrome 实例,然后重试(该配置文件与您的个人配置文件是分开的)。不要同时运行两个 CLI 调用——每个配置文件一个进程。

fetch 打开一个带有滑块 / “确认您是真人”的窗口

这是人工验证步骤按预期工作:在窗口中通过挑战,然后它会重试并保留会话。--no-verify 跳过窗口并仅报告 blocked。

fetch 返回 blocked(无窗口)

网站阻止无头浏览器,且 autoVerify 已关闭(或没有显示器)。尝试同一主题的其他来源,或启用验证运行。

fetch 返回空文本

页面 JS 繁重且尚未完成渲染;重试(它最多稳定约 7 秒),或增加 --timeout。

还原 / 清理

  • 配置:从您的 DSH 配置文件配置中删除 mcp-google 条目。

  • 技能:rm -rf ~/.dsh/skills/google-chrome-search

  • 配置文件/截图:rm -rf ~/.dsh-chrome-google

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers