webflow-mcp 0.3.0

package/dist/src/errors/self-healing.d.ts

@@ -0,0 +1,62 @@
+export interface RawDomSnapshot {
+    html?: string;
+    text?: string;
+}
+export interface SelfHealingPayload {
+    code: string;
+    message: string;
+    flow: string;
+    profile?: string;
+    profileStatus?: string;
+    loginUrl?: string;
+    setupCommand?: string;
+    approvalCommand?: string;
+    flowDigest?: string;
+    releaseId?: string;
+    releaseVersion?: string;
+    releaseSequence?: number;
+    signerKeyId?: string;
+    trustDomain?: string;
+    step?: string;
+    url?: string;
+    retryable: boolean;
+    suggestedAction?: string;
+    domSnapshot?: {
+        html?: string;
+        text?: string;
+        truncated: boolean;
+        originalBytes: number;
+        capturedBytes: number;
+    };
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+export interface SelfHealingContext {
+    flow: string;
+    profile?: string;
+    profileStatus?: string;
+    loginUrl?: string;
+    setupCommand?: string;
+    approvalCommand?: string;
+    flowDigest?: string;
+    releaseId?: string;
+    releaseVersion?: string;
+    releaseSequence?: number;
+    signerKeyId?: string;
+    trustDomain?: string;
+    step?: string;
+    url?: string;
+}
+export declare function buildDomSnapshot(snapshot?: RawDomSnapshot): SelfHealingPayload['domSnapshot'];
+export declare function buildSelfHealingPayload(error: unknown, context: SelfHealingContext & {
+    code?: string;
+    retryable?: boolean;
+    suggestedAction?: string;
+    domSnapshot?: RawDomSnapshot;
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}): SelfHealingPayload;

package/dist/src/errors/self-healing.js

@@ -0,0 +1,77 @@
+const HTML_CAP = 48 * 1024;
+const TEXT_CAP = 16 * 1024;
+const TOTAL_CAP = 64 * 1024;
+function byteLength(value) {
+    return value ? Buffer.byteLength(value, 'utf8') : 0;
+}
+function stripDangerousTags(html) {
+    return html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '').replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
+}
+function truncate(value, cap) {
+    if (!value) {
+        return { value: undefined, truncated: false };
+    }
+    if (Buffer.byteLength(value, 'utf8') <= cap) {
+        return { value, truncated: false };
+    }
+    let current = value;
+    while (Buffer.byteLength(current, 'utf8') > cap && current.length > 0) {
+        current = current.slice(0, Math.max(1, Math.floor(current.length * 0.9)));
+    }
+    return { value: `${current}…`, truncated: true };
+}
+export function buildDomSnapshot(snapshot) {
+    if (!snapshot?.html && !snapshot?.text) {
+        return undefined;
+    }
+    const sanitizedHtml = snapshot.html ? stripDangerousTags(snapshot.html) : undefined;
+    const html = truncate(sanitizedHtml, HTML_CAP);
+    const text = truncate(snapshot.text, TEXT_CAP);
+    const originalBytes = byteLength(sanitizedHtml) + byteLength(snapshot.text);
+    let capturedHtml = html.value;
+    let capturedText = text.value;
+    while (byteLength(capturedHtml) + byteLength(capturedText) > TOTAL_CAP) {
+        if ((capturedHtml?.length ?? 0) >= (capturedText?.length ?? 0) && capturedHtml) {
+            capturedHtml = capturedHtml.slice(0, Math.max(1, Math.floor(capturedHtml.length * 0.9)));
+        }
+        else if (capturedText) {
+            capturedText = capturedText.slice(0, Math.max(1, Math.floor(capturedText.length * 0.9)));
+        }
+        else {
+            break;
+        }
+    }
+    const capturedBytes = byteLength(capturedHtml) + byteLength(capturedText);
+    return {
+        html: capturedHtml,
+        text: capturedText,
+        truncated: html.truncated || text.truncated || capturedBytes < originalBytes,
+        originalBytes,
+        capturedBytes
+    };
+}
+export function buildSelfHealingPayload(error, context) {
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Flow execution failed';
+    return {
+        code: context.code ?? 'FLOW_STEP_FAILED',
+        message,
+        flow: context.flow,
+        profile: context.profile,
+        profileStatus: context.profileStatus,
+        loginUrl: context.loginUrl,
+        setupCommand: context.setupCommand,
+        approvalCommand: context.approvalCommand,
+        flowDigest: context.flowDigest,
+        releaseId: context.releaseId,
+        releaseVersion: context.releaseVersion,
+        releaseSequence: context.releaseSequence,
+        signerKeyId: context.signerKeyId,
+        trustDomain: context.trustDomain,
+        step: context.step,
+        url: context.url,
+        retryable: context.retryable ?? true,
+        suggestedAction: context.suggestedAction,
+        domSnapshot: buildDomSnapshot(context.domSnapshot),
+        validationErrors: context.validationErrors
+    };
+}

package/dist/src/mcp/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/mcp/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { startStdioServer } from './server.js';
+import { toErrorMessage } from '../shared/errors.js';
+function resolveProjectRoot(argv) {
+    const diagnostics = [];
+    const projectRootIndex = argv.findIndex((arg) => arg === '--projectRoot' || arg === '--project-root');
+    const explicitArg = projectRootIndex >= 0 ? argv[projectRootIndex + 1] : argv.find((arg) => !arg.startsWith('-'));
+    if (explicitArg) {
+        return { projectRoot: resolve(explicitArg), diagnostics };
+    }
+    if (process.env.CLAUDE_PROJECT_DIR) {
+        const projectRoot = resolve(process.env.CLAUDE_PROJECT_DIR);
+        diagnostics.push(`No projectRoot argument provided; using CLAUDE_PROJECT_DIR fallback: ${projectRoot}`);
+        return { projectRoot, diagnostics };
+    }
+    const projectRoot = resolve(process.cwd());
+    diagnostics.push(`No projectRoot argument provided; using current working directory fallback: ${projectRoot}`);
+    return { projectRoot, diagnostics };
+}
+async function main() {
+    // Redirect console.log to console.error to keep stdout clean for MCP JSON-RPC stdio transport
+    console.log = (...args) => {
+        console.error(...args);
+    };
+    const { projectRoot, diagnostics } = resolveProjectRoot(process.argv.slice(2));
+    diagnostics.forEach((diagnostic) => console.error(`[diagnostic] ${diagnostic}`));
+    await startStdioServer(projectRoot);
+    if (process.env.WEBFLOW_MCP_SMOKE_EXIT_AFTER_CONNECT === '1') {
+        process.exit(0);
+    }
+}
+main().catch((error) => {
+    console.error(toErrorMessage(error));
+    process.exitCode = 1;
+});

package/dist/src/mcp/relay-gateway.d.ts

@@ -0,0 +1,24 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export { RELAY_MCP_TOKEN_ENV, RELAY_MCP_URL_ENV } from '../shared/paths.js';
+export interface RelayGatewayConfig {
+    url: URL;
+    token: string;
+}
+export declare function resolveRelayGatewayConfig(environment?: NodeJS.ProcessEnv): RelayGatewayConfig | undefined;
+export declare class RelayGateway {
+    private readonly config;
+    private client?;
+    private transport?;
+    private connecting?;
+    private closed;
+    private activeCalls;
+    private resetWhenIdle;
+    constructor(config: RelayGatewayConfig);
+    get endpoint(): string;
+    private connect;
+    private reset;
+    callTool(name: string, args: Record<string, unknown>, signal: AbortSignal): Promise<CallToolResult>;
+    close(): Promise<void>;
+}
+export declare function registerRelayGatewayTools(server: McpServer, gateway: RelayGateway): void;

package/dist/src/mcp/relay-gateway.js

@@ -0,0 +1,208 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { z } from 'zod';
+import { WebFlowError } from '../shared/errors.js';
+import { RELAY_MCP_TOKEN_ENV, RELAY_MCP_URL_ENV } from '../shared/paths.js';
+export { RELAY_MCP_TOKEN_ENV, RELAY_MCP_URL_ENV } from '../shared/paths.js';
+const RELAY_CALL_TIMEOUT_MS = 21 * 60_000;
+const MAX_INPUT_FIELDS = 100;
+function errorResult(code, message) {
+    const error = { code, message };
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(error, null, 2) }],
+        structuredContent: error
+    };
+}
+function boundedInputRecord() {
+    return z.record(z.string(), z.unknown()).refine((value) => Object.keys(value).length <= MAX_INPUT_FIELDS, {
+        message: `Too many top-level input fields (max ${MAX_INPUT_FIELDS}).`
+    });
+}
+export function resolveRelayGatewayConfig(environment = process.env) {
+    const rawUrl = environment[RELAY_MCP_URL_ENV]?.trim();
+    const token = environment[RELAY_MCP_TOKEN_ENV]?.trim();
+    if (!rawUrl && !token)
+        return undefined;
+    if (!rawUrl || !token) {
+        throw new WebFlowError('INCOMPLETE_RELAY_MCP_CONFIG', `${RELAY_MCP_URL_ENV} and ${RELAY_MCP_TOKEN_ENV} must be configured together.`);
+    }
+    if (!token.startsWith('tok_') || token.length <= 4) {
+        throw new WebFlowError('INVALID_RELAY_MCP_TOKEN', `${RELAY_MCP_TOKEN_ENV} must contain an MCP token beginning with "tok_".`);
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new WebFlowError('INVALID_RELAY_MCP_URL', `${RELAY_MCP_URL_ENV} is not a valid URL.`);
+    }
+    const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new WebFlowError('INSECURE_RELAY_MCP_URL', 'The relay MCP URL must use https. Plain http is allowed only for loopback development.');
+    }
+    if (url.username || url.password || url.hash) {
+        throw new WebFlowError('INVALID_RELAY_MCP_URL', 'The relay MCP URL must not contain credentials or a fragment.');
+    }
+    if (url.search) {
+        throw new WebFlowError('INVALID_RELAY_MCP_URL', 'The relay MCP URL must not contain query parameters.');
+    }
+    return { url, token };
+}
+export class RelayGateway {
+    config;
+    client;
+    transport;
+    connecting;
+    closed = false;
+    activeCalls = 0;
+    resetWhenIdle = false;
+    constructor(config) {
+        this.config = config;
+    }
+    get endpoint() {
+        return this.config.url.toString();
+    }
+    async connect() {
+        if (this.closed)
+            throw new WebFlowError('RELAY_MCP_UNAVAILABLE', 'The local gateway is shutting down.');
+        if (this.client)
+            return this.client;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = (async () => {
+            const client = new Client({ name: 'webflow-local-gateway', version: '0.3.0' });
+            const transport = new StreamableHTTPClientTransport(this.config.url, {
+                requestInit: {
+                    headers: { Authorization: `Bearer ${this.config.token}` },
+                    redirect: 'error'
+                }
+            });
+            try {
+                await client.connect(transport);
+                this.client = client;
+                this.transport = transport;
+                return client;
+            }
+            catch (error) {
+                await client.close().catch(() => undefined);
+                if (error instanceof UnauthorizedError) {
+                    throw new WebFlowError('RELAY_MCP_AUTH_FAILED', 'The relay rejected the configured MCP token.');
+                }
+                throw new WebFlowError('RELAY_MCP_UNAVAILABLE', 'Could not connect to the configured relay MCP endpoint.');
+            }
+        })();
+        try {
+            return await this.connecting;
+        }
+        finally {
+            this.connecting = undefined;
+        }
+    }
+    async reset() {
+        const client = this.client;
+        this.client = undefined;
+        this.transport = undefined;
+        if (client)
+            await client.close().catch(() => undefined);
+    }
+    async callTool(name, args, signal) {
+        let connected = false;
+        try {
+            const client = await this.connect();
+            this.activeCalls += 1;
+            connected = true;
+            return await client.callTool({ name, arguments: args }, undefined, { signal, timeout: RELAY_CALL_TIMEOUT_MS, maxTotalTimeout: RELAY_CALL_TIMEOUT_MS });
+        }
+        catch (error) {
+            if (signal.aborted)
+                return errorResult('RELAY_MCP_CANCELLED', 'The relay MCP request was cancelled.');
+            this.resetWhenIdle = true;
+            if (!connected) {
+                this.resetWhenIdle = false;
+                await this.reset();
+            }
+            if (error instanceof WebFlowError)
+                return errorResult(error.code, error.message);
+            if (error instanceof UnauthorizedError)
+                return errorResult('RELAY_MCP_AUTH_FAILED', 'The relay rejected the configured MCP token.');
+            return errorResult('RELAY_MCP_UNAVAILABLE', 'The relay MCP request failed. Retry only if the previous call could not have started a flow.');
+        }
+        finally {
+            if (connected) {
+                this.activeCalls -= 1;
+                if (this.activeCalls === 0 && this.resetWhenIdle) {
+                    this.resetWhenIdle = false;
+                    await this.reset();
+                }
+            }
+        }
+    }
+    async close() {
+        this.closed = true;
+        await this.connecting?.catch(() => undefined);
+        const transport = this.transport;
+        const client = this.client;
+        this.client = undefined;
+        this.transport = undefined;
+        if (transport?.sessionId)
+            await transport.terminateSession().catch(() => undefined);
+        if (client)
+            await client.close().catch(() => undefined);
+    }
+}
+export function registerRelayGatewayTools(server, gateway) {
+    const proxy = (name) => async (args, extra) => gateway.callTool(name, args, extra.signal);
+    server.registerTool('browse_catalog', {
+        title: 'browse_catalog',
+        description: 'Navigate the remote catalog top-down: sector, service, then flow. Never assume a flow name that was not returned by browse_catalog or search_flows.',
+        inputSchema: z.object({ category: z.string().max(200).optional(), service: z.string().max(200).optional() })
+    }, proxy('browse_catalog'));
+    server.registerTool('search_flows', {
+        title: 'search_flows',
+        description: 'Search the remote flow catalog by name or description keyword.',
+        inputSchema: z.object({ query: z.string().min(1).max(200) })
+    }, proxy('search_flows'));
+    server.registerTool('describe_flow', {
+        title: 'describe_flow',
+        description: 'Read remote flow metadata and its real signed input schema before execution.',
+        inputSchema: z.object({ name: z.string().min(1).max(200) })
+    }, proxy('describe_flow'));
+    server.registerTool('add_to_repertoire', {
+        title: 'add_to_repertoire',
+        description: 'Save a discovered flow in this worker\'s local repertoire. This is a standing preference and requires the user\'s prior agreement. In gateway mode, use run_flow_with_options to execute saved flows.',
+        inputSchema: z.object({ name: z.string().min(1).max(200) })
+    }, proxy('add_to_repertoire'));
+    server.registerTool('remove_from_repertoire', {
+        title: 'remove_from_repertoire',
+        description: 'Remove a flow from this worker\'s local repertoire. Only call after the user explicitly asks or agrees.',
+        inputSchema: z.object({ name: z.string().min(1).max(200) })
+    }, proxy('remove_from_repertoire'));
+    server.registerTool('run_flow_once', {
+        title: 'run_flow_once',
+        description: 'Run a discovered flow outside the saved repertoire once. Call without confirmed first, ask the user, then retry with confirmed:true. Use run_flow_with_options for saved flows.',
+        inputSchema: z.object({ name: z.string().min(1).max(200), input: boundedInputRecord().optional(), confirmed: z.boolean().optional() })
+    }, proxy('run_flow_once'));
+    server.registerTool('run_flow_with_options', {
+        title: 'run_flow_with_options',
+        description: 'Run any visible remote flow. Saved flows need no confirmation unless one-off browser options are supplied; unsaved flows require confirmed:true after asking the user.',
+        inputSchema: z.object({
+            name: z.string().min(1).max(200),
+            input: boundedInputRecord().optional(),
+            browserMode: z.enum(['managed', 'cdp']).optional(),
+            browserVisibility: z.enum(['visible', 'hidden']).optional(),
+            confirmed: z.boolean().optional()
+        })
+    }, proxy('run_flow_with_options'));
+    server.registerTool('check_profile_status', {
+        title: 'check_profile_status',
+        description: 'Check the worker-local login status using the remote flow\'s authoritative profile metadata.',
+        inputSchema: z.object({ flowName: z.string().min(1).max(200) })
+    }, proxy('check_profile_status'));
+    server.registerTool('start_profile_login', {
+        title: 'start_profile_login',
+        description: 'Open a real visible Chrome login window on this machine. Call without confirmed first, ask the user, then retry with confirmed:true.',
+        inputSchema: z.object({ flowName: z.string().min(1).max(200), confirmed: z.boolean().optional() })
+    }, proxy('start_profile_login'));
+}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createMcpServer(projectRoot: string, nodeVersion?: string): Promise<{
+    server: McpServer;
+    diagnostics: string[];
+    flowNames: string[];
+    mode: 'local' | 'gateway';
+}>;
+export declare function startStdioServer(projectRoot: string): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerFlowTools } from './tool-registry.js';
+import { RelayGateway, resolveRelayGatewayConfig } from './relay-gateway.js';
+import { assertSupportedNode, assertWorkspaceReady, getPackageRoot, getProfilesRoot, getWorkspacePaths, resolveFlowsProjectRoot } from '../shared/paths.js';
+async function readVersion(projectRoot) {
+    try {
+        const raw = await readFile(resolve(projectRoot, 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        const raw = await readFile(resolve(getPackageRoot(import.meta.url), 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+}
+export async function createMcpServer(projectRoot, nodeVersion = process.versions.node) {
+    assertSupportedNode(nodeVersion);
+    const gatewayConfig = resolveRelayGatewayConfig();
+    if (!gatewayConfig)
+        await assertWorkspaceReady(projectRoot);
+    const gateway = gatewayConfig ? new RelayGateway(gatewayConfig) : undefined;
+    const server = new McpServer({
+        name: 'webflow-mcp',
+        version: await readVersion(projectRoot)
+    }, {
+        instructions: gateway
+            ? 'This is the single local WebFlow gateway. Worker lifecycle, browser preferences, profile administration ' +
+                'and signed-flow approvals operate only on this machine; catalog discovery and flow execution are proxied ' +
+                'to the configured relay. Use start_worker before remote operations. Navigate browse_catalog top-down or ' +
+                'use search_flows, call describe_flow before execution, and use run_flow_with_options for saved flows. ' +
+                'When FLOW_UPDATE_APPROVAL_REQUIRED occurs, call list_flow_approvals, show the exact digest/signer/trust ' +
+                'domain to the user, then call approve_flow_update only after explicit agreement. Never invent confirmed:true. ' +
+                'Initial worker pairing still requires the user to run webflow login and approve it in their browser.'
+            : 'Expose local .webflow flows as validated MCP tools. For a flow that requires login, call ' +
+                'check_profile_status first — if it is not probably valid, ask the user before calling start_profile_login ' +
+                '(with confirmed:true), which opens a real Chrome window for them to log in manually. Worker lifecycle and ' +
+                'signed-flow approval tools operate only on this machine.'
+    });
+    const { diagnostics, flows } = await registerFlowTools(server, projectRoot, { gateway });
+    if (gateway) {
+        diagnostics.push(`Mode: unified local gateway`);
+        diagnostics.push(`Relay MCP endpoint: ${gateway.endpoint}`);
+        server.server.onclose = () => {
+            void gateway.close();
+        };
+    }
+    else {
+        const workspacePaths = getWorkspacePaths(projectRoot);
+        diagnostics.push(`Flows loaded from: ${getWorkspacePaths(resolveFlowsProjectRoot(projectRoot)).flowsDir}`);
+        diagnostics.push(`Downloads (this repo): ${workspacePaths.downloadsDir}`);
+    }
+    diagnostics.push(`Login sessions (global, shared across repos): ${getProfilesRoot()}`);
+    return { server, diagnostics, flowNames: flows.map((flow) => flow.name), mode: gateway ? 'gateway' : 'local' };
+}
+export async function startStdioServer(projectRoot) {
+    const { server, diagnostics } = await createMcpServer(projectRoot);
+    diagnostics.forEach((diagnostic) => console.error(`[diagnostic] ${diagnostic}`));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/mcp/tool-registry.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FlowDefinition } from '../runner/types.js';
+import { type RelayGateway } from './relay-gateway.js';
+export interface ToolRegistryResult {
+    diagnostics: string[];
+    flows: FlowDefinition[];
+}
+export declare function registerFlowTools(server: McpServer, projectRoot: string, options?: {
+    gateway?: RelayGateway;
+}): Promise<ToolRegistryResult>;