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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
feat(mcp): serve the registry as MCP tools over stdio
Shahriar2b2650ec662b
diff --git a/mcp/src/remote-bridge.ts b/mcp/src/remote-bridge.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 }] };+}