browser

name

browser

description

Use for Browser MCP / browser CLI tasks: bringing up the local Browser MCP repo, checking extension/native-host health, choosing the right runtime target, browsing or extracting content, driving interactive pages, and debugging frontend/runtime issues. This skill is progressive: it routes to small references for quickstart, raw stdio JSON-RPC, browsing/extraction, interaction/debugging, and long multi-step runs.

Browser

Use this skill when the task is specifically about Browser MCP / the local browser CLI, not generic web research.

Quick routing

1. Need to bring the system up, verify bridge health, or choose the right target? Read references/quickstart-and-targets.md.
2. Need to drive the server directly over stdio JSON-RPC from shell/Python? Read references/cli-stdio.md.
3. Need ordinary browsing or extraction with the smallest surface? Read references/browsing-and-extraction.md.
4. Need interaction, frontend debugging, or recovery? Read references/interaction-and-debugging.md.
5. Need canvas / whiteboard / diagram / Figma-like / tldraw-like work? Read references/canvas-sites.md.
6. Need long or resumable flows? Read references/long-runs.md.

Default operating law

• Prefer the browser command from PATH first. On this machine it resolves through the stable symlink /Users/amir/.local/bin/browser -> /Users/amir/Documents/projects/MCP/browser/tools/browser and targets repo /Users/amir/Documents/projects/MCP/browser.
• If browser is unavailable, fall back to the repo root directly: /Users/amir/Documents/projects/MCP/browser.
• Start with the smallest decisive move:
  • bridge/runtime health -> browser doctor
  • target choice -> browser(action="runtime") and read preferredTarget, surfaceFamily, sessionNeedHint, why, riskIfWrong
  • quick navigation/read -> run(actions=[{navigate:{url:"..."}}], report="observe")
  • current-page facts -> page(info=true) or page()
• Prefer targets in this order:
  1. owned_headless — default for deterministic automation
  2. owned_visible — when the user should watch
  3. user_browser_extension — only when real tabs/cookies/logins are required
  4. external_attach — only when another system already owns browser startup
• High-signal preference, not a ban: when the task mentions an admin panel, hosting dashboard, mail, payments, cloud console, or any surface where the user's existing authenticated state likely matters (for example Timeweb), strongly consider user_browser_extension first.
• Prefer run(...) over chatty loops.
• High-value Browser CLI habit: once the intent is clear, bias toward one meaningful bounded run(...) instead of many micro-turns. This matters especially on interactive and canvas surfaces, where Browser CLI is strongest when it can carry a short action sequence end-to-end.
• Escalate only when needed:
  • page(detail="content") for read-only extraction
  • page(detail="locators") or page(detail="map") for interactive targeting
  • page(detail="state") for bounded runtime/ui/app truth (workspaceTruth, sessionHints, actionReadiness)
  • page(detail="diagnostics") / page(detail="performance") for debugging
• If page(detail="state") or page(detail="map") says the surface is canvas, switch to the canvas reference instead of treating it like an ordinary DOM page.
• page(detail="map") now also carries a compact family plus workflowHints[*].family / recommendedRunShape / splitHint; use that before inventing your own micro-plan.
• Refs from locators / map are snapshot-scoped. After DOM or navigation changes, refresh them before acting again.
• Prefer explicit hygiene over ad-hoc cleanup: browser(action="fresh_context") first, then deeper recovery actions from the interaction/debugging reference.
• tools/list is the contract authority. On the default surface verified on this machine, the advertised tools are page, run, job, and browser.
• Do not assume legacy/full tools (app, runbook, extract_content, etc.) until tools/list proves they are exposed in the current session.
• For shell entrypoints, prefer:
  • browser doctor
  • browser extension-status --deep --json
  • browser flagship-smoke
  • browser flagship-live
  • MCP_QUIET=1 browser run
• If the Browser MCP repo is open, the richer repo docs live at:
  • <repo-root>/README.md
  • <repo-root>/docs/RUN_GUIDE.md
  • <repo-root>/docs/AGENT_PLAYBOOK.md
  • <repo-root>/TROUBLESHOOTING.md

Locally verified CLI paths

Grounded by real stdio CLI runs and repo-owned live rails on 2026-04-07 against /Users/amir/Documents/projects/MCP/browser:

• browser(action="runtime")
• switching to owned_headless, owned_visible, and user_browser_extension
• run(actions=[{navigate:{url:"https://example.com"}}], report="observe")
• page(info=true)
• page(detail="content")
• page(detail="locators")
• page(detail="map")
• page(detail="state")
• page(detail="diagnostics")
• page(detail="performance")
• run(actions=[{act:{ref:"aff:..."}}]) followed by page(detail="delta", since=...)
• browser(action="fresh_context")
• live tldraw canvas flow: act(focus canvas) -> act(Карандаш) -> transform(draw_scene stroke) in one run, with transition.kind=local_mutation

Keep the body thin. Pull only the reference file that matches the active question.