@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/mcp/helpers.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * src/mcp/helpers.ts — the high-level tools composed SERVER-SIDE from executor
+ * primitives. They never touch the wire directly: `extract_links` and
+ * `read_as_markdown` read via primitives; `fill_form` sequences fill+click.
+ * (Only `download_file` is privileged and lives on the executor.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLinks = extractLinks;
+exports.readAsMarkdown = readAsMarkdown;
+exports.fillForm = fillForm;
+const markdown_extract_1 = require("./markdown-extract");
+/**
+ * Collect anchors from the page (or a subtree). Implemented as a single page
+ * eval so it is one round-trip; falls back to parsing getHtml if eval is denied.
+ */
+async function extractLinks(ex, args) {
+    const root = args.selector ? JSON.stringify(args.selector) : 'null';
+    const expr = `(() => {
+    const root = ${root} ? document.querySelector(${root}) : document;
+    if (!root) return [];
+    const here = location.origin;
+    return [...root.querySelectorAll('a[href]')].map(a => ({
+      href: a.href, text: (a.textContent || '').trim().slice(0, 200),
+    })).filter(l => l.href && (${args.sameOriginOnly ? 'l.href.startsWith(here)' : 'true'}));
+  })()`;
+    const res = await ex.eval(expr, { tabId: args.tabId });
+    if (res.ok && Array.isArray(res.value)) {
+        return { links: res.value };
+    }
+    // Fallback: parse hrefs out of the HTML (e.g. when eval is policy-denied).
+    const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
+        tabId: args.tabId,
+    });
+    const links = [];
+    const re = /<a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+    let m;
+    while ((m = re.exec(html)) !== null) {
+        links.push({ href: m[1], text: m[2].replace(/<[^>]+>/g, '').trim().slice(0, 200) });
+    }
+    return { links };
+}
+/** Read a page (or subtree) as readable markdown. */
+async function readAsMarkdown(ex, args) {
+    const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
+        tabId: args.tabId,
+    });
+    return (0, markdown_extract_1.htmlToMarkdown)(html);
+}
+/** Fill a set of fields (keyed by selector) and optionally submit. */
+async function fillForm(ex, args) {
+    let filled = 0;
+    for (const [selector, value] of Object.entries(args.fields)) {
+        const target = { selector };
+        if (typeof value === 'boolean') {
+            // Checkbox/radio: a click toggles it.
+            await ex.click(target, { tabId: args.tabId });
+        }
+        else {
+            await ex.fill(target, value, { tabId: args.tabId });
+        }
+        filled++;
+    }
+    let submitted = false;
+    if (args.submitSelector) {
+        await ex.click({ selector: args.submitSelector }, { tabId: args.tabId });
+        submitted = true;
+    }
+    return { filled, submitted };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/src/mcp/markdown-extract.d.ts

@@ -0,0 +1,9 @@
+/**
+ * src/mcp/markdown-extract.ts — a dependency-free HTML → readable-markdown
+ * reducer. Not a full Readability port, but it drops non-content chrome
+ * (script/style/nav/header/footer/aside/form), and converts the common block
+ * and inline structure (headings, lists, links, emphasis, code, blockquote,
+ * hr) to markdown, then collapses whitespace.
+ */
+/** Convert an HTML string to readable markdown. */
+export declare function htmlToMarkdown(html: string): string;

package/dist/src/mcp/markdown-extract.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * src/mcp/markdown-extract.ts — a dependency-free HTML → readable-markdown
+ * reducer. Not a full Readability port, but it drops non-content chrome
+ * (script/style/nav/header/footer/aside/form), and converts the common block
+ * and inline structure (headings, lists, links, emphasis, code, blockquote,
+ * hr) to markdown, then collapses whitespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.htmlToMarkdown = htmlToMarkdown;
+/** Convert an HTML string to readable markdown. */
+function htmlToMarkdown(html) {
+    let s = html;
+    // Drop comments and whole non-content subtrees.
+    s = s.replace(/<!--[\s\S]*?-->/g, '');
+    s = s.replace(/<(script|style|noscript|head|svg|nav|header|footer|aside|form|template)[\s\S]*?<\/\1>/gi, '');
+    // Headings.
+    for (let i = 1; i <= 6; i++) {
+        const re = new RegExp(`<\\s*h${i}[^>]*>([\\s\\S]*?)<\\/h${i}>`, 'gi');
+        s = s.replace(re, (_m, t) => `\n\n${'#'.repeat(i)} ${strip(t)}\n\n`);
+    }
+    // Lists: ordered items get "1.", unordered get "-". (Flat; nesting is lossy.)
+    s = s.replace(/<\s*ol[^>]*>([\s\S]*?)<\/ol>/gi, (_m, inner) => {
+        let n = 0;
+        return '\n' + inner.replace(/<\s*li[^>]*>([\s\S]*?)<\/li>/gi, (_x, t) => `\n${++n}. ${strip(t)}`) + '\n';
+    });
+    s = s.replace(/<\s*li[^>]*>([\s\S]*?)<\/li>/gi, (_m, t) => `\n- ${strip(t)}`);
+    // Blockquote, hr, code.
+    s = s.replace(/<\s*blockquote[^>]*>([\s\S]*?)<\/blockquote>/gi, (_m, t) => `\n\n> ${strip(t)}\n\n`);
+    s = s.replace(/<\s*hr[^>]*\/?\s*>/gi, '\n\n---\n\n');
+    s = s.replace(/<\s*(pre|code)[^>]*>([\s\S]*?)<\/\1>/gi, (_m, _tag, t) => `\`${strip(t)}\``);
+    // Inline emphasis.
+    s = s.replace(/<\s*(strong|b)[^>]*>([\s\S]*?)<\/\1>/gi, (_m, _t, t) => `**${strip(t)}**`);
+    s = s.replace(/<\s*(em|i)[^>]*>([\s\S]*?)<\/\1>/gi, (_m, _t, t) => `_${strip(t)}_`);
+    // Links.
+    s = s.replace(/<\s*a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_m, href, t) => {
+        const label = strip(t);
+        return label ? `[${label}](${href})` : '';
+    });
+    // Block boundaries → newlines.
+    s = s.replace(/<\s*(p|br|div|section|article|tr|table|ul|ol)[^>]*>/gi, '\n');
+    // Remove remaining tags, decode entities, collapse blank runs.
+    s = strip(s);
+    s = s.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n');
+    return s.trim();
+}
+function strip(fragment) {
+    return decodeEntities(fragment.replace(/<[^>]+>/g, '')).replace(/[ \t]+/g, ' ').trim();
+}
+function decodeEntities(s) {
+    return s
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&mdash;/g, '—')
+        .replace(/&hellip;/g, '…');
+}
+//# sourceMappingURL=markdown-extract.js.map

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * src/mcp/server.ts — MCP server bootstrap over stdio.
+ *
+ * Wires the SDK `Server` to a `StdioServerTransport` so an MCP host (Claude)
+ * drives chrome-mcp over JSON-RPC on stdin/stdout. CRITICAL: in stdio mode
+ * NOTHING may be written to stdout except the JSON-RPC stream — all diagnostics
+ * go to stderr via `logErr`.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/** stderr only — never stdout in stdio mode. */
+export declare function logErr(message: string): void;
+/** Build a fresh `Server` with the full tool surface registered (no transport). */
+export declare function createServer(): Server;
+/** Start over stdio. Idempotent. */
+export declare function startMcpServer(): Promise<void>;
+/** Stop and release the transport. Idempotent, best-effort. */
+export declare function stopMcpServer(): Promise<void>;
+export declare function isMcpServerRunning(): boolean;

package/dist/src/mcp/server.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * src/mcp/server.ts — MCP server bootstrap over stdio.
+ *
+ * Wires the SDK `Server` to a `StdioServerTransport` so an MCP host (Claude)
+ * drives chrome-mcp over JSON-RPC on stdin/stdout. CRITICAL: in stdio mode
+ * NOTHING may be written to stdout except the JSON-RPC stream — all diagnostics
+ * go to stderr via `logErr`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logErr = logErr;
+exports.createServer = createServer;
+exports.startMcpServer = startMcpServer;
+exports.stopMcpServer = stopMcpServer;
+exports.isMcpServerRunning = isMcpServerRunning;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const tools_1 = require("./tools");
+const SERVER_NAME = 'chrome-mcp';
+const SERVER_VERSION = '0.1.0';
+let server = null;
+let transport = null;
+/** stderr only — never stdout in stdio mode. */
+function logErr(message) {
+    process.stderr.write(`[chrome-mcp] ${message}\n`);
+}
+/** Build a fresh `Server` with the full tool surface registered (no transport). */
+function createServer() {
+    const srv = new index_js_1.Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    (0, tools_1.registerTools)(srv);
+    srv.onerror = (err) => {
+        logErr(`server error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    };
+    return srv;
+}
+/** Start over stdio. Idempotent. */
+async function startMcpServer() {
+    if (server) {
+        logErr('startMcpServer called but already running; ignoring.');
+        return;
+    }
+    const srv = createServer();
+    const tx = new stdio_js_1.StdioServerTransport();
+    try {
+        await srv.connect(tx);
+    }
+    catch (err) {
+        logErr(`failed to connect stdio transport: ${String(err)}`);
+        server = null;
+        transport = null;
+        throw err;
+    }
+    server = srv;
+    transport = tx;
+    logErr(`${SERVER_NAME} v${SERVER_VERSION} connected over stdio.`);
+}
+/** Stop and release the transport. Idempotent, best-effort. */
+async function stopMcpServer() {
+    const srv = server;
+    if (!srv)
+        return;
+    server = null;
+    const tx = transport;
+    transport = null;
+    try {
+        await srv.close();
+    }
+    catch (err) {
+        logErr(`error closing server: ${String(err)}`);
+    }
+    try {
+        await tx?.close();
+    }
+    catch (err) {
+        logErr(`error closing transport: ${String(err)}`);
+    }
+    logErr('MCP server stopped.');
+}
+function isMcpServerRunning() {
+    return server !== null;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/mcp/tools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/mcp/tools.ts — the MCP tool surface: the advertised catalog
+ * (`TOOL_DEFINITIONS`), the name→handler dispatch (`TOOL_HANDLERS`), the
+ * never-throw firewall (`dispatchToolCall`), and `registerTools()` which wires
+ * both onto a `Server`.
+ *
+ * Each handler: validate args → **policy-gate against the relevant URL** → call
+ * the active Executor (or a server-side helper) → serialize via an envelope.
+ * Nothing here throws to the transport: `dispatchToolCall` renders any thrown
+ * `Error` as an `isError` result.
+ */
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Executor } from '../executor/types';
+import { type Policy } from '../security/policy';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOL_DEFINITIONS: ToolDefinition[];
+interface ToolCtx {
+    ex: Executor;
+    policy: Policy;
+}
+type ToolHandler = (args: Record<string, unknown>, ctx: ToolCtx) => Promise<CallToolResult>;
+export declare const TOOL_HANDLERS: Record<string, ToolHandler>;
+export declare function dispatchToolCall(name: string, rawArgs: unknown): Promise<CallToolResult>;
+/** Assert the catalog and the dispatch table describe the same tool set. */
+export declare function assertNoDrift(): void;
+export declare function registerTools(server: Server): void;
+export {};

package/dist/src/mcp/tools.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * src/mcp/tools.ts — the MCP tool surface: the advertised catalog
+ * (`TOOL_DEFINITIONS`), the name→handler dispatch (`TOOL_HANDLERS`), the
+ * never-throw firewall (`dispatchToolCall`), and `registerTools()` which wires
+ * both onto a `Server`.
+ *
+ * Each handler: validate args → **policy-gate against the relevant URL** → call
+ * the active Executor (or a server-side helper) → serialize via an envelope.
+ * Nothing here throws to the transport: `dispatchToolCall` renders any thrown
+ * `Error` as an `isError` result.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_HANDLERS = exports.TOOL_DEFINITIONS = void 0;
+exports.dispatchToolCall = dispatchToolCall;
+exports.assertNoDrift = assertNoDrift;
+exports.registerTools = registerTools;
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const types_1 = require("../executor/types");
+const manager_1 = require("../executor/manager");
+const policy_1 = require("../security/policy");
+const envelopes_1 = require("./envelopes");
+const helpers_1 = require("./helpers");
+const validators_1 = require("./validators");
+const TARGET_PROPS = {
+    selector: { type: 'string', description: 'CSS selector (exactly one of selector|ref)' },
+    ref: { type: 'string', description: 'Element ref from a prior read (exactly one of selector|ref)' },
+};
+const obj = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+});
+exports.TOOL_DEFINITIONS = [
+    { name: 'tabs_list', description: 'List open browser tabs.', inputSchema: obj({}) },
+    { name: 'tab_select', description: 'Make a tab active by tabId.', inputSchema: obj({ tabId: { type: 'string' } }, ['tabId']) },
+    { name: 'tab_new', description: 'Open a new tab, optionally at a URL.', inputSchema: obj({ url: { type: 'string' } }) },
+    { name: 'tab_close', description: 'Close a tab by tabId.', inputSchema: obj({ tabId: { type: 'string' } }, ['tabId']) },
+    { name: 'navigate', description: 'Navigate the active (or given) tab to a URL.', inputSchema: obj({ url: { type: 'string' }, tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }, ['url']) },
+    { name: 'back', description: 'Go back in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
+    { name: 'forward', description: 'Go forward in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
+    { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: obj({ tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }) },
+    { name: 'click', description: 'Click an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' }, button: { type: 'string', enum: ['left', 'right', 'middle'] }, clickCount: { type: 'number' } }) },
+    { name: 'type', description: 'Type text into an element.', inputSchema: obj({ ...TARGET_PROPS, text: { type: 'string' }, tabId: { type: 'string' }, clear: { type: 'boolean' }, pressEnter: { type: 'boolean' }, keyEvents: { type: 'boolean' } }, ['text']) },
+    { name: 'press', description: 'Press a key (with optional modifiers).', inputSchema: obj({ key: { type: 'string' }, modifiers: { type: 'array', items: { type: 'string' } }, tabId: { type: 'string' } }, ['key']) },
+    { name: 'hover', description: 'Hover over an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' } }) },
+    { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: obj({ ...TARGET_PROPS, x: { type: 'number' }, y: { type: 'number' }, deltaX: { type: 'number' }, deltaY: { type: 'number' }, tabId: { type: 'string' } }) },
+    { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: obj({ ...TARGET_PROPS, fullPage: { type: 'boolean' }, tabId: { type: 'string' } }) },
+    { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' } }) },
+    { name: 'get_html', description: 'Get HTML of the page or an element.', inputSchema: obj({ ...TARGET_PROPS, outer: { type: 'boolean' }, tabId: { type: 'string' } }) },
+    { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: obj({ expression: { type: 'string' }, awaitPromise: { type: 'boolean' }, tabId: { type: 'string' } }, ['expression']) },
+    { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: obj({ selector: { type: 'string' }, textContains: { type: 'string' }, gone: { type: 'boolean' }, timeoutMs: { type: 'number' }, tabId: { type: 'string' } }) },
+    { name: 'extract_links', description: 'Extract anchors from the page or a subtree.', inputSchema: obj({ selector: { type: 'string' }, sameOriginOnly: { type: 'boolean' }, tabId: { type: 'string' } }) },
+    { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: obj({ selector: { type: 'string' }, tabId: { type: 'string' } }) },
+    { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: obj({ fields: { type: 'object' }, submitSelector: { type: 'string' }, tabId: { type: 'string' } }, ['fields']) },
+    { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: obj({ url: { type: 'string' }, ...TARGET_PROPS, suggestedName: { type: 'string' }, tabId: { type: 'string' } }) },
+    { name: 'chrome_status', description: 'Report backend/session status.', inputSchema: obj({}) },
+];
+/** Resolve the URL the policy should be evaluated against (the active tab). */
+async function activeUrl(ex) {
+    try {
+        const tabs = await ex.tabsList();
+        return tabs.find((t) => t.active)?.url ?? tabs[0]?.url ?? 'about:blank';
+    }
+    catch {
+        return 'about:blank';
+    }
+}
+/** Policy chokepoint. `urlOverride` is the destination for navigation. */
+async function gate(ctx, method, urlOverride) {
+    const url = urlOverride ?? (await activeUrl(ctx.ex));
+    (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
+}
+const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
+const waitUntil = (args) => (0, validators_1.optionalString)(args, 'waitUntil');
+exports.TOOL_HANDLERS = {
+    tabs_list: async (_a, ctx) => (0, envelopes_1.jsonResult)(await ctx.ex.tabsList()),
+    tab_select: async (a, ctx) => {
+        await gate(ctx, 'tab_select');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.tabSelect((0, validators_1.requireString)(a, 'tabId')));
+    },
+    tab_new: async (a, ctx) => {
+        await gate(ctx, 'tab_new');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.tabNew((0, validators_1.optionalString)(a, 'url')));
+    },
+    tab_close: async (a, ctx) => {
+        await gate(ctx, 'tab_close');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.tabClose((0, validators_1.requireString)(a, 'tabId')));
+    },
+    navigate: async (a, ctx) => {
+        const url = (0, validators_1.requireString)(a, 'url');
+        await gate(ctx, 'navigate', url);
+        return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
+    },
+    back: async (a, ctx) => {
+        await gate(ctx, 'back');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
+    },
+    forward: async (a, ctx) => {
+        await gate(ctx, 'forward');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
+    },
+    reload: async (a, ctx) => {
+        await gate(ctx, 'reload');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
+    },
+    click: async (a, ctx) => {
+        const t = (0, validators_1.requireTarget)(a);
+        await gate(ctx, 'click');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.click(t, {
+            tabId: tabId(a),
+            button: (0, validators_1.optionalString)(a, 'button'),
+            clickCount: (0, validators_1.optionalNumber)(a, 'clickCount', { min: 1, max: 3 }),
+        }));
+    },
+    type: async (a, ctx) => {
+        const t = (0, validators_1.requireTarget)(a);
+        await gate(ctx, 'type');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.type(t, (0, validators_1.requireString)(a, 'text'), {
+            tabId: tabId(a),
+            clear: (0, validators_1.optionalBoolean)(a, 'clear'),
+            pressEnter: (0, validators_1.optionalBoolean)(a, 'pressEnter'),
+            keyEvents: (0, validators_1.optionalBoolean)(a, 'keyEvents'),
+        }));
+    },
+    press: async (a, ctx) => {
+        await gate(ctx, 'press');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
+            tabId: tabId(a),
+            modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
+        }));
+    },
+    hover: async (a, ctx) => {
+        const t = (0, validators_1.requireTarget)(a);
+        await gate(ctx, 'hover');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.hover(t, { tabId: tabId(a) }));
+    },
+    scroll: async (a, ctx) => {
+        await gate(ctx, 'scroll');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.scroll({
+            tabId: tabId(a),
+            x: (0, validators_1.optionalNumber)(a, 'x'),
+            y: (0, validators_1.optionalNumber)(a, 'y'),
+            deltaX: (0, validators_1.optionalNumber)(a, 'deltaX'),
+            deltaY: (0, validators_1.optionalNumber)(a, 'deltaY'),
+            target: (0, validators_1.optionalTarget)(a),
+        }));
+    },
+    screenshot: async (a, ctx) => {
+        await gate(ctx, 'screenshot');
+        const shot = await ctx.ex.screenshot({
+            tabId: tabId(a),
+            fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
+            target: (0, validators_1.optionalTarget)(a),
+        });
+        const caption = shot.truncated ? `(truncated; full height ${shot.fullHeight}px)` : undefined;
+        return (0, envelopes_1.imageResult)(shot.dataBase64, shot.mimeType, caption);
+    },
+    get_text: async (a, ctx) => {
+        await gate(ctx, 'get_text');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a) }));
+    },
+    get_html: async (a, ctx) => {
+        await gate(ctx, 'get_html');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') }));
+    },
+    eval: async (a, ctx) => {
+        await gate(ctx, 'eval');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
+            tabId: tabId(a),
+            awaitPromise: (0, validators_1.optionalBoolean)(a, 'awaitPromise'),
+        }));
+    },
+    wait_for: async (a, ctx) => {
+        await gate(ctx, 'wait_for');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
+            tabId: tabId(a),
+            selector: (0, validators_1.optionalString)(a, 'selector'),
+            textContains: (0, validators_1.optionalString)(a, 'textContains'),
+            gone: (0, validators_1.optionalBoolean)(a, 'gone'),
+            timeoutMs: (0, validators_1.optionalNumber)(a, 'timeoutMs', { min: 0, max: 120_000 }),
+        }));
+    },
+    extract_links: async (a, ctx) => {
+        await gate(ctx, 'get_text'); // read of page content
+        return (0, envelopes_1.jsonResult)(await (0, helpers_1.extractLinks)(ctx.ex, {
+            selector: (0, validators_1.optionalString)(a, 'selector'),
+            sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
+            tabId: tabId(a),
+        }));
+    },
+    read_as_markdown: async (a, ctx) => {
+        await gate(ctx, 'get_text');
+        return (0, envelopes_1.textResult)(await (0, helpers_1.readAsMarkdown)(ctx.ex, { selector: (0, validators_1.optionalString)(a, 'selector'), tabId: tabId(a) }));
+    },
+    fill_form: async (a, ctx) => {
+        await gate(ctx, 'type'); // mutating
+        const fields = a.fields;
+        if (typeof fields !== 'object' || fields === null || Array.isArray(fields)) {
+            throw new validators_1.McpToolError('"fields" must be an object mapping selector -> string|boolean');
+        }
+        return (0, envelopes_1.jsonResult)(await (0, helpers_1.fillForm)(ctx.ex, {
+            fields: fields,
+            submitSelector: (0, validators_1.optionalString)(a, 'submitSelector'),
+            tabId: tabId(a),
+        }));
+    },
+    download_file: async (a, ctx) => {
+        await gate(ctx, 'download_file');
+        const url = (0, validators_1.optionalString)(a, 'url');
+        const target = (0, validators_1.optionalTarget)(a);
+        if (!url && !target)
+            throw new validators_1.McpToolError('provide "url" or a target (selector|ref)');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.download({ url, target, tabId: tabId(a), suggestedName: (0, validators_1.optionalString)(a, 'suggestedName') }));
+    },
+    chrome_status: async (_a, ctx) => (0, envelopes_1.jsonResult)(ctx.ex.status()),
+};
+// ---------------------------------------------------------------------------
+// Dispatch (never-throw firewall)
+// ---------------------------------------------------------------------------
+function errMessage(err) {
+    if (err instanceof validators_1.McpToolError || err instanceof types_1.ExecutorError)
+        return err.message;
+    if (err instanceof Error)
+        return `internal error: ${err.message}`;
+    return `internal error: ${String(err)}`;
+}
+async function dispatchToolCall(name, rawArgs) {
+    const handler = exports.TOOL_HANDLERS[name];
+    if (!handler)
+        return (0, envelopes_1.errorResult)(`unknown tool: ${name}`);
+    try {
+        const mgr = (0, manager_1.getManager)();
+        const ex = await mgr.ensureReady();
+        return await handler((0, validators_1.asArgs)(rawArgs), { ex, policy: mgr.policy });
+    }
+    catch (err) {
+        return (0, envelopes_1.errorResult)(errMessage(err));
+    }
+}
+/** Assert the catalog and the dispatch table describe the same tool set. */
+function assertNoDrift() {
+    const defs = new Set(exports.TOOL_DEFINITIONS.map((d) => d.name));
+    const handlers = new Set(Object.keys(exports.TOOL_HANDLERS));
+    for (const n of defs)
+        if (!handlers.has(n))
+            throw new Error(`tool "${n}" is advertised but has no handler`);
+    for (const n of handlers)
+        if (!defs.has(n))
+            throw new Error(`handler "${n}" has no advertised definition`);
+}
+// ---------------------------------------------------------------------------
+// Wiring
+// ---------------------------------------------------------------------------
+function registerTools(server) {
+    assertNoDrift();
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: exports.TOOL_DEFINITIONS.map((d) => ({
+            name: d.name,
+            description: d.description,
+            inputSchema: d.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => dispatchToolCall(req.params.name, req.params.arguments));
+}
+//# sourceMappingURL=tools.js.map

package/dist/src/mcp/validators.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/mcp/validators.ts — lightweight, dependency-free runtime guards for tool
+ * arguments. The JSON Schema in `tools.ts` is the advertised contract; these
+ * guards defend each handler from malformed input and throw `McpToolError` with
+ * an actionable message (rendered as a structured `isError` result upstream).
+ */
+import type { Target } from '../executor/types';
+/**
+ * Thrown when a tool request can't be fulfilled for a caller-actionable reason
+ * (bad args, exactly-one-of violation, …). The dispatch firewall converts it to
+ * an `isError` result, so it never tears down the transport.
+ */
+export declare class McpToolError extends Error {
+    constructor(message: string);
+}
+/** Coerce raw tool args into a plain object, rejecting non-objects. */
+export declare function asArgs(raw: unknown): Record<string, unknown>;
+export declare function requireString(args: Record<string, unknown>, key: string): string;
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function optionalBoolean(args: Record<string, unknown>, key: string): boolean | undefined;
+export declare function optionalNumber(args: Record<string, unknown>, key: string, bounds?: {
+    min?: number;
+    max?: number;
+}): number | undefined;
+export declare function optionalStringArray(args: Record<string, unknown>, key: string): string[] | undefined;
+/**
+ * Require EXACTLY ONE of `selector` | `ref`. Returns a normalized `Target`.
+ * Both-present and neither-present are both errors — the contract is one-of.
+ */
+export declare function requireTarget(args: Record<string, unknown>): Target;
+/** Like `requireTarget` but the target is optional (whole-page reads). */
+export declare function optionalTarget(args: Record<string, unknown>): Target | undefined;