@wong2kim/wmux 1.1.0 → 1.1.2

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

@@ -0,0 +1,410 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStateTools = registerStateTools;
+const zod_1 = require("zod");
+const playwright_core_1 = require("playwright-core");
+const PlaywrightEngine_1 = require("../PlaywrightEngine");
+// 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.');
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/**
+ * Register state-management MCP tools on the given server.
+ *
+ * Tools:
+ *  - browser_cookies  -- get, set, or clear cookies
+ *  - browser_storage  -- get, set, or clear localStorage / sessionStorage
+ *  - browser_emulate  -- apply various emulation settings
+ *  - browser_resize   -- change the viewport size
+ */
+function registerStateTools(server) {
+    const engine = PlaywrightEngine_1.PlaywrightEngine.getInstance();
+    // -----------------------------------------------------------------------
+    // browser_cookies
+    // -----------------------------------------------------------------------
+    server.tool('browser_cookies', 'Manage browser cookies: get, set, or clear cookies for the current browser context.', {
+        action: zod_1.z
+            .enum(['get', 'set', 'clear'])
+            .describe('Action to perform on cookies.'),
+        url: zod_1.z
+            .string()
+            .optional()
+            .describe('URL to filter cookies by (for "get" action).'),
+        cookies: zod_1.z
+            .array(zod_1.z.object({
+            name: zod_1.z.string().describe('Cookie name'),
+            value: zod_1.z.string().describe('Cookie value'),
+            domain: zod_1.z.string().optional().describe('Cookie domain'),
+            path: zod_1.z.string().optional().describe('Cookie path'),
+        }))
+            .optional()
+            .describe('Cookies to set (for "set" action).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ action, url, cookies, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const context = page.context();
+            switch (action) {
+                case 'get': {
+                    const allCookies = await context.cookies(url ? [url] : []);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(allCookies, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'set': {
+                    if (!cookies || cookies.length === 0) {
+                        throw new Error('No cookies provided for "set" action.');
+                    }
+                    // Playwright requires url or domain+path for each cookie
+                    const cookiesToAdd = cookies.map((c) => ({
+                        name: c.name,
+                        value: c.value,
+                        domain: c.domain,
+                        path: c.path ?? '/',
+                        url: !c.domain ? (url ?? page.url()) : undefined,
+                    }));
+                    await context.addCookies(cookiesToAdd);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Set ${cookies.length} cookie(s).`,
+                            },
+                        ],
+                    };
+                }
+                case 'clear': {
+                    await context.clearCookies();
+                    return {
+                        content: [{ type: 'text', text: 'Cookies cleared.' }],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown action: ${action}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_storage
+    // -----------------------------------------------------------------------
+    server.tool('browser_storage', 'Manage localStorage or sessionStorage: get, set, or clear values.', {
+        type: zod_1.z
+            .enum(['local', 'session'])
+            .describe('Storage type: "local" for localStorage, "session" for sessionStorage.'),
+        action: zod_1.z
+            .enum(['get', 'set', 'clear'])
+            .describe('Action to perform.'),
+        key: zod_1.z
+            .string()
+            .optional()
+            .describe('Storage key (for "get" or "set"). Omit for "get" to retrieve all entries.'),
+        value: zod_1.z
+            .string()
+            .optional()
+            .describe('Value to set (for "set" action).'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ type, action, key, value, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const storageName = type === 'local' ? 'localStorage' : 'sessionStorage';
+            switch (action) {
+                case 'get': {
+                    const result = await page.evaluate(([sName, sKey]) => {
+                        const storage = window[sName];
+                        if (sKey) {
+                            return storage.getItem(sKey);
+                        }
+                        // Return all entries
+                        const entries = {};
+                        for (let i = 0; i < storage.length; i++) {
+                            const k = storage.key(i);
+                            if (k !== null) {
+                                entries[k] = storage.getItem(k) ?? '';
+                            }
+                        }
+                        return entries;
+                    }, [storageName, key]);
+                    const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                    return {
+                        content: [{ type: 'text', text: text ?? 'null' }],
+                    };
+                }
+                case 'set': {
+                    if (!key) {
+                        throw new Error('Key is required for "set" action.');
+                    }
+                    await page.evaluate(([sName, sKey, sValue]) => {
+                        const storage = window[sName];
+                        storage.setItem(sKey, sValue);
+                    }, [storageName, key, value ?? '']);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `${storageName}.${key} = "${value ?? ''}"`,
+                            },
+                        ],
+                    };
+                }
+                case 'clear': {
+                    await page.evaluate((sName) => {
+                        const storage = window[sName];
+                        storage.clear();
+                    }, storageName);
+                    return {
+                        content: [
+                            { type: 'text', text: `${storageName} cleared.` },
+                        ],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown action: ${action}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_emulate
+    // -----------------------------------------------------------------------
+    server.tool('browser_emulate', 'Apply emulation settings to the browser page: offline mode, custom headers, HTTP credentials, geolocation, color scheme, timezone, locale, or device preset.', {
+        offline: zod_1.z
+            .boolean()
+            .optional()
+            .describe('Enable or disable offline mode.'),
+        headers: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.string())
+            .optional()
+            .describe('Extra HTTP headers to send with every request.'),
+        credentials: zod_1.z
+            .object({
+            username: zod_1.z.string(),
+            password: zod_1.z.string(),
+        })
+            .nullable()
+            .optional()
+            .describe('HTTP credentials for Basic/Digest auth. Pass null to clear.'),
+        geo: zod_1.z
+            .object({
+            latitude: zod_1.z.number(),
+            longitude: zod_1.z.number(),
+            accuracy: zod_1.z.number().optional(),
+        })
+            .nullable()
+            .optional()
+            .describe('Geolocation override. Pass null to clear.'),
+        media: zod_1.z
+            .enum(['dark', 'light', 'no-preference'])
+            .nullable()
+            .optional()
+            .describe('Color scheme media emulation. Pass null to reset.'),
+        timezone: zod_1.z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Timezone override (e.g. "America/New_York"). Pass null to reset.'),
+        locale: zod_1.z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Locale override (e.g. "en-US"). Pass null to reset.'),
+        device: zod_1.z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Device preset name from Playwright devices (e.g. "iPhone 13"). Pass null to reset.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ offline, headers, credentials, geo, media, timezone, locale, device, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const context = page.context();
+            const applied = [];
+            // offline
+            if (offline !== undefined) {
+                await context.setOffline(offline);
+                applied.push(`offline=${offline}`);
+            }
+            // headers
+            if (headers !== undefined) {
+                await context.setExtraHTTPHeaders(headers);
+                applied.push(`headers=${Object.keys(headers).length} header(s)`);
+            }
+            // credentials
+            if (credentials !== undefined) {
+                try {
+                    await context.setHTTPCredentials(credentials);
+                    applied.push(credentials ? 'credentials=set' : 'credentials=cleared');
+                }
+                catch {
+                    applied.push('credentials=failed (HTTP credentials via context is not supported in CDP mode. Use browser_emulate headers with a Base64-encoded Authorization header instead.)');
+                }
+            }
+            // geo
+            if (geo !== undefined) {
+                if (geo) {
+                    await context.setGeolocation(geo);
+                    await context.grantPermissions(['geolocation']);
+                    applied.push(`geo=${geo.latitude},${geo.longitude}`);
+                }
+                else {
+                    await context.setGeolocation(null);
+                    applied.push('geo=cleared');
+                }
+            }
+            // media / color scheme
+            if (media !== undefined) {
+                await page.emulateMedia({
+                    colorScheme: media,
+                });
+                applied.push(media ? `colorScheme=${media}` : 'colorScheme=reset');
+            }
+            // timezone via CDP
+            if (timezone !== undefined) {
+                const client = await context.newCDPSession(page);
+                try {
+                    if (timezone) {
+                        await client.send('Emulation.setTimezoneOverride', {
+                            timezoneId: timezone,
+                        });
+                        applied.push(`timezone=${timezone}`);
+                    }
+                    else {
+                        await client.send('Emulation.setTimezoneOverride', {
+                            timezoneId: '',
+                        });
+                        applied.push('timezone=reset');
+                    }
+                }
+                finally {
+                    await client.detach().catch(() => { });
+                }
+            }
+            // locale via CDP
+            if (locale !== undefined) {
+                const client = await context.newCDPSession(page);
+                try {
+                    if (locale) {
+                        await client.send('Emulation.setLocaleOverride', {
+                            locale,
+                        });
+                        applied.push(`locale=${locale}`);
+                    }
+                    else {
+                        await client.send('Emulation.setLocaleOverride', {
+                            locale: '',
+                        });
+                        applied.push('locale=reset');
+                    }
+                }
+                finally {
+                    await client.detach().catch(() => { });
+                }
+            }
+            // device preset
+            if (device !== undefined) {
+                if (device) {
+                    const deviceDescriptor = playwright_core_1.devices[device];
+                    if (!deviceDescriptor) {
+                        throw new Error(`Unknown device "${device}". Use a name from Playwright's device list (e.g. "iPhone 13", "Pixel 5").`);
+                    }
+                    await page.setViewportSize(deviceDescriptor.viewport);
+                    // Apply user agent via extra headers
+                    await context.setExtraHTTPHeaders({
+                        ...(headers ?? {}),
+                        'User-Agent': deviceDescriptor.userAgent,
+                    });
+                    applied.push(`device=${device} (${deviceDescriptor.viewport.width}x${deviceDescriptor.viewport.height})`);
+                }
+                else {
+                    applied.push('device=reset (use browser_resize to set viewport)');
+                }
+            }
+            if (applied.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'No emulation settings provided. Pass at least one option.',
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Emulation applied:\n${applied.map((a) => `  - ${a}`).join('\n')}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_resize
+    // -----------------------------------------------------------------------
+    server.tool('browser_resize', 'Resize the browser viewport to the specified dimensions.', {
+        width: zod_1.z.number().describe('Viewport width in pixels.'),
+        height: zod_1.z.number().describe('Viewport height in pixels.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ width, height, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            await page.setViewportSize({ width, height });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Viewport resized to ${width}x${height}`,
+                    },
+                ],
+            };
+        }
+        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/utility.js

@@ -0,0 +1,167 @@
+"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.registerUtilityTools = registerUtilityTools;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const PlaywrightEngine_1 = require("../PlaywrightEngine");
+// 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 utility MCP tools on the given server.
+ *
+ * Tools:
+ *  - browser_pdf   — export the current page as a PDF
+ *  - browser_trace — start or stop Playwright tracing
+ */
+function registerUtilityTools(server) {
+    const engine = PlaywrightEngine_1.PlaywrightEngine.getInstance();
+    // -----------------------------------------------------------------------
+    // browser_pdf
+    // -----------------------------------------------------------------------
+    server.tool('browser_pdf', 'Export the current page as a PDF file. Falls back to CDP Page.printToPDF when Playwright pdf() is unavailable (e.g. CDP-connected browsers).', {
+        path: zod_1.z
+            .string()
+            .optional()
+            .describe('Output file path for the PDF. Defaults to "output.pdf".'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ path: outputPath, surfaceId }) => {
+        const resolvedPath = outputPath ?? 'output.pdf';
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            try {
+                // Try Playwright's built-in pdf() first
+                await page.pdf({ path: resolvedPath, format: 'A4' });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `PDF saved to ${resolvedPath}`,
+                        },
+                    ],
+                };
+            }
+            catch {
+                // Fallback: use CDP Page.printToPDF directly
+                const client = await page.context().newCDPSession(page);
+                try {
+                    const result = await client.send('Page.printToPDF', {
+                        landscape: false,
+                        printBackground: true,
+                    });
+                    const pdfData = result.data;
+                    // Write the base64 data to file
+                    fs.writeFileSync(resolvedPath, Buffer.from(pdfData, 'base64'));
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `PDF saved to ${resolvedPath} (via CDP)`,
+                            },
+                        ],
+                    };
+                }
+                finally {
+                    await client.detach().catch(() => {
+                        /* best-effort */
+                    });
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // browser_trace
+    // -----------------------------------------------------------------------
+    server.tool('browser_trace', 'Start or stop Playwright tracing. Use "start" to begin recording and "stop" to save the trace file.', {
+        action: zod_1.z
+            .enum(['start', 'stop'])
+            .describe('Whether to start or stop tracing.'),
+        path: zod_1.z
+            .string()
+            .optional()
+            .describe('Output file path for the trace (used with "stop"). Defaults to "trace.zip".'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ action, path: outputPath, surfaceId }) => {
+        try {
+            const page = await engine.getPage(surfaceId);
+            if (!page) {
+                throw new Error('No browser page available. Call browser_open first.');
+            }
+            const context = page.context();
+            if (action === 'start') {
+                await context.tracing.start({ screenshots: true, snapshots: true });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Tracing started. Call browser_trace with action "stop" to save the trace.',
+                        },
+                    ],
+                };
+            }
+            // action === 'stop'
+            const resolvedPath = outputPath ?? 'trace.zip';
+            await context.tracing.stop({ path: resolvedPath });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Trace saved to ${resolvedPath}`,
+                    },
+                ],
+            };
+        }
+        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/wait.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWaitTools = registerWaitTools;
+const zod_1 = require("zod");
+const PlaywrightEngine_1 = require("../PlaywrightEngine");
+// 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 wait-related MCP tools on the given server.
+ *
+ * Tools:
+ *  - browser_wait — wait for a URL, selector, text, JS predicate, or network idle
+ */
+function registerWaitTools(server) {
+    const engine = PlaywrightEngine_1.PlaywrightEngine.getInstance();
+    // -----------------------------------------------------------------------
+    // browser_wait
+    // -----------------------------------------------------------------------
+    server.tool('browser_wait', 'Wait for a condition: URL pattern, CSS selector, text content, custom JS predicate, or network idle. Priority: url > selector > text > fn > networkidle.', {
+        url: zod_1.z
+            .string()
+            .optional()
+            .describe('URL or glob pattern to wait for (e.g. "**/dashboard**").'),
+        selector: zod_1.z
+            .string()
+            .optional()
+            .describe('CSS selector to wait for.'),
+        text: zod_1.z
+            .string()
+            .optional()
+            .describe('Text to wait for in document.body.innerText.'),
+        fn: zod_1.z
+            .string()
+            .optional()
+            .describe('Custom JavaScript predicate function body to wait for (must return truthy).'),
+        timeout: zod_1.z
+            .number()
+            .optional()
+            .describe('Maximum wait time in milliseconds. Defaults to 30000.'),
+        surfaceId: optionalSurfaceId,
+    }, async ({ url, selector, text, fn, 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.');
+            }
+            // Priority: url > selector > text > fn > networkidle
+            if (url) {
+                await page.waitForURL(url, { timeout: resolvedTimeout });
+                return {
+                    content: [{ type: 'text', text: `Wait completed: URL matched "${url}"` }],
+                };
+            }
+            if (selector) {
+                await page.waitForSelector(selector, { timeout: resolvedTimeout });
+                return {
+                    content: [{ type: 'text', text: `Wait completed: selector "${selector}" found` }],
+                };
+            }
+            if (text) {
+                await page.waitForFunction((t) => document.body.innerText.includes(t), text, { timeout: resolvedTimeout });
+                return {
+                    content: [{ type: 'text', text: `Wait completed: text "${text}" found` }],
+                };
+            }
+            if (fn) {
+                await page.waitForFunction(fn, undefined, { timeout: resolvedTimeout });
+                return {
+                    content: [{ type: 'text', text: `Wait completed: custom predicate satisfied` }],
+                };
+            }
+            // Default: wait for network idle
+            await page.waitForLoadState('networkidle', { timeout: resolvedTimeout });
+            return {
+                content: [{ type: 'text', text: `Wait completed: network idle` }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Provide clear timeout messaging
+            if (message.includes('Timeout') || message.includes('timeout')) {
+                const condition = url
+                    ? `URL "${url}"`
+                    : selector
+                        ? `selector "${selector}"`
+                        : text
+                            ? `text "${text}"`
+                            : fn
+                                ? 'custom predicate'
+                                : 'network idle';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Timed out after ${resolvedTimeout}ms waiting for ${condition}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}