@thinkrun/mcp 0.3.5

package/dist/src/server.js

@@ -0,0 +1,1454 @@
+/**
+ * ThinkRun MCP Server — exposes browser automation as MCP tools.
+ *
+ * Security: Selectors are validated via cssSelector() zod refinement to reject
+ * script injection attempts. The server-side also applies JSON.stringify()
+ * escaping when embedding selectors in error messages (defense-in-depth).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+/** Zod schema for CSS selectors — rejects obvious script injection patterns. */
+const cssSelector = z
+    .string()
+    .refine((s) => !/<script/i.test(s) && !/javascript:/i.test(s) && !/on\w+\s*=/i.test(s), { message: 'Selector contains potentially unsafe content' });
+/** Absolute http(s) URL — matches service expectations for page-cache targets. */
+const absoluteHttpUrl = z.string().refine((s) => {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}, { message: 'Must be an absolute http(s) URL' });
+/**
+ * MCP tool input for page-cache `options` — keep aligned with
+ * `mech-browser-service/src/routes/cache.ts` (`pageCacheOptionsSchema`).
+ */
+const pageCacheToolOptionsSchema = z
+    .object({
+    provider: z.enum(['cloud', 'local']).optional(),
+    sensitive: z.boolean().optional(),
+    fullPage: z.boolean().optional(),
+    waitFor: z
+        .union([z.enum(['load', 'domcontentloaded', 'networkidle']), z.number().positive()])
+        .optional(),
+    maxDimension: z.number().positive().optional(),
+    viewport: z
+        .object({
+        width: z.number().positive(),
+        height: z.number().positive(),
+    })
+        .optional(),
+    timeout: z.number().positive().optional(),
+    proxy: z
+        .object({
+        server: absoluteHttpUrl.describe('Proxy URL (http or https)'),
+        username: z.string().optional(),
+        password: z.string().optional(),
+    })
+        .optional(),
+    userAgent: z.string().max(2000).optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    javascript: z.boolean().optional(),
+    adBlocking: z.literal(true).optional(),
+    textFormat: z.literal('plain').optional(),
+})
+    .optional();
+export const MAX_GET_HTML_CHARS = 200_000;
+export const MAX_SLEEP_MS = 30_000;
+const LOCAL_TOOL_ENRICH_TIMEOUT_MS = 300;
+const LOCAL_TOOL_ENRICH_BRIDGE_TIMEOUT_MS = 150;
+function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+async function buildLocalToolErrorResult(client, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const payload = {
+        success: false,
+        error: message,
+    };
+    if (typeof err === 'object' && err !== null) {
+        const maybeCode = 'code' in err ? err.code : undefined;
+        const maybeHint = 'hint' in err ? err.hint : undefined;
+        if (typeof maybeCode === 'string' && maybeCode.length > 0)
+            payload.code = maybeCode;
+        if (typeof maybeHint === 'string' && maybeHint.length > 0)
+            payload.hint = maybeHint;
+    }
+    try {
+        const diagnostics = await withTimeout(client.getLocalDiagnostics({ bridgeTimeoutMs: LOCAL_TOOL_ENRICH_BRIDGE_TIMEOUT_MS }), LOCAL_TOOL_ENRICH_TIMEOUT_MS, 'local diagnostics enrichment');
+        if (typeof diagnostics.code === 'string' && diagnostics.code.length > 0 && !payload.code) {
+            payload.code = diagnostics.code;
+        }
+        if (typeof diagnostics.hint === 'string' && diagnostics.hint.length > 0 && !payload.hint) {
+            payload.hint = diagnostics.hint;
+        }
+        if (diagnostics.success) {
+            const continuityState = diagnostics.continuity?.state ?? null;
+            const recoveryState = diagnostics.bridge?.recoveryState ?? null;
+            const extensionConnected = diagnostics.bridge?.extensionConnected ?? null;
+            payload.continuityState = continuityState;
+            payload.recoveryState = recoveryState;
+            payload.extensionConnected = extensionConnected;
+            if (!payload.code) {
+                if (recoveryState === 'recovering') {
+                    payload.code = 'BRIDGE_RECOVERING';
+                }
+                else if (recoveryState === 'flapping' || recoveryState === 'recently_recovered') {
+                    payload.code = 'BRIDGE_UNSTABLE';
+                }
+                else if (extensionConnected === false) {
+                    payload.code = 'LOCAL_BRIDGE_DISCONNECTED';
+                }
+                else if (continuityState === 'stale_reclaimable') {
+                    payload.code = 'STALE_RECLAIMABLE';
+                }
+                else if (continuityState === 'foreign_controller_live') {
+                    payload.code = 'FOREIGN_CONTROLLER_LIVE';
+                }
+                else if (continuityState === 'same_controller_read_resumable'
+                    || continuityState === 'same_controller_missing_runtime_registration'
+                    || continuityState === 'same_controller_missing_mutating_authority_state') {
+                    payload.code = 'SAME_CONTROLLER_CONTINUITY_REPAIRABLE';
+                }
+            }
+            if (!payload.hint) {
+                if (payload.code === 'STALE_RECLAIMABLE') {
+                    payload.hint = 'Run local_diagnostics, confirm the stale lock, then re-attach to reclaim the tab safely.';
+                }
+                else if (payload.code === 'FOREIGN_CONTROLLER_LIVE') {
+                    payload.hint = 'Another local controller still owns this tab. Use a different tab/window or wait for release.';
+                }
+                else if (payload.code === 'SAME_CONTROLLER_CONTINUITY_REPAIRABLE') {
+                    payload.hint = 'Same-controller continuity still exists. Run local_diagnostics, then re-attach to repair the runtime binding.';
+                }
+                else if (payload.code === 'BRIDGE_RECOVERING') {
+                    payload.hint = 'The local bridge is reconnecting automatically. Wait a few seconds, then retry.';
+                }
+                else if (payload.code === 'BRIDGE_UNSTABLE') {
+                    payload.hint = 'The local bridge is unstable after repeated disconnects. Stabilize the browser or reload the extension before retrying.';
+                }
+                else if (payload.code === 'LOCAL_BRIDGE_DISCONNECTED') {
+                    payload.hint = 'Reload the ThinkRun extension in your Chromium-based browser, then retry.';
+                }
+            }
+        }
+    }
+    catch {
+        // best-effort enrichment only
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: true,
+    };
+}
+/**
+ * Apply the PRD's local-session mutation policy without requiring tool registration.
+ * This is exported so tests can lock the behavior down before the MCP tools are added.
+ */
+export function applyLifecycleDefaultSession(args) {
+    switch (args.operation) {
+        case 'tab_attach':
+        case 'window_new':
+            return args.resultSessionId ?? args.currentDefaultSessionId;
+        case 'tab_switch':
+        case 'tab_focus':
+            return args.currentDefaultSessionId;
+        case 'session_release':
+            if (!args.currentDefaultSessionId)
+                return undefined;
+            if (!args.releasedSessionId)
+                return args.currentDefaultSessionId;
+            return args.currentDefaultSessionId === args.releasedSessionId
+                ? undefined
+                : args.currentDefaultSessionId;
+    }
+}
+/**
+ * clear_logs tool handler logic. Exported for unit tests so we can assert
+ * on content/isError without going through the MCP transport.
+ * Catches rejections from client.clearLogs (e.g. network or unexpected API errors)
+ * and returns a structured ToolResult so the MCP tool always responds with content/isError.
+ */
+export async function handleClearLogs(client, args, sidResolver) {
+    try {
+        const result = await client.clearLogs(sidResolver(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.success ? 'Logs cleared.' : (result.error || 'Failed to clear logs'),
+                }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: message }],
+            isError: true,
+        };
+    }
+}
+export async function handleTabAttach(client, args, defaultSessionRef) {
+    try {
+        const result = await client.attachToTab(args.tabId);
+        defaultSessionRef.current = applyLifecycleDefaultSession({
+            currentDefaultSessionId: defaultSessionRef.current,
+            operation: 'tab_attach',
+            resultSessionId: result.sessionId,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleTabSwitch(client, args, defaultSessionRef) {
+    try {
+        const result = await client.switchToTab(args.tabId);
+        defaultSessionRef.current = applyLifecycleDefaultSession({
+            currentDefaultSessionId: defaultSessionRef.current,
+            operation: 'tab_switch',
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ ...result, tabId: args.tabId }, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleWindowNew(client, args, defaultSessionRef) {
+    try {
+        const result = await client.openNewWindow(args.url);
+        defaultSessionRef.current = applyLifecycleDefaultSession({
+            currentDefaultSessionId: defaultSessionRef.current,
+            operation: 'window_new',
+            resultSessionId: result.sessionId,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+// Matches the full local session ID format `local-<tabId>` (e.g. `local-656856474`).
+// Anchored to prevent false positives on cloud session IDs that end in digits
+// (e.g. `remote-session-42` would match the unanchored form and produce a tab ID).
+const LOCAL_SESSION_TAB_ID_RE = /^local-(\d+)$/;
+function extractLocalTabIdFromSessionId(sessionId) {
+    // Local MCP session IDs are expected to end in the underlying tab ID.
+    // `focus` depends on this convention to foreground the bound local tab
+    // without rebinding default session state.
+    const match = sessionId.match(LOCAL_SESSION_TAB_ID_RE);
+    if (!match)
+        return undefined;
+    const parsed = Number(match[1]);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+export async function handleTabFocus(client, args, sidResolver, defaultSessionRef) {
+    try {
+        const sessionId = sidResolver(args);
+        const tabId = extractLocalTabIdFromSessionId(sessionId);
+        if (!tabId) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: `Cannot derive local tab ID from session ${sessionId}` }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const result = await client.switchToTab(tabId);
+        defaultSessionRef.current = applyLifecycleDefaultSession({
+            currentDefaultSessionId: defaultSessionRef.current,
+            operation: 'tab_focus',
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ ...result, tabId }, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleSessionRelease(client, args, defaultSessionRef) {
+    try {
+        const releasedSessionId = args.sessionId ?? defaultSessionRef.current;
+        const result = await client.releaseSession(releasedSessionId);
+        if (result.success) {
+            defaultSessionRef.current = applyLifecycleDefaultSession({
+                currentDefaultSessionId: defaultSessionRef.current,
+                operation: 'session_release',
+                releasedSessionId,
+            });
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ ...result, releasedSessionId: releasedSessionId ?? null }, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleLocalActionRun(client, args) {
+    try {
+        const result = await client.runLocalAction({
+            instruction: args.instruction,
+            maxIterations: args.maxIterations,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleLocalActionStatus(client, args) {
+    try {
+        const result = await client.getLocalActionStatus(args.actionId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleLocalActionCancel(client, args) {
+    try {
+        const result = await client.cancelLocalAction(args.actionId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return buildLocalToolErrorResult(client, err);
+    }
+}
+export async function handleLocalDiagnostics(client) {
+    try {
+        const result = await client.getLocalDiagnostics();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        // Intentionally avoid buildLocalToolErrorResult() here to prevent recursive diagnostics calls.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+            isError: true,
+        };
+    }
+}
+export async function handleLocalResetConnection(client) {
+    try {
+        const result = await client.resetLocalConnection();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        // Intentionally avoid buildLocalToolErrorResult() here to prevent recursive diagnostics calls.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+            isError: true,
+        };
+    }
+}
+export async function handleGetUrl(client, args, sidResolver) {
+    try {
+        const result = await client.evaluate(sidResolver(args), { script: 'window.location.href' });
+        const hasValue = result.result !== undefined && result.result !== null;
+        return {
+            content: [{ type: 'text', text: String(result.result ?? '') }],
+            isError: !result.success || !hasValue,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: message }], isError: true };
+    }
+}
+export async function handleGetTitle(client, args, sidResolver) {
+    try {
+        const result = await client.evaluate(sidResolver(args), { script: 'document.title' });
+        const hasValue = result.result !== undefined && result.result !== null;
+        return {
+            content: [{ type: 'text', text: String(result.result ?? '') }],
+            isError: !result.success || !hasValue,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: message }], isError: true };
+    }
+}
+export async function handleGetHtml(client, args, sidResolver) {
+    try {
+        const result = await client.evaluate(sidResolver(args), { script: 'document.documentElement.outerHTML' });
+        const hasValue = result.result !== undefined && result.result !== null;
+        const html = String(result.result ?? '');
+        const truncated = html.length > MAX_GET_HTML_CHARS;
+        const payload = truncated
+            ? {
+                html: html.slice(0, MAX_GET_HTML_CHARS),
+                truncated: true,
+                originalLength: html.length,
+                returnedLength: MAX_GET_HTML_CHARS,
+            }
+            : {
+                html,
+                truncated: false,
+                originalLength: html.length,
+                returnedLength: html.length,
+            };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: !result.success || !hasValue,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: message }], isError: true };
+    }
+}
+export async function handleSleep(args) {
+    if (args.durationMs < 0 || args.durationMs > MAX_SLEEP_MS) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: `durationMs must be between 0 and ${MAX_SLEEP_MS}`,
+                    }, null, 2),
+                }],
+            isError: true,
+        };
+    }
+    await new Promise((resolve) => setTimeout(resolve, args.durationMs));
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ success: true, durationMs: args.durationMs }, null, 2),
+            }],
+        isError: false,
+    };
+}
+const READY_STATUSES = new Set(['ready', 'running', 'active']);
+export function createServer(client, options) {
+    const defaultSid = options?.defaultSessionId;
+    const defaultSessionRef = options?.defaultSessionRef;
+    const sessionStateRef = defaultSessionRef ?? { current: defaultSid };
+    const clientRef = options?.clientRef;
+    const onSetMode = options?.onSetMode;
+    // Both clientRef and onSetMode must be provided together — set_mode is skipped otherwise
+    if (onSetMode && !clientRef) {
+        console.error('[thinkrun-mcp] Warning: onSetMode provided without clientRef — set_mode will not be registered');
+    }
+    // All tool handlers use c() to get the current client — supports runtime switching via set_mode.
+    // The swap is not atomic with in-flight tool calls. MCP stdio uses sequential request/response,
+    // so concurrent calls are not expected, but future transports may allow pipelining.
+    const c = clientRef ? () => clientRef.current : () => client;
+    const requiredSessionIdSchema = z.string().describe('The session ID');
+    const defaultableSessionIdSchema = z.string().optional().describe('The session ID (auto-injected if omitted when a default session exists)');
+    /** Resolve session ID: use provided value, then ref, then initial default. */
+    function sid(args) {
+        const id = args.sessionId ?? sessionStateRef.current;
+        if (!id)
+            throw new Error('sessionId is required (no default session configured)');
+        return id;
+    }
+    const effectiveDefault = sessionStateRef.current;
+    const server = new McpServer({ name: 'thinkrun', version: '0.1.0' }, {
+        capabilities: { tools: {} },
+        instructions: effectiveDefault
+            ? 'ThinkRun MCP server provides browser automation tools. ' +
+                `A browser session is already active (ID: ${effectiveDefault}). ` +
+                'Use navigation and interaction tools directly — no need to create a session. ' +
+                'Always include a "thought" parameter to document your reasoning.'
+            : 'ThinkRun MCP server provides browser automation tools. ' +
+                'Create a session first, then use navigation and interaction tools. ' +
+                'Always include a "thought" parameter to document your reasoning.',
+    });
+    // ================================================================
+    // Session lifecycle
+    // ================================================================
+    server.registerTool('session_create', {
+        title: 'Create Browser Session',
+        description: 'Create a new browser session. Returns a sessionId to use with all other tools. ' +
+            'In cloud mode, this provisions a dedicated browser machine.',
+        inputSchema: {
+            initialPrompt: z.string().optional().describe('Describe what you plan to do in this session'),
+            viewportWidth: z.number().optional().describe('Viewport width in pixels (default: 1280)'),
+            viewportHeight: z.number().optional().describe('Viewport height in pixels (default: 720)'),
+        },
+    }, async (args) => {
+        const options = {
+            initialPrompt: args.initialPrompt,
+            ...(args.viewportWidth || args.viewportHeight ? {
+                options: {
+                    viewport: {
+                        width: args.viewportWidth || 1280,
+                        height: args.viewportHeight || 720,
+                    },
+                },
+            } : {}),
+        };
+        const result = await c().createSession(options);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('session_status', {
+        title: 'Get Session Status',
+        description: 'Get the current status of a browser session including URL, title, and action count.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().getSession(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('session_delete', {
+        title: 'Delete Browser Session',
+        description: 'Terminate a browser session and clean up resources. Artifacts are preserved.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().deleteSession(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('session_list', {
+        title: 'List Browser Sessions',
+        description: 'List all active browser sessions for this user.',
+    }, async () => {
+        const result = await c().listSessions();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('session_artifacts', {
+        title: 'List Session Artifacts',
+        description: 'List artifacts (screenshots, recording) for a session. ' +
+            'Cloud mode only; returns presigned URLs when available.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().listArtifacts(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('session_wait_ready', {
+        title: 'Wait for Session Ready',
+        description: 'Poll session status until the session is ready (running/active) or timeout. ' +
+            'Use after session_create in cloud mode when the session may still be provisioning.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            timeoutMs: z.number().min(1000).max(300000).optional()
+                .describe('Max wait in milliseconds (default: 60000, max: 300000)'),
+            pollIntervalMs: z.number().min(500).max(10000).optional()
+                .describe('Poll interval in ms (default: 2000)'),
+        },
+    }, async (args) => {
+        const sessionId = sid(args);
+        const timeoutMs = args.timeoutMs ?? 60000;
+        const pollIntervalMs = args.pollIntervalMs ?? 2000;
+        const deadline = Date.now() + timeoutMs;
+        let last = { status: '' };
+        while (Date.now() < deadline) {
+            const result = await c().getSession(sessionId);
+            last = result;
+            if (READY_STATUSES.has(String(result.status).toLowerCase())) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: true, status: result.status, url: result.url, title: result.title }, null, 2),
+                        }],
+                };
+            }
+            await new Promise(r => setTimeout(r, pollIntervalMs));
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: 'Session did not become ready before timeout',
+                        lastStatus: last.status,
+                        url: last.url,
+                        title: last.title,
+                    }, null, 2),
+                }],
+            isError: true,
+        };
+    });
+    server.registerTool('session_use', {
+        title: 'Set Default Session',
+        description: 'Set the default session for subsequent tool calls so you do not need to pass sessionId every time. ' +
+            'Only available when the server was started with a default-session ref (e.g. --session-id).',
+        inputSchema: {
+            sessionId: z.string().describe('The session ID to use as default'),
+        },
+    }, async (args) => {
+        if (!defaultSessionRef) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'Set-default session is not supported (server was not started with a mutable default session)',
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        sessionStateRef.current = args.sessionId;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, defaultSessionId: args.sessionId }, null, 2),
+                }],
+        };
+    });
+    // ================================================================
+    // Mode switching (only registered when clientRef + onSetMode provided)
+    // ================================================================
+    if (clientRef && onSetMode) {
+        server.registerTool('set_mode', {
+            title: 'Switch Connection Mode',
+            description: 'Switch the MCP server between local (Chrome extension) and cloud (ThinkRun API) modes at runtime. ' +
+                'Avoids restarting the CLI. Active sessions from the previous mode are not automatically cleaned up. ' +
+                'The previous client connection is replaced — ensure any active sessions are deleted first.',
+            inputSchema: {
+                mode: z.enum(['local', 'cloud', 'auto']).describe('Target mode: "local" for Chrome extension, "cloud" for ThinkRun API, "auto" to detect'),
+            },
+        }, async (args) => {
+            try {
+                const result = await onSetMode(args.mode);
+                clientRef.current = result.client;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: true, mode: args.mode, resolvedMode: result.resolvedMode }, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: message, mode: args.mode }, null, 2),
+                        }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // ================================================================
+    // Stateless page cache (no sessionId)
+    // ================================================================
+    async function pageCacheToolResult(fn) {
+        try {
+            const result = await fn();
+            const err = !result.success;
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                isError: err,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }, null, 2) }],
+                isError: true,
+            };
+        }
+    }
+    server.registerTool('page_cache_html', {
+        title: 'Page cache — HTML',
+        description: 'Stateless: fetch rendered HTML for a URL without a browser session (no sessionId). ' +
+            'Calls POST /api/cache/html. Cloud usage may consume credits when the service is configured for billing. ' +
+            'Use options.provider "local" or options.sensitive true to avoid third-party fetch when supported.',
+        inputSchema: {
+            url: absoluteHttpUrl.describe('Page URL'),
+            options: pageCacheToolOptionsSchema,
+        },
+    }, async (args) => pageCacheToolResult(() => c().pageCacheHtml({ url: args.url, options: args.options ?? undefined })));
+    server.registerTool('page_cache_text', {
+        title: 'Page cache — text',
+        description: 'Stateless: extract plain text for a URL without a browser session. POST /api/cache/text. ' +
+            'May consume credits in cloud mode.',
+        inputSchema: {
+            url: absoluteHttpUrl.describe('Page URL'),
+            options: pageCacheToolOptionsSchema,
+        },
+    }, async (args) => pageCacheToolResult(() => c().pageCacheText({ url: args.url, options: args.options ?? undefined })));
+    server.registerTool('page_cache_screenshot', {
+        title: 'Page cache — screenshot',
+        description: 'Stateless: capture a PNG for a URL without a session. Returns JSON with artifactUrl when Accept is application/json. ' +
+            'Screenshot path may use more credits than HTML/text.',
+        inputSchema: {
+            url: absoluteHttpUrl.describe('Page URL'),
+            options: pageCacheToolOptionsSchema,
+        },
+    }, async (args) => pageCacheToolResult(() => c().pageCacheScreenshot({ url: args.url, options: args.options ?? undefined })));
+    // ================================================================
+    // Navigation
+    // ================================================================
+    server.registerTool('navigate', {
+        title: 'Navigate to URL',
+        description: 'Navigate the browser to a URL. Waits for page load before returning. ' +
+            'Use captureHtml to get the page HTML in the response.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            url: z.string().describe('The URL to navigate to'),
+            thought: z.string().optional().describe('Why you are navigating here'),
+            waitUntil: z
+                .enum(['load', 'domcontentloaded', 'networkidle'])
+                .optional()
+                .describe('When to consider navigation complete (default: load)'),
+            timeout: z.number().optional().describe('Max wait time in milliseconds'),
+            captureHtml: z.boolean().optional().describe('Capture page HTML after navigation'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().navigate(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('go_back', {
+        title: 'Go Back',
+        description: 'Navigate back to the previous page in browser history.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().goBack(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('go_forward', {
+        title: 'Go Forward',
+        description: 'Navigate forward to the next page in browser history.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().goForward(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('wait_for_element', {
+        title: 'Wait for Element',
+        description: 'Wait for an element to appear on the page. Useful after navigation or clicking ' +
+            'something that triggers dynamic content loading.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.optional().describe('CSS selector to wait for'),
+            state: z
+                .enum(['visible', 'hidden', 'attached'])
+                .optional()
+                .describe('Element state to wait for (default: visible)'),
+            timeout: z.number().optional().describe('Max wait time in milliseconds (default: 30000)'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().wait(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    // ================================================================
+    // Interaction
+    // ================================================================
+    server.registerTool('click', {
+        title: 'Click Element',
+        description: 'Click an element on the page using a CSS selector. ' +
+            'Prefer specific selectors like button[data-testid="submit"] over fragile ones like div > button.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.describe('CSS selector of the element to click'),
+            thought: z.string().optional().describe('Why you are clicking this element'),
+            button: z
+                .enum(['left', 'right', 'middle'])
+                .optional()
+                .describe('Mouse button (default: left)'),
+            clickCount: z.number().optional().describe('Number of clicks (2 for double-click)'),
+            captureHtml: z.boolean().optional().describe('Capture page HTML after click'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().click(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('type_text', {
+        title: 'Type Text',
+        description: 'Type text into an element (appends to existing text, triggers key events). ' +
+            'Use fill instead if you want to replace the current value.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.describe('CSS selector of the input element'),
+            text: z.string().describe('Text to type'),
+            thought: z.string().optional().describe('Why you are typing this'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().type(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('fill', {
+        title: 'Fill Input Field',
+        description: 'Fill a form field with a value (replaces existing content). ' +
+            'Unlike type_text, this clears the field first and sets the value directly.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.describe('CSS selector of the input element'),
+            value: z.string().describe('Value to fill in'),
+            thought: z.string().optional().describe('Why you are filling this field'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().fill(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('press_key', {
+        title: 'Press Keyboard Key',
+        description: 'Press a keyboard key. Common keys: Enter, Tab, Escape, ArrowDown, ArrowUp, Backspace.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            key: z.string().describe('Key to press (e.g. "Enter", "Tab", "Escape", "ArrowDown")'),
+            thought: z.string().optional().describe('Why you are pressing this key'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().press(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('scroll', {
+        title: 'Scroll Page',
+        description: 'Scroll the page or a specific element. Positive y scrolls down, negative scrolls up.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.optional().describe('CSS selector to scroll within (default: page)'),
+            x: z.number().optional().describe('Horizontal scroll pixels'),
+            y: z.number().optional().describe('Vertical scroll pixels (positive = down)'),
+            thought: z.string().optional().describe('Why you are scrolling'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().scroll(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('hover', {
+        title: 'Hover Over Element',
+        description: 'Hover the mouse over an element. Useful for triggering tooltips or dropdown menus.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.describe('CSS selector of the element to hover'),
+            thought: z.string().optional().describe('Why you are hovering'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().hover(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.registerTool('select_option', {
+        title: 'Select Dropdown Option',
+        description: 'Select an option from a <select> dropdown element.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            selector: cssSelector.describe('CSS selector of the <select> element'),
+            value: z.string().describe('Value of the option to select'),
+            thought: z.string().optional().describe('Why you are selecting this option'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().select(sid(args), params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    // ================================================================
+    // Observation
+    // ================================================================
+    server.registerTool('snapshot', {
+        title: 'Page Snapshot',
+        description: 'Get an accessibility tree snapshot of the current page. This is a lightweight ' +
+            'alternative to screenshots that returns structured text representing the page content. ' +
+            'Use this to understand page structure before interacting with elements.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().snapshot(sid(args));
+        if (result.snapshot) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: result.snapshot,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('screenshot', {
+        title: 'Take Screenshot',
+        description: 'Capture a screenshot of the current page. Returns a base64-encoded image. ' +
+            'Use fullPage to capture the entire scrollable page.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            type: z
+                .enum(['png', 'jpeg', 'webp'])
+                .optional()
+                .describe('Image format (default: png)'),
+            fullPage: z.boolean().optional().describe('Capture full scrollable page'),
+            quality: z
+                .number()
+                .min(0)
+                .max(100)
+                .optional()
+                .describe('Image quality for jpeg/webp (0-100)'),
+            maxDimension: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Resize so the largest dimension does not exceed this value (e.g. 1280)'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().screenshot(sid(args), params);
+        if (result.screenshot) {
+            return {
+                content: [{
+                        type: 'image',
+                        data: result.screenshot,
+                        mimeType: `image/${params.type || 'png'}`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('extract', {
+        title: 'Extract Page Content',
+        description: 'Extract content from the page. Types: "text" for visible text, "html" for raw HTML, ' +
+            '"dom" for structured DOM, "evaluate" to run a JavaScript expression.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            type: z
+                .enum(['text', 'html', 'dom', 'evaluate'])
+                .optional()
+                .describe('Extraction type (default: text)'),
+            selector: cssSelector.optional().describe('CSS selector to scope extraction'),
+            script: z.string().optional().describe('JavaScript expression (when type=evaluate)'),
+            attribute: z.string().optional().describe('HTML attribute to extract'),
+            multiple: z.boolean().optional().describe('Extract from all matching elements'),
+        },
+    }, async (args) => {
+        const { sessionId: _sid, ...params } = args;
+        const result = await c().extract(sid(args), params);
+        const extracted = result.text || result.html
+            || (result.data != null ? JSON.stringify(result.data, null, 2) : null);
+        const text = extracted ?? JSON.stringify(result, null, 2);
+        return {
+            content: [{ type: 'text', text }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('evaluate', {
+        title: 'Run JavaScript',
+        description: 'Execute JavaScript in the browser page context. The script runs in the page, ' +
+            'not in Node.js. Simple expressions are auto-wrapped with return.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            script: z.string().describe('JavaScript code to execute in the page'),
+        },
+    }, async (args) => {
+        const result = await c().evaluate(sid(args), { script: args.script });
+        let text;
+        if (result.error) {
+            text = result.error;
+        }
+        else if (result.result === undefined) {
+            text = 'undefined';
+        }
+        else if (result.result === null) {
+            text = 'null';
+        }
+        else if (typeof result.result === 'string') {
+            text = result.result;
+        }
+        else {
+            text = JSON.stringify(result.result, null, 2);
+        }
+        return {
+            content: [{ type: 'text', text }],
+            isError: !result.success,
+        };
+    });
+    // ================================================================
+    // Tab management (local mode)
+    // ================================================================
+    server.registerTool('tab_list', {
+        title: 'List Browser Tabs',
+        description: 'List all open browser tabs. Local mode only. ' +
+            'In cloud mode, each session has a single page.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().listTabs(args.sessionId ?? sessionStateRef.current ?? '');
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('tab_new', {
+        title: 'Open New Tab',
+        description: 'Open a new browser tab, optionally navigating to a URL. Local mode only.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            url: z.string().optional().describe('URL to open in the new tab'),
+        },
+    }, async (args) => {
+        try {
+            const result = await c().newTab(args.sessionId ?? sessionStateRef.current ?? '', args.url);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: String(error) }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('tab_close', {
+        title: 'Close Browser Tab',
+        description: 'Close a browser tab by ID. If no tabId is provided, closes the current tab. Local mode only.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            tabId: z.number().int().positive().optional().describe('Tab ID to close (default: current tab)'),
+        },
+    }, async (args) => {
+        const result = await c().closeTab(sid(args), args.tabId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('tab_attach', {
+        title: 'Attach To Existing Browser Tab',
+        description: 'Attach to an existing local Chrome tab by tab ID and make it the default session. Local mode only.',
+        inputSchema: {
+            tabId: z.number().int().positive().describe('Chrome tab ID to attach to'),
+        },
+    }, (args) => handleTabAttach(c(), args, sessionStateRef));
+    server.registerTool('tab_switch', {
+        title: 'Switch Active Browser Tab',
+        description: 'Switch the active local Chrome tab without rebinding the current default session. Local mode only.',
+        inputSchema: {
+            tabId: z.number().int().positive().describe('Chrome tab ID to switch to'),
+        },
+    }, (args) => handleTabSwitch(c(), args, sessionStateRef));
+    server.registerTool('focus', {
+        title: 'Focus Current Browser Tab',
+        description: 'Bring the currently bound local browser tab/window to the foreground without rebinding the default session. Local mode only.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, (args) => handleTabFocus(c(), args, sid, sessionStateRef));
+    server.registerTool('window_new', {
+        title: 'Open New Browser Window',
+        description: 'Open a new local Chrome window and bind the resulting tab as the default session. Local mode only.',
+        inputSchema: {
+            url: z.string().optional().describe('Optional initial URL for the new window'),
+        },
+    }, (args) => handleWindowNew(c(), args, sessionStateRef));
+    server.registerTool('session_release', {
+        title: 'Release Local Session Ownership',
+        description: 'Release the current local tab ownership without closing the tab. Clears the default session when releasing the bound local session. Local mode only.',
+        inputSchema: {
+            sessionId: z.string().optional().describe('Optional session ID to release (defaults to the current bound local session)'),
+        },
+    }, (args) => handleSessionRelease(c(), args, sessionStateRef));
+    server.registerTool('local_diagnostics', {
+        title: 'Inspect Local Continuity And Bridge State',
+        description: 'Return structured local continuity, ownership, reclaim, and bridge recovery diagnostics. Local mode only.',
+    }, async () => handleLocalDiagnostics(c()));
+    server.registerTool('local_reset_connection', {
+        title: 'Reset Local Circuit Breaker',
+        description: 'Trigger the bounded native-host reset-connection recovery path used for false local circuit-breaker trips. Local mode only.',
+    }, async () => handleLocalResetConnection(c()));
+    server.registerTool('get_url', {
+        title: 'Get Current Page URL',
+        description: 'Return the current page URL for the active session.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, (args) => handleGetUrl(c(), args, sid));
+    server.registerTool('get_title', {
+        title: 'Get Current Page Title',
+        description: 'Return the current page title for the active session.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, (args) => handleGetTitle(c(), args, sid));
+    server.registerTool('get_html', {
+        title: 'Get Current Page HTML',
+        description: 'Return the current page HTML for the active session. Large documents are truncated explicitly in the response.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, (args) => handleGetHtml(c(), args, sid));
+    server.registerTool('sleep', {
+        title: 'Pause Execution',
+        description: `Pause for a bounded duration in milliseconds (max ${MAX_SLEEP_MS}).`,
+        inputSchema: {
+            durationMs: z.number().int().min(0).max(MAX_SLEEP_MS).describe('Pause duration in milliseconds'),
+        },
+    }, handleSleep);
+    // ================================================================
+    // Dialog handling
+    // ================================================================
+    server.registerTool('get_dialog', {
+        title: 'Get Dialog State',
+        description: 'Check for pending browser dialogs (alert, confirm, prompt) and view dialog history. ' +
+            'Use this to detect dialogs that may be blocking page interaction.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().getDialog(sid(args));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('handle_dialog', {
+        title: 'Handle Dialog',
+        description: 'Accept or dismiss a pending browser dialog (alert, confirm, prompt). ' +
+            'For prompt dialogs, you can provide text to enter. ' +
+            'In local mode, dialogs are auto-handled — this returns dialog history.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            accept: z.boolean().optional().describe('Accept (true) or dismiss (false) the dialog. Default: true'),
+            promptText: z.string().optional().describe('Text to enter for prompt dialogs'),
+        },
+    }, async (args) => {
+        const result = await c().handleDialog(sid(args), {
+            accept: args.accept,
+            promptText: args.promptText,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.success ? `Dialog ${args.accept !== false ? 'accepted' : 'dismissed'}` : (result.error || 'Failed to handle dialog'),
+                }],
+            isError: !result.success,
+        };
+    });
+    // ================================================================
+    // Wait for text
+    // ================================================================
+    server.registerTool('wait_for_text', {
+        title: 'Wait for Text',
+        description: 'Wait for specific text to appear on the page. ' +
+            'Useful for waiting for loading states, confirmation messages, or dynamic content.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            text: z.string().max(1000).describe('Text to wait for on the page'),
+            timeout: z.number().min(1000).max(60000).optional().describe('Timeout in ms (default 30000, max 60000)'),
+        },
+    }, async (args) => {
+        const result = await c().waitForText(sid(args), {
+            text: args.text,
+            timeout: args.timeout,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.success ? `Found text: "${args.text}"` : (result.error || `Text "${args.text}" not found`),
+                }],
+            isError: !result.success,
+        };
+    });
+    // ================================================================
+    // Monitoring
+    // ================================================================
+    server.registerTool('console_messages', {
+        title: 'Get Console Messages',
+        description: 'Get browser console messages (log, warn, error) from the current session. ' +
+            'Useful for debugging JavaScript errors or checking application state.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().getConsoleMessages(sid(args));
+        if (result.logs && result.logs.length > 0) {
+            const formatted = result.logs
+                .map(l => `[${l.level}] ${l.text}`)
+                .join('\n');
+            return {
+                content: [{
+                        type: 'text',
+                        text: formatted,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.error || 'No console messages.',
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('network_requests', {
+        title: 'Get Network Requests',
+        description: 'Get network requests made by the browser during this session. ' +
+            'Useful for debugging API calls, checking responses, and monitoring traffic.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, async (args) => {
+        const result = await c().getNetworkRequests(sid(args));
+        if (result.requests && result.requests.length > 0) {
+            const formatted = result.requests
+                .map(r => `${r.method} ${r.url} → ${r.status ?? 'pending'}`)
+                .join('\n');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${result.count} requests:\n${formatted}`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.error || 'No network requests recorded.',
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('clear_logs', {
+        title: 'Clear Console and Network Logs',
+        description: 'Clear console and network logs for the session. ' +
+            'Useful after inspecting logs so the next capture is clean.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+        },
+    }, (args) => handleClearLogs(c(), args, sid));
+    server.registerTool('local_action_run', {
+        title: 'Run Local Action',
+        description: 'Run a direct native-host action against the currently attached local tab. ' +
+            'Local mode only.',
+        inputSchema: {
+            instruction: z.string().min(1).describe('Natural language instruction for the local browser action'),
+            maxIterations: z.number().int().positive().optional().describe('Optional upper bound for AI iterations'),
+        },
+    }, (args) => handleLocalActionRun(c(), args));
+    server.registerTool('local_action_status', {
+        title: 'Get Local Action Status',
+        description: 'Check the status of a previously started local action. Local mode only.',
+        inputSchema: {
+            actionId: z.string().min(1).describe('The action ID returned from local_action_run'),
+        },
+    }, (args) => handleLocalActionStatus(c(), args));
+    server.registerTool('local_action_cancel', {
+        title: 'Cancel Local Action',
+        description: 'Cancel a running local action. Local mode only.',
+        inputSchema: {
+            actionId: z.string().min(1).describe('The action ID to cancel'),
+        },
+    }, (args) => handleLocalActionCancel(c(), args));
+    // ================================================================
+    // Task planning (cloud only)
+    // ================================================================
+    server.registerTool('task_create', {
+        title: 'Create Task Plan',
+        description: 'Create an AI task plan from natural language. The plan breaks your request into ' +
+            'individual browser actions. Cloud mode only.',
+        inputSchema: {
+            sessionId: defaultableSessionIdSchema,
+            text: z.string().describe('Natural language description of what to do'),
+            url: z.string().optional().describe('Starting URL for the task'),
+        },
+    }, async (args) => {
+        const result = await c().createTask({
+            sessionId: sid(args),
+            text: args.text,
+            url: args.url,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('task_execute', {
+        title: 'Execute Task Plan',
+        description: 'Execute a previously created task plan. Cloud mode only.',
+        inputSchema: {
+            planId: z.string().describe('The plan ID returned from task_create'),
+        },
+    }, async (args) => {
+        const result = await c().executeTask(args.planId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool('task_status', {
+        title: 'Get Task Status',
+        description: 'Check the status of a task plan execution. Cloud mode only.',
+        inputSchema: {
+            planId: z.string().describe('The plan ID to check'),
+        },
+    }, async (args) => {
+        const result = await c().getTaskStatus(args.planId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+            isError: !result.success,
+        };
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map