@hotmeshio/long-tail 0.1.0

package/build/system/mcp-servers/playwright/schemas.d.ts

@@ -0,0 +1,383 @@
+import { z } from 'zod';
+export declare const handleProp: z.ZodOptional<z.ZodObject<{
+    type: z.ZodLiteral<"playwright_page">;
+    cdp_endpoint: z.ZodOptional<z.ZodString>;
+    page_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "playwright_page";
+    page_id: string;
+    cdp_endpoint?: string | undefined;
+}, {
+    type: "playwright_page";
+    page_id: string;
+    cdp_endpoint?: string | undefined;
+}>>;
+export declare const navigateSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    wait_until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    url: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>;
+export declare const screenshotSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    url: z.ZodOptional<z.ZodString>;
+    wait_until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    url?: string | undefined;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+    selector?: string | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+    full_page?: boolean | undefined;
+}, {
+    path: string;
+    url?: string | undefined;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+    selector?: string | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+    full_page?: boolean | undefined;
+}>;
+export declare const clickSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    selector: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    selector: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    selector: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;
+export declare const fillSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    selector: z.ZodString;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    selector: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    value: string;
+    selector: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;
+export declare const waitForSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    selector: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    selector: string;
+    timeout?: number | undefined;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    selector: string;
+    timeout?: number | undefined;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;
+export declare const evaluateSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodOptional<z.ZodString>;
+    script: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    script: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    script: string;
+    page_id?: string | undefined;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;
+export declare const listPagesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const closePageSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    page_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    page_id: string;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    page_id: string;
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;
+export declare const runScriptStepSchema: z.ZodObject<{
+    action: z.ZodEnum<["navigate", "screenshot", "click", "fill", "wait_for", "wait_for_url", "wait", "evaluate"]>;
+    url: z.ZodOptional<z.ZodString>;
+    wait_until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+    path: z.ZodOptional<z.ZodString>;
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    script: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    not: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+    value?: string | undefined;
+    not?: boolean | undefined;
+    url?: string | undefined;
+    path?: string | undefined;
+    timeout?: number | undefined;
+    selector?: string | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+    full_page?: boolean | undefined;
+    script?: string | undefined;
+}, {
+    action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+    value?: string | undefined;
+    not?: boolean | undefined;
+    url?: string | undefined;
+    path?: string | undefined;
+    timeout?: number | undefined;
+    selector?: string | undefined;
+    wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+    full_page?: boolean | undefined;
+    script?: string | undefined;
+}>;
+export declare const runScriptSchema: z.ZodObject<{
+    _handle: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"playwright_page">;
+        cdp_endpoint: z.ZodOptional<z.ZodString>;
+        page_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }, {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    }>>;
+    steps: z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<["navigate", "screenshot", "click", "fill", "wait_for", "wait_for_url", "wait", "evaluate"]>;
+        url: z.ZodOptional<z.ZodString>;
+        wait_until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+        path: z.ZodOptional<z.ZodString>;
+        full_page: z.ZodOptional<z.ZodBoolean>;
+        selector: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        script: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        not: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+        value?: string | undefined;
+        not?: boolean | undefined;
+        url?: string | undefined;
+        path?: string | undefined;
+        timeout?: number | undefined;
+        selector?: string | undefined;
+        wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+        full_page?: boolean | undefined;
+        script?: string | undefined;
+    }, {
+        action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+        value?: string | undefined;
+        not?: boolean | undefined;
+        url?: string | undefined;
+        path?: string | undefined;
+        timeout?: number | undefined;
+        selector?: string | undefined;
+        wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+        full_page?: boolean | undefined;
+        script?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+        value?: string | undefined;
+        not?: boolean | undefined;
+        url?: string | undefined;
+        path?: string | undefined;
+        timeout?: number | undefined;
+        selector?: string | undefined;
+        wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+        full_page?: boolean | undefined;
+        script?: string | undefined;
+    }[];
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}, {
+    steps: {
+        action: "fill" | "navigate" | "screenshot" | "click" | "wait_for" | "wait_for_url" | "wait" | "evaluate";
+        value?: string | undefined;
+        not?: boolean | undefined;
+        url?: string | undefined;
+        path?: string | undefined;
+        timeout?: number | undefined;
+        selector?: string | undefined;
+        wait_until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+        full_page?: boolean | undefined;
+        script?: string | undefined;
+    }[];
+    _handle?: {
+        type: "playwright_page";
+        page_id: string;
+        cdp_endpoint?: string | undefined;
+    } | undefined;
+}>;

package/build/system/mcp-servers/playwright/schemas.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runScriptSchema = exports.runScriptStepSchema = exports.closePageSchema = exports.listPagesSchema = exports.evaluateSchema = exports.waitForSchema = exports.fillSchema = exports.clickSchema = exports.screenshotSchema = exports.navigateSchema = exports.handleProp = void 0;
+const zod_1 = require("zod");
+// _handle is accepted by all page-scoped tools. The YAML generator auto-threads
+// it between activities. Agentic (LLM) callers can ignore it — page_id works.
+exports.handleProp = zod_1.z.object({
+    type: zod_1.z.literal('playwright_page'),
+    cdp_endpoint: zod_1.z.string().optional(),
+    page_id: zod_1.z.string(),
+}).optional().describe('Resource handle from a prior Playwright tool call. Enables cross-activity page access.');
+exports.navigateSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().optional()
+        .describe('Reuse an existing page to preserve session (cookies, auth). If omitted, opens a new page.'),
+    url: zod_1.z.string().describe('URL to navigate to'),
+    wait_until: zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).optional()
+        .describe('When to consider navigation complete (default: load)'),
+});
+exports.screenshotSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    url: zod_1.z.string().optional()
+        .describe('URL to navigate to before screenshotting. When used WITH page_id, navigates the existing page (preserving session). Without page_id, opens a new page.'),
+    wait_until: zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).optional()
+        .describe('When to consider navigation complete — only used with url (default: load)'),
+    page_id: zod_1.z.string().optional()
+        .describe('Page to screenshot (default: most recent). When combined with url, navigates that page first (preserving session/cookies).'),
+    path: zod_1.z.string()
+        .describe('File path to save the screenshot PNG'),
+    full_page: zod_1.z.boolean().optional()
+        .describe('Capture the full scrollable page (default: false)'),
+    selector: zod_1.z.string().optional()
+        .describe('CSS selector to screenshot a specific element'),
+});
+exports.clickSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().optional()
+        .describe('Page to act on (default: most recent)'),
+    selector: zod_1.z.string().describe('CSS selector of the element to click'),
+});
+exports.fillSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().optional()
+        .describe('Page to act on (default: most recent)'),
+    selector: zod_1.z.string().describe('CSS selector of the input element'),
+    value: zod_1.z.string().describe('Value to type into the input'),
+});
+exports.waitForSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().optional()
+        .describe('Page to act on (default: most recent)'),
+    selector: zod_1.z.string().describe('CSS selector to wait for'),
+    timeout: zod_1.z.number().optional()
+        .describe('Max wait time in ms (default: 10000)'),
+});
+exports.evaluateSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().optional()
+        .describe('Page to act on (default: most recent)'),
+    script: zod_1.z.string()
+        .describe('JavaScript expression to evaluate in the page context'),
+});
+exports.listPagesSchema = zod_1.z.object({});
+exports.closePageSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    page_id: zod_1.z.string().describe('Page ID to close'),
+});
+exports.runScriptStepSchema = zod_1.z.object({
+    action: zod_1.z.enum(['navigate', 'screenshot', 'click', 'fill', 'wait_for', 'wait_for_url', 'wait', 'evaluate'])
+        .describe('Browser action to perform'),
+    url: zod_1.z.string().optional().describe('URL for navigate action, or URL pattern for wait_for_url'),
+    wait_until: zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).optional()
+        .describe('Navigation wait strategy (default: load)'),
+    path: zod_1.z.string().optional().describe('File path for screenshot action'),
+    full_page: zod_1.z.boolean().optional().describe('Full-page screenshot (default: false)'),
+    selector: zod_1.z.string().optional().describe('CSS selector for click/fill/wait_for/screenshot'),
+    value: zod_1.z.string().optional().describe('Value for fill action'),
+    script: zod_1.z.string().optional().describe('JavaScript for evaluate action'),
+    timeout: zod_1.z.number().optional().describe('Timeout in ms for wait_for/wait_for_url/wait actions'),
+    not: zod_1.z.boolean().optional().describe('For wait_for_url: wait until URL does NOT match (default: false)'),
+});
+exports.runScriptSchema = zod_1.z.object({
+    _handle: exports.handleProp,
+    steps: zod_1.z.array(exports.runScriptStepSchema)
+        .describe('Ordered list of browser actions to execute sequentially on a single page. ' +
+        'Preferred for deterministic YAML workflows — encapsulates an entire browser interaction in one activity.'),
+});

package/build/system/mcp-servers/playwright/tools-atomic.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAtomicTools(srv: McpServer): void;

package/build/system/mcp-servers/playwright/tools-atomic.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAtomicTools = registerAtomicTools;
+const tools_navigation_1 = require("./tools-navigation");
+const tools_page_interaction_1 = require("./tools-page-interaction");
+function registerAtomicTools(srv) {
+    (0, tools_navigation_1.registerNavigationTools)(srv);
+    (0, tools_page_interaction_1.registerPageInteractionTools)(srv);
+}

package/build/system/mcp-servers/playwright/tools-navigation.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerNavigationTools(srv: McpServer): void;

package/build/system/mcp-servers/playwright/tools-navigation.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerNavigationTools = registerNavigationTools;
+const logger_1 = require("../../../services/logger");
+const storage_1 = require("../../../services/storage");
+const browser_lifecycle_1 = require("./browser-lifecycle");
+const schemas_1 = require("./schemas");
+function registerNavigationTools(srv) {
+    // ── navigate ─────────────────────────────────────────────
+    srv.registerTool('navigate', {
+        title: 'Navigate to URL',
+        description: 'Navigate to a URL. Pass page_id or _handle to reuse an existing page (preserving session/cookies). ' +
+            'Without page_id, opens a NEW page — no cookies from prior pages. ' +
+            'IMPORTANT: After login, always pass the page_id to maintain the authenticated session.',
+        inputSchema: schemas_1.navigateSchema,
+    }, async (args) => {
+        let page;
+        let id;
+        // Reuse existing page if page_id or _handle provided (preserves session/cookies)
+        if (args.page_id || args._handle) {
+            try {
+                ({ page, pageId: id } = await (0, browser_lifecycle_1.resolvePage)(args));
+            }
+            catch (err) {
+                if (err.code) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ error: err.message, code: err.code }) }], isError: true };
+                }
+                throw err;
+            }
+        }
+        else {
+            const b = await (0, browser_lifecycle_1.ensureBrowser)();
+            page = await b.newPage();
+            id = (0, browser_lifecycle_1.allocatePageId)();
+            browser_lifecycle_1.pages.set(id, page);
+        }
+        await page.goto(args.url, {
+            waitUntil: args.wait_until || 'load',
+            timeout: 30_000,
+        });
+        const title = await page.title();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        page_id: id,
+                        url: args.url,
+                        title,
+                        _handle: (0, browser_lifecycle_1.buildHandle)(id),
+                    }),
+                }],
+        };
+    });
+    // ── screenshot ───────────────────────────────────────────
+    srv.registerTool('screenshot', {
+        title: 'Take Screenshot',
+        description: 'Capture a screenshot and save as PNG. Accepts _handle or page_id from a prior tool call ' +
+            'for cross-activity access. Pass `url` for self-contained navigate+screenshot. ' +
+            'When both url and page_id are provided, navigates the EXISTING page (preserving session).',
+        inputSchema: schemas_1.screenshotSchema,
+    }, async (args) => {
+        let page;
+        let pageId;
+        if (args.url && (args.page_id || args._handle)) {
+            // Navigate existing page to URL (preserves session/cookies), then screenshot
+            try {
+                ({ page, pageId } = await (0, browser_lifecycle_1.resolvePage)(args));
+                await page.goto(args.url, {
+                    waitUntil: args.wait_until || 'load',
+                    timeout: 30_000,
+                });
+            }
+            catch (err) {
+                if (err.code) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ error: err.message, code: err.code }) }], isError: true };
+                }
+                throw err;
+            }
+        }
+        else if (args.url) {
+            // Self-contained mode: new page + navigate + screenshot (no session)
+            const b = await (0, browser_lifecycle_1.ensureBrowser)();
+            page = await b.newPage();
+            pageId = (0, browser_lifecycle_1.allocatePageId)();
+            browser_lifecycle_1.pages.set(pageId, page);
+            await page.goto(args.url, {
+                waitUntil: args.wait_until || 'load',
+                timeout: 30_000,
+            });
+        }
+        else {
+            // Use _handle or page_id to find existing page
+            try {
+                ({ page, pageId } = await (0, browser_lifecycle_1.resolvePage)(args));
+            }
+            catch (err) {
+                if (err.code) {
+                    return { content: [{ type: 'text', text: JSON.stringify({ error: err.message, code: err.code }) }], isError: true };
+                }
+                throw err;
+            }
+        }
+        // Write screenshot via storage backend (local or S3)
+        const backend = (0, storage_1.getStorageBackend)();
+        const localPath = await backend.getLocalPath(args.path);
+        if (args.selector) {
+            const element = await page.$(args.selector);
+            if (!element) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ error: `Element not found: ${args.selector}` }),
+                        }],
+                    isError: true,
+                };
+            }
+            await element.screenshot({ path: localPath });
+        }
+        else {
+            await page.screenshot({
+                path: localPath,
+                fullPage: args.full_page ?? false,
+            });
+        }
+        const { size } = await backend.commitLocalPath(args.path, localPath);
+        logger_1.loggerRegistry.info(`[lt-mcp:playwright] screenshot saved: ${args.path} (${size} bytes)`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        page_id: pageId,
+                        path: args.path,
+                        size_bytes: size,
+                        url: page.url(),
+                        _handle: (0, browser_lifecycle_1.buildHandle)(pageId),
+                    }),
+                }],
+        };
+    });
+}

package/build/system/mcp-servers/playwright/tools-page-interaction.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPageInteractionTools(srv: McpServer): void;