browser-debugging-daemon 1.0.0

package/mcp_server.js

@@ -0,0 +1,999 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import path from "path";
+import { fileURLToPath } from "url";
+import { BrowserRuntime } from "./runtime/BrowserRuntime.js";
+import { BrowserSubagent } from "./subagent/BrowserSubagent.js";
+import { TaskRunner } from "./orchestrator/TaskRunner.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const runtime = new BrowserRuntime(__dirname);
+const subagent = new BrowserSubagent(runtime);
+const taskRunner = new TaskRunner(__dirname, { runtime, subagent });
+const SUPPORTED_BROWSER_SOURCES = new Set(["auto", "managed", "attached"]);
+const RUN_TERMINAL_STATUSES = new Set(["completed", "failed", "aborted"]);
+const RUN_HANDOFF_STATUSES = new Set(["waiting_for_instruction", "manual_control_requested", "manual_control"]);
+const RUN_WATCH_READY_STATUSES = new Set([...RUN_TERMINAL_STATUSES, ...RUN_HANDOFF_STATUSES]);
+
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function normalizeNumberInRange(value, fallback, { min = null, max = null } = {}) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    if (Number.isFinite(min) && parsed < min) {
+        return min;
+    }
+    if (Number.isFinite(max) && parsed > max) {
+        return max;
+    }
+    return parsed;
+}
+
+function normalizeBrowserSource(source) {
+    const normalized = typeof source === "string" ? source.trim().toLowerCase() : "";
+    if (SUPPORTED_BROWSER_SOURCES.has(normalized)) {
+        return normalized;
+    }
+    return "auto";
+}
+
+function normalizeOptionalBrowserSource(source) {
+    if (typeof source !== "string" || !source.trim()) {
+        return null;
+    }
+    return normalizeBrowserSource(source);
+}
+
+// -----------------------------------------------------------------
+// 2. 初始化 MCP Server
+// -----------------------------------------------------------------
+const server = new Server(
+    {
+        name: "browser-automation-mcp",
+        version: "1.0.0",
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+// -----------------------------------------------------------------
+// 3. 注册可用的 Tools (原生函数调用)
+// -----------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "browser_goto",
+                description: "Navigate the persistent browser to a specified URL.",
+                inputSchema: {
+                    type: "object",
+                    properties: { url: { type: "string", description: "The full URL to navigate to" } },
+                    required: ["url"],
+                },
+            },
+            {
+                name: "browser_observe",
+                description: "Analyze the current page with full observability. Returns: (1) SoM interactive elements with IDs for click/type/hover actions, (2) Accessibility Tree (YAML) for complete page semantics including headings, paragraphs, tables, code blocks, and parent-child structure, (3) page content summary, (4) recent console errors, (5) a full-page screenshot. ALWAYS call this before interacting with the page.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "browser_click",
+                description: "Click an element on the page based on the ID returned by `browser_observe`.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "number", description: "The ID of the Set-of-Mark element" } },
+                    required: ["id"],
+                },
+            },
+            {
+                name: "browser_type",
+                description: "Type text into an input element based on the ID returned by `browser_observe`. Set submit to true to automatically press Enter after typing.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "number", description: "The ID of the Input element" },
+                        text: { type: "string", description: "The text to type" },
+                        submit: { type: "boolean", description: "If true, press Enter after typing to submit the form or send the message." },
+                    },
+                    required: ["id", "text"],
+                },
+            },
+            {
+                name: "browser_hover",
+                description: "Hover over an element on the page based on the ID returned by `browser_observe`.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "number", description: "The ID of the Set-of-Mark element" } },
+                    required: ["id"],
+                },
+            },
+            {
+                name: "browser_keypress",
+                description: "Press a keyboard key such as Enter, Escape, or ArrowDown.",
+                inputSchema: {
+                    type: "object",
+                    properties: { key: { type: "string", description: "The key name to press" } },
+                    required: ["key"],
+                },
+            },
+            {
+                name: "browser_scroll",
+                description: "Scroll the page.",
+                inputSchema: {
+                    type: "object",
+                    properties: { direction: { type: "string", enum: ["down", "up", "top", "bottom"] } },
+                    required: ["direction"],
+                },
+            },
+            {
+                name: "browser_upload",
+                description: "Upload files to a file input element on the page based on the ID returned by `browser_observe`. Supports local file paths and/or base64-encoded file content.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "number", description: "The ID of the file input element from Set-of-Mark observation." },
+                        paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Absolute file paths on the daemon's local filesystem.",
+                        },
+                        files: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    name: { type: "string", description: "Filename with extension." },
+                                    mimeType: { type: "string", description: "MIME type (e.g. image/png)." },
+                                    content: { type: "string", description: "Base64-encoded file content." },
+                                },
+                                required: ["name", "content"],
+                            },
+                            description: "Base64-encoded file objects.",
+                        },
+                    },
+                    required: ["id"],
+                },
+            },
+            {
+                name: "browser_drag",
+                description: "Drag a page element onto another element. Both elements are identified by their Set-of-Mark IDs from `browser_observe`.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        fromId: { type: "number", description: "The ID of the element to drag." },
+                        toId: { type: "number", description: "The ID of the target drop zone element." },
+                    },
+                    required: ["fromId", "toId"],
+                },
+            },
+            {
+                name: "browser_drag_file",
+                description: "Drag local files from the daemon's filesystem onto a page drop zone element. Supports local file paths and/or base64-encoded file content.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        toId: { type: "number", description: "The ID of the drop zone element from Set-of-Mark observation." },
+                        paths: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Absolute file paths on the daemon's local filesystem.",
+                        },
+                        files: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    name: { type: "string", description: "Filename with extension." },
+                                    mimeType: { type: "string", description: "MIME type (e.g. image/png)." },
+                                    content: { type: "string", description: "Base64-encoded file content." },
+                                },
+                                required: ["name", "content"],
+                            },
+                            description: "Base64-encoded file objects.",
+                        },
+                    },
+                    required: ["toId"],
+                },
+            },
+            {
+                name: "browser_debug_state",
+                description: "Return recent console, network, error, and artifact state for the active or last browser session.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "number", description: "How many recent events to include", default: 20 },
+                    },
+                },
+            },
+            {
+                name: "browser_waitFor",
+                description: "Wait for a specific condition on the page before proceeding. Supports waiting for text to appear, text to disappear, a CSS selector to become visible, or a fixed time delay. Use this instead of sleep when you need to synchronize with page state changes (e.g., wait for loading to complete, wait for an element to appear).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "Wait until this text appears anywhere on the page." },
+                        textGone: { type: "string", description: "Wait until this text is no longer present on the page." },
+                        selector: { type: "string", description: "Wait until a CSS selector matches a visible element." },
+                        timeout: { type: "number", description: "Maximum wait time in milliseconds (default 30000, max 300000).", default: 30000 },
+                    },
+                },
+            },
+            {
+                name: "browser_evaluate",
+                description: "Execute JavaScript code in the browser page context and return the result. The `page` Playwright Page object is available. Use for reading page state, extracting data, triggering events, or any custom logic not covered by other tools. Results are serialized (max 8KB).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        expression: { type: "string", description: "JavaScript code to execute. The Playwright `page` object is available as `page`. Example: `return await page.title()`" },
+                    },
+                    required: ["expression"],
+                },
+            },
+            {
+                name: "browser_select_option",
+                description: "Select one or more options in a dropdown (<select>) element identified by its SoM ID from `browser_observe`.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "number", description: "The SoM element ID of the select element." },
+                        values: {
+                            oneOf: [
+                                { type: "string" },
+                                { type: "array", items: { type: "string" } },
+                            ],
+                            description: "The option value(s) to select. String for single, array for multiple.",
+                        },
+                    },
+                    required: ["id", "values"],
+                },
+            },
+            {
+                name: "browser_handle_dialog",
+                description: "Accept or dismiss a browser dialog (alert, confirm, prompt). For prompt dialogs, you can provide text to fill in.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        action: { type: "string", enum: ["accept", "dismiss"], description: "Whether to accept or dismiss the dialog.", default: "accept" },
+                        promptText: { type: "string", description: "Text to enter in a prompt dialog (only used when action is accept)." },
+                    },
+                },
+            },
+            {
+                name: "browser_navigate_back",
+                description: "Go back to the previous page in browser history. Equivalent to clicking the browser back button.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "browser_tabs",
+                description: "Manage browser tabs: list all open tabs, create a new tab, switch to a tab by index, or close a tab.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        action: { type: "string", enum: ["list", "new", "close", "select"], description: "Tab action to perform." },
+                        index: { type: "number", description: "Tab index for 'close' or 'select' actions." },
+                        url: { type: "string", description: "URL to navigate to when creating a new tab." },
+                    },
+                    required: ["action"],
+                },
+            },
+            {
+                name: "delegate_browser_task",
+                description: "Delegate a multi-step browser task to the autonomous browser subagent. The subagent observes the page, chooses actions, and returns a structured summary with artifacts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task_instruction: { type: "string", description: "Detailed browser task to accomplish" },
+                        max_steps: { type: "number", description: "Maximum planning/action steps before stopping", default: 12 },
+                        browser_source: {
+                            type: "string",
+                            enum: ["auto", "managed", "attached"],
+                            description: "Browser source strategy. auto prefers attached Chrome and falls back to managed runtime.",
+                        },
+                        cdp_endpoint: { type: "string", description: "Optional CDP endpoint for attached mode (default http://127.0.0.1:9222)." },
+                        auto_stop: { type: "boolean", description: "Whether to stop the runtime after task completion (default true)." },
+                    },
+                    required: ["task_instruction"],
+                },
+            },
+            {
+                name: "browser_task_start",
+                description: "Start an Antigravity-style background browser run and return a run ID for polling.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        template_id: { type: "string", description: "Optional run template ID. When provided, template defaults are applied." },
+                        task_instruction: { type: "string", description: "Detailed browser task to queue" },
+                        max_steps: { type: "number", description: "Maximum planning/action steps", default: 12 },
+                        browser_source: {
+                            type: "string",
+                            enum: ["auto", "managed", "attached"],
+                            description: "Browser source strategy. auto prefers attached Chrome and falls back to managed runtime.",
+                        },
+                        cdp_endpoint: { type: "string", description: "Optional CDP endpoint for attached mode (default http://127.0.0.1:9222)." },
+                        handoff_timeout_ms: { type: "number", description: "Optional timeout for waiting human instructions." },
+                    },
+                },
+            },
+            {
+                name: "browser_task_get",
+                description: "Get the current state of a previously started browser run.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier returned by browser_task_start" },
+                    },
+                    required: ["run_id"],
+                },
+            },
+            {
+                name: "browser_task_list",
+                description: "List recent browser task runs.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "number", description: "How many runs to return", default: 20 },
+                    },
+                },
+            },
+            {
+                name: "browser_task_reply",
+                description: "Reply to a waiting run with new guidance so the subagent can continue.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier." },
+                        instruction: { type: "string", description: "Guidance from the main agent." },
+                    },
+                    required: ["run_id", "instruction"],
+                },
+            },
+            {
+                name: "browser_task_resume",
+                description: "Resume a run from manual control or waiting state.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier." },
+                        instruction: { type: "string", description: "Resume instruction (optional)." },
+                    },
+                    required: ["run_id"],
+                },
+            },
+            {
+                name: "browser_task_manual_control",
+                description: "Request manual control for an active run.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier." },
+                        reason: { type: "string", description: "Why manual control is needed." },
+                    },
+                    required: ["run_id"],
+                },
+            },
+            {
+                name: "browser_task_abort",
+                description: "Abort an active or queued run.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier." },
+                        reason: { type: "string", description: "Abort reason." },
+                    },
+                    required: ["run_id"],
+                },
+            },
+            {
+                name: "browser_task_watch",
+                description: "Wait until a run reaches a terminal or handoff-required state, then return the latest run snapshot.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        run_id: { type: "string", description: "Run identifier." },
+                        timeout_ms: { type: "number", description: "Maximum wait time.", default: 30000 },
+                        poll_interval_ms: { type: "number", description: "Polling interval.", default: 1500 },
+                    },
+                    required: ["run_id"],
+                },
+            },
+            {
+                name: "browser_template_save",
+                description: "Create or update a reusable run template with start URL, login checks, assertions, and timeout policy.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Optional existing template ID for updates." },
+                        name: { type: "string", description: "Template display name." },
+                        description: { type: "string", description: "Optional template description." },
+                        task_instruction: { type: "string", description: "Default task instruction for this template." },
+                        browser_source: { type: "string", enum: ["auto", "managed", "attached"] },
+                        cdp_endpoint: { type: "string" },
+                        start_url: { type: "string", description: "Fixed URL to open before task execution." },
+                        pre_login_checks: {
+                            type: "array",
+                            description: "Array of checks with kind/url_includes|title_includes|text_includes and expected.",
+                            items: { type: "object" },
+                        },
+                        assertion_rules: {
+                            type: "array",
+                            description: "Array of assertions with kind/url_includes|title_includes|text_includes and expected.",
+                            items: { type: "object" },
+                        },
+                        timeout_policy: {
+                            type: "object",
+                            properties: {
+                                max_steps: { type: "number" },
+                                handoff_timeout_ms: { type: "number" },
+                            },
+                        },
+                    },
+                    required: ["name"],
+                },
+            },
+            {
+                name: "browser_template_list",
+                description: "List reusable run templates.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "number", default: 100 },
+                    },
+                },
+            },
+            {
+                name: "browser_template_run",
+                description: "Queue a new run directly from a template ID.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        template_id: { type: "string" },
+                        task_instruction: { type: "string" },
+                        max_steps: { type: "number" },
+                        browser_source: { type: "string", enum: ["auto", "managed", "attached"] },
+                        cdp_endpoint: { type: "string" },
+                        handoff_timeout_ms: { type: "number" },
+                    },
+                    required: ["template_id"],
+                },
+            },
+            {
+                name: "browser_template_compare",
+                description: "Compare recent runs created from the same template.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        template_id: { type: "string" },
+                        limit: { type: "number", default: 8 },
+                    },
+                    required: ["template_id"],
+                },
+            },
+            {
+                name: "browser_stop",
+                description: "Stop the browser and save the debug trace recording (.zip). Use this when the testing task is complete.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "browser_cdp_health",
+                description: "Check whether the target Chrome remote debugging endpoint is reachable.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        cdp_endpoint: { type: "string", description: "CDP endpoint such as http://127.0.0.1:9222" },
+                        timeout_ms: { type: "number", description: "Health-check timeout in milliseconds", default: 3000 },
+                    },
+                },
+            },
+            {
+                name: "browser_text_layout_audit",
+                description: "Audit visible UI text for overflow risk using canvas-based line estimation and actual overflow checks.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: { type: "number", description: "Maximum number of candidate elements to inspect", default: 80 },
+                        selectors: { type: "string", description: "Optional CSS selector list used to pick text-bearing elements." },
+                        overflow_threshold: { type: "number", description: "Pixel threshold before overflow is considered an issue.", default: 1 },
+                    },
+                },
+            },
+            {
+                name: "browser_attach_diagnostics",
+                description: "Run one-shot diagnostics for attaching to an existing Chrome session and return remediation hints.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        cdp_endpoint: { type: "string", description: "CDP endpoint such as http://127.0.0.1:9222" },
+                        timeout_ms: { type: "number", description: "Diagnostics timeout in milliseconds", default: 3000 },
+                    },
+                },
+            },
+        ],
+    };
+});
+
+// -----------------------------------------------------------------
+// 4. 处理客户端的 Tools 调用
+// -----------------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        switch (request.params.name) {
+            case "browser_goto": {
+                const url = request.params.arguments.url;
+                const result = await runtime.goto(url);
+
+                const gotoParts = [
+                    { type: "text", text: `Successfully navigated to ${result.url}` },
+                ];
+
+                if (result.metadata) {
+                    gotoParts.push({ type: "text", text: `# Page Metadata\n${JSON.stringify(result.metadata, null, 2)}` });
+                }
+
+                if (result.accessibilityTree) {
+                    gotoParts.push({ type: "text", text: `# Accessibility Tree (YAML)\n${result.accessibilityTree}` });
+                }
+
+                if (result.pageContent && Object.keys(result.pageContent).length > 0) {
+                    gotoParts.push({ type: "text", text: `# Page Content\n${JSON.stringify(result.pageContent, null, 2)}` });
+                }
+
+                gotoParts.push({ type: "text", text: `# Interactive Elements (SoM)\n${JSON.stringify(result.elements, null, 2)}` });
+
+                return { content: gotoParts };
+            }
+
+            case "browser_observe": {
+                const result = await runtime.observe();
+
+                const parts = [
+                    { type: "text", text: `Observation complete. Check ${result.screenshotPath} for reference.` },
+                ];
+
+                if (result.accessibilityTree) {
+                    parts.push({ type: "text", text: `# Accessibility Tree (YAML)\n${result.accessibilityTree}` });
+                }
+
+                if (result.pageContent && Object.keys(result.pageContent).length > 0) {
+                    parts.push({ type: "text", text: `# Page Content\n${JSON.stringify(result.pageContent, null, 2)}` });
+                }
+
+                if (result.recentErrors && result.recentErrors.length > 0) {
+                    parts.push({ type: "text", text: `# Recent Console Errors\n${JSON.stringify(result.recentErrors, null, 2)}` });
+                }
+
+                parts.push({ type: "text", text: `# Interactive Elements (SoM)\n${JSON.stringify(result.elements, null, 2)}` });
+
+                return { content: parts };
+            }
+
+            case "browser_click": {
+                const id = request.params.arguments.id;
+                const result = await runtime.click(id);
+                return { content: [{ type: "text", text: `Successfully clicked element ${id} [${result.target.tag}]` }] };
+            }
+
+            case "browser_type": {
+                const { id, text, submit } = request.params.arguments;
+                await runtime.type(id, text, { submit: !!submit });
+                return { content: [{ type: "text", text: `Successfully typed "${text}" into element ${id}${submit ? " and pressed Enter" : ""}` }] };
+            }
+
+            case "browser_hover": {
+                const id = request.params.arguments.id;
+                const result = await runtime.hover(id);
+                return { content: [{ type: "text", text: `Successfully hovered element ${id} [${result.target.tag}]` }] };
+            }
+
+            case "browser_keypress": {
+                const key = request.params.arguments.key;
+                await runtime.keypress(key);
+                return { content: [{ type: "text", text: `Successfully pressed ${key}` }] };
+            }
+
+            case "browser_scroll": {
+                const dir = request.params.arguments.direction;
+                await runtime.scroll(dir);
+                return { content: [{ type: "text", text: `Scrolled ${dir}` }] };
+            }
+
+            case "browser_upload": {
+                const uploadArgs = request.params.arguments;
+                const uploadResult = await runtime.upload(uploadArgs.id, {
+                    paths: uploadArgs.paths || [],
+                    files: uploadArgs.files || [],
+                });
+                return { content: [{ type: "text", text: `Uploaded ${uploadResult.fileCount} file(s) to element ${uploadArgs.id}` }] };
+            }
+
+            case "browser_drag": {
+                const dragArgs = request.params.arguments;
+                const dragResult = await runtime.drag(dragArgs.fromId, dragArgs.toId);
+                return { content: [{ type: "text", text: `Dragged element ${dragArgs.fromId} onto element ${dragArgs.toId}` }] };
+            }
+
+            case "browser_drag_file": {
+                const dragFileArgs = request.params.arguments;
+                const dragFileResult = await runtime.dragFile({
+                    paths: dragFileArgs.paths || [],
+                    files: dragFileArgs.files || [],
+                    toId: dragFileArgs.toId,
+                });
+                return { content: [{ type: "text", text: `Dragged ${dragFileResult.fileCount} file(s) onto element ${dragFileArgs.toId}` }] };
+            }
+
+            case "browser_debug_state": {
+                const limit = request.params.arguments?.limit ?? 20;
+                return {
+                    content: [{ type: "text", text: JSON.stringify(runtime.getDebugState(limit), null, 2) }]
+                };
+            }
+
+            case "browser_waitFor": {
+                const waitArgs = request.params.arguments || {};
+                const waitResult = await runtime.waitFor({
+                    text: waitArgs.text,
+                    textGone: waitArgs.textGone,
+                    selector: waitArgs.selector,
+                    timeout: waitArgs.timeout,
+                });
+                const waitMsg = waitResult.timedOut
+                    ? `Timed out after ${waitResult.waitedMs}ms waiting for ${waitArgs.text || waitArgs.textGone || waitArgs.selector}`
+                    : `Condition met (${waitResult.matched}) after ${waitResult.waitedMs}ms`;
+                return { content: [{ type: "text", text: waitMsg }] };
+            }
+
+            case "delegate_browser_task": {
+                const taskInstruction = request.params.arguments.task_instruction;
+                const maxSteps = request.params.arguments?.max_steps ?? 12;
+                const browserSource = normalizeBrowserSource(request.params.arguments?.browser_source);
+                const cdpEndpoint = request.params.arguments?.cdp_endpoint;
+                const autoStop = request.params.arguments?.auto_stop !== false;
+                let result = await subagent.delegateTask(taskInstruction, {
+                    maxSteps,
+                    startOptions: {
+                        source: browserSource,
+                        cdpEndpoint: cdpEndpoint || undefined,
+                    },
+                });
+
+                if (autoStop) {
+                    const stopResult = await runtime.stop().catch(() => null);
+                    if (stopResult?.artifacts) {
+                        result.artifacts = stopResult.artifacts;
+                        result.debug = {
+                            ...(result.debug || {}),
+                            artifacts: stopResult.artifacts,
+                        };
+                        const refreshedReports = subagent.writeReports(result);
+                        result.reports = refreshedReports;
+                    }
+                }
+
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+                };
+            }
+
+            case "browser_task_start": {
+                const templateId = request.params.arguments?.template_id;
+                const taskInstruction = request.params.arguments?.task_instruction || "";
+                const maxSteps = request.params.arguments?.max_steps;
+                const browserSource = normalizeOptionalBrowserSource(request.params.arguments?.browser_source);
+                const cdpEndpoint = request.params.arguments?.cdp_endpoint;
+                const handoffTimeoutMs = request.params.arguments?.handoff_timeout_ms;
+                const run = templateId
+                    ? taskRunner.createRunFromTemplate(templateId, {
+                        taskInstruction,
+                        maxSteps,
+                        browserSource: browserSource || undefined,
+                        cdpEndpoint: cdpEndpoint || null,
+                        handoffTimeoutMs,
+                    })
+                    : taskRunner.createRun(taskInstruction, {
+                        maxSteps: maxSteps ?? 12,
+                        browserSource,
+                        cdpEndpoint: cdpEndpoint || null,
+                        handoffTimeoutMs,
+                    });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_get": {
+                const runId = request.params.arguments.run_id;
+                const run = taskRunner.getRun(runId);
+                if (!run) {
+                    throw new Error(`Run not found: ${runId}`);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_list": {
+                const limit = request.params.arguments?.limit ?? 20;
+                return {
+                    content: [{ type: "text", text: JSON.stringify(taskRunner.listRuns(limit), null, 2) }]
+                };
+            }
+
+            case "browser_task_reply": {
+                const runId = request.params.arguments?.run_id;
+                const instruction = String(request.params.arguments?.instruction || "").trim();
+                if (!instruction) {
+                    throw new Error("instruction is required.");
+                }
+                const run = await taskRunner.replyToRun(runId, instruction);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_resume": {
+                const runId = request.params.arguments?.run_id;
+                const instruction = typeof request.params.arguments?.instruction === "string"
+                    ? request.params.arguments.instruction.trim()
+                    : "";
+                const run = instruction
+                    ? await taskRunner.resumeRun(runId, instruction)
+                    : await taskRunner.resumeRun(runId);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_manual_control": {
+                const runId = request.params.arguments?.run_id;
+                const reason = String(request.params.arguments?.reason || "Manual control requested by operator.").trim();
+                const run = await taskRunner.requestManualControl(runId, reason);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_abort": {
+                const runId = request.params.arguments?.run_id;
+                const reason = String(request.params.arguments?.reason || "Run aborted by operator.").trim();
+                const run = taskRunner.abortRun(runId, reason);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }]
+                };
+            }
+
+            case "browser_task_watch": {
+                const runId = request.params.arguments?.run_id;
+                const timeoutMs = normalizeNumberInRange(
+                    request.params.arguments?.timeout_ms,
+                    30000,
+                    { min: 0, max: 5 * 60 * 1000 }
+                );
+                const pollIntervalMs = normalizeNumberInRange(
+                    request.params.arguments?.poll_interval_ms,
+                    1500,
+                    { min: 200, max: 10000 }
+                );
+
+                let run = taskRunner.getRun(runId);
+                if (!run) {
+                    throw new Error(`Run not found: ${runId}`);
+                }
+
+                const startedAt = Date.now();
+                const isReady = (candidate) => candidate && RUN_WATCH_READY_STATUSES.has(candidate.status);
+                while (!isReady(run) && (Date.now() - startedAt) < timeoutMs) {
+                    const elapsed = Date.now() - startedAt;
+                    const remaining = timeoutMs - elapsed;
+                    const waitMs = Math.max(50, Math.min(pollIntervalMs, remaining));
+                    await sleep(waitMs);
+                    run = taskRunner.getRun(runId);
+                    if (!run) {
+                        throw new Error(`Run not found: ${runId}`);
+                    }
+                }
+
+                const endedAt = Date.now();
+                const timedOut = !isReady(run);
+                const watchResult = {
+                    run,
+                    watch: {
+                        runId,
+                        timedOut,
+                        waitedMs: endedAt - startedAt,
+                        readyStatuses: Array.from(RUN_WATCH_READY_STATUSES),
+                    },
+                };
+
+                return {
+                    content: [{ type: "text", text: JSON.stringify(watchResult, null, 2) }]
+                };
+            }
+
+            case "browser_template_save": {
+                const args = request.params.arguments || {};
+                const template = taskRunner.saveTemplate({
+                    id: args.id,
+                    name: args.name,
+                    description: args.description,
+                    taskInstruction: args.task_instruction,
+                    browserSource: normalizeOptionalBrowserSource(args.browser_source) || "auto",
+                    cdpEndpoint: args.cdp_endpoint || null,
+                    startUrl: args.start_url,
+                    preLoginChecks: args.pre_login_checks || [],
+                    assertionRules: args.assertion_rules || [],
+                    timeoutPolicy: {
+                        maxSteps: args.timeout_policy?.max_steps,
+                        handoffTimeoutMs: args.timeout_policy?.handoff_timeout_ms,
+                    },
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(template, null, 2) }],
+                };
+            }
+
+            case "browser_template_list": {
+                const limit = request.params.arguments?.limit ?? 100;
+                return {
+                    content: [{ type: "text", text: JSON.stringify(taskRunner.listTemplates(limit), null, 2) }],
+                };
+            }
+
+            case "browser_template_run": {
+                const args = request.params.arguments || {};
+                const run = taskRunner.createRunFromTemplate(args.template_id, {
+                    taskInstruction: args.task_instruction || "",
+                    maxSteps: args.max_steps,
+                    browserSource: normalizeOptionalBrowserSource(args.browser_source) || undefined,
+                    cdpEndpoint: args.cdp_endpoint || null,
+                    handoffTimeoutMs: args.handoff_timeout_ms,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(run, null, 2) }],
+                };
+            }
+
+            case "browser_template_compare": {
+                const args = request.params.arguments || {};
+                const comparison = taskRunner.compareTemplateRuns(args.template_id, {
+                    limit: args.limit ?? 8,
+                });
+                if (!comparison.template) {
+                    throw new Error(`Template not found: ${args.template_id}`);
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(comparison, null, 2) }],
+                };
+            }
+
+            case "browser_stop": {
+                const result = await runtime.stop();
+                if (result.alreadyStopped) {
+                    return { content: [{ type: "text", text: "Browser already stopped." }] };
+                }
+                return { content: [{ type: "text", text: `Browser stopped. Session saved. Trace: ${result.artifacts?.tracePath}` }] };
+            }
+
+            case "browser_cdp_health": {
+                const cdpEndpoint = request.params.arguments?.cdp_endpoint;
+                const timeoutMs = request.params.arguments?.timeout_ms ?? 3000;
+                const health = await runtime.getCdpHealth({
+                    endpoint: cdpEndpoint,
+                    timeoutMs,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(health, null, 2) }],
+                    isError: !health.ok,
+                };
+            }
+
+            case "browser_text_layout_audit": {
+                const audit = await runtime.auditTextLayout({
+                    limit: request.params.arguments?.limit ?? 80,
+                    selectors: request.params.arguments?.selectors,
+                    overflowThreshold: request.params.arguments?.overflow_threshold,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(audit, null, 2) }],
+                };
+            }
+
+            case "browser_attach_diagnostics": {
+                const diagnostics = await runtime.getCdpDiagnostics({
+                    endpoint: request.params.arguments?.cdp_endpoint,
+                    timeoutMs: request.params.arguments?.timeout_ms ?? 3000,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(diagnostics, null, 2) }],
+                    isError: !diagnostics.ok,
+                };
+            }
+
+            case "browser_evaluate": {
+                const expression = request.params.arguments.expression;
+                if (!expression) {
+                    throw new Error("'expression' is required.");
+                }
+                const result = await runtime.evaluate(expression);
+                return {
+                    content: [{ type: "text", text: result.result }],
+                    isError: result.isError,
+                };
+            }
+
+            case "browser_select_option": {
+                const { id, values } = request.params.arguments;
+                const result = await runtime.selectOption(id, values);
+                return { content: [{ type: "text", text: `Selected option(s) ${JSON.stringify(values)} in element ${id}` }] };
+            }
+
+            case "browser_handle_dialog": {
+                const action = request.params.arguments?.action || "accept";
+                const promptText = request.params.arguments?.promptText || "";
+                const result = await runtime.handleDialog({ action, promptText });
+                if (!result.handled) {
+                    return { content: [{ type: "text", text: result.message }] };
+                }
+                return { content: [{ type: "text", text: `Dialog ${result.action}: type=${result.dialogInfo.type}, message="${result.dialogInfo.message}"` }] };
+            }
+
+            case "browser_navigate_back": {
+                const result = await runtime.goBack();
+                return { content: [{ type: "text", text: `Navigated back to ${result.url}` }] };
+            }
+
+            case "browser_tabs": {
+                const tabAction = request.params.arguments.action;
+                const tabIndex = request.params.arguments.index;
+                const tabUrl = request.params.arguments.url;
+                const result = await runtime.tabAction(tabAction, { index: tabIndex, url: tabUrl });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+
+            default:
+                throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+    } catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+
+// -----------------------------------------------------------------
+// 5. 启动 MCP Server 管道
+// -----------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Browser Automation MCP Server running on stdio");
+}
+
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});