@hotmeshio/long-tail 0.1.0

package/build/system/mcp-servers/human-queue.d.ts

@@ -0,0 +1,26 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create the Long Tail Human Queue MCP server.
+ *
+ * Registers five tools that expose the escalation API:
+ * - escalate_to_human — create a new escalation (fire-and-forget)
+ * - check_resolution — check escalation status
+ * - get_available_work — list available escalations by role
+ * - claim_and_resolve — claim + resolve in one step
+ * - escalate_and_wait — create escalation and return signal for durable wait
+ *
+ * The server is created with tools registered but no transport
+ * auto-connected. Callers connect a transport programmatically
+ * or via the Streamable HTTP endpoint.
+ */
+export declare function createHumanQueueServer(options?: {
+    name?: string;
+}): Promise<McpServer>;
+/**
+ * Get the current MCP server instance.
+ */
+export declare function getServer(): McpServer | null;
+/**
+ * Stop the MCP server and release resources.
+ */
+export declare function stopServer(): Promise<void>;

package/build/system/mcp-servers/human-queue.js

@@ -0,0 +1,287 @@
+"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.createHumanQueueServer = createHumanQueueServer;
+exports.getServer = getServer;
+exports.stopServer = stopServer;
+const crypto = __importStar(require("crypto"));
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const logger_1 = require("../../services/logger");
+const escalationService = __importStar(require("../../services/escalation"));
+let server = null;
+// ── Schemas (extracted to break TS2589 deep-instantiation in registerTool generics) ──
+const escalateSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
+    message: zod_1.z.string().describe('Description of what needs human review'),
+    data: zod_1.z.record(zod_1.z.any()).optional().describe('Contextual data for the reviewer'),
+    type: zod_1.z.string().optional().default('mcp').describe('Escalation type classification'),
+    subtype: zod_1.z.string().optional().default('tool_call').describe('Escalation subtype'),
+    priority: zod_1.z.number().min(1).max(4).optional().default(2)
+        .describe('Priority: 1 (highest) to 4 (lowest)'),
+});
+const checkResolutionSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation ID to check'),
+});
+const getAvailableWorkSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Role to filter by'),
+    limit: zod_1.z.number().optional().default(10).describe('Max results to return'),
+});
+const claimAndResolveSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation ID to claim and resolve'),
+    resolver_id: zod_1.z.string().describe('Identifier for who/what is resolving'),
+    payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
+});
+const escalateAndWaitSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
+    message: zod_1.z.string().describe('Description of what input is needed from the human'),
+    form_schema: zod_1.z.record(zod_1.z.any()).optional()
+        .describe('JSON Schema for the resolver form. Use format:"password" for sensitive fields.'),
+    data: zod_1.z.record(zod_1.z.any()).optional().describe('Contextual data for the reviewer'),
+    assigned_to: zod_1.z.string().optional().describe('Auto-assign to a specific user'),
+    type: zod_1.z.string().optional().default('mcp').describe('Escalation type classification'),
+    subtype: zod_1.z.string().optional().default('wait_for_human').describe('Escalation subtype'),
+    priority: zod_1.z.number().min(1).max(4).optional().default(1)
+        .describe('Priority: 1 (highest) to 4 (lowest)'),
+}).passthrough();
+/**
+ * Create the Long Tail Human Queue MCP server.
+ *
+ * Registers five tools that expose the escalation API:
+ * - escalate_to_human — create a new escalation (fire-and-forget)
+ * - check_resolution — check escalation status
+ * - get_available_work — list available escalations by role
+ * - claim_and_resolve — claim + resolve in one step
+ * - escalate_and_wait — create escalation and return signal for durable wait
+ *
+ * The server is created with tools registered but no transport
+ * auto-connected. Callers connect a transport programmatically
+ * or via the Streamable HTTP endpoint.
+ */
+async function createHumanQueueServer(options) {
+    if (server)
+        return server;
+    const name = options?.name || 'long-tail-human-queue';
+    server = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    // ── escalate_to_human ───────────────────────────────────────────────
+    server.registerTool('escalate_to_human', {
+        title: 'Escalate to Human',
+        description: 'Create a new escalation for human review. Returns the escalation ID.',
+        inputSchema: escalateSchema,
+    }, async (args) => {
+        const escalation = await escalationService.createEscalation({
+            type: args.type || 'mcp',
+            subtype: args.subtype || 'tool_call',
+            description: args.message,
+            priority: args.priority,
+            role: args.role,
+            envelope: JSON.stringify(args.data || {}),
+            metadata: { source: 'mcp_server' },
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        escalation_id: escalation.id,
+                        status: escalation.status,
+                        role: escalation.role,
+                        created_at: escalation.created_at,
+                    }),
+                }],
+        };
+    });
+    // ── check_resolution ────────────────────────────────────────────────
+    server.registerTool('check_resolution', {
+        title: 'Check Escalation Resolution',
+        description: 'Check the status of an escalation. Returns status and resolver payload if resolved.',
+        inputSchema: checkResolutionSchema,
+    }, async (args) => {
+        const escalation = await escalationService.getEscalation(args.escalation_id);
+        if (!escalation) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Escalation not found' }),
+                    }],
+                isError: true,
+            };
+        }
+        const result = {
+            escalation_id: escalation.id,
+            status: escalation.status,
+        };
+        if (escalation.status === 'resolved' && escalation.resolver_payload) {
+            try {
+                result.resolver_payload = JSON.parse(escalation.resolver_payload);
+            }
+            catch {
+                result.resolver_payload = escalation.resolver_payload;
+            }
+            result.resolved_at = escalation.resolved_at;
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    // ── get_available_work ──────────────────────────────────────────────
+    server.registerTool('get_available_work', {
+        title: 'Get Available Work',
+        description: 'List available escalations for a role. Returns pending, unassigned escalations.',
+        inputSchema: getAvailableWorkSchema,
+    }, async (args) => {
+        const { escalations } = await escalationService.listAvailableEscalations({
+            role: args.role,
+            limit: args.limit,
+        });
+        const items = escalations.map((e) => ({
+            escalation_id: e.id,
+            type: e.type,
+            subtype: e.subtype,
+            description: e.description,
+            priority: e.priority,
+            role: e.role,
+            created_at: e.created_at,
+        }));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ count: items.length, escalations: items }),
+                }],
+        };
+    });
+    // ── claim_and_resolve ───────────────────────────────────────────────
+    server.registerTool('claim_and_resolve', {
+        title: 'Claim and Resolve',
+        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation.',
+        inputSchema: claimAndResolveSchema,
+    }, async (args) => {
+        const claimed = await escalationService.claimEscalation(args.escalation_id, args.resolver_id, 5);
+        if (!claimed) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Escalation not available for claim' }),
+                    }],
+                isError: true,
+            };
+        }
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        if (!resolved) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Failed to resolve escalation' }),
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        escalation_id: resolved.id,
+                        status: resolved.status,
+                        resolved_at: resolved.resolved_at,
+                    }),
+                }],
+        };
+    });
+    // ── escalate_and_wait ──────────────────────────────────────────────
+    server.registerTool('escalate_and_wait', {
+        title: 'Escalate and Wait',
+        description: 'Create an escalation and pause the workflow until a human responds. ' +
+            'Returns a signal ID that the workflow uses to wait. ' +
+            'Preferred over escalate_to_human + check_resolution polling.',
+        inputSchema: escalateAndWaitSchema,
+    }, async (args) => {
+        const signalId = `wait-for-human-${crypto.randomUUID()}`;
+        // YAML workflows inject _yaml_signal_routing to override Durable's signalId-based routing
+        const yamlRouting = args._yaml_signal_routing;
+        const signalRouting = yamlRouting
+            ? { ...yamlRouting, signalId }
+            : { signalId };
+        const metadata = {
+            source: 'mcp_server',
+            signal_routing: signalRouting,
+        };
+        if (args.form_schema) {
+            metadata.form_schema = args.form_schema;
+        }
+        const escalation = await escalationService.createEscalation({
+            type: args.type || 'mcp',
+            subtype: args.subtype || 'wait_for_human',
+            description: args.message,
+            priority: args.priority,
+            role: args.role,
+            envelope: JSON.stringify(args.data || {}),
+            metadata,
+            // YAML routing provides workflow context for dashboard visibility
+            workflow_type: yamlRouting?.workflowType,
+            workflow_id: yamlRouting?.workflowId,
+            task_queue: yamlRouting?.taskQueue,
+        });
+        if (args.assigned_to) {
+            await escalationService.claimEscalation(escalation.id, args.assigned_to, 240);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        type: 'waitFor',
+                        signalId,
+                        escalationId: escalation.id,
+                    }),
+                }],
+        };
+    });
+    logger_1.loggerRegistry.info(`[lt-mcp:server] ${name} ready (5 tools registered)`);
+    return server;
+}
+/**
+ * Get the current MCP server instance.
+ */
+function getServer() {
+    return server;
+}
+/**
+ * Stop the MCP server and release resources.
+ */
+async function stopServer() {
+    if (server) {
+        await server.close();
+        server = null;
+        logger_1.loggerRegistry.info('[lt-mcp:server] stopped');
+    }
+}

package/build/system/mcp-servers/oauth.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create an OAuth MCP server.
+ *
+ * Provides 3 tools for OAuth token management:
+ *   get_access_token, list_connections, revoke_connection
+ *
+ * Workflows call get_access_token to get fresh credentials
+ * before making authenticated API calls to external services.
+ */
+export declare function createOAuthServer(): Promise<McpServer>;

package/build/system/mcp-servers/oauth.js

@@ -0,0 +1,100 @@
+"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.createOAuthServer = createOAuthServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const logger_1 = require("../../services/logger");
+const oauth = __importStar(require("../activities/oauth"));
+const getAccessTokenSchema = zod_1.z.object({
+    provider: zod_1.z.string().describe('OAuth provider name (google, github, microsoft, anthropic, etc.)'),
+    user_id: zod_1.z.string().describe('User ID to get token for'),
+    label: zod_1.z.string().optional().describe('Credential label (default: "default"). Use to select among multiple credentials for the same provider.'),
+});
+const listConnectionsSchema = zod_1.z.object({
+    user_id: zod_1.z.string().describe('User ID to list connections for'),
+});
+const revokeConnectionSchema = zod_1.z.object({
+    provider: zod_1.z.string().describe('OAuth provider name to disconnect'),
+    user_id: zod_1.z.string().describe('User ID to revoke connection for'),
+    label: zod_1.z.string().optional().describe('Credential label to revoke (default: "default")'),
+});
+/**
+ * Create an OAuth MCP server.
+ *
+ * Provides 3 tools for OAuth token management:
+ *   get_access_token, list_connections, revoke_connection
+ *
+ * Workflows call get_access_token to get fresh credentials
+ * before making authenticated API calls to external services.
+ */
+async function createOAuthServer() {
+    const instance = new mcp_js_1.McpServer({ name: 'long-tail-oauth', version: '1.0.0' });
+    instance.registerTool('get_access_token', {
+        title: 'Get OAuth Access Token',
+        description: 'Get a fresh OAuth access token for an external service (Google, GitHub, etc.). ' +
+            'Automatically refreshes expired tokens. Call this immediately before making an ' +
+            'authenticated API request — do not cache or reuse across workflow steps. ' +
+            'Use the label parameter to select a specific credential when multiple exist.',
+        inputSchema: getAccessTokenSchema,
+    }, async (args) => {
+        const result = await oauth.getAccessToken(args);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    instance.registerTool('list_connections', {
+        title: 'List OAuth Connections',
+        description: 'List all OAuth providers connected for a user. Returns provider, label, and credential type for each connection.',
+        inputSchema: listConnectionsSchema,
+    }, async (args) => {
+        const result = await oauth.listConnections(args);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    instance.registerTool('revoke_connection', {
+        title: 'Revoke OAuth Connection',
+        description: 'Disconnect an OAuth provider for a user, removing stored tokens. Use label to target a specific credential.',
+        inputSchema: revokeConnectionSchema,
+    }, async (args) => {
+        const result = await oauth.revokeConnection(args);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    logger_1.loggerRegistry.info('[lt-mcp:oauth] long-tail-oauth ready (3 tools registered)');
+    return instance;
+}

package/build/system/mcp-servers/playwright/browser-lifecycle.d.ts

@@ -0,0 +1,26 @@
+import { type Browser, type Page } from 'playwright';
+import type { PlaywrightHandle } from './types';
+export declare const pages: Map<string, Page>;
+/** Allocate a unique page ID (shared across both playwright servers). */
+export declare function allocatePageId(): string;
+export declare function ensureBrowser(): Promise<Browser>;
+/**
+ * Resolve a page from either a local `page_id`, a `_handle`, or "most recent".
+ * Handles cross-container reconnection via CDP when needed.
+ */
+export declare function resolvePage(args: {
+    page_id?: string;
+    _handle?: PlaywrightHandle;
+}): Promise<{
+    page: Page;
+    pageId: string;
+}>;
+/**
+ * Build a _handle for a page. Includes CDP endpoint when available
+ * (for cross-container access in distributed deployments).
+ */
+export declare function buildHandle(pageId: string): PlaywrightHandle;
+/**
+ * Shut down the shared browser and release all pages.
+ */
+export declare function stopPlaywrightServer(): Promise<void>;

package/build/system/mcp-servers/playwright/browser-lifecycle.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pages = void 0;
+exports.allocatePageId = allocatePageId;
+exports.ensureBrowser = ensureBrowser;
+exports.resolvePage = resolvePage;
+exports.buildHandle = buildHandle;
+exports.stopPlaywrightServer = stopPlaywrightServer;
+const playwright_1 = require("playwright");
+const logger_1 = require("../../../services/logger");
+const types_1 = require("./types");
+// ── Browser lifecycle ────────────────────────────────────────────────────────
+// Shared browser instance across tool calls within a single server lifetime.
+// Lazy-launched on first use, cleaned up via stopPlaywrightServer().
+let browser = null;
+exports.pages = new Map();
+let pageCounter = 0;
+/** Remote browsers connected via CDP — cached to avoid reconnecting per call. */
+const remoteBrowsers = new Map();
+/** Allocate a unique page ID (shared across both playwright servers). */
+function allocatePageId() {
+    return `page_${++pageCounter}`;
+}
+async function ensureBrowser() {
+    if (!browser || !browser.isConnected()) {
+        browser = await playwright_1.chromium.launch({ headless: true });
+        logger_1.loggerRegistry.info('[lt-mcp:playwright] browser launched');
+    }
+    return browser;
+}
+/**
+ * Resolve a page from either a local `page_id`, a `_handle`, or "most recent".
+ * Handles cross-container reconnection via CDP when needed.
+ */
+async function resolvePage(args) {
+    // 1. Try local pages Map (fast path — same container)
+    const localId = args._handle?.page_id || args.page_id;
+    if (localId) {
+        const local = exports.pages.get(localId);
+        if (local)
+            return { page: local, pageId: localId };
+    }
+    // 2. Try CDP reconnection via handle (cross-container)
+    if (args._handle?.cdp_endpoint) {
+        const cdp = args._handle.cdp_endpoint;
+        let remoteBrowser = remoteBrowsers.get(cdp);
+        if (!remoteBrowser || !remoteBrowser.isConnected()) {
+            try {
+                remoteBrowser = await playwright_1.chromium.connectOverCDP(cdp);
+                remoteBrowsers.set(cdp, remoteBrowser);
+                logger_1.loggerRegistry.info(`[lt-mcp:playwright] connected to remote browser: ${cdp}`);
+            }
+            catch (err) {
+                throw Object.assign(new Error(`Cannot reach browser at ${cdp}`), { code: types_1.SESSION_UNREACHABLE, cdp_endpoint: cdp });
+            }
+        }
+        // Find the page — for now, use the first page in the default context
+        const contexts = remoteBrowser.contexts();
+        const ctx = contexts[0] || await remoteBrowser.newContext();
+        const remotePages = ctx.pages();
+        if (remotePages.length > 0) {
+            const page = remotePages[remotePages.length - 1];
+            const id = args._handle.page_id || `remote_${++pageCounter}`;
+            exports.pages.set(id, page);
+            return { page, pageId: id };
+        }
+        throw Object.assign(new Error(`No pages found on remote browser at ${cdp}`), { code: types_1.SESSION_NOT_FOUND, cdp_endpoint: cdp });
+    }
+    // 3. If a specific page_id was requested but not found, throw structured error
+    if (localId) {
+        throw Object.assign(new Error(`Page ${localId} not found`), { code: types_1.SESSION_NOT_FOUND, page_id: localId });
+    }
+    // 4. Fall back to most recent local page
+    const entries = Array.from(exports.pages.entries());
+    if (entries.length === 0) {
+        throw Object.assign(new Error('No pages open. Navigate to a URL first, or pass a _handle.'), { code: types_1.SESSION_NOT_FOUND });
+    }
+    return { page: entries[entries.length - 1][1], pageId: entries[entries.length - 1][0] };
+}
+/**
+ * Build a _handle for a page. Includes CDP endpoint when available
+ * (for cross-container access in distributed deployments).
+ */
+function buildHandle(pageId) {
+    const handle = {
+        type: 'playwright_page',
+        page_id: pageId,
+    };
+    // Include CDP endpoint if browser exposes one (e.g., launchServer or remote)
+    if (browser && typeof browser.wsEndpoint === 'function') {
+        try {
+            handle.cdp_endpoint = browser.wsEndpoint();
+        }
+        catch {
+            // Not available — single-process mode, local pages Map suffices
+        }
+    }
+    return handle;
+}
+/**
+ * Shut down the shared browser and release all pages.
+ */
+async function stopPlaywrightServer() {
+    for (const [id, page] of exports.pages) {
+        try {
+            await page.close();
+        }
+        catch { /* ignore */ }
+        exports.pages.delete(id);
+    }
+    // Close remote browsers
+    for (const [endpoint, rb] of remoteBrowsers) {
+        try {
+            await rb.close();
+        }
+        catch { /* ignore */ }
+        remoteBrowsers.delete(endpoint);
+    }
+    if (browser) {
+        await browser.close();
+        browser = null;
+    }
+    pageCounter = 0;
+    logger_1.loggerRegistry.info('[lt-mcp:playwright] browser closed');
+}

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

@@ -0,0 +1,25 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { pages, allocatePageId, ensureBrowser, buildHandle, stopPlaywrightServer } from './browser-lifecycle';
+export type { PlaywrightHandle } from './types';
+/**
+ * Create a Playwright Browser MCP server.
+ *
+ * Provides 9 tools for browser automation:
+ *   navigate, screenshot, click, fill, wait_for, evaluate, run_script, list_pages, close_page
+ *
+ * All page-scoped tools participate in the _handle convention:
+ * - navigate returns a _handle in its result
+ * - All other tools accept _handle to locate the page across activities
+ * - Fast path: local pages Map (same container)
+ * - Slow path: CDP reconnection (different container)
+ *
+ * `run_script` is the preferred tool for YAML workflows — it executes a
+ * multi-step browser script in a single activity, avoiding cross-activity
+ * session issues entirely.
+ *
+ * Returns a fresh McpServer instance each time. The browser is shared
+ * and lazy-launched on first tool call.
+ */
+export declare function createPlaywrightServer(options?: {
+    name?: string;
+}): Promise<McpServer>;

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stopPlaywrightServer = exports.buildHandle = exports.ensureBrowser = exports.allocatePageId = exports.pages = void 0;
+exports.createPlaywrightServer = createPlaywrightServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const logger_1 = require("../../../services/logger");
+const tools_atomic_1 = require("./tools-atomic");
+const tools_run_script_1 = require("./tools-run-script");
+// Re-export public API consumed by playwright-cli.ts and system/index.ts
+var browser_lifecycle_1 = require("./browser-lifecycle");
+Object.defineProperty(exports, "pages", { enumerable: true, get: function () { return browser_lifecycle_1.pages; } });
+Object.defineProperty(exports, "allocatePageId", { enumerable: true, get: function () { return browser_lifecycle_1.allocatePageId; } });
+Object.defineProperty(exports, "ensureBrowser", { enumerable: true, get: function () { return browser_lifecycle_1.ensureBrowser; } });
+Object.defineProperty(exports, "buildHandle", { enumerable: true, get: function () { return browser_lifecycle_1.buildHandle; } });
+Object.defineProperty(exports, "stopPlaywrightServer", { enumerable: true, get: function () { return browser_lifecycle_1.stopPlaywrightServer; } });
+/**
+ * Create a Playwright Browser MCP server.
+ *
+ * Provides 9 tools for browser automation:
+ *   navigate, screenshot, click, fill, wait_for, evaluate, run_script, list_pages, close_page
+ *
+ * All page-scoped tools participate in the _handle convention:
+ * - navigate returns a _handle in its result
+ * - All other tools accept _handle to locate the page across activities
+ * - Fast path: local pages Map (same container)
+ * - Slow path: CDP reconnection (different container)
+ *
+ * `run_script` is the preferred tool for YAML workflows — it executes a
+ * multi-step browser script in a single activity, avoiding cross-activity
+ * session issues entirely.
+ *
+ * Returns a fresh McpServer instance each time. The browser is shared
+ * and lazy-launched on first tool call.
+ */
+async function createPlaywrightServer(options) {
+    const name = options?.name || 'long-tail-playwright';
+    const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    (0, tools_atomic_1.registerAtomicTools)(instance);
+    (0, tools_run_script_1.registerRunScript)(instance);
+    logger_1.loggerRegistry.info(`[lt-mcp:playwright] ${name} ready (9 tools registered)`);
+    return instance;
+}