browserd

継続的に記録するChromiumとプログラム可能なDevToolsを備え、MCP経由でAIに公開

「LLMに駆動されるPlaywright」ではありません。ブラウザデーモンとして、目にしたすべてを記録するので、エージェントは、聞こうと思った前に発生したトラフィックについて質問できます。

これが実際にやっていること

ほとんどのブラウザMCPサーバーはPlaywrightをラップし、モデルに要素をクリックさせるだけです。しかし、それは開発者がブラウザを開いて行うことのほんの一部にすぎません。

browserd は、エージェントが背後で見守る中、あなた自身が使える本物のヘッド付きChromiumを実行します。永続的なCDP接続を保持し、ネットワーク、コンソール、例外、ナビゲーションを継続的に記録してSQLiteに保存します。モデルが最終的に質問すると、ブラウザではなくデータベースをクエリします。

   AI ──MCP──> browserd ──CDP──> Chromium (headed, yours to use)
                  │
                  ├── network recorder ──┐
                  ├── console recorder ──┼──> SQLite + content-addressed blobs
                  ├── page recorder ─────┤
                  └── target manager ────┘        (bodies, traces, heap snapshots)

この違いは重要です。通常のブラウザ自動化MCPに「なぜチェックアウトは失敗したのか？」と尋ねても、何も返ってきません。リクエストは消えてしまっているからです。browserd に尋ねれば、ペイロード、レスポンスボディ、コンソールエラー、スタックトレース、そして正確なソース行が得られます。

エージェントができること

人々が予想しない部分

タイムトラベル。 time.run("30m") は時計を進め、期限が来たすべてのタイマーを発火させます — 60秒間隔は即座に30回発火します。time.jump("30m") は各タイマーを1回だけ発火させて前方に跳びます。「ノートPCを3時間閉じていた」ケースです。異なるバグのクラスには、異なるツールがあります。

time.install({ time: "2030-01-01T00:00:00Z" })   # page now believes it is 2030
time.run({ duration: "30m" })                     # 30 interval ticks, no waiting
time.freeze()                                     # pin it and inspect

フォールトインジェクション。 「保存に20秒かかったらUIはどうなる？」と尋ねて、実際に確かめます。

fault.delay({ url: "**/api/save", delay: "20s" })
fault.replace_response({ url: "**/api/user", status: 500, body: {...} })
fault.drop_next({ url: "**/api/payment", count: 1 })

リークハンティング。 2つのヒープスナップショットと差分を、切り離されたDOMノードを指摘してコンストラクターごとに報告します — 古典的なリークのシグネチャです。

ヒューマン ↔ AI ハンドオフ。 inspector.pick は実際のDevTools要素ピッカーを起動し、あなたが壊れたものをクリックします。エージェントはノードハンドルを読み返します。page.highlight はその逆方向です。

インストール

Node ≥ 20.11 が必要です。Chromiumは、Playwrightのバンドルビルドが存在する場合はそこから解決されます（ブランド版Chrome 137+は--load-extensionを廃止しましたが、バンドルビルドにはまだあります）。それ以外の場合はシステムインストールから解決されます。

git clone <your-remote> browserd && cd browserd
npm install
npm run build

MCPクライアントに登録する

node scripts/install-mcp.mjs

これはClaude Desktop、Claude Code、Codex CLI、Cursor、Windsurf、VS Codeを検出し、既存の設定にマージします（まず.bakを書き込みます）。他のサーバーを上書きすることはありません。

node scripts/install-mcp.mjs --print            # show the JSON, change nothing
node scripts/install-mcp.mjs --client codex     # just one client
node scripts/install-mcp.mjs --headless         # auto-launch headless
node scripts/install-mcp.mjs --http --port 7331 # register the HTTP endpoint instead

対応クライアント: Claude Desktop、Claude Code、Codex CLI、Cursor、Windsurf、VS Code。CodexはJSONではなく[mcp_servers.browserd] TOMLセクションを使用します。インストーラーはそのファイルを外科的に編集するため、コメントや他の設定は残ります。

次に、すべてのクライアントが実際に起動できることを確認します:

npm run verify-mcp

  OK    Claude Code      174 tools advertised
  OK    Codex CLI        174 tools advertised
  OK    VS Code          174 tools advertised

これは実際の設定ファイルを読み取り、指定された内容でMCPハンドシェイクを完了します。そのため、古いパスや手動編集されたエントリは、動作を仮定するのではなく検出されます。

または手動で追加します:

{
  "mcpServers": {
    "browserd": {
      "command": "node",
      "args": ["/absolute/path/to/browserd/dist/cli.js"]
    }
  }
}

クライアントを再起動します。ブラウザを開いておく必要はありません — ブラウザを必要とする最初のツール呼び出しが起動します。

試す

エージェントに尋ねてみてください:

news.ycombinator.comを開いて、スクリーンショットを見せて、500ms以上かかったすべてのリクエストと、 最も遅かったものが何を返したか教えてください。

または、完全なデモはこちら:

localhost:3000の自分のアプリに行って、Checkoutをクリックして、なぜ失敗するか教えてください。

失敗のスクリーンショットを撮り、コンソールエラーを読み取り、失敗したリクエストを見つけ、ペイロードと400レスポンスボディを表示し、読み込まれたソースから呼び出し関数をgrepして、ファイルと行を提示します。

デーモンを直接実行する

node dist/cli.js                 # MCP over stdio (default)
node dist/cli.js --http          # Streamable HTTP on 127.0.0.1:7331/mcp
node dist/cli.js --tools         # print the tool surface and exit
node dist/cli.js --help

環境変数: AGENTBROWSER_HOME, AGENTBROWSER_PORT, AGENTBROWSER_LOG_LEVEL, AGENTBROWSER_HEADLESS.

HTTPモードはループバックのみにバインドし、Originを検証します。このエンドポイントは完全なブラウザ制御であり、オープンウェブ上のページが到達できないようにする必要があります。

2つの設計ルール

1. まず記録し、後でクエリする

Chromiumがイベントをプッシュし、デーモンがそれを永続化します。事前に準備する必要はなく、モデルが考えている間もイベントを見逃しません。履歴はナビゲーション、タブを閉じる、デーモンの再起動を超えて存続します。

これは重要な設計です。コレクターはドメインを有効にする前にCDPイベントにサブスクライブし、ターゲットマネージャーはインストルメンテーションが有効になるまでwaitForDebuggerOnStartで新しいターゲットを保持します。これにより、「リクエストを見逃さなかった」ということが可能性ではなく事実になります。

2. 大きなペイロードはコンテキストに入らない

200MBのレスポンスは、コンテンツアドレス可能なblobとして保存され、アーティファクトハンドルとして返されます。エージェントはartifact.search、artifact.read_lines、またはartifact.json_query（JSONPathのサブセット）でそれを読み取ります。トレース、ヒープスナップショット、DOMダンプ、コンソールエクスポートも同様です。

ツールは設計上、クエリファーストです。dom.get_htmlの前にdom.summary、network.list_requestsの前にnetwork.summarize、js.get_sourceの前にjs.search_sourceを使用します。

1つのブラウザ上の人間とAI

ブラウザはヘッド付きで、あなたのものです。browser.set_control_modeが調停します:

すべての変更系ツールはこれをチェックします — 生のcdp.sendエスケープハッチも含みます。

ツールサーフェス

174のツール。node dist/cli.js --toolsで全リストが表示されます。

browser.*      list, launch, connect, status, list_targets, set_control_mode, close
page.*         navigate, screenshot, snapshot, click, type, press, scroll, extract_text,
               wait_for, highlight, dialogs, viewport, frames, tabs
dom.*          summary, query, inspect, get_html, set_html, set_attribute, remove, export
css.*          computed, matched_rules, set_style, stylesheets, explain_visibility
js.*           evaluate, list_scripts, get_source, search_source
console.*      query, exceptions, export, clear
network.*      list_requests, get_request, get_body, summarize, search_bodies,
               list_websockets, ws_messages, export_har, simulate, clear
storage.*      local/session, cookies, indexeddb, caches, usage, export
debugger.*     enable, breakpoints, pause, resume, step, call_frames,
               evaluate_on_frame, inspect_object, wait_for_pause
inspector.*    pick, picked, element, parents, children, snapshot, accessibility_tree
profile.*      start/stop/status (presets: cpu, slow-page, hang, memory-leak, full)
profiler.*     cpu, coverage, trace, long_tasks
memory.*       heap.snapshot, heap.compare, gc, usage
time.*         install, freeze, run, jump, resume, set_fixed_date, set_wall_clock, virtual
device.*       preset, viewport, orientation, reset
environment.*  timezone, locale, color_scheme, reduced_motion, vision, status, reset
fault.*        abort, delay, replace_response, drop_next, modify_headers, list, clear
artifact.*     list, stat, read, read_lines, search, json_query, export
cdp.send       escape hatch to any raw CDP method

テスト

npm test                      # build + live MCP suite + HTTP suite
npm run test:live             # 117 checks: real MCP client, real Chromium, local fixture
npm run test:live:headed      # same, with a visible window
npm run test:deep             # 35 checks against a real public site
npm run test:http             # Streamable HTTP transport + origin guard
npm run test:real             # headed narrated walkthrough on live sites

すべてのスイートは実際のサーバーを起動し、実際のMCPクライアントに接続します。アサーションはtools/callを通るため、スキーマ検証、ハンドラーの配線、操作が一緒にカバーされます。

それらは呼び出しが返ったことではなく、動作をアサートします:

• 400のリクエストペイロードとレスポンスボディが両方とも読み取れること

• 700KBのレスポンスが、インラインで約500文字のアーティファクトとして返ってくること

• time.run("30m")が60秒間隔をちょうど30回発火させること。time.jumpは1回だけ発火させること

• 一時停止中のコールフレームからローカル変数が読み取れること（total=75、tax=15）

• observeモードが読み取りを許可しつつ、3/3の変更を拒否すること

• エクスポートされたHARが有効なHAR 1.2としてパースし直せること

• ヒープスナップショットが実際の.heapsnapshotとして読み込めること

tests/deep-dive.mjsは、実際のHacker Newsに対して実行されます。h2/nginx/リモートIPの詳細を含む14件の実際のリクエストを記録し、34KBのレスポンスボディをワイヤーから読み取り、1285ノードのDOMSnapshot、1603ノードのアクセシビリティツリー、8MBのヒープ差分を検出します。

レイアウト

src/
  cdp/        persistent WebSocket, flat-session multiplexing
  browser/    launcher, target manager (auto-attach + debugger hold), registry, faults
  collect/    network, console, page and execution-context recorders
  store/      SQLite schema, blob store, artifact store
  ops/        the actual capabilities, independent of MCP
  mcp/        tool definitions and server wiring
  cli.ts      stdio / HTTP entry point
tests/        live MCP suites
scripts/      install-mcp.mjs

MCPはデーモンへの1つのインターフェースであり、デーモン自体ではありません。src/index.tsはコアをエクスポートするため、CLI、RESTレイヤー、テストハーネスが直接駆動できます。

データは~/.agent-browserにあります（移動するにはAGENTBROWSER_HOME）: browserd.db、blobs/、artifacts/、profiles/、logs/。

セキュリティに関する注意

• ループバックのみにバインドします。このエンドポイントは、ログイン中のセッションを保持するブラウザの完全な制御です。

• ~/.agent-browser/profilesのブラウザプロファイルには、クッキーとセッショントークンが含まれます。記録されたボディには、訪問したページが返したものが含まれます。その両方がgitignoreされています。その状態を維持してください。

• --net-log-capture-mode=Everythingは、ワイヤー上の生のバイトを含む可能性があります。自分が所有するトラフィックにのみ使用してください。

• cdp.sendは無制限のCDPであり、制御モードによってのみ制限されます。

既知の制限

• Debugger.setScriptSource ライブ編集は現在のChromiumには存在しません — ソースを編集してリロードしてください。

• Network.getRequestPostData はマルチパートアップロードからファイルを省略することがあるため、「すべてのアップロードの全バイト」はそのパスだけでは保証されません。スタックレベルの詳細（DNS、ソケット、TLS）を得るには、capture_netlog を指定して起動してください。

• 制御されたクロックは、addScriptToEvaluateOnNewDocument を介してインストールされるフェイクタイマーシムであり、デーモンが生のCDPを話すため、PlaywrightのClock APIではありません。time.virtual はChromium自身の仮想時間ポリシーを公開します。この2つを同じターゲットで組み合わせることはできず、デーモンはそれらを重ねることを拒否します。

• タッチエミュレーションは意図的に Emulation.setEmitTouchEventsForMouse を設定しない: そのフラグはChromiumが Input.dispatchMouseEvent を恒久的に認識しなくさせるからです。代わりに page.click がタップを合成します。

• ontouchstart in window はドキュメント作成時に決定されるため、リロード後に現れます。navigator.maxTouchPoints は即座にライブです。

• Target.openDevTools (devtools.open) は実験的であり、一部のビルドはそれを拒否します。

• センサーエミュレーションは実装されていません。生のプロセスメモリの読み書きは対象外です — それには別のデバッガアダプタが必要です。

ライセンス

MIT