Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

feat(mcp): serve the registry as MCP tools over stdio

Shahriar2b2650ec662b
diff --git a/mcp/src/remote-bridge.ts b/mcp/src/remote-bridge.ts
new file mode 100644
index 0000000..c144295
--- /dev/null
+++ b/mcp/src/remote-bridge.ts
@@ -0,0 +1,108 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocket } from 'ws';
+import { failure, type ActionResult } from '@/lib/actions/protocol';
+import type { ToolDescriptor } from '@/lib/actions/manifest';
+import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, SessionSummary } from './control';
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+/**
+ * A `Bridge` backed by the daemon's control socket. Used by the stdio MCP process, which
+ * owns no browser connection of its own — the daemon is the single owner.
+ */
+export class RemoteBridge implements Bridge {
+ private readonly pending = new Map<string, (message: ControlMessage) => void>();
+ private readonly manifestListeners = new Set<() => void>();
+
+ private constructor(
+ private readonly socket: WebSocket,
+ /** Set when this process serves a spawned agent run; tags every invoke with the run id. */
+ private readonly runId?: string,
+ ) {
+ socket.on('message', (raw) => this.receive(String(raw)));
+ }
+
+ static connect(port: number, token: string, runId?: string): Promise<RemoteBridge> {
+ return new Promise((resolve, reject) => {
+ // No Origin header from Node, so the daemon classifies this as a control client.
+ const socket = new WebSocket(`ws://127.0.0.1:${port}/control`, {
+ headers: { authorization: `Bearer ${token}` },
+ });
+ socket.once('open', () => resolve(new RemoteBridge(socket, runId)));
+ socket.once('error', reject);
+ });
+ }
+
+ async describe(): Promise<ToolDescriptor[]> {
+ const reply = await this.request({ id: randomUUID(), op: 'describe' });
+ return reply && 'tools' in reply ? reply.tools : [];
+ }
+
+ async invoke(action: string, input?: unknown): Promise<ActionResult> {
+ const reply = await this.request({ id: randomUUID(), op: 'invoke', action, input, runId: this.runId });
+ if (reply && 'result' in reply) return reply.result;
+ return failure('DAEMON_UNREACHABLE', 'The VoiceLink daemon did not respond');
+ }
+
+ async status(): Promise<BridgeStatus> {
+ const reply = await this.request({ id: randomUUID(), op: 'status' });
+ if (reply && 'status' in reply) return reply.status;
+ throw new Error('The VoiceLink daemon did not respond to a status request');
+ }
+
+ async pair(): Promise<{ code: string; expiresAt: number }> {
+ const reply = await this.request({ id: randomUUID(), op: 'pair' });
+ if (reply && 'code' in reply) return reply;
+ throw new Error('The VoiceLink daemon did not issue a pairing code');
+ }
+
+ async sessions(): Promise<SessionSummary[]> {
+ const reply = await this.request({ id: randomUUID(), op: 'sessions' });
+ return reply && 'sessions' in reply ? reply.sessions : [];
+ }
+
+ async revoke(origin?: string): Promise<number> {
+ const reply = await this.request({ id: randomUUID(), op: 'revoke', origin });
+ return reply && 'revoked' in reply ? reply.revoked : 0;
+ }
+
+ onManifestChanged(listener: () => void): void {
+ this.manifestListeners.add(listener);
+ }
+
+ async close(): Promise<void> {
+ this.socket.close(1000, 'client exiting');
+ }
+
+ private request(request: ControlRequest): Promise<ControlMessage | null> {
+ if (this.socket.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => {
+ this.pending.delete(request.id);
+ resolve(null);
+ }, REQUEST_TIMEOUT_MS);
+ this.pending.set(request.id, (message) => {
+ clearTimeout(timer);
+ resolve(message);
+ });
+ this.socket.send(JSON.stringify(request));
+ });
+ }
+
+ private receive(raw: string): void {
+ let message: ControlMessage;
+ try {
+ message = JSON.parse(raw) as ControlMessage;
+ } catch {
+ return;
+ }
+ if ('event' in message) {
+ if (message.event === 'manifest-changed') for (const listener of this.manifestListeners) listener();
+ return;
+ }
+ const settle = this.pending.get(message.id);
+ if (!settle) return;
+ this.pending.delete(message.id);
+ settle(message);
+ }
+}
diff --git a/mcp/src/screenshots.ts b/mcp/src/screenshots.ts
new file mode 100644
index 0000000..e4ac4a6
--- /dev/null
+++ b/mcp/src/screenshots.ts
@@ -0,0 +1,66 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+import { readAgentConfig } from './agent/config';
+
+/**
+ * Save a base64 `data:` image (produced by the `page.screenshot` capture in the background) to
+ * disk. Only the daemon can do this — the extension is filesystem-sandboxed. The directory is
+ * `config.screenshotDir` (from `~/.voicelink/config.json`) or, by default, the user-facing
+ * `~/voicelink/screenshot`. Mirrors the mkdir/write pattern in `lockfile.ts`.
+ */
+export function saveScreenshot(dataUrl: string, opts: { filename?: string } = {}): string {
+ const { mime, bytes } = parseDataUrl(dataUrl);
+ const dir = resolveDir();
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+ const ext = extensionFor(mime);
+ // A random suffix keeps two auto-named saves in the same second from clobbering each other; an
+ // explicit filename is written as given (the caller owns that path and may mean to overwrite).
+ const name = opts.filename ? sanitize(opts.filename, ext) : `screenshot-${stamp()}-${randomBytes(3).toString('hex')}.${ext}`;
+ const target = join(dir, name);
+ // Screenshots can capture logged-in pages; keep them owner-only, and re-assert since writeFileSync
+ // only applies `mode` when creating the file (mirrors lockfile.ts / auth-store.ts).
+ writeFileSync(target, bytes, { mode: 0o600 });
+ chmodSync(target, 0o600);
+ return target;
+}
+
+function resolveDir(): string {
+ const configured = readAgentConfig().screenshotDir;
+ if (typeof configured === 'string' && configured.trim()) return expandHome(configured.trim());
+ return join(homedir(), 'voicelink', 'screenshot');
+}
+
+function expandHome(p: string): string {
+ if (p === '~') return homedir();
+ if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+ return isAbsolute(p) ? p : join(homedir(), p);
+}
+
+function parseDataUrl(dataUrl: string): { mime: string; bytes: Buffer } {
+ const match = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl);
+ if (!match) throw new Error('screenshot result was not a base64 data URL');
+ return { mime: match[1], bytes: Buffer.from(match[2], 'base64') };
+}
+
+function extensionFor(mime: string): string {
+ if (mime === 'image/jpeg') return 'jpg';
+ if (mime === 'image/webp') return 'webp';
+ return 'png';
+}
+
+/** Keep only a safe basename with the right extension — no directory traversal, no odd chars. */
+function sanitize(filename: string, ext: string): string {
+ let name = basename(filename).replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+ if (!name) name = `screenshot-${stamp()}`;
+ return name.toLowerCase().endsWith(`.${ext}`) ? name : `${name}.${ext}`;
+}
+
+/** yyyymmdd-hhmmss in local time; unique enough per capture and sorts chronologically. */
+function stamp(): string {
+ const d = new Date();
+ const p = (n: number) => String(n).padStart(2, '0');
+ return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
diff --git a/mcp/src/server.ts b/mcp/src/server.ts
new file mode 100644
index 0000000..33cf9b5
--- /dev/null
+++ b/mcp/src/server.ts
@@ -0,0 +1,190 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+ CallToolRequestSchema,
+ ListResourcesRequestSchema,
+ ListToolsRequestSchema,
+ ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { ActionResult } from '@/lib/actions/protocol';
+import { actionNameFor, assertToolNamesRoundTrip, toolNameFor } from '@/lib/actions/tool-names';
+import type { Bridge } from './control';
+import { log } from './log';
+
+const STATUS_TOOL = 'voicelink_status';
+const SCREENSHOT_TOOL = 'page_screenshot';
+
+const RESOURCES = [
+ {
+ uri: 'voicelink://page/current',
+ name: 'Active page snapshot',
+ description: 'Full page.getPageInfo snapshot of the active tab: metadata, layout tree, headings, interactive inventory.',
+ mimeType: 'application/json',
+ },
+ {
+ uri: 'voicelink://page/diagram',
+ name: 'Active page layout diagram',
+ description: 'Text diagram of the active tab’s landmark regions — the cheapest useful view of a page.',
+ mimeType: 'text/plain',
+ },
+ {
+ uri: 'voicelink://page/text',
+ name: 'Active page text',
+ description: 'Rendered text of the active tab.',
+ mimeType: 'text/plain',
+ },
+] as const;
+
+export function createMcpServer(bridge: Bridge, version: string): Server {
+ const server = new Server(
+ { name: 'voicelink', version },
+ {
+ capabilities: { tools: { listChanged: true }, resources: {} },
+ instructions:
+ 'Controls the user’s browser through the VoiceLink extension. Tools act on the active tab. ' +
+ 'Start with page_getPageInfo (or the voicelink://page/diagram resource) to learn what is on the page and ' +
+ 'get stable selectors, then target elements by selector or visible text.',
+ },
+ );
+
+ server.setRequestHandler(ListToolsRequestSchema, async () => {
+ const actions = await bridge.describe();
+ assertToolNamesRoundTrip(actions.map((action) => action.name));
+ return {
+ tools: [
+ ...actions.map((action) => ({
+ name: toolNameFor(action.name),
+ description: action.description,
+ inputSchema: action.inputSchema as { type: 'object' },
+ })),
+ {
+ name: STATUS_TOOL,
+ description:
+ 'Report whether the VoiceLink browser extension is connected, its version, and the active tab. Use this first if a page tool fails.',
+ inputSchema: { type: 'object' as const, properties: {}, additionalProperties: false },
+ },
+ ],
+ };
+ });
+
+ server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+ if (params.name === STATUS_TOOL) return render(await status(bridge));
+ const result = await bridge.invoke(actionNameFor(params.name), params.arguments ?? {});
+ // A screenshot comes back as an image the model can actually see, not JSON.
+ return params.name === SCREENSHOT_TOOL ? renderScreenshot(result) : render(result);
+ });
+
+ server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [...RESOURCES] }));
+
+ server.setRequestHandler(ReadResourceRequestSchema, async ({ params }) => {
+ const { uri } = params;
+ const resource = RESOURCES.find((candidate) => candidate.uri === uri);
+ if (!resource) throw new Error(`Unknown resource: ${uri}`);
+
+ if (uri === 'voicelink://page/text') {
+ const result = await bridge.invoke('page.extractText', { format: 'text' });
+ return text(uri, resource.mimeType, unwrap(result, (data) => String((data as { content: string }).content)));
+ }
+ const result = await bridge.invoke('page.getPageInfo', { maxPerKind: uri === 'voicelink://page/diagram' ? 1 : 30 });
+ if (uri === 'voicelink://page/diagram') {
+ return text(uri, resource.mimeType, unwrap(result, (data) => String((data as PageInfo).layout.diagram)));
+ }
+ return text(uri, resource.mimeType, unwrap(result, (data) => JSON.stringify(data, null, 2)));
+ });
+
+ // The connected extension may ship a different registry than this build; re-advertise if so.
+ bridge.onManifestChanged(() => {
+ log('manifest changed; notifying MCP client');
+ void server.sendToolListChanged().catch((error) => log('failed to notify tool list change', error));
+ });
+
+ return server;
+}
+
+interface PageInfo {
+ document: { url: string; title: string };
+ layout: { diagram: string };
+}
+
+async function status(bridge: Bridge) {
+ const base = await bridge.status();
+ if (!base.connected) {
+ return {
+ ok: true as const,
+ data: { ...base, activeTab: null, hint: 'Open your browser with the VoiceLink extension loaded.' },
+ };
+ }
+ // getPageInfo is the cheapest way to see the active tab without a `tabs` permission.
+ const page = await bridge.invoke('page.getPageInfo', { maxPerKind: 1 });
+ if (page.ok) return { ok: true as const, data: { ...base, activeTab: (page.data as PageInfo).document } };
+ return {
+ ok: true as const,
+ data: {
+ ...base,
+ activeTab: null,
+ // Almost always a page that hosts no content script; page_navigate still works there.
+ hint: `Cannot read the active tab (${page.error.code}). Use page_navigate to open an http(s) page first.`,
+ },
+ };
+}
+
+/**
+ * Screenshots return an MCP image content block so the model — an external client or the spawned
+ * agent, both of which pass through here — can look at the pixels, plus a text line with the
+ * dimensions and where it was saved. The base64 is never dumped as text.
+ */
+function renderScreenshot(result: ActionResult) {
+ if (!result.ok) return render(result);
+ const data = result.data as {
+ dataUrl?: string;
+ format?: string;
+ width?: number;
+ height?: number;
+ savedTo?: string;
+ saveError?: string;
+ truncated?: boolean;
+ };
+ if (typeof data.dataUrl !== 'string') return render(result);
+
+ const [mimeType, base64] = splitDataUrl(data.dataUrl);
+ const notes = [
+ `Captured ${data.width}×${data.height} ${data.format ?? 'image'}.`,
+ data.truncated ? 'The page was taller than the capture limit, so the bottom is cut off.' : '',
+ data.savedTo ? `Saved to ${data.savedTo}.` : '',
+ data.saveError ? `Requested save failed: ${data.saveError}.` : '',
+ ]
+ .filter(Boolean)
+ .join(' ');
+
+ return {
+ content: [
+ { type: 'image' as const, data: base64, mimeType },
+ { type: 'text' as const, text: notes },
+ ],
+ };
+}
+
+/** Split a `data:<mime>;base64,<payload>` URL into its parts for an MCP image content block. */
+function splitDataUrl(dataUrl: string): [mimeType: string, base64: string] {
+ const match = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl);
+ return match ? [match[1], match[2]] : ['image/png', ''];
+}
+
+/** Failures come back as tool errors so the model can adapt (retry a target, open a page) rather than abort. */
+function render(result: ActionResult) {
+ if (result.ok) {
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }] };
+ }
+ return {
+ isError: true,
+ content: [{ type: 'text' as const, text: `${result.error.code}: ${result.error.message}` }],
+ };
+}
+
+function unwrap(result: ActionResult, project: (data: unknown) => string): string {
+ if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
+ return project(result.data);
+}
+
+function text(uri: string, mimeType: string, body: string) {
+ return { contents: [{ uri, mimeType, text: body }] };
+}