@agentruntime-labs/browser-agent 0.0.0-stage → 0.1.0
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.
- package/README.md +214 -2
- package/bin/browser-agent.js +2 -0
- package/cli/hosts.mjs +53 -0
- package/cli/main.mjs +156 -0
- package/cli/mcp.mjs +42 -0
- package/extension/approval.html +56 -0
- package/extension/approval.js +54 -0
- package/extension/background.js +711 -0
- package/extension/constants.js +4 -0
- package/extension/content.js +1160 -0
- package/extension/manifest.json +23 -0
- package/extension/popup.html +56 -0
- package/extension/popup.js +166 -0
- package/package.json +42 -4
- package/server/dist/arBrowserPaths.d.ts +11 -0
- package/server/dist/arBrowserPaths.d.ts.map +1 -0
- package/server/dist/arBrowserPaths.js +93 -0
- package/server/dist/arBrowserPaths.js.map +1 -0
- package/server/dist/automationSession.d.ts +49 -0
- package/server/dist/automationSession.d.ts.map +1 -0
- package/server/dist/automationSession.js +225 -0
- package/server/dist/automationSession.js.map +1 -0
- package/server/dist/bridge.d.ts +43 -0
- package/server/dist/bridge.d.ts.map +1 -0
- package/server/dist/bridge.js +307 -0
- package/server/dist/bridge.js.map +1 -0
- package/server/dist/browserToolsExtras.d.ts +5 -0
- package/server/dist/browserToolsExtras.d.ts.map +1 -0
- package/server/dist/browserToolsExtras.js +304 -0
- package/server/dist/browserToolsExtras.js.map +1 -0
- package/server/dist/compositeTools.d.ts +12 -0
- package/server/dist/compositeTools.d.ts.map +1 -0
- package/server/dist/compositeTools.js +43 -0
- package/server/dist/compositeTools.js.map +1 -0
- package/server/dist/debugSnapshot.d.ts +13 -0
- package/server/dist/debugSnapshot.d.ts.map +1 -0
- package/server/dist/debugSnapshot.js +54 -0
- package/server/dist/debugSnapshot.js.map +1 -0
- package/server/dist/guardrails.d.ts +8 -0
- package/server/dist/guardrails.d.ts.map +1 -0
- package/server/dist/guardrails.js +24 -0
- package/server/dist/guardrails.js.map +1 -0
- package/server/dist/humanLike.d.ts +24 -0
- package/server/dist/humanLike.d.ts.map +1 -0
- package/server/dist/humanLike.js +97 -0
- package/server/dist/humanLike.js.map +1 -0
- package/server/dist/main.d.ts +2 -0
- package/server/dist/main.d.ts.map +1 -0
- package/server/dist/main.js +79 -0
- package/server/dist/main.js.map +1 -0
- package/server/dist/policyTiers.d.ts +3 -0
- package/server/dist/policyTiers.d.ts.map +1 -0
- package/server/dist/policyTiers.js +9 -0
- package/server/dist/policyTiers.js.map +1 -0
- package/server/dist/protocol.d.ts +62 -0
- package/server/dist/protocol.d.ts.map +1 -0
- package/server/dist/protocol.js +55 -0
- package/server/dist/protocol.js.map +1 -0
- package/server/dist/richEditorFill.d.ts +7 -0
- package/server/dist/richEditorFill.d.ts.map +1 -0
- package/server/dist/richEditorFill.js +27 -0
- package/server/dist/richEditorFill.js.map +1 -0
- package/server/dist/screenshotCrop.d.ts +11 -0
- package/server/dist/screenshotCrop.d.ts.map +1 -0
- package/server/dist/screenshotCrop.js +17 -0
- package/server/dist/screenshotCrop.js.map +1 -0
- package/server/dist/sessionLog.d.ts +42 -0
- package/server/dist/sessionLog.d.ts.map +1 -0
- package/server/dist/sessionLog.js +112 -0
- package/server/dist/sessionLog.js.map +1 -0
- package/server/dist/sessionPhase.d.ts +5 -0
- package/server/dist/sessionPhase.d.ts.map +1 -0
- package/server/dist/sessionPhase.js +24 -0
- package/server/dist/sessionPhase.js.map +1 -0
- package/server/dist/sessionSummary.d.ts +16 -0
- package/server/dist/sessionSummary.d.ts.map +1 -0
- package/server/dist/sessionSummary.js +70 -0
- package/server/dist/sessionSummary.js.map +1 -0
- package/server/dist/skillsInstructions.d.ts +5 -0
- package/server/dist/skillsInstructions.d.ts.map +1 -0
- package/server/dist/skillsInstructions.js +45 -0
- package/server/dist/skillsInstructions.js.map +1 -0
- package/server/dist/structureFilter.d.ts +21 -0
- package/server/dist/structureFilter.d.ts.map +1 -0
- package/server/dist/structureFilter.js +22 -0
- package/server/dist/structureFilter.js.map +1 -0
- package/server/dist/surveyCatalog.d.ts +10 -0
- package/server/dist/surveyCatalog.d.ts.map +1 -0
- package/server/dist/surveyCatalog.js +59 -0
- package/server/dist/surveyCatalog.js.map +1 -0
- package/server/dist/surveyRunner.d.ts +28 -0
- package/server/dist/surveyRunner.d.ts.map +1 -0
- package/server/dist/surveyRunner.js +109 -0
- package/server/dist/surveyRunner.js.map +1 -0
- package/server/dist/toolHelpers.d.ts +44 -0
- package/server/dist/toolHelpers.d.ts.map +1 -0
- package/server/dist/toolHelpers.js +83 -0
- package/server/dist/toolHelpers.js.map +1 -0
- package/server/dist/toolRuntime.d.ts +41 -0
- package/server/dist/toolRuntime.d.ts.map +1 -0
- package/server/dist/toolRuntime.js +263 -0
- package/server/dist/toolRuntime.js.map +1 -0
- package/server/dist/toolSchemas.d.ts +431 -0
- package/server/dist/toolSchemas.d.ts.map +1 -0
- package/server/dist/toolSchemas.js +408 -0
- package/server/dist/toolSchemas.js.map +1 -0
- package/server/dist/tools.d.ts +5 -0
- package/server/dist/tools.d.ts.map +1 -0
- package/server/dist/tools.js +484 -0
- package/server/dist/tools.js.map +1 -0
- package/server/dist/verdictExtract.d.ts +7 -0
- package/server/dist/verdictExtract.d.ts.map +1 -0
- package/server/dist/verdictExtract.js +24 -0
- package/server/dist/verdictExtract.js.map +1 -0
- package/server/dist/workflowTools.d.ts +5 -0
- package/server/dist/workflowTools.d.ts.map +1 -0
- package/server/dist/workflowTools.js +96 -0
- package/server/dist/workflowTools.js.map +1 -0
package/README.md
CHANGED
|
@@ -1,3 +1,215 @@
|
|
|
1
|
-
#
|
|
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
|
-
|
|
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.
|
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();
|