weboperator-mcp 1.5.0 → 1.6.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 CHANGED
@@ -6,10 +6,16 @@ It drives the browser you are already signed into, so your sessions, cookies, an
6
6
 
7
7
  ## Tools
8
8
 
9
- `browser_snapshot` · `browser_navigate` · `browser_click` · `browser_type` · `browser_press` · `browser_scroll` · `browser_screenshot` · `browser_extract` · `browser_solve_captcha` · `weboperator_execute_goal`
9
+ The stdio server and HTTP MCP endpoint expose the same **45 tools**: browser actions, image reading, JavaScript dialogs, tabs, task lifecycle, network and console observation, cookies, storage, file transfers and clipboard access. See the [tool catalogue](https://github.com/KazKozDev/WebOperator/blob/main/docs/mcp-tools.md).
10
+
11
+ New tools include `browser_image`, `browser_select_option`, `browser_handle_dialog`, and `agent_task_pause`, `agent_task_resume`, `agent_task_wait`.
12
+
13
+ `browser_extract` with `mode:"rows"` or `mode:"chunk"` collects a long list or article and checks that it is complete. Ask for 200 records and the extension pages or scrolls through the list, rechecks a load that stalls, and reports the actual count if the site has fewer; for an article it reads by section and says where it stopped. Repeat the call with the returned `collectionId` until `complete` is true.
10
14
 
11
15
  `browser_snapshot` returns an accessibility tree with numbered interactive elements; the action tools take those numbers, so an agent never guesses at CSS selectors.
12
16
 
17
+ After updating, rebuild and reload the extension and reconnect your MCP client so it fetches the new tool list. Running clients keep their current server process until restarted; local changes do not update an already published npm package.
18
+
13
19
  ## Install
14
20
 
15
21
  The server talks to Chrome through the [WebOperator extension](https://github.com/KazKozDev/WebOperator) and a Native Messaging host, so install the extension first, then register the host:
package/bridge.js CHANGED
@@ -4,6 +4,7 @@ const http = require('http');
4
4
  const net = require('net');
5
5
  const { randomUUID } = require('crypto');
6
6
  const fs = require('fs');
7
+ const { prepareLocalRequest, completeLocalRequest, clipboardRequest } = require('./local-files');
7
8
 
8
9
  const HOST = process.env.WEBOPERATOR_BRIDGE_HOST || '127.0.0.1';
9
10
  const PORT = Number(process.env.WEBOPERATOR_BRIDGE_PORT || 8765);
@@ -20,25 +21,39 @@ function log(line) {
20
21
  try { fs.appendFileSync(LOG, `${new Date().toISOString()} ${line}\n`); } catch {}
21
22
  }
22
23
 
23
- function ensureSingleInstance() {
24
+ let ownsEndpointLease = false;
25
+
26
+ function tryAcquireEndpointLease() {
24
27
  try {
25
28
  if (fs.existsSync(PID_FILE)) {
26
29
  const oldPid = Number(fs.readFileSync(PID_FILE, 'utf8').trim());
27
- if (oldPid && oldPid !== process.pid) {
28
- try { process.kill(oldPid, 'SIGTERM'); } catch {}
30
+ if (oldPid === process.pid) return true;
31
+ if (oldPid) {
32
+ try { process.kill(oldPid, 0); return false; } catch {}
29
33
  }
34
+ fs.unlinkSync(PID_FILE);
30
35
  }
31
36
  } catch {}
32
- try { fs.writeFileSync(PID_FILE, String(process.pid)); } catch {}
37
+ try {
38
+ const fd = fs.openSync(PID_FILE, 'wx', 0o600);
39
+ fs.writeFileSync(fd, String(process.pid));
40
+ fs.closeSync(fd);
41
+ ownsEndpointLease = true;
42
+ return true;
43
+ } catch { return false; }
33
44
  }
34
45
 
35
- ensureSingleInstance();
46
+ tryAcquireEndpointLease();
36
47
 
37
48
  log(`process start pid=${process.pid} ppid=${process.ppid} argv=${JSON.stringify(redactArgv(process.argv))} cwd=${process.cwd()}`);
38
49
  process.on('beforeExit', (code) => log(`beforeExit code=${code}`));
39
50
  process.on('exit', (code) => {
40
51
  log(`exit code=${code}`);
41
- try { if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE); } catch {}
52
+ if (ownsEndpointLease) {
53
+ try {
54
+ if (fs.existsSync(PID_FILE) && Number(fs.readFileSync(PID_FILE, 'utf8').trim()) === process.pid) fs.unlinkSync(PID_FILE);
55
+ } catch {}
56
+ }
42
57
  });
43
58
 
44
59
  process.on('uncaughtException', (err) => log(`uncaughtException ${err && err.stack ? err.stack : err}`));
@@ -156,8 +171,15 @@ function rejectAll(err) {
156
171
  }
157
172
  }
158
173
 
159
- function requestExtension(type, payload = {}, timeoutMs = 60_000) {
160
- if (!extensionOnline) throw new Error('WebOperator extension is not connected to the bridge');
174
+ async function requestExtension(type, payload = {}, timeoutMs = 60_000) {
175
+ if (extensionOnline && process.platform === 'darwin' && ['clipboard.read', 'clipboard.write'].includes(type)) return clipboardRequest(type, payload);
176
+ const prepared = await prepareLocalRequest(type, payload);
177
+ const result = await rawRequestExtension(type, prepared, timeoutMs);
178
+ return completeLocalRequest(type, prepared, result);
179
+ }
180
+
181
+ function rawRequestExtension(type, payload = {}, timeoutMs = 60_000) {
182
+ if (!extensionOnline) throw httpError(500, 'WebOperator extension is not connected to the bridge');
161
183
  const id = randomUUID();
162
184
  const promise = new Promise((resolve, reject) => {
163
185
  const timeout = setTimeout(() => {
@@ -187,7 +209,8 @@ const server = http.createServer(async (req, res) => {
187
209
  const result = await route(req.method || 'GET', url, body);
188
210
  sendJson(res, 200, result);
189
211
  } catch (err) {
190
- sendJson(res, statusForError(err), { error: err instanceof Error ? err.message : String(err) });
212
+ log(`http request failed: ${err instanceof Error ? err.stack : String(err)}`);
213
+ sendJson(res, statusForError(err), { error: publicErrorMessage(err) });
191
214
  }
192
215
  });
193
216
 
@@ -200,12 +223,15 @@ server.on('error', (err) => {
200
223
  }, 1000);
201
224
  }
202
225
  });
203
- server.listen(PORT, HOST, () => {
204
- log(`http listening on http://${HOST}:${PORT}`);
205
- });
206
-
226
+ function startEndpointServers() {
227
+ server.listen(PORT, HOST, () => log(`http listening on http://${HOST}:${PORT}`));
228
+ startAgentSocket();
229
+ }
207
230
 
208
- startAgentSocket();
231
+ if (ownsEndpointLease) startEndpointServers();
232
+ setInterval(() => {
233
+ if (!ownsEndpointLease && tryAcquireEndpointLease()) startEndpointServers();
234
+ }, 1000).unref();
209
235
 
210
236
  function writeCors(_req, res) {
211
237
  res.setHeader('access-control-allow-origin', 'http://127.0.0.1');
@@ -228,9 +254,14 @@ function sendJson(res, status, value) {
228
254
  res.end(body);
229
255
  }
230
256
 
257
+ function publicErrorMessage(err) {
258
+ return err && err.publicMessage ? err.publicMessage : 'Internal server error';
259
+ }
260
+
231
261
  function httpError(status, message) {
232
262
  const err = new Error(message);
233
263
  err.status = status;
264
+ err.publicMessage = message;
234
265
  return err;
235
266
  }
236
267
 
@@ -314,7 +345,7 @@ async function route(method, url, body) {
314
345
  if (method === 'POST' && action === 'stop') return requestExtension('tasks.stop', { id }, 30_000);
315
346
  if (method === 'POST' && action === 'pause') return requestExtension('tasks.pause', { id }, 30_000);
316
347
  if (method === 'POST' && action === 'resume') return requestExtension('tasks.resume', { id }, 30_000);
317
- if (method === 'POST' && action === 'confirm') return requestExtension('tasks.confirm', { id, allow: body.allow }, 30_000);
348
+ if (method === 'POST' && action === 'confirm') return requestExtension('tasks.confirm', { id, ...(body.approve === undefined ? { allow: body.allow } : { approve: body.approve }) }, 30_000);
318
349
  if (method === 'POST' && action === 'wait') {
319
350
  return requestExtension('tasks.wait', { id, timeoutMs: body.timeoutMs }, Number(body.timeoutMs || 120_000) + 5_000);
320
351
  }
@@ -395,6 +426,7 @@ function writeSse(res, event, data) {
395
426
  }
396
427
 
397
428
  function startAgentSocket() {
429
+ let socketInode = null;
398
430
  try {
399
431
  if (fs.existsSync(AGENT_SOCKET)) fs.unlinkSync(AGENT_SOCKET);
400
432
  } catch (err) {
@@ -419,11 +451,14 @@ function startAgentSocket() {
419
451
  socketServer.on('error', (err) => log(`agent socket server error: ${err.message}`));
420
452
  socketServer.listen(AGENT_SOCKET, () => {
421
453
  try { fs.chmodSync(AGENT_SOCKET, 0o600); } catch {}
454
+ try { socketInode = fs.statSync(AGENT_SOCKET).ino; } catch {}
422
455
  log(`agent socket listening on ${AGENT_SOCKET}`);
423
456
  });
424
457
 
425
458
  process.on('exit', () => {
426
- try { if (fs.existsSync(AGENT_SOCKET)) fs.unlinkSync(AGENT_SOCKET); } catch {}
459
+ try {
460
+ if (socketInode !== null && fs.existsSync(AGENT_SOCKET) && fs.statSync(AGENT_SOCKET).ino === socketInode) fs.unlinkSync(AGENT_SOCKET);
461
+ } catch {}
427
462
  });
428
463
  }
429
464
 
@@ -483,113 +518,24 @@ function sendAgentFrame(socket, obj) {
483
518
  socket.write(Buffer.concat([header, body]));
484
519
  }
485
520
 
486
- const AGENT_TOOLS = [
487
- {
488
- type: 'function',
489
- function: {
490
- name: 'browser_snapshot',
491
- description: 'Capture the structured accessibility tree and numbered interactive elements from the active tab.',
492
- parameters: { type: 'object', properties: {} },
493
- },
494
- },
495
- {
496
- type: 'function',
497
- function: {
498
- name: 'browser_navigate',
499
- description: 'Navigate the active browser tab to a specified URL.',
500
- parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
501
- },
502
- },
503
- {
504
- type: 'function',
505
- function: {
506
- name: 'browser_click',
507
- description: 'Click an element on the active webpage by numeric index or selector.',
508
- parameters: { type: 'object', properties: { index: { type: 'number' }, selector: { type: 'string' } } },
509
- },
510
- },
511
- {
512
- type: 'function',
513
- function: {
514
- name: 'browser_type',
515
- description: 'Type text into an input field by element index or selector.',
516
- parameters: { type: 'object', properties: { index: { type: 'number' }, selector: { type: 'string' }, text: { type: 'string' }, clear: { type: 'boolean' } }, required: ['text'] },
517
- },
518
- },
519
- {
520
- type: 'function',
521
- function: {
522
- name: 'browser_press',
523
- description: 'Press a keyboard key on the active webpage (e.g. Enter, Tab, Escape).',
524
- parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] },
525
- },
526
- },
527
- {
528
- type: 'function',
529
- function: {
530
- name: 'browser_scroll',
531
- description: 'Scroll the active webpage.',
532
- parameters: { type: 'object', properties: { direction: { type: 'string', enum: ['down', 'up'] }, amount: { type: 'number' } } },
533
- },
534
- },
535
- {
536
- type: 'function',
537
- function: {
538
- name: 'browser_screenshot',
539
- description: 'Capture a visual PNG screenshot of the current tab.',
540
- parameters: { type: 'object', properties: {} },
541
- },
542
- },
543
- {
544
- type: 'function',
545
- function: {
546
- name: 'browser_extract',
547
- description: 'Extract targeted text or structured content from the page.',
548
- parameters: { type: 'object', properties: { instruction: { type: 'string' }, selector: { type: 'string' } } },
549
- },
550
- },
551
- {
552
- type: 'function',
553
- function: {
554
- name: 'browser_solve_captcha',
555
- description: 'Attempt to detect and automatically solve or click Cloudflare Turnstile, reCAPTCHA, or hCaptcha verification challenges in the active tab.',
556
- parameters: { type: 'object', properties: { type: { type: 'string', enum: ['cloudflare', 'recaptcha', 'hcaptcha', 'auto'] } } },
557
- },
558
- },
559
- {
560
- type: 'function',
561
- function: {
562
- name: 'weboperator_execute_goal',
563
- description: 'Execute an autonomous browser goal end-to-end.',
564
- parameters: { type: 'object', properties: { goal: { type: 'string' }, timeoutMs: { type: 'number' } }, required: ['goal'] },
565
- },
566
- },
567
- ];
521
+ const { TOOLS, TOOL_TYPES, imageContent } = require('./tools');
522
+ const AGENT_TOOLS = TOOLS.map(({ name, description, inputSchema }) => ({ type: 'function', function: { name, description, parameters: inputSchema } }));
568
523
 
569
524
  async function executeToolByName(name, args = {}, timeoutMs = 30_000) {
525
+ if (name !== 'weboperator_execute_goal' && TOOL_TYPES[name]) {
526
+ const response = await requestExtension(TOOL_TYPES[name], { ...args, ...(args.type === 'auto' ? { type: undefined } : {}) }, Math.max(timeoutMs, Number(args.timeoutMs ?? 0) + 10_000));
527
+ const result = response?.kind === 'action:result' ? response.result : response;
528
+ if (['browser_click', 'browser_type', 'browser_scroll', 'browser_select_option'].includes(name) && (response?.kind === 'error' || result?.ok === false)) {
529
+ throw httpError(400, result?.error || response.error || 'Browser action failed');
530
+ }
531
+ return response;
532
+ }
570
533
  switch (name) {
571
- case 'browser_snapshot':
572
- return requestExtension('browser.snapshot', {}, timeoutMs);
573
- case 'browser_navigate':
574
- return requestExtension('browser.navigate', { url: args.url }, timeoutMs);
575
- case 'browser_click':
576
- return requestExtension('browser.click', { index: args.index, selector: args.selector }, timeoutMs);
577
- case 'browser_type':
578
- return requestExtension('browser.type', { index: args.index, selector: args.selector, text: args.text, clear: args.clear }, timeoutMs);
579
- case 'browser_press':
580
- return requestExtension('browser.press', { key: args.key }, timeoutMs);
581
- case 'browser_scroll':
582
- return requestExtension('browser.scroll', { direction: args.direction || 'down', amount: args.amount || 500 }, timeoutMs);
583
- case 'browser_screenshot':
584
- return requestExtension('browser.screenshot', {}, timeoutMs);
585
- case 'browser_extract':
586
- return requestExtension('browser.extract', { instruction: args.instruction, selector: args.selector }, timeoutMs);
587
- case 'browser_solve_captcha':
588
- return requestExtension('browser.solve_captcha', { type: args.type === 'auto' ? undefined : args.type }, timeoutMs);
589
534
  case 'weboperator_execute_goal': {
590
535
  const taskTimeout = Number(args.timeoutMs || timeoutMs || 120_000);
591
- const startRes = await requestExtension('tasks.start', { goal: args.goal, timeoutMs: taskTimeout }, 30_000);
592
- const taskId = startRes && startRes.id;
536
+ const startRes = await requestExtension('tasks.start', { ...args, goal: args.goal, timeoutMs: taskTimeout, wait: false }, 30_000);
537
+ const taskId = startRes && (startRes.taskId || startRes.id);
538
+ if (args.wait === false) return { ...startRes, taskId };
593
539
  if (!taskId) return startRes;
594
540
  const finalTask = await requestExtension('tasks.wait', { id: taskId, timeoutMs: taskTimeout }, taskTimeout + 10_000);
595
541
  return formatTaskResultForAgent(finalTask || startRes);
@@ -649,6 +595,7 @@ function formatTaskResultForAgent(task) {
649
595
 
650
596
  return {
651
597
  ok: task.status === 'done',
598
+ taskId: task.taskId || task.id,
652
599
  status: task.status,
653
600
  goal: task.goal,
654
601
  answer,
@@ -669,7 +616,7 @@ async function handleMcpHttp(msg) {
669
616
  result: {
670
617
  protocolVersion: '2024-11-05',
671
618
  capabilities: { tools: { listChanged: false } },
672
- serverInfo: { name: 'weboperator-bridge', version: '1.4.0' },
619
+ serverInfo: { name: 'weboperator-bridge', version: require('./package.json').version },
673
620
  },
674
621
  };
675
622
  }
@@ -694,7 +641,7 @@ async function handleMcpHttp(msg) {
694
641
  jsonrpc: '2.0',
695
642
  id,
696
643
  result: {
697
- content: [{ type: 'text', text: typeof res === 'string' ? res : JSON.stringify(res, null, 2) }],
644
+ content: name === 'browser_image' ? imageContent(res) : [{ type: 'text', text: typeof res === 'string' ? res : JSON.stringify(res, null, 2) }],
698
645
  },
699
646
  };
700
647
  } catch (err) {
@@ -713,4 +660,3 @@ async function handleMcpHttp(msg) {
713
660
  }
714
661
  return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
715
662
  }
716
-
@@ -1,11 +1,13 @@
1
1
  {
2
2
  "name": "hermes-weboperator",
3
- "version": "1.4.0",
3
+ "version": "1.6.0",
4
4
  "description": "Hermes Agent MCP harness configuration for WebOperator browser control",
5
5
  "mcpServers": {
6
6
  "weboperator": {
7
7
  "command": "node",
8
- "args": ["weboperator-bridge/mcp-server.js"],
8
+ "args": [
9
+ "weboperator-bridge/mcp-server.js"
10
+ ],
9
11
  "env": {
10
12
  "WEBOPERATOR_AGENT_SOCKET": "/tmp/weboperator-bridge.sock"
11
13
  }
package/local-files.js ADDED
@@ -0,0 +1,68 @@
1
+ const fs = require('node:fs/promises');
2
+ const path = require('node:path');
3
+
4
+ function absolutePath(value) {
5
+ if (typeof value !== 'string' || !path.isAbsolute(value) || value.includes('\0')) throw new Error('An absolute filesystem path is required');
6
+ return value;
7
+ }
8
+
9
+ async function prepareLocalRequest(type, payload) {
10
+ if (type !== 'browser.upload_file') return payload;
11
+ const filePath = absolutePath(payload.path);
12
+ const stat = await fs.stat(filePath);
13
+ if (!stat.isFile()) throw new Error('Upload path must name a regular file');
14
+ if (stat.size > 40 * 1024 * 1024) throw new Error('Upload file exceeds 40 MiB');
15
+ return { ...payload, path: filePath, fileName: path.basename(filePath), fileSize: stat.size };
16
+ }
17
+
18
+ async function completeLocalRequest(type, payload, result) {
19
+ if (type === 'browser.screenshot' && payload.saveTo) {
20
+ const filePath = absolutePath(payload.saveTo);
21
+ if (!result?.dataUrl?.match(/^data:image\/(png|jpeg);base64,/)) throw new Error('Extension returned no screenshot');
22
+ await fs.writeFile(filePath, Buffer.from(result.dataUrl.split(',')[1], 'base64'), { flag: 'wx', mode: 0o600 });
23
+ return { ...result, path: filePath };
24
+ }
25
+ if (type !== 'downloads.read') return result;
26
+ if (!result || result.state !== 'complete') throw new Error('Download is not complete');
27
+ const maxBytes = payload.maxBytes ?? 20000000;
28
+ if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 20000000) throw new Error('maxBytes must be between 1 and 20000000');
29
+ // The extension supplies the path from chrome.downloads by id; caller-supplied paths are never used.
30
+ const handle = await fs.open(absolutePath(result.path), 'r');
31
+ try {
32
+ const stat = await handle.stat();
33
+ if (!stat.isFile()) throw new Error('Downloaded path is not a regular file');
34
+ const buffer = Buffer.alloc(Math.min(stat.size, maxBytes));
35
+ let offset = 0;
36
+ while (offset < buffer.length) { const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset); if (!bytesRead) break; offset += bytesRead; }
37
+ const bytes = buffer.subarray(0, offset);
38
+ const isText = /^(text\/)|json|xml|javascript|csv/.test(result.mime ?? '') || /\.(txt|md|csv|tsv|json|xml|html?|log)$/i.test(result.path);
39
+ return { kind: isText ? 'text' : 'base64', content: bytes.toString(isText ? 'utf8' : 'base64'), truncated: stat.size > offset, bytes: offset, mimeType: result.mime };
40
+ } finally { await handle.close(); }
41
+ }
42
+
43
+ module.exports = { prepareLocalRequest, completeLocalRequest };
44
+
45
+ function clipboardRequest(type, payload = {}) {
46
+ if (type === 'clipboard.write' && (typeof payload.text !== 'string' || Buffer.byteLength(payload.text) > 1024 * 1024)) throw new Error('Clipboard text must be a string up to 1 MiB');
47
+ const { spawn } = require('node:child_process');
48
+ return new Promise((resolve, reject) => {
49
+ const child = spawn(type === 'clipboard.read' ? '/usr/bin/pbpaste' : '/usr/bin/pbcopy', [], { stdio: ['pipe', 'pipe', 'ignore'] });
50
+ const chunks = [];
51
+ let bytes = 0;
52
+ const timer = setTimeout(() => { child.kill(); reject(new Error('System clipboard timed out')); }, 5000);
53
+ child.on('error', (error) => { clearTimeout(timer); reject(error); });
54
+ child.stdin.on('error', (error) => { clearTimeout(timer); reject(error); });
55
+ child.stdout.on('data', (chunk) => {
56
+ bytes += chunk.length;
57
+ if (bytes > 1024 * 1024) { child.kill(); clearTimeout(timer); reject(new Error('Clipboard text exceeds 1 MiB')); }
58
+ else chunks.push(chunk);
59
+ });
60
+ child.on('close', (code) => {
61
+ clearTimeout(timer);
62
+ if (code !== 0) reject(new Error(`System clipboard command failed: ${code}`));
63
+ else resolve(type === 'clipboard.read' ? { text: Buffer.concat(chunks).toString('utf8') } : { ok: true });
64
+ });
65
+ child.stdin.end(type === 'clipboard.write' ? payload.text : undefined);
66
+ });
67
+ }
68
+ module.exports.clipboardRequest = clipboardRequest;
package/mcp-server.js CHANGED
@@ -17,6 +17,13 @@ const BRIDGE_HOST = process.env.WEBOPERATOR_BRIDGE_HOST || '127.0.0.1';
17
17
  const BRIDGE_PORT = Number(process.env.WEBOPERATOR_BRIDGE_PORT || 8765);
18
18
  const API_TOKEN = process.env.WEBOPERATOR_API_TOKEN || '';
19
19
 
20
+ // Shared, optional tool properties understood by the extension itself:
21
+ // `tabId` acts on one specific tab instead of the focused one, `ref` targets an
22
+ // element straight from a snapshot (e.g. "@e12") — including scroll containers,
23
+ // which is how a virtualized list (Gmail, chat apps) is scrolled without
24
+ // touching the window.
25
+ const { TOOLS, TOOL_TYPES, imageContent } = require('./tools');
26
+
20
27
  process.stdout.on('error', (err) => {
21
28
  if (err && err.code === 'EPIPE') process.exit(0);
22
29
  });
@@ -25,187 +32,47 @@ process.on('uncaughtException', (err) => {
25
32
  });
26
33
 
27
34
 
28
- const TOOLS = [
29
- {
30
- name: 'browser_snapshot',
31
- description: 'Capture the structured accessibility tree and numbered interactive elements (buttons, inputs, links) from the current active browser tab.',
32
- inputSchema: {
33
- type: 'object',
34
- properties: {},
35
- additionalProperties: false,
36
- },
37
- },
38
- {
39
- name: 'browser_navigate',
40
- description: 'Navigate the active browser tab to a specified URL.',
41
- inputSchema: {
42
- type: 'object',
43
- properties: {
44
- url: {
45
- type: 'string',
46
- description: 'The URL to navigate to (e.g. "https://google.com").',
47
- },
48
- },
49
- required: ['url'],
50
- additionalProperties: false,
51
- },
52
- },
53
- {
54
- name: 'browser_click',
55
- description: 'Click an element on the webpage by its numeric index (from browser_snapshot) or CSS selector.',
56
- inputSchema: {
57
- type: 'object',
58
- properties: {
59
- index: {
60
- type: 'number',
61
- description: 'The numeric index of the interactive element from the snapshot.',
62
- },
63
- selector: {
64
- type: 'string',
65
- description: 'Alternative CSS selector of the element to click.',
66
- },
67
- },
68
- additionalProperties: false,
69
- },
70
- },
71
- {
72
- name: 'browser_type',
73
- description: 'Type text into an input field by element index or selector.',
74
- inputSchema: {
75
- type: 'object',
76
- properties: {
77
- index: {
78
- type: 'number',
79
- description: 'The numeric index of the input element from the snapshot.',
80
- },
81
- selector: {
82
- type: 'string',
83
- description: 'Alternative CSS selector of the input element.',
84
- },
85
- text: {
86
- type: 'string',
87
- description: 'The text to type into the field.',
88
- },
89
- clear: {
90
- type: 'boolean',
91
- description: 'Whether to clear existing text before typing (default: false).',
92
- },
93
- },
94
- required: ['text'],
95
- additionalProperties: false,
96
- },
97
- },
98
- {
99
- name: 'browser_press',
100
- description: 'Press a keyboard key on the active webpage (e.g. "Enter", "Tab", "Escape", "ArrowDown", "Backspace").',
101
- inputSchema: {
102
- type: 'object',
103
- properties: {
104
- key: {
105
- type: 'string',
106
- description: 'The key to press (e.g. "Enter", "Tab", "Escape").',
107
- },
108
- },
109
- required: ['key'],
110
- additionalProperties: false,
111
- },
112
- },
113
- {
114
- name: 'browser_scroll',
115
- description: 'Scroll the active webpage up or down.',
116
- inputSchema: {
117
- type: 'object',
118
- properties: {
119
- direction: {
120
- type: 'string',
121
- enum: ['down', 'up'],
122
- description: 'Direction to scroll (default: "down").',
123
- },
124
- amount: {
125
- type: 'number',
126
- description: 'Number of pixels to scroll (default: 500).',
127
- },
128
- },
129
- additionalProperties: false,
130
- },
131
- },
132
- {
133
- name: 'browser_screenshot',
134
- description: 'Capture a visual PNG screenshot of the current active browser tab.',
135
- inputSchema: {
136
- type: 'object',
137
- properties: {},
138
- additionalProperties: false,
139
- },
140
- },
141
- {
142
- name: 'browser_extract',
143
- description: 'Extract text or structured data from the webpage according to an extraction instruction.',
144
- inputSchema: {
145
- type: 'object',
146
- properties: {
147
- instruction: {
148
- type: 'string',
149
- description: 'Extraction guidance or prompt (e.g. "Extract all product prices and titles").',
150
- },
151
- selector: {
152
- type: 'string',
153
- description: 'Optional CSS selector to scope extraction.',
154
- },
155
- },
156
- additionalProperties: false,
157
- },
158
- },
159
- {
160
- name: 'browser_solve_captcha',
161
- description: 'Attempt to detect and automatically solve or click Cloudflare Turnstile, reCAPTCHA, or hCaptcha verification challenges in the active tab.',
162
- inputSchema: {
163
- type: 'object',
164
- properties: {
165
- type: {
166
- type: 'string',
167
- enum: ['cloudflare', 'recaptcha', 'hcaptcha', 'auto'],
168
- description: 'Optional captcha type to target (default: auto).',
169
- },
170
- },
171
- additionalProperties: false,
172
- },
173
- },
174
- {
175
- name: 'weboperator_execute_goal',
176
- description: 'Execute an autonomous browser goal end-to-end using WebOperator multi-step planner.',
177
- inputSchema: {
178
- type: 'object',
179
- properties: {
180
- goal: {
181
- type: 'string',
182
- description: 'Natural language goal for the agent to achieve (e.g. "Find cheapest flight from Paris to Rome on Kayak").',
183
- },
184
- timeoutMs: {
185
- type: 'number',
186
- description: 'Maximum timeout in milliseconds (default: 120000).',
187
- },
188
- },
189
- required: ['goal'],
190
- additionalProperties: false,
191
- },
192
- },
193
- ];
194
35
 
195
36
  async function callBridge(type, payload = {}, timeoutMs = 60_000) {
196
37
  // Try Unix Domain Socket first
197
38
  try {
198
39
  return await callSocket(type, payload, timeoutMs);
199
- } catch {
200
- // Fallback to HTTP API
40
+ } catch (err) {
41
+ // Once the bridge has taken the request, its answer is the answer. A
42
+ // retry over HTTP would hide the real error behind whatever the second
43
+ // attempt says, and after a timeout it would run the action again — a
44
+ // second click, a second form submission.
45
+ if (err && err.reachedBridge) throw err;
46
+ // The socket could not be opened at all: fall back to the HTTP API.
201
47
  return await callHttp(type, payload, timeoutMs);
202
48
  }
203
49
  }
204
50
 
51
+ // The socket takes the extension's own request types; the HTTP API has its
52
+ // own routes and tool names. This is the translation between the two.
53
+ function httpRequestFor(type, payload, timeoutMs) {
54
+ if (type === 'tasks.start') {
55
+ return { path: '/v1/tasks', body: payload };
56
+ }
57
+ if (type === 'tasks.wait') {
58
+ return {
59
+ path: `/v1/tasks/${encodeURIComponent(payload.id)}/wait`,
60
+ body: { timeoutMs: payload.timeoutMs },
61
+ };
62
+ }
63
+ // browser.snapshot -> browser_snapshot, and so on for every browser tool.
64
+ return {
65
+ path: '/v1/tools/call',
66
+ body: { tool: Object.keys(TOOL_TYPES).find((name) => TOOL_TYPES[name] === type) ?? type.replace('.', '_'), arguments: payload, timeoutMs },
67
+ };
68
+ }
69
+
205
70
 
206
71
  function callSocket(type, payload, timeoutMs) {
207
72
  return new Promise((resolve, reject) => {
208
73
  let resolved = false;
74
+ let connected = false;
75
+ const fail = (err) => reject(Object.assign(err, { reachedBridge: connected }));
209
76
  const socket = net.createConnection(SOCKET_PATH);
210
77
  const id = randomUUID();
211
78
  const message = { id, type, payload, timeoutMs, ...(API_TOKEN ? { token: API_TOKEN } : {}) };
@@ -214,7 +81,7 @@ function callSocket(type, payload, timeoutMs) {
214
81
  if (!resolved) {
215
82
  resolved = true;
216
83
  socket.destroy();
217
- reject(new Error(`Bridge socket timeout for ${type}`));
84
+ fail(new Error(`Bridge socket timeout for ${type}`));
218
85
  }
219
86
  }, timeoutMs);
220
87
 
@@ -222,6 +89,7 @@ function callSocket(type, payload, timeoutMs) {
222
89
  let nextLength = null;
223
90
 
224
91
  socket.on('connect', () => {
92
+ connected = true;
225
93
  const body = Buffer.from(JSON.stringify(message), 'utf8');
226
94
  const header = Buffer.alloc(4);
227
95
  header.writeUInt32LE(body.length, 0);
@@ -248,7 +116,7 @@ function callSocket(type, payload, timeoutMs) {
248
116
  resolved = true;
249
117
  clearTimeout(timer);
250
118
  socket.end();
251
- if (msg.error) reject(new Error(msg.error));
119
+ if (msg.error) fail(new Error(msg.error));
252
120
  else resolve(msg.result);
253
121
  }
254
122
  } catch (parseErr) {
@@ -256,7 +124,7 @@ function callSocket(type, payload, timeoutMs) {
256
124
  resolved = true;
257
125
  clearTimeout(timer);
258
126
  socket.destroy();
259
- reject(parseErr);
127
+ fail(parseErr);
260
128
  }
261
129
  }
262
130
  }
@@ -266,7 +134,7 @@ function callSocket(type, payload, timeoutMs) {
266
134
  if (!resolved) {
267
135
  resolved = true;
268
136
  clearTimeout(timer);
269
- reject(err);
137
+ fail(err);
270
138
  }
271
139
  });
272
140
  });
@@ -274,9 +142,8 @@ function callSocket(type, payload, timeoutMs) {
274
142
 
275
143
  function callHttp(type, payload, timeoutMs) {
276
144
  return new Promise((resolve, reject) => {
277
- let path = '/v1/tools/call';
145
+ const { path, body: bodyObj } = httpRequestFor(type, payload, timeoutMs);
278
146
  const method = 'POST';
279
- const bodyObj = { tool: type, arguments: payload, timeoutMs };
280
147
 
281
148
  const headers = {
282
149
  'content-type': 'application/json',
@@ -319,10 +186,66 @@ function callHttp(type, payload, timeoutMs) {
319
186
  });
320
187
  }
321
188
 
189
+ // Snapshot refs look like "@e12". A bare numeric index maps onto the same
190
+ // scheme ("12" -> "@e12"), anything already carrying the "@" prefix or a CSS
191
+ // selector is passed through untouched.
192
+ function assertActionSucceeded(res) {
193
+ const result = res?.kind === 'action:result' ? res.result : res;
194
+ if (res?.kind === 'error' || result?.ok === false) throw new Error(result?.error || res.error || 'Browser action failed');
195
+ }
196
+
197
+ function refArg(args = {}) {
198
+ if (args.ref !== undefined && args.ref !== null && args.ref !== '') return String(args.ref);
199
+ if (args.index !== undefined && args.index !== null && args.index !== '') {
200
+ const raw = String(args.index).trim();
201
+ if (raw.startsWith('@')) return raw;
202
+ return `@e${raw.replace(/^e/i, '')}`;
203
+ }
204
+ return '';
205
+ }
206
+
207
+ function refPayload(args = {}) {
208
+ const payload = {};
209
+ const ref = refArg(args);
210
+ if (ref) payload.ref = ref;
211
+ if (args.selector !== undefined && args.selector !== null && args.selector !== '') payload.selector = String(args.selector);
212
+ return payload;
213
+ }
214
+
215
+ function tabIdArg(args = {}) {
216
+ const raw = args.tabId;
217
+ if (raw === undefined || raw === null || raw === '') return undefined;
218
+ const n = Number(raw);
219
+ return Number.isFinite(n) ? n : undefined;
220
+ }
221
+
222
+ function withTabId(payload, args = {}) {
223
+ const tabId = tabIdArg(args);
224
+ return tabId === undefined ? payload : { ...payload, tabId };
225
+ }
226
+
227
+ // The extension types via `mode`; the historic MCP `clear` flag is mapped onto it.
228
+ function typeOptions(args = {}) {
229
+ if (args.mode === 'append' || args.mode === 'replace') return { mode: args.mode };
230
+ if (args.clear === true) return { mode: 'replace' };
231
+ if (args.clear === false) return { mode: 'append' };
232
+ return {};
233
+ }
234
+
322
235
  async function handleToolCall(name, args) {
236
+ if (name.startsWith('agent_task_') || name.startsWith('tabs_') || name === 'browser_eval' || name === 'browser_wait') {
237
+ if (!TOOL_TYPES[name]) throw new Error(`Unknown tool: ${name}`);
238
+ const timeoutMs = Number(args.timeoutMs ?? (name === 'agent_task_wait' || (name === 'agent_task_start' && args.wait) ? 120_000 : 30_000)) + 10_000;
239
+ const res = await callBridge(TOOL_TYPES[name], args, timeoutMs);
240
+ return { ...(res?.ok === false ? { isError: true } : {}), content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
241
+ }
323
242
  switch (name) {
243
+ case 'browser_image': {
244
+ const res = await callBridge('browser.image', args, 30_000);
245
+ return { content: imageContent(res) };
246
+ }
324
247
  case 'browser_snapshot': {
325
- const res = await callBridge('browser.snapshot', {}, 30_000);
248
+ const res = await callBridge('browser.snapshot', args, 30_000);
326
249
  return {
327
250
  content: [
328
251
  {
@@ -333,7 +256,7 @@ async function handleToolCall(name, args) {
333
256
  };
334
257
  }
335
258
  case 'browser_navigate': {
336
- const res = await callBridge('browser.navigate', { url: args.url }, 60_000);
259
+ const res = await callBridge('browser.navigate', withTabId({ url: args.url }, args), 60_000);
337
260
  return {
338
261
  content: [
339
262
  {
@@ -344,7 +267,8 @@ async function handleToolCall(name, args) {
344
267
  };
345
268
  }
346
269
  case 'browser_click': {
347
- const res = await callBridge('browser.click', { index: args.index, selector: args.selector }, 30_000);
270
+ const res = await callBridge('browser.click', withTabId({ ...refPayload(args), ...(args.button !== undefined ? { button: args.button } : {}), ...(args.clickCount !== undefined ? { clickCount: args.clickCount } : {}), ...(args.modifiers !== undefined ? { modifiers: args.modifiers } : {}) }, args), 30_000);
271
+ assertActionSucceeded(res);
348
272
  return {
349
273
  content: [
350
274
  {
@@ -355,7 +279,8 @@ async function handleToolCall(name, args) {
355
279
  };
356
280
  }
357
281
  case 'browser_type': {
358
- const res = await callBridge('browser.type', { index: args.index, selector: args.selector, text: args.text, clear: args.clear }, 30_000);
282
+ const res = await callBridge('browser.type', withTabId({ ...refPayload(args), text: args.text, ...typeOptions(args) }, args), 30_000);
283
+ assertActionSucceeded(res);
359
284
  return {
360
285
  content: [
361
286
  {
@@ -366,7 +291,7 @@ async function handleToolCall(name, args) {
366
291
  };
367
292
  }
368
293
  case 'browser_press': {
369
- const res = await callBridge('browser.press', { key: args.key }, 30_000);
294
+ const res = await callBridge('browser.press', withTabId({ ...refPayload(args), key: args.key, ...(args.modifiers ? { modifiers: String(args.modifiers) } : {}) }, args), 30_000);
370
295
  return {
371
296
  content: [
372
297
  {
@@ -377,19 +302,22 @@ async function handleToolCall(name, args) {
377
302
  };
378
303
  }
379
304
  case 'browser_scroll': {
380
- const res = await callBridge('browser.scroll', { direction: args.direction || 'down', amount: args.amount || 500 }, 30_000);
305
+ const amount = Number(args.amount || 500);
306
+ const res = await callBridge('browser.scroll', withTabId({ ...refPayload(args), direction: args.direction || 'down', amount, amountPx: amount, ...(args.to !== undefined ? { to: args.to, block: args.block ?? 'center' } : {}) }, args), 30_000);
307
+ assertActionSucceeded(res);
381
308
  return {
382
309
  content: [
383
310
  {
384
311
  type: 'text',
385
- text: `Scrolled ${args.direction || 'down'}. ${res?.status || 'ok'}`,
312
+ text: JSON.stringify(res, null, 2),
386
313
  },
387
314
  ],
388
315
  };
389
316
  }
390
317
  case 'browser_screenshot': {
391
- const res = await callBridge('browser.screenshot', {}, 30_000);
392
- const dataUri = res?.dataUri || res?.screenshot || '';
318
+ const res = await callBridge('browser.screenshot', args, 30_000);
319
+ if (res?.path) return { content: [{ type: 'text', text: JSON.stringify({ path: res.path, w: res.w, h: res.h }) }] };
320
+ const dataUri = res?.dataUrl || res?.dataUri || res?.screenshot || '';
393
321
  const base64Data = dataUri.replace(/^data:image\/[a-z]+;base64,/, '');
394
322
  if (base64Data) {
395
323
  return {
@@ -397,7 +325,7 @@ async function handleToolCall(name, args) {
397
325
  {
398
326
  type: 'image',
399
327
  data: base64Data,
400
- mimeType: 'image/png',
328
+ mimeType: dataUri.startsWith('data:image/jpeg') ? 'image/jpeg' : 'image/png',
401
329
  },
402
330
  ],
403
331
  };
@@ -412,7 +340,8 @@ async function handleToolCall(name, args) {
412
340
  };
413
341
  }
414
342
  case 'browser_extract': {
415
- const res = await callBridge('browser.extract', { instruction: args.instruction, selector: args.selector }, 30_000);
343
+ const collection = Object.fromEntries(['mode', 'target', 'collectionId', 'since'].filter((key) => args[key] !== undefined).map((key) => [key, args[key]]));
344
+ const res = await callBridge('browser.extract', withTabId({ ...refPayload(args), instruction: args.instruction, selector: args.selector, ...(args.schema !== undefined ? { schema: args.schema } : {}), ...collection }, args), args.schema ? 120_000 : collection.mode ? 45_000 : 30_000);
416
345
  return {
417
346
  content: [
418
347
  {
@@ -423,7 +352,7 @@ async function handleToolCall(name, args) {
423
352
  };
424
353
  }
425
354
  case 'browser_solve_captcha': {
426
- const res = await callBridge('browser.solve_captcha', { type: args.type === 'auto' ? undefined : args.type }, 30_000);
355
+ const res = await callBridge('browser.solve_captcha', withTabId({ type: args.type === 'auto' ? undefined : args.type }, args), 30_000);
427
356
  return {
428
357
  content: [
429
358
  {
@@ -435,14 +364,15 @@ async function handleToolCall(name, args) {
435
364
  }
436
365
  case 'weboperator_execute_goal': {
437
366
  const taskTimeout = Number(args.timeoutMs || 120_000);
438
- const startRes = await callBridge('tasks.start', { goal: args.goal, timeoutMs: taskTimeout }, 30_000);
439
- const taskId = startRes && startRes.id;
367
+ const startRes = await callBridge('tasks.start', withTabId({ ...args, goal: args.goal, timeoutMs: taskTimeout, wait: false }, args), 30_000);
368
+ const taskId = startRes && (startRes.taskId || startRes.id);
369
+ if (args.wait === false) return { content: [{ type: 'text', text: JSON.stringify({ ...startRes, taskId }, null, 2) }] };
440
370
  let finalTask = startRes;
441
371
  if (taskId) {
442
372
  finalTask = await callBridge('tasks.wait', { id: taskId, timeoutMs: taskTimeout }, taskTimeout + 10_000);
443
373
  }
444
374
  const formatted = formatTaskResultForAgent(finalTask || startRes);
445
- const responseText = formatted.answer || JSON.stringify(formatted, null, 2);
375
+ const responseText = JSON.stringify(formatted, null, 2);
446
376
  return {
447
377
  content: [
448
378
  {
@@ -452,8 +382,13 @@ async function handleToolCall(name, args) {
452
382
  ],
453
383
  };
454
384
  }
455
- default:
456
- throw new Error(`Unknown tool: ${name}`);
385
+ default: {
386
+ if (!TOOL_TYPES[name]) throw new Error(`Unknown tool: ${name}`);
387
+ const timeout = Math.max(30000, Number(args.timeoutMs ?? (name === 'browser_download' ? 120000 : 0)) + 10000);
388
+ const res = await callBridge(TOOL_TYPES[name], args, timeout);
389
+ assertActionSucceeded(res);
390
+ return { content: [{ type: 'text', text: typeof res === 'string' ? res : JSON.stringify(res, null, 2) }] };
391
+ }
457
392
  }
458
393
  }
459
394
 
@@ -507,6 +442,7 @@ function formatTaskResultForAgent(task) {
507
442
 
508
443
  return {
509
444
  ok: task.status === 'done',
445
+ taskId: task.taskId || task.id,
510
446
  status: task.status,
511
447
  goal: task.goal,
512
448
  answer,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openclaw-weboperator",
3
- "version": "1.4.0",
3
+ "version": "1.6.0",
4
4
  "description": "OpenClaw agent toolset configuration for WebOperator",
5
5
  "gateway": {
6
6
  "url": "http://127.0.0.1:8765/mcp",
@@ -18,6 +18,41 @@
18
18
  "browser_screenshot",
19
19
  "browser_extract",
20
20
  "browser_solve_captcha",
21
- "weboperator_execute_goal"
21
+ "weboperator_execute_goal",
22
+ "browser_eval",
23
+ "browser_wait",
24
+ "tabs_list",
25
+ "tabs_current",
26
+ "tabs_open",
27
+ "tabs_activate",
28
+ "tabs_close",
29
+ "agent_task_start",
30
+ "agent_task_list",
31
+ "agent_task_get",
32
+ "agent_task_stop",
33
+ "agent_task_confirm",
34
+ "agent_task_pause",
35
+ "agent_task_resume",
36
+ "agent_task_wait",
37
+ "browser_image",
38
+ "browser_select_option",
39
+ "browser_handle_dialog",
40
+ "network_list",
41
+ "network_get",
42
+ "network_clear",
43
+ "console_list",
44
+ "cookies_get",
45
+ "cookies_set",
46
+ "storage_get",
47
+ "storage_set",
48
+ "browser_upload_file",
49
+ "browser_download",
50
+ "downloads_list",
51
+ "downloads_read",
52
+ "browser_read",
53
+ "browser_hover",
54
+ "browser_drag",
55
+ "clipboard_read",
56
+ "clipboard_write"
22
57
  ]
23
58
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "weboperator-mcp",
3
- "version": "1.5.0",
4
- "mcpName": "io.github.kazkozdev/weboperator",
3
+ "version": "1.6.0",
4
+ "mcpName": "io.github.KazKozDev/weboperator",
5
5
  "description": "Hands your live Chrome tab to any MCP client — snapshot, navigate, click, type, extract.",
6
6
  "keywords": [
7
7
  "mcp",
@@ -29,6 +29,8 @@
29
29
  },
30
30
  "files": [
31
31
  "mcp-server.js",
32
+ "tools.js",
33
+ "local-files.js",
32
34
  "bridge.js",
33
35
  "agent-client.js",
34
36
  "native-host.sh",
package/tools.js ADDED
@@ -0,0 +1,294 @@
1
+ const TAB_ID_PROP = {
2
+ tabId: {
3
+ type: 'number',
4
+ description: 'Optional browser tab id to act on instead of the focused tab.',
5
+ },
6
+ };
7
+ const REF_PROP = {
8
+ ref: {
9
+ type: 'string',
10
+ description: 'Element reference from browser_snapshot (e.g. "@e12"). Preferred over index; also used to target a scroll container.',
11
+ },
12
+ };
13
+
14
+ const TOOLS = [
15
+ {
16
+ name: 'browser_snapshot',
17
+ description: 'Capture the structured accessibility tree and numbered interactive elements (buttons, inputs, links) from a browser tab (the focused one unless tabId is given).',
18
+ inputSchema: {
19
+ type: 'object',
20
+ properties: {
21
+ ...TAB_ID_PROP,
22
+ },
23
+ additionalProperties: false,
24
+ },
25
+ },
26
+ {
27
+ name: 'browser_navigate',
28
+ description: 'Navigate a browser tab (the focused one unless tabId is given) to a specified URL.',
29
+ inputSchema: {
30
+ type: 'object',
31
+ properties: {
32
+ ...TAB_ID_PROP,
33
+ url: {
34
+ type: 'string',
35
+ description: 'The URL to navigate to (e.g. "https://google.com").',
36
+ },
37
+ },
38
+ required: ['url'],
39
+ additionalProperties: false,
40
+ },
41
+ },
42
+ {
43
+ name: 'browser_click',
44
+ description: 'Click an element on the webpage by its snapshot ref (e.g. "@e12"), numeric index, or CSS selector.',
45
+ inputSchema: {
46
+ type: 'object',
47
+ properties: {
48
+ ...TAB_ID_PROP,
49
+ ...REF_PROP,
50
+ index: {
51
+ type: 'number',
52
+ description: 'The numeric index of the interactive element from the snapshot (mapped to ref "@e<index>").',
53
+ },
54
+ selector: {
55
+ type: 'string',
56
+ description: 'Alternative CSS selector of the element to click.',
57
+ },
58
+ },
59
+ additionalProperties: false,
60
+ },
61
+ },
62
+ {
63
+ name: 'browser_type',
64
+ description: 'Type text into an input field by snapshot ref, element index or CSS selector.',
65
+ inputSchema: {
66
+ type: 'object',
67
+ properties: {
68
+ ...TAB_ID_PROP,
69
+ ...REF_PROP,
70
+ index: {
71
+ type: 'number',
72
+ description: 'The numeric index of the input element from the snapshot (mapped to ref "@e<index>").',
73
+ },
74
+ selector: {
75
+ type: 'string',
76
+ description: 'Alternative CSS selector of the input element.',
77
+ },
78
+ text: {
79
+ type: 'string',
80
+ description: 'The text to type into the field.',
81
+ },
82
+ clear: {
83
+ type: 'boolean',
84
+ description: 'true replaces the field content, false appends to it (default: replace).',
85
+ },
86
+ },
87
+ required: ['text'],
88
+ additionalProperties: false,
89
+ },
90
+ },
91
+ {
92
+ name: 'browser_press',
93
+ description: 'Press a keyboard key on a webpage (e.g. "Enter", "Tab", "Escape", "ArrowDown", "Backspace").',
94
+ inputSchema: {
95
+ type: 'object',
96
+ properties: {
97
+ ...TAB_ID_PROP,
98
+ ...REF_PROP,
99
+ key: {
100
+ type: 'string',
101
+ description: 'The key to press (e.g. "Enter", "Tab", "Escape").',
102
+ },
103
+ modifiers: {
104
+ type: 'string',
105
+ description: 'Optional key modifiers, e.g. "Control+Shift".',
106
+ },
107
+ },
108
+ required: ['key'],
109
+ additionalProperties: false,
110
+ },
111
+ },
112
+ {
113
+ name: 'browser_scroll',
114
+ description: 'Scroll a page or an inner scroll container. Pass ref to scroll a specific container (e.g. a virtualized message list) instead of the window.',
115
+ inputSchema: {
116
+ type: 'object',
117
+ properties: {
118
+ ...TAB_ID_PROP,
119
+ ...REF_PROP,
120
+ direction: {
121
+ type: 'string',
122
+ enum: ['down', 'up', 'top', 'bottom'],
123
+ description: 'Direction to scroll (default: "down").',
124
+ },
125
+ amount: {
126
+ type: 'number',
127
+ description: 'Number of pixels to scroll (default: 500).',
128
+ },
129
+ },
130
+ additionalProperties: false,
131
+ },
132
+ },
133
+ {
134
+ name: 'browser_screenshot',
135
+ description: 'Capture a visual PNG screenshot of a browser tab (the focused one unless tabId is given).',
136
+ inputSchema: {
137
+ type: 'object',
138
+ properties: {
139
+ ...TAB_ID_PROP,
140
+ },
141
+ additionalProperties: false,
142
+ },
143
+ },
144
+ {
145
+ name: 'browser_extract',
146
+ description: 'Extract text or structured data from the webpage according to an extraction instruction.',
147
+ inputSchema: {
148
+ type: 'object',
149
+ properties: {
150
+ ...TAB_ID_PROP,
151
+ ...REF_PROP,
152
+ instruction: {
153
+ type: 'string',
154
+ description: 'Extraction guidance or prompt (e.g. "Extract all product prices and titles").',
155
+ },
156
+ selector: {
157
+ type: 'string',
158
+ description: 'Optional CSS selector to scope extraction.',
159
+ },
160
+ },
161
+ additionalProperties: false,
162
+ },
163
+ },
164
+ {
165
+ name: 'browser_solve_captcha',
166
+ description: 'Attempt to detect and automatically solve or click Cloudflare Turnstile, reCAPTCHA, hCaptcha, slider puzzle, or visual text challenges in the active tab.',
167
+ inputSchema: {
168
+ type: 'object',
169
+ properties: {
170
+ ...TAB_ID_PROP,
171
+ type: {
172
+ type: 'string',
173
+ enum: ['cloudflare', 'recaptcha', 'hcaptcha', 'slider', 'image', 'audio', 'press_and_hold', 'pow', 'auto'],
174
+ description: 'Optional captcha type to target (default: auto).',
175
+ },
176
+ },
177
+ additionalProperties: false,
178
+ },
179
+ },
180
+ {
181
+ name: 'weboperator_execute_goal',
182
+ description: 'Execute an autonomous browser goal end-to-end using WebOperator multi-step planner.',
183
+ inputSchema: {
184
+ type: 'object',
185
+ properties: {
186
+ ...TAB_ID_PROP,
187
+ goal: {
188
+ type: 'string',
189
+ description: 'Natural language goal for the agent to achieve (e.g. "Find cheapest flight from Paris to Rome on Kayak").',
190
+ },
191
+ timeoutMs: {
192
+ type: 'number',
193
+ description: 'Maximum timeout in milliseconds (default: 120000).',
194
+ },
195
+ },
196
+ required: ['goal'],
197
+ additionalProperties: false,
198
+ },
199
+ },
200
+ ];
201
+
202
+ const TIMEOUT = { type: 'integer', minimum: 0, maximum: 120000 };
203
+ const TASK_ID = { id: { type: 'string', minLength: 1 } };
204
+ const P0_TOOLS = [
205
+ ['browser_eval', 'browser.eval', 'Evaluate JavaScript in the page main world. Nonzero frameId targets that Chrome frame when available to CDP.', {
206
+ ...TAB_ID_PROP, expression: { type: 'string', minLength: 1 }, returnByValue: { type: 'boolean' }, awaitPromise: { type: 'boolean' },
207
+ timeoutMs: { ...TIMEOUT, minimum: 1 }, frameId: { type: 'integer', minimum: 0 },
208
+ }, ['expression']],
209
+ ['browser_wait', 'browser.wait', 'Wait for a condition. urlPattern is a URL substring; network_idle observes fewer than 2 requests for 500ms, with an explicit DOM quiet fallback if CDP is unavailable.', {
210
+ ...TAB_ID_PROP, ...REF_PROP, until: { type: 'string', enum: ['element', 'text', 'url', 'network_idle', 'load', 'timeout'] },
211
+ selector: { type: 'string' }, text: { type: 'string' }, urlPattern: { type: 'string' },
212
+ timeoutMs: TIMEOUT, pollMs: { type: 'integer', minimum: 10, maximum: 1000 }, visible: { type: 'boolean' },
213
+ }, ['until']],
214
+ ['tabs_list', 'tabs.list', 'List browser tabs with ids, titles, URLs and window ids.', {}, []],
215
+ ['tabs_current', 'tabs.current', 'Return the focused browser tab id.', {}, []],
216
+ ['tabs_open', 'tabs.open', 'Open a browser tab.', { url: { type: 'string', minLength: 1 }, active: { type: 'boolean' }, windowId: { type: 'integer', minimum: 1 } }, ['url']],
217
+ ['tabs_activate', 'tabs.activate', 'Activate a tab and focus its window.', TAB_ID_PROP, ['tabId']],
218
+ ['tabs_close', 'tabs.close', 'Close specified tabs, reporting individual errors.', { tabIds: { type: 'array', minItems: 1, items: { type: 'integer', minimum: 1 } } }, ['tabIds']],
219
+ ['agent_task_start', 'tasks.start', 'Start a browser agent task; returns taskId immediately unless wait=true.', {
220
+ ...TAB_ID_PROP, goal: { type: 'string', minLength: 1 }, startUrl: { type: 'string' }, autoConfirm: { type: 'boolean' }, wait: { type: 'boolean' }, timeoutMs: { ...TIMEOUT, maximum: 600000 },
221
+ }, ['goal']],
222
+ ['agent_task_list', 'tasks.list', 'List recent agent tasks.', { limit: { type: 'integer', minimum: 1, maximum: 1000 } }, []],
223
+ ['agent_task_get', 'tasks.get', 'Read a task and its recorded steps.', TASK_ID, ['id']],
224
+ ['agent_task_stop', 'tasks.stop', 'Request cooperative cancellation; an in-flight model call may finish first.', TASK_ID, ['id']],
225
+ ['agent_task_confirm', 'tasks.confirm', 'Approve or reject a task pending confirmation.', { ...TASK_ID, approve: { type: 'boolean' }, allow: { type: 'boolean', description: 'Legacy alias for approve.' } }, ['id']],
226
+ ['agent_task_pause', 'tasks.pause', 'Request cooperative pause at the next agent checkpoint.', TASK_ID, ['id']],
227
+ ['agent_task_resume', 'tasks.resume', 'Resume a cooperatively paused task.', TASK_ID, ['id']],
228
+ ['agent_task_wait', 'tasks.wait', 'Wait for a task to finish, or return its current state at timeout.', { ...TASK_ID, timeoutMs: { ...TIMEOUT, maximum: 600000 } }, ['id']],
229
+ ];
230
+ for (const [name, , description, properties, required] of P0_TOOLS) {
231
+ TOOLS.push({ name, description, inputSchema: { type: 'object', properties, required, additionalProperties: false } });
232
+ }
233
+ const goal = TOOLS.find((tool) => tool.name === 'weboperator_execute_goal');
234
+ Object.assign(goal.inputSchema.properties, {
235
+ wait: { type: 'boolean', description: 'false returns taskId immediately; default true.' },
236
+ startUrl: { type: 'string' }, autoConfirm: { type: 'boolean' },
237
+ });
238
+ const TOOL_TYPES = Object.fromEntries(TOOLS.map((tool) => [tool.name, P0_TOOLS.find(([name]) => name === tool.name)?.[1] ?? tool.name.replace('browser_', 'browser.')]));
239
+
240
+ TOOLS.find((tool) => tool.name === 'agent_task_confirm').inputSchema.anyOf = [{ required: ['approve'] }, { required: ['allow'] }];
241
+ Object.assign(TOOLS.find((tool) => tool.name === 'browser_scroll').inputSchema.properties, {
242
+ to: { type: 'string', enum: ['element'] },
243
+ block: { type: 'string', enum: ['start', 'center', 'end', 'nearest'] },
244
+ });
245
+
246
+ const EXTRA_TOOLS = [
247
+ ['browser_image', 'browser.image', 'Read an image by snapshot ref, returning its bytes as MCP image content.', { ...REF_PROP }, ['ref']],
248
+ ['browser_select_option', 'browser.select_option', 'Select an option in a native HTML select by value or label.', { ...REF_PROP, selector: { type: 'string' }, value: { type: 'string' } }, ['value']],
249
+ ['browser_handle_dialog', 'browser.handle_dialog', 'Call action=status before triggering alert/confirm/prompt to start observing dialogs. Then explicitly accept or dismiss a pending dialog. Does not handle native file pickers or browser security prompts.', { action: { type: 'string', enum: ['status', 'accept', 'dismiss'] }, promptText: { type: 'string', maxLength: 10000 } }, ['action']],
250
+ ['network_list', 'network.list', 'Start persistent capture for this tab and list captured XHR/fetch/document requests. Call before navigation to include initial traffic.', { sinceMs: { type: 'integer', minimum: 0 }, urlPattern: { type: 'string' }, type: { type: 'string', enum: ['xhr', 'fetch', 'document'] }, limit: { type: 'integer', minimum: 1, maximum: 500 } }, []],
251
+ ['network_get', 'network.get', 'Read a captured response body (up to 5 MiB); request ids are scoped to tabId.', { requestId: { type: 'string', minLength: 1 } }, ['requestId']],
252
+ ['network_clear', 'network.clear', 'Start capture and clear the tab request buffer.', {}, []],
253
+ ['console_list', 'console.list', 'Start persistent console/error capture and list recent entries. Earlier page console history may be unavailable.', { sinceMs: { type: 'integer', minimum: 0 }, level: { type: 'string', enum: ['error', 'warn', 'log', 'all'] }, limit: { type: 'integer', minimum: 1, maximum: 500 } }, []],
254
+ ['cookies_get', 'cookies.get', 'Read cookies via the existing debugger permission, filtered by domain or URL.', { domain: { type: 'string' }, url: { type: 'string' } }, []],
255
+ ['cookies_set', 'cookies.set', 'Set a cookie for an HTTP(S) URL via the existing debugger permission.', { url: { type: 'string' }, name: { type: 'string' }, value: { type: 'string' }, domain: { type: 'string' }, path: { type: 'string' }, secure: { type: 'boolean' }, httpOnly: { type: 'boolean' }, sameSite: { type: 'string', enum: ['Strict', 'Lax', 'None'] }, expires: { type: 'number' } }, ['url', 'name', 'value']],
256
+ ['storage_get', 'storage.get', 'Read local/session storage from the page origin.', { kind: { type: 'string', enum: ['local', 'session'] }, keys: { type: 'array', items: { type: 'string' } }, ...REF_PROP }, ['kind']],
257
+ ['storage_set', 'storage.set', 'Write string values to page local/session storage.', { kind: { type: 'string', enum: ['local', 'session'] }, items: { type: 'object', additionalProperties: { type: 'string' } }, ...REF_PROP }, ['kind', 'items']],
258
+ ['browser_upload_file', 'browser.upload_file', 'Select an existing local file in a file input. Native host validates an absolute regular-file path and size <=40 MiB.', { ...REF_PROP, path: { type: 'string', minLength: 1 } }, ['ref', 'path']],
259
+ ['browser_download', 'browser.download', 'Download a URL and wait for completion.', { url: { type: 'string', minLength: 1 }, filename: { type: 'string' }, saveAs: { type: 'boolean' }, timeoutMs: { type: 'integer', minimum: 1, maximum: 300000 } }, ['url']],
260
+ ['downloads_list', 'downloads.list', 'List browser downloads.', { sinceMs: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 500 } }, []],
261
+ ['downloads_read', 'downloads.read', 'Read a completed local download by Chrome download id, without refetching its URL.', { downloadId: { type: 'integer', minimum: 1 }, maxBytes: { type: 'integer', minimum: 1, maximum: 20000000 } }, ['downloadId']],
262
+ ['browser_read', 'browser.read', 'Read a page subtree as text or Markdown, preserving headings and links.', { ...REF_PROP, selector: { type: 'string' }, format: { type: 'string', enum: ['text', 'markdown'] }, maxChars: { type: 'integer', minimum: 1, maximum: 200000 } }, []],
263
+ ['browser_hover', 'browser.hover', 'Move a real mouse pointer to an element, triggering hover menus.', { ...REF_PROP }, ['ref']],
264
+ ['browser_drag', 'browser.drag', 'Drag between two snapshot refs using real mouse events.', { from: { type: 'string' }, to: { type: 'string' }, steps: { type: 'integer', minimum: 1, maximum: 100 }, modifiers: { type: 'string' } }, ['from', 'to']],
265
+ ['clipboard_read', 'clipboard.read', 'Read system clipboard text (native host on macOS; page context elsewhere).', {}, []],
266
+ ['clipboard_write', 'clipboard.write', 'Write system clipboard text (native host on macOS; page context elsewhere).', { text: { type: 'string' } }, ['text']],
267
+ ];
268
+ for (const [name, type, description, properties, required] of EXTRA_TOOLS) {
269
+ TOOLS.push({ name, description, inputSchema: { type: 'object', properties: { ...TAB_ID_PROP, ...properties }, required, additionalProperties: false } });
270
+ TOOL_TYPES[name] = type;
271
+ }
272
+ const extend = (name, properties) => Object.assign(TOOLS.find((tool) => tool.name === name).inputSchema.properties, properties);
273
+ extend('browser_snapshot', {
274
+ allElements: { type: 'boolean' }, maxNodes: { type: 'integer', minimum: 1, maximum: 10000 }, refPrefix: { type: 'string', maxLength: 32 },
275
+ roles: { type: 'array', items: { type: 'string' } }, query: { type: 'string' }, text: { type: 'boolean' }, diff: { type: 'boolean' },
276
+ includeImages: { type: 'boolean' }, minImageArea: { type: 'integer', minimum: 0 }, shadow: { type: 'boolean' },
277
+ });
278
+ extend('browser_extract', {
279
+ schema: { type: 'object', description: 'JSON Schema, validated without eval. Unsupported keywords return an explicit error. Extraction uses the configured model.' },
280
+ mode: { type: 'string', enum: ['rows', 'chunk'], description: 'Self-checking collection. "rows" saves list records, follows Next or scrolls the list, rechecks a load that adds nothing, and stops at target or at the total the pager claims. "chunk" reads long text in paragraph-sized chunks and records the section reached. Each call works for up to about 12 s; call again with collectionId until complete is true or stopReason explains the shortfall.' },
281
+ target: { type: 'integer', minimum: 1, maximum: 10000, description: 'With mode="rows": how many records to collect. Without it, one capture of the current list.' },
282
+ collectionId: { type: 'string', pattern: '^[\\w-]{1,64}$', description: 'Returned by the first mode call; pass it to resume the same collection.' },
283
+ since: { type: 'integer', minimum: 0, description: 'Return only rows (or text characters) after this count; pass nextSince from the previous call.' },
284
+ });
285
+ extend('browser_click', { button: { type: 'string', enum: ['left', 'right', 'middle'] }, clickCount: { type: 'integer', minimum: 1, maximum: 3 }, modifiers: { type: 'string' } });
286
+ extend('browser_screenshot', { ...REF_PROP, fullPage: { type: 'boolean' }, format: { type: 'string', enum: ['png', 'jpeg'] }, quality: { type: 'integer', minimum: 0, maximum: 100 }, saveTo: { type: 'string', description: 'Absolute local output path. Existing files are not overwritten.' } });
287
+
288
+ function imageContent(result) {
289
+ if (!result || typeof result.base64 !== 'string' || !/^image\/(png|jpeg|webp|gif)$/.test(result.mimeType)) throw new Error('Expected a PNG, JPEG, WebP or GIF image from the extension');
290
+ const { base64, ...metadata } = result;
291
+ return [{ type: 'image', data: base64, mimeType: result.mimeType }, { type: 'text', text: JSON.stringify(metadata) }];
292
+ }
293
+
294
+ module.exports = { TOOLS, TOOL_TYPES, imageContent };