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): add the voicelink-mcp CLI
Shahriarf413bc1e69a8
diff --git a/mcp/src/cli.ts b/mcp/src/cli.tsnew file mode 100644index 0000000..36dcc60--- /dev/null+++ b/mcp/src/cli.ts@@ -0,0 +1,193 @@+import { readFileSync } from 'node:fs';+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';+import { describeActions } from '@/lib/actions/registry';+import { assertToolNamesRoundTrip, toolNameFor } from '@/lib/actions/tool-names';+import { ensureDaemon, probeExisting } from './ensure-daemon';+import { clearLockfile, logPath, readLockfile } from './lockfile';+import { log } from './log';+import { RemoteBridge } from './remote-bridge';+import { createMcpServer } from './server';+import pkg from '../package.json';++const USAGE = `voicelink-mcp ${pkg.version} — MCP access to your browser via the VoiceLink extension++ voicelink-mcp serve MCP over stdio (what an MCP client runs)+ voicelink-mcp pair issue a one-time code to type into the extension+ voicelink-mcp sessions list paired browsers+ voicelink-mcp revoke [origin] unpair one browser, or all of them+ voicelink-mcp tools print the bundled tool manifest (no browser needed)+ voicelink-mcp status show daemon and extension connection state+ voicelink-mcp stop stop the background daemon+ voicelink-mcp logs print the daemon log+ voicelink-mcp token print the control token (for MCP clients, not the browser)+ voicelink-mcp --version print the version++The extension connects to nothing until you pair it:+ 1. run "voicelink-mcp pair"+ 2. open the VoiceLink popup, paste the code, press Connect++Register with Claude Code: claude mcp add voicelink -- npx -y @voicelink/mcp+`;++const [command] = process.argv.slice(2);++switch (command) {+ case undefined:+ await serve();+ break;+ case 'pair':+ await pair();+ break;+ case 'sessions':+ await showSessions();+ break;+ case 'revoke':+ await revoke(process.argv[3]);+ break;+ case 'tools':+ printTools();+ break;+ case 'status':+ await showStatus();+ break;+ case 'stop':+ stop();+ break;+ case 'logs':+ showLogs();+ break;+ case 'token':+ printToken();+ break;+ case '--version':+ case '-v':+ console.log(pkg.version);+ break;+ case 'help':+ case '--help':+ case '-h':+ console.log(USAGE);+ break;+ default:+ console.error(`Unknown command "${command}"\n\n${USAGE}`);+ process.exit(1);+}++/** Serve MCP on stdio. Nothing may write to stdout past this point — it is the JSON-RPC stream. */+async function serve(): Promise<void> {+ const lock = await ensureDaemon();+ // Present when the daemon spawned a Claude Code run and that run spawned us: tagging the+ // invocations is what routes them through the run's approval gate and timeline.+ const bridge = await RemoteBridge.connect(lock.port, lock.token, process.env.VOICELINK_AGENT_RUN);+ const server = createMcpServer(bridge, pkg.version);+ await server.connect(new StdioServerTransport());+ log(`stdio MCP server attached to daemon on port ${lock.port}`);++ const shutdown = async () => {+ await bridge.close();+ await server.close();+ process.exit(0);+ };+ for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => void shutdown());+}++/**+ * Print the tool manifest straight from the bundled registry — no daemon, no browser.+ * Also the standing check that no action grew a top-level DOM reference: this bundle is+ * loaded in plain Node, where `document` at module scope would throw on import.+ */+function printTools(): void {+ const actions = describeActions();+ assertToolNamesRoundTrip(actions.map((action) => action.name));+ console.log(+ JSON.stringify(+ actions.map((action) => ({ ...action, name: toolNameFor(action.name), action: action.name })),+ null,+ 2,+ ),+ );+}++async function showStatus(): Promise<void> {+ const lock = await probeExisting();+ if (!lock) {+ console.log('daemon: not running');+ console.log('extension: unknown (start an MCP client, or run a tool, to launch the daemon)');+ return;+ }+ const bridge = await RemoteBridge.connect(lock.port, lock.token);+ const status = await bridge.status();+ await bridge.close();+ console.log(`daemon: running on 127.0.0.1:${status.port} (pid ${lock.pid}, v${status.daemonVersion})`);+ console.log(`extension: ${status.connected ? `connected (v${status.extensionVersion})` : 'not connected'}`);+ console.log(`manifest: ${status.manifestInSync ? 'in sync' : 'DRIFTED — extension and CLI were built from different registries'}`);+ console.log(+ `paired: ${status.pairedBrowsers || 'none'}${status.pairingPending ? ' (a pairing code is outstanding)' : ''}`,+ );+ if (!status.pairedBrowsers) console.log('\nRun "voicelink-mcp pair" to connect your browser.');+}++function stop(): void {+ const lock = readLockfile();+ if (!lock) return console.log('No daemon lockfile; nothing to stop.');+ try {+ process.kill(lock.pid, 'SIGTERM');+ console.log(`Stopped daemon (pid ${lock.pid}).`);+ } catch {+ console.log(`Daemon (pid ${lock.pid}) was not running; clearing the lockfile.`);+ clearLockfile();+ }+}++function showLogs(): void {+ try {+ process.stdout.write(readFileSync(logPath, 'utf8'));+ } catch {+ console.log(`No log at ${logPath} yet.`);+ }+}++function printToken(): void {+ const lock = readLockfile();+ if (!lock) return console.error('No daemon lockfile yet — start the daemon first.');+ console.log(lock.token);+}++/** Issue a one-time code. The daemon must be running to hold it, so start it if needed. */+async function pair(): Promise<void> {+ const bridge = await connect();+ const { code, expiresAt } = await bridge.pair();+ await bridge.close();+ const minutes = Math.round((expiresAt - Date.now()) / 60_000);+ const grouped = `${code.slice(0, 4)}-${code.slice(4)}`;+ console.log(`\n Pairing code: ${grouped}\n`);+ console.log(` Open the VoiceLink popup, paste it, and press Connect.`);+ console.log(` Expires in ${minutes} minutes and works once.\n`);+}++async function showSessions(): Promise<void> {+ const bridge = await connect();+ const sessions = await bridge.sessions();+ await bridge.close();+ if (!sessions.length) {+ return console.log('No paired browsers. Run "voicelink-mcp pair" to add one.');+ }+ for (const session of sessions) {+ console.log(`${session.connected ? '●' : '○'} ${session.origin}`);+ console.log(` extension v${session.extensionVersion}, paired ${session.pairedAt}, last seen ${session.lastSeenAt}`);+ }+}++async function revoke(origin?: string): Promise<void> {+ const bridge = await connect();+ const revoked = await bridge.revoke(origin);+ await bridge.close();+ if (!revoked) return console.log(origin ? `No session for ${origin}.` : 'Nothing to revoke.');+ console.log(`Revoked ${revoked} session(s). Pair again with "voicelink-mcp pair".`);+}++/** Every command that talks to the daemon needs it running; start it if it is not. */+async function connect(): Promise<RemoteBridge> {+ const lock = await ensureDaemon();+ return RemoteBridge.connect(lock.port, lock.token);+}diff --git a/mcp/src/control.ts b/mcp/src/control.tsnew file mode 100644index 0000000..e6bf842--- /dev/null+++ b/mcp/src/control.ts@@ -0,0 +1,54 @@+import type { ActionResult } from '@/lib/actions/protocol';+import type { ToolDescriptor } from '@/lib/actions/manifest';++/** What the daemon knows about its own link to the browser. */+export interface BridgeStatus {+ connected: boolean;+ daemonVersion: string;+ protocolVersion: number;+ port: number;+ manifestInSync: boolean;+ extensionVersion?: string;+ /** How many browsers are paired, and whether a pairing code is currently outstanding. */+ pairedBrowsers: number;+ pairingPending: boolean;+}++/** A paired browser, as reported to the CLI. */+export interface SessionSummary {+ origin: string;+ extensionVersion: string;+ pairedAt: string;+ lastSeenAt: string;+ connected: boolean;+}++/** CLI → daemon, over the control WebSocket. */+export type ControlRequest =+ | { id: string; op: 'describe' }+ | { id: string; op: 'status' }+ /** `runId` marks an invocation made on an agent run's behalf — it gets gated and reported. */+ | { id: string; op: 'invoke'; action: string; input?: unknown; runId?: string }+ | { id: string; op: 'pair' }+ | { id: string; op: 'sessions' }+ | { id: string; op: 'revoke'; origin?: string };++/** daemon → CLI. `event` frames are unsolicited. */+export type ControlMessage =+ | { id: string; op: 'describe'; tools: ToolDescriptor[] }+ | { id: string; op: 'status'; status: BridgeStatus }+ | { id: string; op: 'invoke'; result: ActionResult }+ | { id: string; op: 'pair'; code: string; expiresAt: number }+ | { id: string; op: 'sessions'; sessions: SessionSummary[] }+ | { id: string; op: 'revoke'; revoked: number }+ | { event: 'manifest-changed' };++/** The daemon-side view of the browser, however it is reached. */+export interface Bridge {+ describe(): Promise<ToolDescriptor[]>;+ invoke(action: string, input?: unknown): Promise<ActionResult>;+ status(): Promise<BridgeStatus>;+ /** Fires when the connected extension's manifest differs from the bundled one. */+ onManifestChanged(listener: () => void): void;+ close(): Promise<void>;+}