@minionry/minion 0.7.36

package/dist/server/mcp/browser-mcp-server.js

@@ -0,0 +1,915 @@
+#!/usr/bin/env -S npx tsx
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+export const BROWSER_MCP_SERVER_NAME = 'minionry-browser';
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+export const DEFAULT_RPC_TIMEOUT_MS = 15_000;
+export const RPC_DEADLINE_SLACK_MS = 5_000;
+export function rpcDeadlineMs(params) {
+    const own = params?.timeoutMs;
+    if (typeof own !== 'number' || !Number.isFinite(own) || own <= 0)
+        return DEFAULT_RPC_TIMEOUT_MS;
+    return Math.max(DEFAULT_RPC_TIMEOUT_MS, own + RPC_DEADLINE_SLACK_MS);
+}
+export class LeaseManager {
+    client;
+    log;
+    setIntervalFn;
+    clearIntervalFn;
+    heartbeatIntervalMs;
+    owned = new Set();
+    heartbeatHandle = null;
+    heartbeatTicks = 0;
+    lastDroppedTabs = [];
+    constructor(deps) {
+        this.client = deps.client;
+        this.log = deps.log ?? ((m) => console.error(m));
+        this.setIntervalFn = deps.setIntervalFn ?? ((handler, ms) => setInterval(handler, ms));
+        this.clearIntervalFn = deps.clearIntervalFn ?? clearInterval;
+        this.heartbeatIntervalMs = deps.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    }
+    ownedTabs() {
+        return [...this.owned];
+    }
+    trackForTest(tabId) {
+        this.owned.add(tabId);
+    }
+    async ensure(tabId) {
+        if (this.owned.has(tabId)) {
+            const hb = await this.client.call('agent.tab.heartbeat', { tabIds: [tabId] });
+            throwIfErr(hb);
+            const stillLeased = extractStillLeased(hb);
+            if (!stillLeased.includes(tabId)) {
+                this.owned.delete(tabId);
+            }
+            else {
+                return;
+            }
+        }
+        const lease = await this.client.call('agent.tab.lease', { tabId });
+        if (lease.body.error) {
+            const code = lease.body.error.code;
+            if (code === 'tab_already_leased') {
+                const owner = lease.body.error.data
+                    ?.currentOwner;
+                throw new TabAlreadyLeasedError(tabId, owner);
+            }
+            throw new BrowserOpError(code, lease.body.error.message, lease.body.error.data);
+        }
+        this.owned.add(tabId);
+    }
+    async release(tabId) {
+        this.owned.delete(tabId);
+        try {
+            await this.client.call('agent.tab.release', { tabId });
+        }
+        catch (err) {
+            this.log(`[BrowserMcp] release(${tabId}) failed: ${stringifyError(err)}`);
+        }
+    }
+    start() {
+        if (this.heartbeatHandle)
+            return;
+        this.heartbeatHandle = this.setIntervalFn(() => {
+            void this.tick();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (this.heartbeatHandle) {
+            this.clearIntervalFn(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+        const tabs = this.ownedTabs();
+        await Promise.all(tabs.map((t) => this.release(t)));
+    }
+    async tick() {
+        this.heartbeatTicks += 1;
+        if (this.owned.size === 0) {
+            this.lastDroppedTabs = [];
+            return;
+        }
+        const tabIds = this.ownedTabs();
+        try {
+            const res = await this.client.call('agent.tab.heartbeat', { tabIds });
+            if (res.body.error) {
+                this.log(`[BrowserMcp] heartbeat error: ${res.body.error.message}`);
+                return;
+            }
+            const stillLeased = extractStillLeased(res);
+            const dropped = tabIds.filter((t) => !stillLeased.includes(t));
+            this.lastDroppedTabs = dropped;
+            for (const t of dropped) {
+                this.owned.delete(t);
+                this.log(`[BrowserMcp] lost lease on tab ${t}`);
+            }
+        }
+        catch (err) {
+            this.log(`[BrowserMcp] heartbeat threw: ${stringifyError(err)}`);
+        }
+    }
+}
+export class BrowserOpError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'BrowserOpError';
+        this.code = code;
+        this.data = data;
+    }
+}
+export class TabAlreadyLeasedError extends BrowserOpError {
+    tabId;
+    currentOwner;
+    constructor(tabId, currentOwner) {
+        super('tab_already_leased', `Tab ${tabId} is already leased by another agent`, { currentOwner });
+        this.name = 'TabAlreadyLeasedError';
+        this.tabId = tabId;
+        this.currentOwner = currentOwner;
+    }
+}
+function throwIfErr(res) {
+    if (res.body.error) {
+        throw new BrowserOpError(res.body.error.code, res.body.error.message, res.body.error.data);
+    }
+}
+function extractStillLeased(res) {
+    const r = res.body.result;
+    return Array.isArray(r?.stillLeased)
+        ? r.stillLeased.filter((t) => typeof t === 'string')
+        : [];
+}
+function stringifyError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function ok(text, extra) {
+    return { content: [{ type: 'text', text }], ...(extra ? { _meta: extra } : {}) };
+}
+function okJson(payload, extra) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        ...(extra ? { _meta: extra } : {}),
+    };
+}
+function fail(code, message, data) {
+    return {
+        content: [{ type: 'text', text: `${code}: ${message}` }],
+        isError: true,
+        _meta: { errorCode: code, ...(data !== undefined ? { data } : {}) },
+    };
+}
+function resolveTabId(args, ctx) {
+    const t = args.tabId;
+    if (typeof t === 'string' && t)
+        return t;
+    if (ctx.defaultTabId)
+        return ctx.defaultTabId;
+    throw new BrowserOpError('tabId_required', 'no tabId provided and no MINIONRY_DEFAULT_TAB_ID configured');
+}
+function navigationTabId(args, ctx) {
+    const named = args.tabId;
+    if (typeof named === 'string' && named)
+        return named;
+    return ctx.defaultTabId;
+}
+async function navigateLeased(ctx, args, method, params = {}) {
+    const tabId = navigationTabId(args, ctx);
+    if (tabId === undefined) {
+        await rpc(ctx, method, params);
+        return;
+    }
+    await withLease(ctx, tabId, () => rpc(ctx, method, { ...params, tabId }));
+}
+async function withLease(ctx, tabId, fn) {
+    await ctx.leases.ensure(tabId);
+    return fn();
+}
+async function rpc(ctx, method, params) {
+    const res = await ctx.client.call(method, params, { timeoutMs: rpcDeadlineMs(params) });
+    throwIfErr(res);
+    return res.body.result;
+}
+const tools = [
+    {
+        name: 'browser_snapshot',
+        description: 'Capture an accessibility-tree snapshot of the current page. Returns a tree of nodes with stable refs that other browser_* tools accept.',
+        inputSchema: {
+            type: 'object',
+            properties: { tabId: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const snap = await withLease(ctx, tabId, () => rpc(ctx, 'dom.snapshot', { tabId }));
+            return okJson(snap);
+        },
+    },
+    {
+        name: 'browser_click',
+        description: 'Click an element identified by its snapshot ref.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref'],
+            properties: {
+                tabId: { type: 'string' },
+                ref: { type: 'string' },
+                button: { type: 'string', enum: ['left', 'right', 'middle'] },
+                clickCount: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const ref = String(args.ref ?? '');
+            if (!ref)
+                return fail('invalid_params', 'ref is required');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.click', {
+                tabId,
+                ref,
+                ...(args.button ? { button: args.button } : {}),
+                ...(typeof args.clickCount === 'number' ? { clickCount: args.clickCount } : {}),
+            }));
+            return ok(`Clicked ${ref}`);
+        },
+    },
+    {
+        name: 'browser_type',
+        description: 'Focus an input by ref and type the given text. Set `submit:true` to press Enter at the end.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref', 'text'],
+            properties: {
+                tabId: { type: 'string' },
+                ref: { type: 'string' },
+                text: { type: 'string' },
+                submit: { type: 'boolean' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const ref = String(args.ref ?? '');
+            const text = typeof args.text === 'string' ? args.text : '';
+            if (!ref)
+                return fail('invalid_params', 'ref is required');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.type', {
+                tabId,
+                ref,
+                text,
+                submit: args.submit === true,
+            }));
+            return ok(`Typed into ${ref}`);
+        },
+    },
+    {
+        name: 'browser_hover',
+        description: 'Move the mouse over an element identified by its snapshot ref.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref'],
+            properties: { tabId: { type: 'string' }, ref: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const ref = String(args.ref ?? '');
+            if (!ref)
+                return fail('invalid_params', 'ref is required');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.hover', { tabId, ref }));
+            return ok(`Hovered ${ref}`);
+        },
+    },
+    {
+        name: 'browser_press_key',
+        description: 'Press a single key (e.g. "Enter", "Tab", "a"). Triggers keydown + keyup.',
+        inputSchema: {
+            type: 'object',
+            required: ['key'],
+            properties: { tabId: { type: 'string' }, key: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const key = String(args.key ?? '');
+            if (!key)
+                return fail('invalid_params', 'key is required');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.press_key', { tabId, key }));
+            return ok(`Pressed ${key}`);
+        },
+    },
+    {
+        name: 'browser_select_option',
+        description: 'Select one or more values from a <select> element identified by ref.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref', 'values'],
+            properties: {
+                tabId: { type: 'string' },
+                ref: { type: 'string' },
+                values: { type: 'array', items: { type: 'string' } },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const ref = String(args.ref ?? '');
+            const values = Array.isArray(args.values)
+                ? args.values.filter((v) => typeof v === 'string')
+                : null;
+            if (!ref)
+                return fail('invalid_params', 'ref is required');
+            if (!values)
+                return fail('invalid_params', 'values must be string[]');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.select_option', {
+                tabId,
+                ref,
+                values,
+            }));
+            return ok(`Selected ${values.length} value(s) on ${ref}`);
+        },
+    },
+    {
+        name: 'browser_fill_form',
+        description: 'Fill multiple form fields atomically. Each field is { ref, value }.',
+        inputSchema: {
+            type: 'object',
+            required: ['fields'],
+            properties: {
+                tabId: { type: 'string' },
+                fields: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['ref', 'value'],
+                        properties: { ref: { type: 'string' }, value: { type: 'string' } },
+                    },
+                },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const fields = Array.isArray(args.fields) ? args.fields : null;
+            if (!fields)
+                return fail('invalid_params', 'fields[] is required');
+            const norm = [];
+            for (const f of fields) {
+                if (!f || typeof f !== 'object')
+                    return fail('invalid_params', 'field is not an object');
+                const ref = f.ref;
+                const value = f.value;
+                if (typeof ref !== 'string' || typeof value !== 'string') {
+                    return fail('invalid_params', 'each field needs string ref + value');
+                }
+                norm.push({ ref, value });
+            }
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.fill_form', {
+                tabId,
+                fields: norm,
+            }));
+            return ok(`Filled ${norm.length} field(s)`);
+        },
+    },
+    {
+        name: 'browser_drag',
+        description: 'Drag from one element ref to another (mouseDown + move + mouseUp).',
+        inputSchema: {
+            type: 'object',
+            required: ['fromRef', 'toRef'],
+            properties: {
+                tabId: { type: 'string' },
+                fromRef: { type: 'string' },
+                toRef: { type: 'string' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const fromRef = String(args.fromRef ?? '');
+            const toRef = String(args.toRef ?? '');
+            if (!fromRef || !toRef)
+                return fail('invalid_params', 'fromRef and toRef are required');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.drag_drop', {
+                tabId,
+                fromRef,
+                toRef,
+            }));
+            return ok(`Dragged ${fromRef} -> ${toRef}`);
+        },
+    },
+    {
+        name: 'browser_file_upload',
+        description: 'Attach one or more files (by absolute path) to a file input identified by ref.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref', 'paths'],
+            properties: {
+                tabId: { type: 'string' },
+                ref: { type: 'string' },
+                paths: { type: 'array', items: { type: 'string' } },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const ref = String(args.ref ?? '');
+            const paths = Array.isArray(args.paths)
+                ? args.paths.filter((p) => typeof p === 'string')
+                : null;
+            if (!ref)
+                return fail('invalid_params', 'ref is required');
+            if (!paths || paths.length === 0)
+                return fail('invalid_params', 'paths must be non-empty string[]');
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.file_upload', {
+                tabId,
+                ref,
+                paths,
+            }));
+            return ok(`Attached ${paths.length} file(s) to ${ref}`);
+        },
+    },
+    {
+        name: 'browser_handle_dialog',
+        description: 'Respond to a pending JavaScript dialog (alert / confirm / prompt). Set accept:true to accept, false to dismiss.',
+        inputSchema: {
+            type: 'object',
+            required: ['accept'],
+            properties: {
+                tabId: { type: 'string' },
+                accept: { type: 'boolean' },
+                promptText: { type: 'string' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const accept = args.accept === true;
+            const promptText = typeof args.promptText === 'string' ? args.promptText : undefined;
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.handle_dialog', {
+                tabId,
+                accept,
+                ...(promptText !== undefined ? { promptText } : {}),
+            }));
+            return ok(accept ? 'Dialog accepted' : 'Dialog dismissed');
+        },
+    },
+    {
+        name: 'browser_wait_for',
+        description: 'Block until the given condition becomes true. condition is either {type:"expression", expr:"…"} or {type:"navigation"}.',
+        inputSchema: {
+            type: 'object',
+            required: ['condition'],
+            properties: {
+                tabId: { type: 'string' },
+                condition: { type: 'object' },
+                timeoutMs: { type: 'number' },
+                pollIntervalMs: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const condition = args.condition;
+            if (!condition || typeof condition !== 'object') {
+                return fail('invalid_params', 'condition is required');
+            }
+            const timeoutMs = typeof args.timeoutMs === 'number' ? args.timeoutMs : 5_000;
+            await withLease(ctx, tabId, () => rpc(ctx, 'dom.wait_for', {
+                tabId,
+                timeoutMs,
+                ...(typeof args.pollIntervalMs === 'number'
+                    ? { pollIntervalMs: args.pollIntervalMs }
+                    : {}),
+                condition,
+            }));
+            return ok('wait_for satisfied');
+        },
+    },
+    {
+        name: 'browser_take_screenshot',
+        description: 'Capture a screenshot of the current viewport (or full page). Returns a PNG/JPEG image inline.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tabId: { type: 'string' },
+                fullPage: { type: 'boolean' },
+                format: { type: 'string', enum: ['png', 'jpeg'] },
+                quality: { type: 'number' },
+                clip: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'number' },
+                        y: { type: 'number' },
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                    },
+                },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const res = await withLease(ctx, tabId, () => rpc(ctx, 'dom.screenshot', {
+                tabId,
+                ...(args.fullPage === true ? { fullPage: true } : {}),
+                ...(args.format ? { format: args.format } : {}),
+                ...(typeof args.quality === 'number' ? { quality: args.quality } : {}),
+                ...(args.clip && typeof args.clip === 'object' ? { clip: args.clip } : {}),
+            }));
+            return {
+                content: [
+                    {
+                        type: 'image',
+                        data: res.data,
+                        mimeType: res.format === 'jpeg' ? 'image/jpeg' : 'image/png',
+                    },
+                ],
+            };
+        },
+    },
+    {
+        name: 'browser_console_messages',
+        description: 'Return console messages buffered for this tab. Pass `since:<seq>` to get only newer entries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tabId: { type: 'string' },
+                since: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const since = typeof args.since === 'number' ? args.since : undefined;
+            const out = await withLease(ctx, tabId, () => rpc(ctx, 'dom.console', {
+                tabId,
+                ...(since !== undefined ? { since } : {}),
+            }));
+            return okJson(out);
+        },
+    },
+    {
+        name: 'browser_network_request',
+        description: 'Return the buffered network entry for `requestId` (one row from the per-tab network log). Use browser_network_requests for the full list.',
+        inputSchema: {
+            type: 'object',
+            required: ['requestId'],
+            properties: {
+                tabId: { type: 'string' },
+                requestId: { type: 'string' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const requestId = String(args.requestId ?? '');
+            if (!requestId)
+                return fail('invalid_params', 'requestId is required');
+            const entries = await withLease(ctx, tabId, () => rpc(ctx, 'dom.network', { tabId }));
+            const match = entries.find((e) => e.requestId === requestId);
+            if (!match) {
+                return fail('not_found', `no network entry for requestId ${requestId}`);
+            }
+            return okJson(match);
+        },
+    },
+    {
+        name: 'browser_network_requests',
+        description: 'Return network requests buffered for this tab. Pass `since:<seq>` to get only newer entries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tabId: { type: 'string' },
+                since: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const since = typeof args.since === 'number' ? args.since : undefined;
+            const out = await withLease(ctx, tabId, () => rpc(ctx, 'dom.network', {
+                tabId,
+                ...(since !== undefined ? { since } : {}),
+            }));
+            return okJson(out);
+        },
+    },
+    {
+        name: 'browser_navigate',
+        description: 'Navigate your tab (tabId, else this session\'s tab) to the given URL. The browser bouncer enforces the allowlist.',
+        inputSchema: {
+            type: 'object',
+            required: ['url'],
+            properties: { url: { type: 'string' }, tabId: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const url = String(args.url ?? '');
+            if (!url)
+                return fail('invalid_params', 'url is required');
+            await navigateLeased(ctx, args, 'view.navigate', { url });
+            return ok(`Navigated to ${url}`);
+        },
+    },
+    {
+        name: 'browser_back',
+        description: 'Navigate your tab back one entry in history.',
+        inputSchema: { type: 'object', properties: { tabId: { type: 'string' } } },
+        handler: async (ctx, args) => {
+            await navigateLeased(ctx, args, 'view.back');
+            return ok('Navigated back');
+        },
+    },
+    {
+        name: 'browser_forward',
+        description: 'Navigate your tab forward one entry in history.',
+        inputSchema: { type: 'object', properties: { tabId: { type: 'string' } } },
+        handler: async (ctx, args) => {
+            await navigateLeased(ctx, args, 'view.forward');
+            return ok('Navigated forward');
+        },
+    },
+    {
+        name: 'browser_reload',
+        description: 'Reload your tab.',
+        inputSchema: { type: 'object', properties: { tabId: { type: 'string' } } },
+        handler: async (ctx, args) => {
+            await navigateLeased(ctx, args, 'view.reload');
+            return ok('Reloaded');
+        },
+    },
+    {
+        name: 'browser_tabs',
+        description: 'List tabs the current agent owns leases on, with their cached metadata (url, title, favicon).',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async (ctx) => {
+            const leases = await rpc(ctx, 'agent.tab.list', {});
+            const tabIds = leases.map((l) => l.tabId);
+            const tabs = await rpc(ctx, 'tab.list', { tabIds });
+            return okJson({ leases, tabs });
+        },
+    },
+    {
+        name: 'browser_tab_new',
+        description: 'Open a new tab at `url` (defaults to about:blank) and return its tabId.',
+        inputSchema: {
+            type: 'object',
+            properties: { url: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const url = typeof args.url === 'string' && args.url ? args.url : 'about:blank';
+            const res = await rpc(ctx, 'tab.open', { url });
+            await ctx.leases.ensure(res.id);
+            return okJson({ tabId: res.id });
+        },
+    },
+    {
+        name: 'browser_tab_close',
+        description: 'Close a tab by id. Releases the lease if the caller held one.',
+        inputSchema: {
+            type: 'object',
+            properties: { tabId: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            await rpc(ctx, 'tab.close', { id: tabId });
+            await ctx.leases.release(tabId);
+            return ok(`Closed tab ${tabId}`);
+        },
+    },
+    {
+        name: 'browser_tab_select',
+        description: 'Switch focus to the given tab id. Auto-leases on first use.',
+        inputSchema: {
+            type: 'object',
+            required: ['tabId'],
+            properties: { tabId: { type: 'string' } },
+        },
+        handler: async (ctx, args) => {
+            const tabId = String(args.tabId ?? '');
+            if (!tabId)
+                return fail('invalid_params', 'tabId is required');
+            await ctx.leases.ensure(tabId);
+            await rpc(ctx, 'tab.select', { id: tabId });
+            return ok(`Selected tab ${tabId}`);
+        },
+    },
+    {
+        name: 'browser_evaluate',
+        description: 'Evaluate a JS expression in the tab. `world:"isolated"` (default) keeps the page DOM untouched; `world:"main"` uses the page realm.',
+        inputSchema: {
+            type: 'object',
+            required: ['expr'],
+            properties: {
+                tabId: { type: 'string' },
+                expr: { type: 'string' },
+                world: { type: 'string', enum: ['main', 'isolated'] },
+                timeoutMs: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const expr = String(args.expr ?? '');
+            if (!expr)
+                return fail('invalid_params', 'expr is required');
+            const world = args.world === 'main' ? 'main' : 'isolated';
+            const out = await withLease(ctx, tabId, () => rpc(ctx, 'js.evaluate', {
+                tabId,
+                expr,
+                world,
+                ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+            }));
+            return okJson(out);
+        },
+    },
+    {
+        name: 'browser_run_code_unsafe',
+        description: 'Evaluate JS in the main world. Equivalent to browser_evaluate with world:"main"; surfaced separately so the Bouncer can apply stricter review.',
+        inputSchema: {
+            type: 'object',
+            required: ['code'],
+            properties: {
+                tabId: { type: 'string' },
+                code: { type: 'string' },
+                timeoutMs: { type: 'number' },
+            },
+        },
+        handler: async (ctx, args) => {
+            const tabId = resolveTabId(args, ctx);
+            const expr = String(args.code ?? '');
+            if (!expr)
+                return fail('invalid_params', 'code is required');
+            const out = await withLease(ctx, tabId, () => rpc(ctx, 'js.evaluate', {
+                tabId,
+                expr,
+                world: 'main',
+                ...(typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : {}),
+            }));
+            return okJson(out);
+        },
+    },
+];
+export const TOOLS = tools;
+export async function callTool(ctx, name, args) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return fail('unknown_tool', `no such browser tool: ${name}`);
+    }
+    try {
+        return await tool.handler(ctx, args);
+    }
+    catch (err) {
+        if (err instanceof TabAlreadyLeasedError) {
+            return fail(err.code, err.message, { currentOwner: err.currentOwner });
+        }
+        if (err instanceof BrowserOpError) {
+            return fail(err.code, err.message, err.data);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log(`[BrowserMcp] tool ${name} threw: ${message}`);
+        return fail('internal_error', message);
+    }
+}
+export function createBrowserMcpServer(deps) {
+    const log = deps.log ?? ((m) => console.error(m));
+    const leases = new LeaseManager({
+        client: deps.client,
+        log,
+        ...(deps.setIntervalFn ? { setIntervalFn: deps.setIntervalFn } : {}),
+        ...(deps.clearIntervalFn ? { clearIntervalFn: deps.clearIntervalFn } : {}),
+        ...(deps.heartbeatIntervalMs !== undefined
+            ? { heartbeatIntervalMs: deps.heartbeatIntervalMs }
+            : {}),
+    });
+    const toolCtx = {
+        client: deps.client,
+        leases,
+        ...(deps.defaultTabId ? { defaultTabId: deps.defaultTabId } : {}),
+        log,
+    };
+    const server = new Server({ name: BROWSER_MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: TOOLS.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        const result = await callTool(toolCtx, name, args);
+        return result;
+    });
+    leases.start();
+    return {
+        server,
+        leases,
+        async shutdown() {
+            await leases.stop();
+        },
+    };
+}
+export function createFetchBrowserOpClient(opts) {
+    const url = `http://127.0.0.1:${opts.port}/internal/browser/op`;
+    const fetchImpl = opts.fetchFn ?? fetch;
+    const defaultTimeoutMs = opts.timeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+    return {
+        async call(method, params, callOpts) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), callOpts?.timeoutMs ?? defaultTimeoutMs);
+            try {
+                const res = await fetchImpl(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-minionry-bouncer-secret': opts.bouncerSecret,
+                        'x-minionry-capability-token': opts.capabilityToken,
+                    },
+                    body: JSON.stringify({ method, params: params ?? {} }),
+                    signal: ac.signal,
+                });
+                const status = res.status;
+                let body;
+                try {
+                    body = (await res.json());
+                }
+                catch {
+                    body = {
+                        error: {
+                            code: 'invalid_response',
+                            message: `non-JSON response (status ${status})`,
+                        },
+                    };
+                }
+                return { status, body };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    status: 0,
+                    body: { error: { code: 'transport_error', message } },
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+export function readBootEnv(env) {
+    if (!env.MINIONRY_PORT) {
+        throw new Error('MINIONRY_PORT env var is required');
+    }
+    if (!env.MINIONRY_BOUNCER_SECRET) {
+        throw new Error('MINIONRY_BOUNCER_SECRET env var is required');
+    }
+    if (!env.MINIONRY_CAPABILITY_TOKEN) {
+        throw new Error('MINIONRY_CAPABILITY_TOKEN env var is required');
+    }
+    const port = Number(env.MINIONRY_PORT);
+    if (!Number.isFinite(port) || port <= 0) {
+        throw new Error(`MINIONRY_PORT must be a positive number (got "${env.MINIONRY_PORT}")`);
+    }
+    return {
+        port,
+        bouncerSecret: env.MINIONRY_BOUNCER_SECRET,
+        capabilityToken: env.MINIONRY_CAPABILITY_TOKEN,
+        ...(env.MINIONRY_DEFAULT_TAB_ID ? { defaultTabId: env.MINIONRY_DEFAULT_TAB_ID } : {}),
+        ...(env.MINIONRY_AGENT_LABEL ? { agentLabel: env.MINIONRY_AGENT_LABEL } : {}),
+    };
+}
+async function main() {
+    const cfg = readBootEnv(process.env);
+    const client = createFetchBrowserOpClient({
+        port: cfg.port,
+        bouncerSecret: cfg.bouncerSecret,
+        capabilityToken: cfg.capabilityToken,
+    });
+    const handle = createBrowserMcpServer({
+        client,
+        ...(cfg.defaultTabId ? { defaultTabId: cfg.defaultTabId } : {}),
+    });
+    const transport = new StdioServerTransport();
+    await handle.server.connect(transport);
+    console.error(`[BrowserMcp] connected on stdio${cfg.agentLabel ? ` (${cfg.agentLabel})` : ''} — ${TOOLS.length} tools`);
+    const shutdown = async (reason) => {
+        console.error(`[BrowserMcp] shutting down: ${reason}`);
+        try {
+            await handle.shutdown();
+        }
+        catch (err) {
+            console.error(`[BrowserMcp] shutdown error: ${stringifyError(err)}`);
+        }
+        process.exit(0);
+    };
+    process.stdin.on('end', () => {
+        void shutdown('stdin EOF (parent closed)');
+    });
+    process.stdin.on('close', () => {
+        void shutdown('stdin closed');
+    });
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+}
+const isMain = typeof process !== 'undefined' &&
+    Array.isArray(process.argv) &&
+    process.argv[1] &&
+    /browser-mcp-server\.(t|j)s$/.test(process.argv[1]);
+if (isMain) {
+    main().catch((err) => {
+        console.error(`[BrowserMcp] fatal: ${stringifyError(err)}`);
+        process.exit(1);
+    });
+}