@wong2kim/wmux 1.1.1 → 1.1.2

package/dist/mcp/mcp/playwright/snapshot.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSnapshot = generateSnapshot;
+exports.resolveRef = resolveRef;
+// Roles considered interactive — these get a ref number in 'ai' format
+const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'checkbox',
+    'radio',
+    'combobox',
+    'listbox',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'searchbox',
+    'slider',
+    'spinbutton',
+    'switch',
+    'tab',
+    'treeitem',
+]);
+// ---------------------------------------------------------------------------
+// CDP → AXNode tree builder
+// ---------------------------------------------------------------------------
+function buildTree(nodes) {
+    if (nodes.length === 0)
+        return null;
+    const map = new Map();
+    for (const n of nodes)
+        map.set(n.nodeId, n);
+    function convert(cdp) {
+        if (cdp.ignored)
+            return null;
+        const role = cdp.role?.value ?? 'none';
+        const name = cdp.name?.value ?? '';
+        const node = { role, name };
+        if (cdp.value?.value)
+            node.value = cdp.value.value;
+        if (cdp.description?.value)
+            node.description = cdp.description.value;
+        if (cdp.backendDOMNodeId !== undefined)
+            node.backendDOMNodeId = cdp.backendDOMNodeId;
+        // Extract boolean/enum properties
+        if (cdp.properties) {
+            for (const prop of cdp.properties) {
+                switch (prop.name) {
+                    case 'checked':
+                        node.checked = prop.value.value === 'mixed' ? 'mixed' : !!prop.value.value;
+                        break;
+                    case 'disabled':
+                        node.disabled = !!prop.value.value;
+                        break;
+                    case 'expanded':
+                        node.expanded = !!prop.value.value;
+                        break;
+                    case 'focused':
+                        node.focused = !!prop.value.value;
+                        break;
+                    case 'level':
+                        node.level = Number(prop.value.value);
+                        break;
+                    case 'selected':
+                        node.selected = !!prop.value.value;
+                        break;
+                    case 'pressed':
+                        node.pressed = prop.value.value === 'mixed' ? 'mixed' : !!prop.value.value;
+                        break;
+                    case 'valuetext':
+                        node.valuetext = String(prop.value.value);
+                        break;
+                }
+            }
+        }
+        // Build children
+        if (cdp.childIds && cdp.childIds.length > 0) {
+            const children = [];
+            for (const cid of cdp.childIds) {
+                const child = map.get(cid);
+                if (child) {
+                    const converted = convert(child);
+                    if (converted)
+                        children.push(converted);
+                }
+            }
+            if (children.length > 0)
+                node.children = children;
+        }
+        return node;
+    }
+    return convert(nodes[0]);
+}
+/** Per-page storage of the last generated refMap to avoid concurrency issues */
+const pageRefMaps = new WeakMap();
+function isInteractive(role) {
+    return INTERACTIVE_ROLES.has(role);
+}
+function serializeNode(node, format, currentDepth, maxDepth, indent, refs) {
+    if (currentDepth > maxDepth)
+        return '';
+    const pad = '  '.repeat(indent);
+    const role = node.role;
+    const name = node.name || '';
+    // Build attribute string
+    const attrs = [];
+    if (format === 'ai' && isInteractive(role)) {
+        const ref = refs.length;
+        refs.push({ role, name, backendDOMNodeId: node.backendDOMNodeId });
+        attrs.push(`ref="${ref}"`);
+    }
+    if (node.checked !== undefined)
+        attrs.push(`checked="${node.checked}"`);
+    if (node.disabled)
+        attrs.push('disabled');
+    if (node.expanded !== undefined)
+        attrs.push(`expanded="${node.expanded}"`);
+    if (node.selected)
+        attrs.push('selected');
+    if (node.level !== undefined)
+        attrs.push(`level="${node.level}"`);
+    if (node.valuetext)
+        attrs.push(`valuetext="${node.valuetext}"`);
+    if (node.value)
+        attrs.push(`value="${node.value}"`);
+    const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
+    const nameStr = name ? ` "${name}"` : '';
+    let line = `${pad}- ${role}${nameStr}${attrStr}`;
+    // Recurse into children
+    const childLines = [];
+    if (node.children) {
+        for (const child of node.children) {
+            const childStr = serializeNode(child, format, currentDepth + 1, maxDepth, indent + 1, refs);
+            if (childStr)
+                childLines.push(childStr);
+        }
+    }
+    if (childLines.length > 0) {
+        line += '\n' + childLines.join('\n');
+    }
+    return line;
+}
+function serializeTree(root, format, maxDepth, refs) {
+    const children = root.children ?? [root];
+    const lines = [];
+    for (const child of children) {
+        const s = serializeNode(child, format, 0, maxDepth, 0, refs);
+        if (s)
+            lines.push(s);
+    }
+    return lines.join('\n');
+}
+function stripNonInteractive(node) {
+    if (isInteractive(node.role))
+        return node;
+    if (!node.children)
+        return null;
+    const filtered = node.children
+        .map(stripNonInteractive)
+        .filter((c) => c !== null);
+    if (filtered.length === 0)
+        return null;
+    return { ...node, children: filtered };
+}
+// ---------------------------------------------------------------------------
+// CDP helpers
+// ---------------------------------------------------------------------------
+async function getAccessibilityTree(page) {
+    const client = await page.context().newCDPSession(page);
+    try {
+        const { nodes } = await client.send('Accessibility.getFullAXTree');
+        return buildTree(nodes);
+    }
+    finally {
+        await client.detach().catch(() => { });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate an accessibility-tree snapshot of the page.
+ *
+ * In 'ai' format every interactive element receives a sequential `ref="N"`
+ * attribute that can later be resolved back to an ElementHandle via
+ * `resolveRef()`.
+ *
+ * Uses CDP `Accessibility.getFullAXTree` under the hood to obtain a
+ * structured tree that can be filtered and annotated.
+ */
+async function generateSnapshot(page, options) {
+    const format = options?.format ?? 'ai';
+    const depth = options?.depth ?? 10;
+    const maxLength = options?.maxLength ?? 50000;
+    const tree = await getAccessibilityTree(page);
+    if (!tree) {
+        pageRefMaps.set(page, []);
+        return '(empty page)';
+    }
+    let refs = [];
+    let output = serializeTree(tree, format, depth, refs);
+    // If the output exceeds maxLength AND we are in 'ai' mode, strip
+    // non-interactive nodes and regenerate.
+    if (output.length > maxLength && format === 'ai') {
+        const trimmed = stripNonInteractive(tree);
+        if (trimmed) {
+            refs = [];
+            output = serializeTree(trimmed, format, depth, refs);
+        }
+    }
+    // Hard-truncate as a last resort
+    if (output.length > maxLength) {
+        output = output.slice(0, maxLength) + '\n... (truncated)';
+    }
+    // Store the refMap for this page so resolveRef can use it without re-querying
+    pageRefMaps.set(page, refs);
+    return output;
+}
+/**
+ * Resolve a ref number (produced by `generateSnapshot` with format='ai')
+ * back to a live ElementHandle.
+ *
+ * Uses the refMap stored during the last `generateSnapshot()` call for
+ * the same page, avoiding a full accessibility tree re-query.
+ *
+ * Falls back to role-based locator matching using the stored role+name.
+ */
+async function resolveRef(page, ref) {
+    const targetIndex = parseInt(ref, 10);
+    if (Number.isNaN(targetIndex) || targetIndex < 0)
+        return null;
+    const refs = pageRefMaps.get(page);
+    if (!refs || targetIndex >= refs.length)
+        return null;
+    const target = refs[targetIndex];
+    // Use Playwright's getByRole to locate the element
+    try {
+        const locator = page.getByRole(target.role, {
+            name: target.name || undefined,
+            exact: true,
+        });
+        const count = await locator.count();
+        if (count === 0)
+            return null;
+        // Find which instance corresponds to our ref by counting all
+        // refs with the same role+name before our target index
+        let sameRoleNameBefore = 0;
+        for (let i = 0; i < targetIndex; i++) {
+            if (refs[i].role === target.role &&
+                refs[i].name === target.name) {
+                sameRoleNameBefore++;
+            }
+        }
+        const nth = Math.min(sameRoleNameBefore, count - 1);
+        return await locator.nth(nth).elementHandle();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mcp/mcp/playwright/tools/extraction.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExtractionTools = registerExtractionTools;
+const zod_1 = require("zod");
+const PlaywrightEngine_1 = require("../PlaywrightEngine");
+const dom_intelligence_1 = require("../dom-intelligence");
+const markdown_extractor_1 = require("../markdown-extractor");
+// Optional surfaceId schema reused across tools
+const optionalSurfaceId = zod_1.z
+    .string()
+    .optional()
+    .describe('Target a specific surface by ID. Omit to use the active surface.');
+/**
+ * Register extraction-related MCP tools on the given server.
+ *
+ * Tools:
+ *  - browser_smart_snapshot   -- smart snapshot with indexed interactive elements
+ *  - browser_extract_text     -- extract page content as clean markdown
+ *  - browser_extract_data     -- extract structured data as JSON
+ */
+function registerExtractionTools(server) {
+    const engine = PlaywrightEngine_1.PlaywrightEngine.getInstance();
+    // -----------------------------------------------------------------------
+    // browser_smart_snapshot
+    // -----------------------------------------------------------------------
+    server.tool('browser_smart_snapshot', 'Get a smart snapshot of the page with indexed interactive elements and clean text content. Use element ref numbers with browser_click to interact.', {
+        maxContentLength: zod_1.z
+            .number()
+            .optional()
+            .describe('Maximum length of the content summary in characters (default 3000).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ maxContentLength, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const snapshot = await (0, dom_intelligence_1.getSmartSnapshot)(page, {
+                maxContentLength: maxContentLength ?? 3000,
+            });
+            // Format the snapshot output: indexed elements + content summary
+            const lines = [];
+            lines.push(`Page: ${snapshot.title ?? page.url()}`);
+            lines.push('');
+            if (snapshot.elements && snapshot.elements.length > 0) {
+                lines.push('Interactive Elements:');
+                for (const el of snapshot.elements) {
+                    lines.push(`  [${el.ref}] ${el.role} "${el.name}"${el.description ? ` - ${el.description}` : ''}`);
+                }
+                lines.push('');
+            }
+            if (snapshot.content) {
+                lines.push('Page Content:');
+                lines.push(snapshot.content);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_extract_text
+    // -----------------------------------------------------------------------
+    server.tool('browser_extract_text', 'Extract page content as clean markdown text, stripping navigation and noise.', {
+        selector: zod_1.z
+            .string()
+            .optional()
+            .describe('CSS selector to scope extraction to a specific element.'),
+        maxLength: zod_1.z
+            .number()
+            .optional()
+            .describe('Maximum length of the returned markdown in characters.'),
+        includeLinks: zod_1.z
+            .boolean()
+            .optional()
+            .describe('If true, preserve hyperlinks in the markdown output (default false).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ selector, maxLength, includeLinks, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const markdown = await (0, markdown_extractor_1.extractMarkdown)(page, {
+                selector,
+                maxLength,
+                includeLinks,
+            });
+            return {
+                content: [{ type: 'text', text: markdown }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_extract_data
+    // -----------------------------------------------------------------------
+    server.tool('browser_extract_data', 'Extract structured data from the page (tables, lists, repeated items) as JSON.', {
+        goal: zod_1.z
+            .string()
+            .describe('Description of what data to extract (e.g. "product list", "search results").'),
+        fields: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.string())
+            .describe('Map of field names to their expected types (e.g. { name: "string", price: "number", url: "string" }).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ goal, fields, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const records = await (0, markdown_extractor_1.extractStructuredData)(page, goal, fields);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(records, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/mcp/mcp/playwright/tools/file.js

@@ -0,0 +1,274 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFileTools = registerFileTools;
+const zod_1 = require("zod");
+const PlaywrightEngine_1 = require("../PlaywrightEngine");
+const snapshot_1 = require("../snapshot");
+// Optional surfaceId schema reused across tools
+const optionalSurfaceId = zod_1.z
+    .string()
+    .optional()
+    .describe('Target a specific surface by ID. Omit to use the active surface.');
+/**
+ * Register file-related MCP tools on the given server.
+ *
+ * Tools:
+ *  - browser_file_upload        — upload files to a file input
+ *  - browser_download           — click an element and capture the download
+ *  - browser_wait_for_download  — wait for a download event
+ *  - browser_dialog             — pre-register a dialog accept/dismiss handler
+ */
+function registerFileTools(server) {
+    const engine = PlaywrightEngine_1.PlaywrightEngine.getInstance();
+    // -----------------------------------------------------------------------
+    // browser_file_upload
+    // -----------------------------------------------------------------------
+    server.tool('browser_file_upload', 'Upload files to a file input element. Specify a ref to target a specific input, or omit to use the first file input on the page.', {
+        paths: zod_1.z
+            .array(zod_1.z.string())
+            .describe('Array of absolute file paths to upload.'),
+        ref: zod_1.z
+            .string()
+            .optional()
+            .describe('Ref number of the file input element (from browser_snapshot).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ paths, ref, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            if (ref) {
+                const el = await (0, snapshot_1.resolveRef)(page, ref);
+                if (!el) {
+                    throw new Error(`Could not resolve ref="${ref}" to an element.`);
+                }
+                await el.setInputFiles(paths);
+            }
+            else {
+                // Find the first file input on the page
+                const fileInput = await page.$('input[type="file"]');
+                if (!fileInput) {
+                    throw new Error('No file input element found on the page.');
+                }
+                await fileInput.setInputFiles(paths);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Uploaded ${paths.length} file(s)`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_download
+    // -----------------------------------------------------------------------
+    server.tool('browser_download', 'Click an element (identified by ref) and capture the resulting download. Returns the downloaded file path.', {
+        ref: zod_1.z
+            .string()
+            .describe('Ref number of the element to click to trigger the download.'),
+        filename: zod_1.z
+            .string()
+            .optional()
+            .describe('Optional filename to save the download as.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ ref, filename, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const el = await (0, snapshot_1.resolveRef)(page, ref);
+            if (!el) {
+                throw new Error(`Could not resolve ref="${ref}" to an element.`);
+            }
+            // Start waiting for download before clicking
+            const [download] = await Promise.all([
+                page.waitForEvent('download'),
+                el.click(),
+            ]);
+            let filePath;
+            if (filename) {
+                const path = await Promise.resolve().then(() => __importStar(require('path')));
+                const os = await Promise.resolve().then(() => __importStar(require('os')));
+                const savePath = path.join(os.tmpdir(), filename);
+                await download.saveAs(savePath);
+                filePath = savePath;
+            }
+            else {
+                const downloadPath = await download.path();
+                filePath = downloadPath ?? download.suggestedFilename();
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Downloaded: ${filePath}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_wait_for_download
+    // -----------------------------------------------------------------------
+    server.tool('browser_wait_for_download', 'Wait for a download event on the page. Optionally filter by filename.', {
+        filename: zod_1.z
+            .string()
+            .optional()
+            .describe('Expected filename to match against the download.'),
+        timeout: zod_1.z
+            .number()
+            .optional()
+            .describe('Maximum wait time in milliseconds. Defaults to 30000.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ filename, timeout, surfaceId }) => {
+        const resolvedTimeout = timeout ?? 30000;
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const download = await page.waitForEvent('download', {
+                timeout: resolvedTimeout,
+            });
+            const suggestedName = download.suggestedFilename();
+            if (filename && suggestedName !== filename) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Download received but filename mismatch: expected "${filename}", got "${suggestedName}"`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const downloadPath = await download.path();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            suggestedFilename: suggestedName,
+                            url: download.url(),
+                            path: downloadPath ?? '(pending)',
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('Timeout') || message.includes('timeout')) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Timed out after ${resolvedTimeout}ms waiting for download`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_dialog
+    // -----------------------------------------------------------------------
+    server.tool('browser_dialog', 'Pre-register a handler for the next browser dialog (alert, confirm, prompt, beforeunload). The handler will automatically accept or dismiss the dialog when it appears.', {
+        accept: zod_1.z
+            .boolean()
+            .describe('Whether to accept (true) or dismiss (false) the dialog.'),
+        text: zod_1.z
+            .string()
+            .optional()
+            .describe('Text to enter in a prompt dialog before accepting.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ accept, text, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            page.once('dialog', async (dialog) => {
+                if (accept) {
+                    await dialog.accept(text);
+                }
+                else {
+                    await dialog.dismiss();
+                }
+            });
+            const action = accept ? 'accepted' : 'dismissed';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Dialog handler set. Next dialog will be ${action}.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}