yuzi-ska/DSH-Chrome-devtools

DSH-Chrome-devtools

Real Chrome browser control for DeepSeek Harness agents, powered by Chrome DevTools MCP

Uncategorizedbrowser-automationchrome-devtoolsdeepseek-harness

dsh-chrome-devtools — Chrome DevTools for DeepSeek Harness

中文 | English

Give DeepSeek Harness agents control over a real Chrome browser via chrome-devtools-mcp: navigation, clicking, typing, screenshots, DOM snapshots, console, network requests, performance traces, and cookies.

The only install path is the official dsh plugin one-command install (GitHub source; no clone required). This repository root is itself an official bundle plugin (package.json declares dsh.bundle, cordis.patch.yml is the patch layer): the MCP server row is built into the plugin, so it is ready to use right after install — no extra components to install, no MCP configuration to write.

Features

One-command install: dsh plugin add github:...; the package is reconciled into the profile's patch-layer stack automatically, zero manual config.
npx, ready to use: the server runs via npx -y chrome-devtools-mcp@latest — the same convention Claude Code / Claude Desktop / Cursor use for chrome-devtools-mcp. First use downloads it automatically (30-60s); afterwards the npx cache starts it in about a second. No global install, no prerequisites.
Global: after a host restart every session (including child agents) sees the mcp__chrome-devtools__* tools.
Real browser: headed or headless Chrome, multiple tabs, cookies, network interception, performance traces.
Auto-reconnect: the dsh-mcp-client supervisor restarts a crashed server with exponential backoff and a failure budget that prevents infinite restarts.
Cross-platform: Windows / macOS / Linux; the bundled installer script is zero-dependency (pure Node standard library).

Requirements

Dependency	Notes
DeepSeek Harness	ships `@deepseek-ai/dsh-mcp-client`, the bridge plugin
Node.js ≥ 20	`npx` on PATH (ships with Node)
pnpm	package manager behind `dsh plugin` (`npm i -g pnpm` or `corepack enable`)
Chrome / Chromium / Edge	installed locally; pick one via `--channel` in the plugin `args`

Install

dsh plugin --profile web add github:yuzi-ska/DSH-Chrome-devtools

(Replace web with your profile name — tui, headless, etc.)

Then restart the host (dsh web / however you launch it). After the restart every session sees tools such as mcp__chrome-devtools__navigate_page, take_snapshot, take_screenshot, list_console_messages, get_network_request, performance_start_trace (exact set per the server's declaration). No further configuration is needed.

First use downloads the server via npx (~30-60s) and launches Chrome; afterwards it stays resident and starts in about a second.

Uninstall:

dsh plugin --profile web remove dsh-chrome-devtools

Repo installer script (development / local setups)

git clone https://github.com/yuzi-ska/DSH-Chrome-devtools.git
cd DSH-Chrome-devtools

node scripts/install.mjs            # installs into the web profile (local link; edits take effect after restart)
node scripts/install.mjs --check    # environment check (read-only)
node scripts/install.mjs --uninstall

node scripts/install.mjs [options]
  --check             environment check: node/pnpm/dsh/browser/DSH_HOME; writes nothing
  --uninstall         uninstall (dsh plugin remove)
  --profile <name>    target profile (default web)
  --dsh-home <path>   override DSH_HOME (default $DSH_HOME or ~/.dsh)
  --harness <path>    harness repo/install path (runs the CLI via node when dsh is not on PATH)
  --plugin-spec <s>   plugin source (default this repo root; npm name, git source, or local path)
  --package-name <n>  package name used by uninstall (default dsh-chrome-devtools)

Architecture

Harness (profile composition)
   │
   │  bundle plugin patch layer (this repo's cordis.patch.yml)
   ▼
@deepseek-ai/dsh-mcp-client row (stdio, shipped with Harness; config built into the plugin)
   │
   ▼
chrome-devtools-mcp server (npx -y chrome-devtools-mcp@latest, spawned by the host; first-run auto download, then cache hit)
   │
   │  Chrome DevTools Protocol
   ▼
One shared Chrome instance (auto-launches the locally installed Chrome/Chromium/Edge)

Every MCP tool is registered on ctx.tools as mcp__chrome-devtools__<tool> and called like a native tool by the model.
One profile mounts one resident server: all sessions share the same browser.
If the server crashes, the dsh-mcp-client supervisor reconnects with exponential backoff; after 10 consecutive failures the tools are unregistered (recover by restarting the host).
Each tool call may run up to 120 seconds (configurable).

Tool capabilities

Per the server's actual declaration (28 tools in the current version):

Family	Tools (mcp__chrome-devtools__ prefix)
Pages	navigate_page / new_page / close_page / select_page / list_pages / resize_page
Snapshots	take_snapshot (DOM/accessibility tree) / take_screenshot
Interaction	click / fill / fill_form / type_text / press_key / hover / drag
Scripting	evaluate_script (run JS in the page, returns JSON)
Emulation	emulate (viewport/network/UA/geolocation/color scheme)
Console	list_console_messages / get_console_message
Network	list_network_requests / get_network_request (with request/response bodies)
Performance	performance_start_trace / performance_stop_trace / performance_analyze_insight
Auditing	lighthouse_audit
Other	handle_dialog / upload_file / wait_for

Configuration reference

The defaults work out of the box; the following are optional (restart the host after editing cordis.patch.yml).

The MCP row (built into the plugin)

- id: mcp-chrome-devtools
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: chrome-devtools     # tool namespace: mcp__chrome-devtools__*
    transport: stdio
    command: npx
    args: ['-y', 'chrome-devtools-mcp@latest']
    toolCallTimeoutMs: 120000
    failOnStartupError: false

Field	Default	Meaning
`serverName`	chrome-devtools	`[A-Za-z0-9_-]{1,32}`, unique across live mcp-client instances
`command` / `args`	npx -y ...	stdio launch command; the same convention as the Claude Code ecosystem; `npx` resolves correctly on Windows via the SDK's cross-spawn
`toolCallTimeoutMs`	120000	per-tool-call timeout; loosen for page loads / traces
`failOnStartupError`	false	true rejects the composition on first-connect failure; false logs and retries with backoff
`env` / `cwd`	empty	extra env vars / working directory (defaults to the host's)
`reconnect.*`	see docs	backoff budget: initialDelayMs 500 / maxDelayMs 30000 / maxAttempts 10

chrome-devtools-mcp server options (put them in `args`)

Option	Effect
`--headless`	headless mode, no visible window
`--channel <name>`	pick the browser: `chrome` (default) / `stable` / `beta` / `dev` / `canary` / `msedge` / executable path
`--browserUrl <url>`	attach to an already-running Chrome (e.g. `http://localhost:9222`)
`--isolated`	a fresh isolated Chrome profile per server process
`--viewport <WxH>`	fixed window/viewport size, e.g. `1280x720`
`--proxy-server <url>`	route the browser through a proxy
`--user-data-dir <path>`	custom Chrome user-data directory
`--keepAlive`	keep the server alive when all MCP connections close (default on)

See the official docs/cli.md for the full list.

Tools register in the host composition: every agent under the profile (including child agents) sees them.
All sessions share one browser and server process, so browser state (tabs, cookies, console buffer) is visible across sessions.
To isolate browser contexts: change serverName and args (e.g. --isolated or a separate --user-data-dir) in another instance.

Security notes

Browser capability is shell-level trust: it can read/write cookies, issue arbitrary requests, and reach internal networks. Use it only with trusted sessions.
Page content (DOM snapshots, console, response bodies) enters the model context and session logs — beware sensitive pages.
In global mode every request carries this tool family's schemas (token cost).
With failOnStartupError: false, a server in a crash loop burns the reconnect budget and the tools are unregistered — deliberate failure visibility, no infinite restarts.

Troubleshooting

Symptom	Fix
First call is slow (30-60s+)	npx first download + Chrome first launch; one-time cost, then cache hit and resident
No browser tools appear	Check host logs for `mcp-client(chrome-devtools)`: reconnecting (warn), recovered (info), disabled-loss (error)
Tools missing after install	Bundle plugins load at startup — restart the host; the profile-layer config hot-reload does not apply new rows
Chrome missing/not found	Add `--channel` to `args` (e.g. `msedge`), or confirm default Chrome exists
npx download fails	Check npm registry connectivity; pin a version in `args: ['-y', 'chrome-devtools-mcp@<version>']` to reduce drift
Attach an already-open Chrome	Start Chrome with `--remote-debugging-port=9222`, add `--browserUrl http://localhost:9222` to `args`
`dsh plugin` reports missing pnpm	Install pnpm (`npm i -g pnpm` or `corepack enable`)
Tool call times out	120s per call; raise `toolCallTimeoutMs` for slow networks or stuck pages
EPERM when switching from a local link to a GitHub source	Windows junctions cannot be renamed over by pnpm: `dsh plugin remove` first, then add the new source
Marketplace install fails with `entry file missing` (dsh-plugin.org)	The marketplace installer requires a resolvable entry in the distributed package; since v0.1.1 the package ships one (`index.js`, packaging-only, carries no capability) — refresh to the latest version and reinstall

Development

git clone https://github.com/yuzi-ska/DSH-Chrome-devtools.git
cd DSH-Chrome-devtools

# local link install (edits to cordis.patch.yml take effect after restart; no push needed)
node scripts/install.mjs --harness <harness-repo-path>

# verify the composed tree without booting (boot-free)
node <harness>/apps/cli/lib/bin.js --profile web --dump-config | grep -A8 mcp-chrome-devtools

After pushing, remote install: dsh plugin --profile web add github:yuzi-ska/DSH-Chrome-devtools.
Internal development notes live in docs/development.md and are excluded from the remote repository (see .gitignore).

References

ChromeDevTools/chrome-devtools-mcp (the server; tool list and CLI options per its README / docs/cli.md)
deepseek-ai/deepseek-harness — packages/mcp/mcp-client (the Harness-side MCP client bridge)
deepseek-ai/deepseek-harness — packages/bundle (bundle plugin mechanism)
deepseek-ai/deepseek-harness — apps/cli/src/plugin.ts (the dsh plugin command)

Navigation

DSH-Chrome-devtools

dsh-chrome-devtools — Chrome DevTools for DeepSeek Harness

Features

Requirements

Install

Repo installer script (development / local setups)

Architecture

Tool capabilities

Configuration reference

The MCP row (built into the plugin)

chrome-devtools-mcp server options (put them in `args`)

Security notes

Troubleshooting

Development

References

dsh-web

answer-me-with-html

dsh-our-free-model

DSH-Chrome-devtools

dsh-chrome-devtools — Chrome DevTools for DeepSeek Harness

Features

Requirements

Install

Repo installer script (development / local setups)

Architecture

Tool capabilities

Configuration reference

The MCP row (built into the plugin)

chrome-devtools-mcp server options (put them in args)

Sharing semantics

Security notes

Troubleshooting

Development

References

Related plugins

dsh-web

answer-me-with-html

dsh-our-free-model

chrome-devtools-mcp server options (put them in `args`)