@agentruntime-labs/browser-agent 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +214 -2
  2. package/bin/browser-agent.js +2 -0
  3. package/cli/hosts.mjs +53 -0
  4. package/cli/main.mjs +156 -0
  5. package/cli/mcp.mjs +42 -0
  6. package/extension/approval.html +56 -0
  7. package/extension/approval.js +54 -0
  8. package/extension/background.js +711 -0
  9. package/extension/constants.js +4 -0
  10. package/extension/content.js +1160 -0
  11. package/extension/manifest.json +23 -0
  12. package/extension/popup.html +56 -0
  13. package/extension/popup.js +166 -0
  14. package/package.json +42 -4
  15. package/server/dist/arBrowserPaths.d.ts +11 -0
  16. package/server/dist/arBrowserPaths.d.ts.map +1 -0
  17. package/server/dist/arBrowserPaths.js +93 -0
  18. package/server/dist/arBrowserPaths.js.map +1 -0
  19. package/server/dist/automationSession.d.ts +49 -0
  20. package/server/dist/automationSession.d.ts.map +1 -0
  21. package/server/dist/automationSession.js +225 -0
  22. package/server/dist/automationSession.js.map +1 -0
  23. package/server/dist/bridge.d.ts +43 -0
  24. package/server/dist/bridge.d.ts.map +1 -0
  25. package/server/dist/bridge.js +307 -0
  26. package/server/dist/bridge.js.map +1 -0
  27. package/server/dist/browserToolsExtras.d.ts +5 -0
  28. package/server/dist/browserToolsExtras.d.ts.map +1 -0
  29. package/server/dist/browserToolsExtras.js +304 -0
  30. package/server/dist/browserToolsExtras.js.map +1 -0
  31. package/server/dist/compositeTools.d.ts +12 -0
  32. package/server/dist/compositeTools.d.ts.map +1 -0
  33. package/server/dist/compositeTools.js +43 -0
  34. package/server/dist/compositeTools.js.map +1 -0
  35. package/server/dist/debugSnapshot.d.ts +13 -0
  36. package/server/dist/debugSnapshot.d.ts.map +1 -0
  37. package/server/dist/debugSnapshot.js +54 -0
  38. package/server/dist/debugSnapshot.js.map +1 -0
  39. package/server/dist/guardrails.d.ts +8 -0
  40. package/server/dist/guardrails.d.ts.map +1 -0
  41. package/server/dist/guardrails.js +24 -0
  42. package/server/dist/guardrails.js.map +1 -0
  43. package/server/dist/humanLike.d.ts +24 -0
  44. package/server/dist/humanLike.d.ts.map +1 -0
  45. package/server/dist/humanLike.js +97 -0
  46. package/server/dist/humanLike.js.map +1 -0
  47. package/server/dist/main.d.ts +2 -0
  48. package/server/dist/main.d.ts.map +1 -0
  49. package/server/dist/main.js +79 -0
  50. package/server/dist/main.js.map +1 -0
  51. package/server/dist/policyTiers.d.ts +3 -0
  52. package/server/dist/policyTiers.d.ts.map +1 -0
  53. package/server/dist/policyTiers.js +9 -0
  54. package/server/dist/policyTiers.js.map +1 -0
  55. package/server/dist/protocol.d.ts +62 -0
  56. package/server/dist/protocol.d.ts.map +1 -0
  57. package/server/dist/protocol.js +55 -0
  58. package/server/dist/protocol.js.map +1 -0
  59. package/server/dist/richEditorFill.d.ts +7 -0
  60. package/server/dist/richEditorFill.d.ts.map +1 -0
  61. package/server/dist/richEditorFill.js +27 -0
  62. package/server/dist/richEditorFill.js.map +1 -0
  63. package/server/dist/screenshotCrop.d.ts +11 -0
  64. package/server/dist/screenshotCrop.d.ts.map +1 -0
  65. package/server/dist/screenshotCrop.js +17 -0
  66. package/server/dist/screenshotCrop.js.map +1 -0
  67. package/server/dist/sessionLog.d.ts +42 -0
  68. package/server/dist/sessionLog.d.ts.map +1 -0
  69. package/server/dist/sessionLog.js +112 -0
  70. package/server/dist/sessionLog.js.map +1 -0
  71. package/server/dist/sessionPhase.d.ts +5 -0
  72. package/server/dist/sessionPhase.d.ts.map +1 -0
  73. package/server/dist/sessionPhase.js +24 -0
  74. package/server/dist/sessionPhase.js.map +1 -0
  75. package/server/dist/sessionSummary.d.ts +16 -0
  76. package/server/dist/sessionSummary.d.ts.map +1 -0
  77. package/server/dist/sessionSummary.js +70 -0
  78. package/server/dist/sessionSummary.js.map +1 -0
  79. package/server/dist/skillsInstructions.d.ts +5 -0
  80. package/server/dist/skillsInstructions.d.ts.map +1 -0
  81. package/server/dist/skillsInstructions.js +45 -0
  82. package/server/dist/skillsInstructions.js.map +1 -0
  83. package/server/dist/structureFilter.d.ts +21 -0
  84. package/server/dist/structureFilter.d.ts.map +1 -0
  85. package/server/dist/structureFilter.js +22 -0
  86. package/server/dist/structureFilter.js.map +1 -0
  87. package/server/dist/surveyCatalog.d.ts +10 -0
  88. package/server/dist/surveyCatalog.d.ts.map +1 -0
  89. package/server/dist/surveyCatalog.js +59 -0
  90. package/server/dist/surveyCatalog.js.map +1 -0
  91. package/server/dist/surveyRunner.d.ts +28 -0
  92. package/server/dist/surveyRunner.d.ts.map +1 -0
  93. package/server/dist/surveyRunner.js +109 -0
  94. package/server/dist/surveyRunner.js.map +1 -0
  95. package/server/dist/toolHelpers.d.ts +44 -0
  96. package/server/dist/toolHelpers.d.ts.map +1 -0
  97. package/server/dist/toolHelpers.js +83 -0
  98. package/server/dist/toolHelpers.js.map +1 -0
  99. package/server/dist/toolRuntime.d.ts +41 -0
  100. package/server/dist/toolRuntime.d.ts.map +1 -0
  101. package/server/dist/toolRuntime.js +263 -0
  102. package/server/dist/toolRuntime.js.map +1 -0
  103. package/server/dist/toolSchemas.d.ts +431 -0
  104. package/server/dist/toolSchemas.d.ts.map +1 -0
  105. package/server/dist/toolSchemas.js +408 -0
  106. package/server/dist/toolSchemas.js.map +1 -0
  107. package/server/dist/tools.d.ts +5 -0
  108. package/server/dist/tools.d.ts.map +1 -0
  109. package/server/dist/tools.js +484 -0
  110. package/server/dist/tools.js.map +1 -0
  111. package/server/dist/verdictExtract.d.ts +7 -0
  112. package/server/dist/verdictExtract.d.ts.map +1 -0
  113. package/server/dist/verdictExtract.js +24 -0
  114. package/server/dist/verdictExtract.js.map +1 -0
  115. package/server/dist/workflowTools.d.ts +5 -0
  116. package/server/dist/workflowTools.d.ts.map +1 -0
  117. package/server/dist/workflowTools.js +96 -0
  118. package/server/dist/workflowTools.js.map +1 -0
package/README.md CHANGED
@@ -1,3 +1,215 @@
1
- # Temporary Holding Version
1
+ # browser-agent
2
+
3
+ MCP server + Chrome MV3 extension for automating your **real** active tab. Sibling repo: [desktop-agent](https://github.com/agentruntime-io/desktop-agent) (Windows OS input for hybrid flows).
4
+
5
+ Repo: https://github.com/agentruntime-io/browser-agent — assembled from the legacy monorepo; see `docs/SPLIT_REPOS.md`.
6
+
7
+ ## Install CLI (Cursor / Claude — no manual JSON)
8
+
9
+ From a clone (after building the server):
10
+
11
+ ```bash
12
+ cd server && npm install && npm run build && cd ..
13
+ npm link # optional
14
+ browser-agent install
15
+ ```
16
+
17
+ Published (no git clone):
18
+
19
+ ```bash
20
+ npx @agentruntime-labs/browser-agent install
21
+ ```
22
+
23
+ Commands: `install`, `uninstall`, `doctor`, `paths`. Flags: `--no-claude`, `--claude-port 18792`, etc. (`browser-agent --help`).
24
+
25
+ Pair the **Chrome extension** (Web Store or Load unpacked from `extension/`).
26
+
27
+ ---
28
+ # Browser automation (MCP + real Chrome)
2
29
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
30
+ Local-first connector: **stdio MCP server** ↔ **WebSocket (localhost)** ↔ **Chrome MV3 extension** ↔ your active tab.
31
+
32
+ **One Node server per bridge:** Each MCP host that spawns this server gets its own WebSocket port (`BRIDGE_PORT` on stderr). The extension must connect to **that same** port. Running `npm start` **and** Cursor MCP (or two CLIs) binds two bridges — “Connected” on the wrong port means tools hit an empty server. See **OpenAI test client** / troubleshooting below.
33
+
34
+ Full design: [`docs/README.md`](docs/README.md).
35
+
36
+ ## Quick start
37
+
38
+ Optional server environment variables (stdio MCP host):
39
+
40
+ | Variable | Effect |
41
+ |----------|--------|
42
+ | `BROWSER_AUTOMATION_HOME` | Override user data root (default: `~/.ar_browser`). |
43
+ | `BROWSER_AUTOMATION_SESSION_LOG` | Session JSONL: **on by default** → `~/.ar_browser/logs/ba-session-*.jsonl`. Set `0` to disable. |
44
+ | `BROWSER_AUTOMATION_ENFORCE_NAV_DISCIPLINE` | Navigate guard (default **on**): one navigate until evidence (`get_page_text`, `debug_snapshot`, …). Set `0` to disable. |
45
+ | `BROWSER_AUTOMATION_WS_PORT` | Default WebSocket listen port (also first positional CLI arg). |
46
+ | `BROWSER_AUTOMATION_CONFIRM_CROSS_ORIGIN=1` | Prompt in-browser before `browser_navigate` to a different host than the current tab. |
47
+ | `BROWSER_AUTOMATION_CONFIRM_TAB_CLOSE=1` | Prompt before `browser_tab_close`. |
48
+ | `BROWSER_AUTOMATION_ALLOW_EVAL=1` | Allow `browser_evaluate` (MAIN-world `eval` in the page). |
49
+ | `BROWSER_AUTOMATION_HUMAN_LIKE=1` | Tier-1 human-like mode: random pacing between act tools, hover-before-click, char-by-char fill, CAPTCHA/bot-wall detection on page text. Optional: `BROWSER_AUTOMATION_HUMAN_LIKE_MIN_MS` (400), `BROWSER_AUTOMATION_HUMAN_LIKE_MAX_MS` (1200). |
50
+
51
+ ### Desktop automation MCP (sibling repo)
52
+
53
+ Windows OS input lives in **[desktop-agent](https://github.com/agentruntime-io/desktop-agent)**. Install both MCP servers for hybrid flows; see `docs/HYBRID.md` and `docs/DESKTOP_MCP.md`.
54
+ ### ~/.ar_browser (shared user data)
55
+
56
+ On first server start, the MCP server bootstraps:
57
+
58
+ | Path | Purpose |
59
+ |------|---------|
60
+ | `~/.ar_browser/logs/` | Session JSONL + `screenshots/` (default on; `BROWSER_AUTOMATION_SESSION_LOG=0` to disable) |
61
+ | `~/.ar_browser/sessions/` | Persisted `automationSessionId` state for resume |
62
+ | `~/.ar_browser/skills/` | Workflow skills (copied from `openai-test-client/skills/` when missing) |
63
+ | `~/.ar_browser/catalog/bot-detectors.json` | Direct bot-detector URLs for surveys |
64
+
65
+ Override root with `BROWSER_AUTOMATION_HOME`. Tool results may include `[server-hint]` (navigate discipline, empty structure, etc.).
66
+
67
+ **openai-test-client** (optional): set `BROWSER_AUTOMATION_CLIENT_SESSION_LOG=1` for a duplicate client log under `./logs/`. Skills load from `~/.ar_browser/skills/` first, then the package copy.
68
+
69
+ ### 1. Server (MCP + bridge)
70
+
71
+ ```bash
72
+ cd server
73
+ npm install
74
+ npm run build
75
+ npm start
76
+ ```
77
+
78
+ - Binds **WebSocket** to `127.0.0.1` (default port **18791**, override with `BROWSER_AUTOMATION_WS_PORT` or `npm start -- 19000`).
79
+ - Prints `SESSION=<token>` to **stderr** — paste into the extension.
80
+ - **stdio** is reserved for MCP; keep logs on stderr.
81
+
82
+ **Dev-only** (no token):
83
+
84
+ ```bash
85
+ npm run start:insecure
86
+ ```
87
+
88
+ ### 2. Extension
89
+
90
+ 1. Open `chrome://extensions` → **Developer mode** → **Load unpacked** → select the `extension/` folder. After you change extension files or `git pull`, use **Reload** on the card (MV3 service workers cache code easily).
91
+ 2. Click the extension icon → enter **port** and **SESSION token** → **Connect to server**. After a successful connect, the server may confirm the port in the session payload — use **Copy pairing info** to copy port + token for your CLI or notes, or **Copy Cursor MCP config snippet** for a merge-ready `mcpServers` block (replace the path placeholder).
92
+ 3. Focus the tab you want to automate (any **`http(s)://`** page). By default the agent drives the **active tab** in your focused Chrome window — no setup click required. Optionally **Pin this tab** in the popup to keep automating one tab while you work elsewhere.
93
+
94
+ **Limits:** `chrome://`, `edge://`, and similar **browser UI** pages are not normal websites — content scripts often do not run there, so structure/search/fill may fail. Point the target tab at **`http(s)://...`** before relying on tools.
95
+
96
+ ### 3. Cursor / MCP client
97
+
98
+ **Cursor:** MCP tool names in this server use underscores (`browser_get_page_text`, …). Dotted names like `browser.get_page_text` are rejected by some hosts.
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "browser-automation": {
104
+ "command": "node",
105
+ "args": ["C:/agentruntime/browser_automation/server/dist/main.js"]
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ Use an absolute path on your machine. Restart the MCP client after `npm run build`.
112
+
113
+ Project file: [`.cursor/mcp.json`](.cursor/mcp.json) (uses `${workspaceFolder}`).
114
+
115
+ ### OpenAI test client (optional)
116
+
117
+ Standalone chat loop that **spawns** the MCP server over stdio and calls **OpenAI** tool mode (does not use Cursor).
118
+
119
+ ```bash
120
+ cd openai-test-client
121
+ npm install
122
+ npm run build
123
+ # set OPENAI_API_KEY in your environment, then:
124
+ npm start
125
+ ```
126
+
127
+ One-shot: `npm start -- "Open example.com in the tab"`. Defaults to **`MCP_INSECURE=1`** and **`OPENAI_MODEL=gpt-5.1`** (override with env). WebSocket port defaults to **18791** (same as Cursor MCP); if busy, the server tries **18792, 18793, …** and prints **`BRIDGE_PORT`** on stderr — match that in the extension or click Connect (extension tries the same range).
128
+
129
+ **Skills:** [`openai-test-client/skills/`](openai-test-client/skills/) — `BROWSER_AUTOMATION_CLIENT_SKILLS=browser-automation` (default), `all`, or comma-separated names. Interactive: `/skills` lists; `/skill browser-multi-site-survey` forces a skill. Multi-site / bot-detector user prompts auto-attach the survey skill.
130
+
131
+ **Recommended env for multi-site surveys:**
132
+
133
+ ```powershell
134
+ $env:OPENAI_MODEL = "gpt-5.1"
135
+ $env:BROWSER_AUTOMATION_CLIENT_SKILLS = "all"
136
+ # Server JSONL (default on): ~/.ar_browser/logs/ba-session-*.jsonl
137
+ # Optional duplicate client log:
138
+ # $env:BROWSER_AUTOMATION_CLIENT_SESSION_LOG = "1"
139
+ $env:BROWSER_AUTOMATION_MAX_TOOL_DEPTH = "64" # default; raise if needed
140
+ npm start
141
+ ```
142
+
143
+ Client logs `[openai] model`, `[client] max tool depth`, and navigate discipline status on startup. Server logs to `~/.ar_browser/logs/` by default. JSONL rows include `verdictExcerpt` on read tools when a bot-detector-style line is found.
144
+
145
+ ### Cursor: port already in use (`EADDRINUSE`)
146
+
147
+ If **MCP Logs** show `listen EADDRINUSE ... 127.0.0.1:18791`, something else is already bound to that port (often a leftover `node` process or a second MCP spawn).
148
+
149
+ 1. **Free the port** (PowerShell): `Get-NetTCPConnection -LocalPort 18791 | Select OwningProcess` then stop that PID, or close any extra terminal where you ran `npm start`.
150
+ 2. **Or** rely on auto-fallback: the server tries **18791, 18792, …** and logs **`BRIDGE_PORT=<n>`** on stderr. Set the extension popup to that port (read it from **View → Output → MCP**), or click Connect — the extension tries the same N+1 range.
151
+ 3. **Or** change `BROWSER_AUTOMATION_WS_PORT` in `.cursor/mcp.json` to a free port (e.g. `18792`).
152
+
153
+ ## Tests
154
+
155
+ ### Unit (`vitest`)
156
+
157
+ ```bash
158
+ cd server
159
+ npm test
160
+ ```
161
+
162
+ Covers JSON wire envelopes and WebSocket **session.open** + **request/response** round-trip (mock “extension” WebSocket client).
163
+
164
+ **GitHub Actions** runs `npm test` plus `npm run test:e2e` under `xvfb-run` (headed Chromium + MV3 extension).
165
+
166
+ ### E2E (`playwright`, real unpacked extension)
167
+
168
+ First-time browser download:
169
+
170
+ ```bash
171
+ cd server
172
+ npx playwright install chromium
173
+ ```
174
+
175
+ Run (opens a **headed** Chromium window; required for MV3 extensions):
176
+
177
+ ```bash
178
+ cd server
179
+ npm run test:e2e
180
+ ```
181
+
182
+ The suite covers **wait_for** (delayed DOM text), **screenshot_element** + **Jimp** crop, **set_file_input**, and **get_network_log** (after `fetch`), plus the original text/structure/click flow.
183
+
184
+ The default run finishes in **a few seconds** and closes the browser immediately—easy to miss. To **see** the flow (slowed actions + **15s** pause before close):
185
+
186
+ ```bash
187
+ cd server
188
+ npm run test:e2e:visible
189
+ ```
190
+
191
+ Optional env vars:
192
+
193
+ | Variable | Effect |
194
+ |----------|--------|
195
+ | `PW_SLOW_MO` | Milliseconds between Playwright actions (e.g. `200`). |
196
+ | `PW_E2E_HOLD_MS` | Keep the browser open this many ms after tests (e.g. `30000`). |
197
+ | `PW_CHROME_CHANNEL` | Set to `chrome` to use installed Google Chrome instead of bundled Chromium. |
198
+
199
+ `PW_HEADLESS=1` is **not** supported for this suite—Playwright’s headless Chromium does not load extensions; the spec file skips in that case.
200
+
201
+ The test starts a local HTTP harness, launches Chromium with `--load-extension=…/extension`, connects the bridge (no session token), wires the harness tab via `chrome.tabs` from the extension popup context, then asserts `get_page_text` / `get_page_structure` / `click_element` over the real WebSocket.
202
+
203
+ ## MCP structured outputs
204
+
205
+ Every browser tool registers a Zod **`outputSchema`** and returns validated **`structuredContent`** (plus a JSON `text` content part for logs). Schemas live in `server/src/toolSchemas.ts`. Clients can rely on typed objects instead of parsing `content` strings.
206
+
207
+ ## Sibling repo
208
+
209
+ Pair with **[desktop-agent](https://github.com/agentruntime-io/desktop-agent)** for OS-level input (docs/HYBRID.md, docs/DESKTOP_MCP.md). Shared docs are repeated in both repos � see `docs/REPEATED_DOCS.md`.
210
+
211
+ ## Stack decisions
212
+
213
+ - **Node + `@modelcontextprotocol/sdk` + Zod** — maintained MCP APIs and schema validation.
214
+ - **WebSocket to `127.0.0.1` + session token** — stricter than “localhost only” bridges that omit pairing (see `docs/MESSAGES.md`).
215
+ - **Broad `http(s)://*/*` host permission in the extension** for MVP so a single “target tab” works across sites; tighten later via optional host permissions + docs.
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import '../cli/main.mjs';
package/cli/hosts.mjs ADDED
@@ -0,0 +1,53 @@
1
+ import fs from 'node:fs';
2
+ import os from 'node:os';
3
+ import path from 'node:path';
4
+
5
+ export function cursorConfigPath() {
6
+ return path.join(os.homedir(), '.cursor', 'mcp.json');
7
+ }
8
+
9
+ export function claudeConfigPaths() {
10
+ const out = [];
11
+ const roaming = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
12
+ const classic = path.join(roaming, 'Claude', 'claude_desktop_config.json');
13
+ if (fs.existsSync(path.dirname(classic))) out.push(classic);
14
+
15
+ const packages = path.join(process.env.LOCALAPPDATA || '', 'Packages');
16
+ if (fs.existsSync(packages)) {
17
+ for (const name of fs.readdirSync(packages)) {
18
+ if (!name.startsWith('Claude_')) continue;
19
+ const p = path.join(
20
+ packages,
21
+ name,
22
+ 'LocalCache',
23
+ 'Roaming',
24
+ 'Claude',
25
+ 'claude_desktop_config.json'
26
+ );
27
+ if (fs.existsSync(path.dirname(p))) out.push(p);
28
+ }
29
+ }
30
+ return [...new Set(out)];
31
+ }
32
+
33
+ export function resolveTargets({ cursor, claude, claudePort, cursorPort }) {
34
+ const targets = [];
35
+ if (cursor) {
36
+ targets.push({ label: 'Cursor', path: cursorConfigPath(), port: cursorPort });
37
+ }
38
+ if (claude) {
39
+ const claudePaths = claudeConfigPaths();
40
+ for (const p of claudePaths) {
41
+ targets.push({ label: 'Claude', path: p, port: claudePort });
42
+ }
43
+ if (claudePaths.length === 0) {
44
+ const roaming = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
45
+ targets.push({
46
+ label: 'Claude',
47
+ path: path.join(roaming, 'Claude', 'claude_desktop_config.json'),
48
+ port: claudePort,
49
+ });
50
+ }
51
+ }
52
+ return targets;
53
+ }
package/cli/main.mjs ADDED
@@ -0,0 +1,156 @@
1
+ #!/usr/bin/env node
2
+ import path from 'node:path';
3
+ import fs from 'node:fs';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { applyBrowserServer, readMcpFile, writeMcpFile, MCP_SERVER_KEY } from './mcp.mjs';
6
+ import { resolveTargets } from './hosts.mjs';
7
+
8
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
9
+ const REPO_ROOT = path.resolve(__dirname, '..');
10
+ const SERVER_MAIN = path.join(REPO_ROOT, 'server', 'dist', 'main.js');
11
+ const EXTENSION_DIR = path.join(REPO_ROOT, 'extension');
12
+
13
+ function usage() {
14
+ console.log(`browser-agent — install the browser MCP server for Cursor / Claude
15
+
16
+ Usage:
17
+ browser-agent install [options]
18
+ browser-agent uninstall [options]
19
+ browser-agent doctor
20
+ browser-agent paths
21
+
22
+ Install options:
23
+ --cursor Wire Cursor (~/.cursor/mcp.json) (default: on)
24
+ --no-cursor
25
+ --claude Wire Claude Desktop (default: on)
26
+ --no-claude
27
+ --port <n> WebSocket port when only one host (default: 18791)
28
+ --cursor-port <n> Port for Cursor (default: 18791)
29
+ --claude-port <n> Port for Claude (default: 18792)
30
+
31
+ Examples:
32
+ npx @agentruntime-labs/browser-agent install
33
+ browser-agent install --no-claude --port 18791
34
+ browser-agent uninstall --claude
35
+ `);
36
+ }
37
+
38
+ function parseFlags(argv) {
39
+ const flags = {
40
+ cursor: true,
41
+ claude: true,
42
+ cursorPort: 18791,
43
+ claudePort: 18792,
44
+ };
45
+ for (let i = 0; i < argv.length; i++) {
46
+ const a = argv[i];
47
+ if (a === '--cursor') flags.cursor = true;
48
+ else if (a === '--no-cursor') flags.cursor = false;
49
+ else if (a === '--claude') flags.claude = true;
50
+ else if (a === '--no-claude') flags.claude = false;
51
+ else if (a === '--port') flags.cursorPort = flags.claudePort = Number(argv[++i]);
52
+ else if (a === '--cursor-port') flags.cursorPort = Number(argv[++i]);
53
+ else if (a === '--claude-port') flags.claudePort = Number(argv[++i]);
54
+ else if (a === '--help' || a === '-h') return { help: true };
55
+ }
56
+ return flags;
57
+ }
58
+
59
+ function nodeForMcp() {
60
+ return process.execPath;
61
+ }
62
+
63
+ function cmdInstall(flags) {
64
+ if (!fs.existsSync(SERVER_MAIN)) {
65
+ console.error(`MCP server not built.\n Missing: ${SERVER_MAIN}\n Run: cd server && npm install && npm run build`);
66
+ process.exit(1);
67
+ }
68
+ const nodeExe = nodeForMcp();
69
+ const targets = resolveTargets({
70
+ cursor: flags.cursor,
71
+ claude: flags.claude,
72
+ cursorPort: flags.cursorPort,
73
+ claudePort: flags.claudePort,
74
+ });
75
+ if (targets.length === 0) {
76
+ console.error('Pick at least one host: --cursor and/or --claude');
77
+ process.exit(1);
78
+ }
79
+ for (const t of targets) {
80
+ const doc = readMcpFile(t.path);
81
+ applyBrowserServer(doc, {
82
+ nodeExe,
83
+ mainJs: SERVER_MAIN,
84
+ port: t.port,
85
+ remove: false,
86
+ });
87
+ writeMcpFile(t.path, doc);
88
+ console.log(`Updated ${t.label}: ${t.path} (port ${t.port})`);
89
+ }
90
+ console.log(`
91
+ Next:
92
+ 1. Chrome extension: ${EXTENSION_DIR}
93
+ (Chrome Web Store when published — until then: Load unpacked)
94
+ 2. Extension popup → port ${flags.cursor ? flags.cursorPort : flags.claudePort} → Connect (token blank)
95
+ 3. Restart Cursor / Claude Desktop
96
+ `);
97
+ }
98
+
99
+ function cmdUninstall(flags) {
100
+ const targets = resolveTargets({
101
+ cursor: flags.cursor,
102
+ claude: flags.claude,
103
+ cursorPort: 18791,
104
+ claudePort: 18792,
105
+ });
106
+ for (const t of targets) {
107
+ const doc = readMcpFile(t.path);
108
+ applyBrowserServer(doc, { remove: true });
109
+ writeMcpFile(t.path, doc);
110
+ console.log(`Removed ${MCP_SERVER_KEY} from ${t.label}: ${t.path}`);
111
+ }
112
+ }
113
+
114
+ function cmdDoctor() {
115
+ const ok = fs.existsSync(SERVER_MAIN);
116
+ console.log(`Repo root: ${REPO_ROOT}`);
117
+ console.log(`MCP server: ${SERVER_MAIN} ${ok ? 'OK' : 'MISSING (run npm run build in server/)'}`);
118
+ console.log(`Extension: ${EXTENSION_DIR} ${fs.existsSync(EXTENSION_DIR) ? 'OK' : 'MISSING'}`);
119
+ console.log(`Node: ${process.version}`);
120
+ process.exit(ok ? 0 : 1);
121
+ }
122
+
123
+ function cmdPaths() {
124
+ console.log(JSON.stringify({ repoRoot: REPO_ROOT, serverMain: SERVER_MAIN, extensionDir: EXTENSION_DIR }, null, 2));
125
+ }
126
+
127
+ const [cmd, ...rest] = process.argv.slice(2);
128
+ if (!cmd || cmd === '--help' || cmd === '-h') {
129
+ usage();
130
+ process.exit(cmd ? 0 : 1);
131
+ }
132
+
133
+ const flags = parseFlags(rest);
134
+ if (flags.help) {
135
+ usage();
136
+ process.exit(0);
137
+ }
138
+
139
+ switch (cmd) {
140
+ case 'install':
141
+ cmdInstall(flags);
142
+ break;
143
+ case 'uninstall':
144
+ cmdUninstall(flags);
145
+ break;
146
+ case 'doctor':
147
+ cmdDoctor();
148
+ break;
149
+ case 'paths':
150
+ cmdPaths();
151
+ break;
152
+ default:
153
+ console.error(`Unknown command: ${cmd}`);
154
+ usage();
155
+ process.exit(1);
156
+ }
package/cli/mcp.mjs ADDED
@@ -0,0 +1,42 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ export function readMcpFile(filePath) {
5
+ if (!fs.existsSync(filePath)) return { mcpServers: {} };
6
+ const raw = fs.readFileSync(filePath, 'utf8');
7
+ if (!raw.trim()) return { mcpServers: {} };
8
+ const doc = JSON.parse(raw);
9
+ return doc?.mcpServers ? { mcpServers: { ...doc.mcpServers } } : { mcpServers: {} };
10
+ }
11
+
12
+ export function writeMcpFile(filePath, doc) {
13
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
14
+ if (fs.existsSync(filePath)) {
15
+ const stamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
16
+ fs.copyFileSync(filePath, `${filePath}.bak-${stamp}`);
17
+ }
18
+ fs.writeFileSync(filePath, `${JSON.stringify({ mcpServers: doc.mcpServers }, null, 2)}\n`, 'utf8');
19
+ }
20
+
21
+ function winPath(p) {
22
+ return path.normalize(p);
23
+ }
24
+
25
+ export const MCP_SERVER_KEY = 'browser-automation';
26
+
27
+ export function serverEntry(nodeExe, mainJs, port) {
28
+ return {
29
+ command: nodeExe,
30
+ args: [winPath(mainJs), '--insecure-no-token'],
31
+ env: { BROWSER_AUTOMATION_WS_PORT: String(port) },
32
+ };
33
+ }
34
+
35
+ export function applyBrowserServer(doc, { nodeExe, mainJs, port, remove }) {
36
+ if (remove) {
37
+ delete doc.mcpServers[MCP_SERVER_KEY];
38
+ } else {
39
+ doc.mcpServers[MCP_SERVER_KEY] = serverEntry(nodeExe, mainJs, port);
40
+ }
41
+ return doc;
42
+ }
@@ -0,0 +1,56 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <title>Confirm action</title>
6
+ <style>
7
+ body {
8
+ font-family: system-ui, sans-serif;
9
+ margin: 16px;
10
+ max-width: 480px;
11
+ }
12
+ h1 {
13
+ font-size: 1.1rem;
14
+ margin-top: 0;
15
+ }
16
+ .risk {
17
+ font-weight: 600;
18
+ }
19
+ pre {
20
+ white-space: pre-wrap;
21
+ background: #f4f4f4;
22
+ padding: 8px;
23
+ border-radius: 6px;
24
+ font-size: 13px;
25
+ }
26
+ .actions {
27
+ display: flex;
28
+ gap: 8px;
29
+ margin-top: 16px;
30
+ }
31
+ button {
32
+ flex: 1;
33
+ padding: 10px;
34
+ }
35
+ .deny {
36
+ background: #eee;
37
+ }
38
+ .approve {
39
+ background: #0a6;
40
+ color: white;
41
+ border: none;
42
+ }
43
+ </style>
44
+ </head>
45
+ <body>
46
+ <h1 id="title">Confirmation</h1>
47
+ <p>Risk: <span id="risk" class="risk"></span></p>
48
+ <p id="suggested" style="display: none"></p>
49
+ <pre id="summary"></pre>
50
+ <div class="actions">
51
+ <button type="button" class="deny" id="deny">Deny</button>
52
+ <button type="button" class="approve" id="approve">Approve</button>
53
+ </div>
54
+ <script src="approval.js"></script>
55
+ </body>
56
+ </html>
@@ -0,0 +1,54 @@
1
+ const params = new URLSearchParams(location.search);
2
+ const rid = params.get('rid');
3
+ const titleEl = document.getElementById('title');
4
+ const riskEl = document.getElementById('risk');
5
+ const summaryEl = document.getElementById('summary');
6
+ const suggestedEl = document.getElementById('suggested');
7
+
8
+ async function main() {
9
+ if (!rid) {
10
+ titleEl.textContent = 'Missing request id';
11
+ return;
12
+ }
13
+ const key = `confirm:${rid}`;
14
+ const data = (await chrome.storage.session.get(key))[key];
15
+ if (!data) {
16
+ titleEl.textContent = 'Request expired or unknown';
17
+ return;
18
+ }
19
+ titleEl.textContent = data.title || 'Confirm';
20
+ riskEl.textContent = data.risk || 'unknown';
21
+ summaryEl.textContent = data.summary || '';
22
+ if (data.suggestedAction) {
23
+ suggestedEl.style.display = 'block';
24
+ suggestedEl.textContent = 'Suggested: ' + data.suggestedAction;
25
+ }
26
+ }
27
+
28
+ function finish(decision) {
29
+ if (!rid) {
30
+ return;
31
+ }
32
+ if (decision === 'approved') {
33
+ chrome.runtime.sendMessage({
34
+ type: 'approval-done',
35
+ rid,
36
+ decision: 'approved',
37
+ approvalToken: crypto.randomUUID(),
38
+ approvedAt: new Date().toISOString()
39
+ });
40
+ } else {
41
+ chrome.runtime.sendMessage({
42
+ type: 'approval-done',
43
+ rid,
44
+ decision: 'denied',
45
+ reason: 'user_rejected'
46
+ });
47
+ }
48
+ window.close();
49
+ }
50
+
51
+ document.getElementById('approve').onclick = () => finish('approved');
52
+ document.getElementById('deny').onclick = () => finish('denied');
53
+
54
+ void main();