@synergenius/flow-weaver 0.2.0

package/dist/mcp/tools-query.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerQueryTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-query.d.ts.map

package/dist/mcp/tools-query.js

@@ -0,0 +1,364 @@
+import { z } from 'zod';
+import * as path from 'path';
+import { parseWorkflow, validateWorkflow, compileWorkflow } from '../api/index.js';
+import { getNodes, getConnections, getDependencies, getDependents, getDataDependencies, getTopologicalOrder, findIsolatedNodes, findDeadEndDetails, findDisconnectedOutputPorts, } from '../api/query.js';
+import { describeWorkflow, formatDescribeOutput } from '../cli/commands/describe.js';
+import { runDoctorChecks } from '../cli/commands/doctor.js';
+import { WorkflowDiffer } from '../diff/WorkflowDiffer.js';
+import { formatDiff } from '../diff/formatDiff.js';
+import { makeToolResult, makeErrorResult, addHintsToItems } from './response-utils.js';
+import { getFriendlyError } from '../friendly-errors.js';
+import { generateInngestFunction } from '../generator/inngest.js';
+import { AnnotationParser } from '../parser.js';
+/** Detect MULTIPLE_WORKFLOWS_FOUND marker in parse errors and return the right error code */
+function parseErrorCode(errors) {
+    if (errors.some((e) => e.includes('[MULTIPLE_WORKFLOWS_FOUND]'))) {
+        return 'MULTIPLE_WORKFLOWS_FOUND';
+    }
+    return 'PARSE_ERROR';
+}
+export function registerQueryTools(mcp) {
+    mcp.tool('fw_describe', 'Describe a workflow in LLM-friendly format (nodes, connections, graph, validation).', {
+        filePath: z.string().describe('Path to the workflow .ts file'),
+        format: z
+            .enum(['json', 'text', 'mermaid', 'paths'])
+            .optional()
+            .describe('Output format (default: json)'),
+        node: z.string().optional().describe('Focus on a specific node ID'),
+        workflowName: z.string().optional().describe('Specific workflow if file has multiple'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            const parseResult = await parseWorkflow(filePath, { workflowName: args.workflowName });
+            // If no workflows found, try node-type-only mode
+            if (parseResult.errors.length > 0 &&
+                parseResult.errors.some((e) => typeof e === 'string' && e.includes('No workflows found'))) {
+                try {
+                    const ntResult = await parseWorkflow(filePath, { nodeTypesOnly: true });
+                    if (ntResult.errors.length === 0 && ntResult.ast.nodeTypes?.length > 0) {
+                        return makeToolResult({
+                            nodeTypesOnly: true,
+                            nodeTypes: ntResult.ast.nodeTypes.map((nt) => ({
+                                name: nt.name,
+                                inputs: Object.keys(nt.inputs),
+                                outputs: Object.keys(nt.outputs),
+                                isExpression: nt.isExpression ?? false,
+                            })),
+                        });
+                    }
+                }
+                catch {
+                    /* fall through to original error */
+                }
+            }
+            if (parseResult.errors.length > 0) {
+                return makeErrorResult(parseErrorCode(parseResult.errors), `Parse errors:\n${parseResult.errors.join('\n')}`);
+            }
+            const output = describeWorkflow(parseResult.ast, { node: args.node });
+            const format = args.format ?? 'json';
+            const formatted = formatDescribeOutput(parseResult.ast, output, format);
+            return makeToolResult(format === 'json' ? JSON.parse(formatted) : formatted);
+        }
+        catch (err) {
+            return makeErrorResult('DESCRIBE_ERROR', `fw_describe failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_validate', 'Validate a workflow file and return errors/warnings.', {
+        filePath: z.string().describe('Path to the workflow file'),
+        workflowName: z.string().optional().describe('Specific workflow name'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            const parseResult = await parseWorkflow(filePath, { workflowName: args.workflowName });
+            // If no workflows found, try node-type-only mode
+            if (parseResult.errors.length > 0 &&
+                parseResult.errors.some((e) => typeof e === 'string' && e.includes('No workflows found'))) {
+                try {
+                    const ntResult = await parseWorkflow(filePath, { nodeTypesOnly: true });
+                    if (ntResult.errors.length === 0 && ntResult.ast.nodeTypes?.length > 0) {
+                        const count = ntResult.ast.nodeTypes.length;
+                        return makeToolResult({
+                            valid: true,
+                            nodeTypesOnly: true,
+                            nodeTypeCount: count,
+                            warnings: [
+                                {
+                                    message: `No workflow function found (found ${count} node type${count === 1 ? '' : 's'}). Add a /** @flowWeaver workflow */ annotation above an exported function to define a workflow.`,
+                                    severity: 'warning',
+                                    code: 'NO_WORKFLOW_FOUND',
+                                },
+                            ],
+                        });
+                    }
+                }
+                catch {
+                    /* fall through to original error */
+                }
+            }
+            if (parseResult.errors.length > 0) {
+                return makeToolResult({
+                    valid: false,
+                    errors: parseResult.errors,
+                    warnings: parseResult.warnings,
+                });
+            }
+            const result = validateWorkflow(parseResult.ast);
+            const errors = result.errors.map((e) => ({
+                message: e.message,
+                severity: e.type,
+                nodeId: e.node,
+                code: e.code,
+            }));
+            const warnings = [
+                ...parseResult.warnings,
+                ...result.warnings.map((w) => ({
+                    message: w.message,
+                    severity: w.type,
+                    nodeId: w.node,
+                    code: w.code,
+                })),
+            ];
+            return makeToolResult({
+                valid: result.valid,
+                errors: addHintsToItems(errors, getFriendlyError),
+                warnings: addHintsToItems(warnings, getFriendlyError),
+            });
+        }
+        catch (err) {
+            return makeErrorResult('VALIDATE_ERROR', `fw_validate failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_compile', 'Compile a workflow to executable code. Use target=inngest for per-node step.run() durability.', {
+        filePath: z.string().describe('Path to the workflow file'),
+        write: z.boolean().optional().describe('Whether to write the output file (default: true)'),
+        production: z
+            .boolean()
+            .optional()
+            .describe('Production mode — no debug events (default: false)'),
+        workflowName: z.string().optional().describe('Specific workflow name'),
+        target: z
+            .enum(['typescript', 'inngest'])
+            .optional()
+            .describe('Compilation target: typescript (default) or inngest (per-node step.run)'),
+        cron: z.string().optional().describe('Cron schedule expression (e.g. "0 9 * * *"). Overrides @trigger annotation.'),
+        serve: z.boolean().optional().describe('Generate serve() handler for HTTP framework integration'),
+        framework: z.enum(['next', 'express', 'hono', 'fastify', 'remix']).optional().describe('Framework adapter for serve handler (requires serve=true)'),
+        typedEvents: z.boolean().optional().describe('Generate Zod event schemas from workflow @param annotations'),
+        retries: z.number().int().min(0).optional().describe('Number of retries per function. Overrides @retries annotation.'),
+        timeout: z.string().optional().describe('Function timeout (e.g. "30m", "1h"). Overrides @timeout annotation.'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            if (args.target === 'inngest') {
+                // Use deep Inngest generator
+                const parser = new AnnotationParser();
+                const parseResult = parser.parse(filePath);
+                if (parseResult.errors.length > 0) {
+                    return makeErrorResult('PARSE_ERROR', `Parse errors:\n${parseResult.errors.join('\n')}`);
+                }
+                if (parseResult.workflows.length === 0) {
+                    return makeErrorResult('PARSE_ERROR', 'No workflows found in file');
+                }
+                const workflow = args.workflowName
+                    ? parseResult.workflows.find((w) => w.name === args.workflowName || w.functionName === args.workflowName)
+                    : parseResult.workflows[0];
+                if (!workflow) {
+                    const available = parseResult.workflows.map((w) => w.name).join(', ');
+                    return makeErrorResult('PARSE_ERROR', `Workflow "${args.workflowName}" not found. Available: ${available}`);
+                }
+                const allNodeTypes = [...(workflow.nodeTypes || [])];
+                // Apply CLI overrides to workflow options
+                if (args.cron) {
+                    workflow.options = workflow.options || {};
+                    workflow.options.trigger = { ...workflow.options.trigger, cron: args.cron };
+                }
+                if (args.retries !== undefined) {
+                    workflow.options = workflow.options || {};
+                    workflow.options.retries = args.retries;
+                }
+                if (args.timeout) {
+                    workflow.options = workflow.options || {};
+                    workflow.options.timeout = args.timeout;
+                }
+                const code = generateInngestFunction(workflow, allNodeTypes, {
+                    production: args.production ?? false,
+                    typedEvents: args.typedEvents,
+                    serveHandler: args.serve,
+                    framework: args.framework,
+                });
+                const outputFile = filePath.replace(/\.ts$/, '.inngest.ts');
+                if (args.write !== false) {
+                    const fs = await import('fs');
+                    fs.writeFileSync(outputFile, code, 'utf8');
+                }
+                return makeToolResult({
+                    target: 'inngest',
+                    outputFile,
+                    workflowName: workflow.name,
+                    code: args.write === false ? code : undefined,
+                });
+            }
+            const result = await compileWorkflow(filePath, {
+                write: args.write ?? true,
+                parse: { workflowName: args.workflowName },
+                generate: { production: args.production ?? false },
+            });
+            return makeToolResult({
+                outputFile: result.metadata?.outputFile ?? filePath,
+                warnings: result.analysis?.warnings ?? [],
+            });
+        }
+        catch (err) {
+            return makeErrorResult('COMPILE_ERROR', `fw_compile failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_diff', 'Semantic diff between two workflow files — node type changes, instance changes, connection changes, breaking changes.', {
+        file1: z.string().describe('Path to first workflow file'),
+        file2: z.string().describe('Path to second workflow file'),
+        format: z
+            .enum(['text', 'json', 'compact'])
+            .optional()
+            .describe('Output format (default: text)'),
+        workflowName: z.string().optional().describe('Specific workflow name'),
+    }, async (args) => {
+        try {
+            const [result1, result2] = await Promise.all([
+                parseWorkflow(path.resolve(args.file1), { workflowName: args.workflowName }),
+                parseWorkflow(path.resolve(args.file2), { workflowName: args.workflowName }),
+            ]);
+            if (result1.errors.length > 0) {
+                return makeErrorResult(parseErrorCode(result1.errors), `Parse errors in file1:\n${result1.errors.join('\n')}`);
+            }
+            if (result2.errors.length > 0) {
+                return makeErrorResult(parseErrorCode(result2.errors), `Parse errors in file2:\n${result2.errors.join('\n')}`);
+            }
+            const diff = WorkflowDiffer.compare(result1.ast, result2.ast);
+            const format = args.format ?? 'text';
+            const formatted = formatDiff(diff, format);
+            return makeToolResult(format === 'json' ? JSON.parse(formatted) : formatted);
+        }
+        catch (err) {
+            return makeErrorResult('DIFF_ERROR', `fw_diff failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_query', 'Query workflow structure.\n\nQuery types:\n- nodes: All node instances [{id, nodeType, parent}]\n- connections: All connections [{from, to}] in "node.port" format. Optional: nodeId to filter.\n- deps: Direct upstream dependencies [nodeId[]]. Requires: nodeId\n- dependents: Direct downstream dependents [nodeId[]]. Requires: nodeId\n- data-deps: Data-only upstream dependencies (excludes control flow). Requires: nodeId\n- execution-order: Topological sort of main-flow nodes. Scoped nodes are listed separately.\n- isolated: Nodes with no connections [nodeId[]]\n- dead-ends: Nodes that don\'t reach Exit [nodeId[]]\n- disconnected-outputs: Output ports not connected to anything [{nodeId, ports[]}]\n- node-types: All node type definitions [{name, functionName, inputs[], outputs[]}]', {
+        filePath: z.string().describe('Path to the workflow file'),
+        query: z
+            .enum([
+            'nodes',
+            'connections',
+            'deps',
+            'dependents',
+            'data-deps',
+            'execution-order',
+            'isolated',
+            'dead-ends',
+            'disconnected-outputs',
+            'node-types',
+        ])
+            .describe('Query type'),
+        nodeId: z
+            .string()
+            .optional()
+            .describe('Required for deps/dependents. Optional filter for connections.'),
+        workflowName: z.string().optional().describe('Specific workflow name'),
+    }, async (args) => {
+        try {
+            const filePath = path.resolve(args.filePath);
+            let parseResult = await parseWorkflow(filePath, { workflowName: args.workflowName });
+            // For node-types query, fall back to nodeTypesOnly mode if no workflows found
+            if (parseResult.errors.length > 0 &&
+                args.query === 'node-types' &&
+                parseResult.errors.some((e) => typeof e === 'string' && e.includes('No workflows found'))) {
+                try {
+                    const ntResult = await parseWorkflow(filePath, { nodeTypesOnly: true });
+                    if (ntResult.errors.length === 0) {
+                        parseResult = ntResult;
+                    }
+                }
+                catch {
+                    /* fall through to original error */
+                }
+            }
+            if (parseResult.errors.length > 0) {
+                return makeErrorResult(parseErrorCode(parseResult.errors), `Parse errors:\n${parseResult.errors.join('\n')}`);
+            }
+            const ast = parseResult.ast;
+            switch (args.query) {
+                case 'nodes':
+                    return makeToolResult(getNodes(ast).map((n) => ({
+                        id: n.id,
+                        nodeType: n.nodeType,
+                        parent: n.parent ?? null,
+                    })));
+                case 'connections':
+                    return makeToolResult(getConnections(ast, args.nodeId).map((c) => ({
+                        from: `${c.from.node}.${c.from.port}`,
+                        to: `${c.to.node}.${c.to.port}`,
+                    })));
+                case 'deps':
+                    if (!args.nodeId)
+                        return makeErrorResult('MISSING_PARAM', 'nodeId is required for "deps" query');
+                    return makeToolResult(getDependencies(ast, args.nodeId));
+                case 'dependents':
+                    if (!args.nodeId)
+                        return makeErrorResult('MISSING_PARAM', 'nodeId is required for "dependents" query');
+                    return makeToolResult(getDependents(ast, args.nodeId));
+                case 'execution-order':
+                    try {
+                        const order = getTopologicalOrder(ast);
+                        const allNodeIds = ast.instances.map((n) => n.id);
+                        const scopedNodes = allNodeIds.filter((id) => !order.includes(id));
+                        return makeToolResult({
+                            order,
+                            ...(scopedNodes.length > 0 && {
+                                scopedNodes,
+                                note: 'Scoped nodes execute within their parent scope and are excluded from top-level execution order.',
+                            }),
+                        });
+                    }
+                    catch (cycleErr) {
+                        return makeErrorResult('CYCLE_DETECTED', cycleErr instanceof Error ? cycleErr.message : String(cycleErr));
+                    }
+                case 'isolated':
+                    return makeToolResult(findIsolatedNodes(ast));
+                case 'data-deps':
+                    if (!args.nodeId)
+                        return makeErrorResult('MISSING_PARAM', 'nodeId is required for "data-deps" query');
+                    return makeToolResult(getDataDependencies(ast, args.nodeId));
+                case 'dead-ends':
+                    return makeToolResult(findDeadEndDetails(ast));
+                case 'disconnected-outputs':
+                    return makeToolResult(findDisconnectedOutputPorts(ast));
+                case 'node-types':
+                    return makeToolResult(ast.nodeTypes.map((nt) => ({
+                        name: nt.name,
+                        functionName: nt.functionName,
+                        inputs: Object.keys(nt.inputs),
+                        outputs: Object.keys(nt.outputs),
+                    })));
+                default:
+                    return makeErrorResult('UNKNOWN_QUERY', `Unknown query type: ${args.query}`);
+            }
+        }
+        catch (err) {
+            return makeErrorResult('QUERY_ERROR', `fw_query failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    mcp.tool('fw_doctor', 'Check project environment and configuration for flow-weaver compatibility.', {
+        directory: z
+            .string()
+            .optional()
+            .describe('Directory to check (default: cwd)'),
+    }, async (args) => {
+        try {
+            const dir = path.resolve(args.directory ?? process.cwd());
+            const report = runDoctorChecks(dir);
+            return makeToolResult(report);
+        }
+        catch (err) {
+            return makeErrorResult('DOCTOR_ERROR', `fw_doctor failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=tools-query.js.map

package/dist/mcp/tools-template.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers MCP tools for listing and scaffolding workflow/node templates.
+ * Registers two tools:
+ * - `fw_list_templates` - lists available scaffold templates, optionally filtered by type.
+ * - `fw_scaffold` - generates a workflow or node file from a named template.
+ * @param mcp - The MCP server instance to register tools on.
+ */
+export declare function registerTemplateTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-template.d.ts.map

package/dist/mcp/tools-template.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import * as path from 'path';
+import * as fs from 'fs';
+import { listWorkflowTemplates, listNodeTemplates, getWorkflowTemplate, getNodeTemplate, generateWorkflowFromTemplate, generateNodeFromTemplate, } from '../api/templates.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+/**
+ * Registers MCP tools for listing and scaffolding workflow/node templates.
+ * Registers two tools:
+ * - `fw_list_templates` - lists available scaffold templates, optionally filtered by type.
+ * - `fw_scaffold` - generates a workflow or node file from a named template.
+ * @param mcp - The MCP server instance to register tools on.
+ */
+export function registerTemplateTools(mcp) {
+    mcp.tool('fw_list_templates', 'List available scaffold templates for workflows and nodes.', {
+        type: z
+            .enum(['workflow', 'node', 'all'])
+            .optional()
+            .describe('Filter template type (default: all)'),
+    }, async (args) => {
+        const filterType = args.type ?? 'all';
+        const result = [];
+        if (filterType === 'workflow' || filterType === 'all') {
+            for (const t of listWorkflowTemplates()) {
+                result.push({
+                    id: t.id,
+                    name: t.name,
+                    description: t.description,
+                    type: 'workflow',
+                    category: t.category,
+                });
+            }
+        }
+        if (filterType === 'node' || filterType === 'all') {
+            for (const t of listNodeTemplates()) {
+                result.push({ id: t.id, name: t.name, description: t.description, type: 'node' });
+            }
+        }
+        return makeToolResult(result);
+    });
+    mcp.tool('fw_scaffold', 'Create a workflow or node from a template.', {
+        template: z.string().describe('Template name (e.g. "sequential", "validator")'),
+        filePath: z.string().describe('Output file path'),
+        name: z.string().optional().describe('Workflow/node function name'),
+        preview: z
+            .boolean()
+            .optional()
+            .describe('Preview only — return generated code without writing (default: false)'),
+        config: z
+            .record(z.unknown())
+            .optional()
+            .describe('Template configuration (e.g. { nodes: ["fetch", "parse"], input: "rawData" })'),
+    }, async (args) => {
+        try {
+            const outPath = path.resolve(args.filePath);
+            // Try workflow template first
+            const wt = getWorkflowTemplate(args.template);
+            if (wt) {
+                const code = generateWorkflowFromTemplate(args.template, {
+                    workflowName: args.name ?? 'myWorkflow',
+                    config: args.config,
+                });
+                if (args.preview) {
+                    return makeToolResult({
+                        success: true,
+                        preview: true,
+                        type: 'workflow',
+                        template: args.template,
+                        code,
+                    });
+                }
+                // Append to file if it exists, otherwise create
+                if (fs.existsSync(outPath)) {
+                    fs.appendFileSync(outPath, '\n\n' + code, 'utf8');
+                }
+                else {
+                    fs.writeFileSync(outPath, code, 'utf8');
+                }
+                return makeToolResult({
+                    success: true,
+                    filePath: outPath,
+                    type: 'workflow',
+                    template: args.template,
+                });
+            }
+            // Try node template
+            const nt = getNodeTemplate(args.template);
+            if (nt) {
+                const code = generateNodeFromTemplate(args.template, args.name ?? 'myNode', args.config);
+                if (args.preview) {
+                    return makeToolResult({
+                        success: true,
+                        preview: true,
+                        type: 'node',
+                        template: args.template,
+                        code,
+                    });
+                }
+                // Append to file if it exists, otherwise create
+                if (fs.existsSync(outPath)) {
+                    fs.appendFileSync(outPath, '\n\n' + code, 'utf8');
+                }
+                else {
+                    fs.writeFileSync(outPath, code, 'utf8');
+                }
+                return makeToolResult({
+                    success: true,
+                    filePath: outPath,
+                    type: 'node',
+                    template: args.template,
+                });
+            }
+            return makeErrorResult('TEMPLATE_NOT_FOUND', `Template "${args.template}" not found. Use fw_list_templates to see available templates.`);
+        }
+        catch (err) {
+            return makeErrorResult('SCAFFOLD_ERROR', `fw_scaffold failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=tools-template.js.map

package/dist/mcp/types.d.ts

@@ -0,0 +1,70 @@
+import type { io as socketIO } from 'socket.io-client';
+import type { EventBuffer } from './event-buffer.js';
+import type { EditorConnection } from './editor-connection.js';
+/** Options for initializing the MCP server. */
+export interface McpServerOptions {
+    /** WebSocket server URL for editor connection. */
+    server?: string;
+    /** Whether to use stdio transport instead of SSE. */
+    stdio?: boolean;
+    /** Internal: injected deps for testing */
+    _testDeps?: {
+        buffer?: EventBuffer;
+        connection?: EditorConnection;
+    };
+}
+/** Dependencies injected into tool registration functions for CLI interaction and logging. */
+export interface RegistrationDeps {
+    /** Execute a shell command and return its stdout and exit code. */
+    execCommand: (cmd: string) => Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+    /** Prompt the user for interactive input. */
+    prompt: (question: string) => Promise<string>;
+    /** Log a message to the console. */
+    log: (msg: string) => void;
+    /** Resolve the path to the Flow Weaver CLI executable. */
+    resolveCliPath: () => string;
+}
+/** Acknowledgement response returned by the editor after processing a command. */
+export interface AckResponse {
+    /** Unique identifier correlating the response to its originating request. */
+    requestId: string;
+    /** Whether the command executed successfully. */
+    success: boolean;
+    /** The command result payload, present on success. */
+    result?: unknown;
+    /** Error message, present on failure. */
+    error?: string;
+}
+/** A timestamped event stored in the event buffer. */
+export interface BufferedEvent {
+    /** The event name (e.g. "fw:node-added", "mcp:status"). */
+    event: string;
+    /** The event payload. */
+    data: unknown;
+    /** ISO 8601 timestamp of when the event was buffered. */
+    timestamp: string;
+}
+/** Options for configuring the editor WebSocket connection. */
+export interface EditorConnectionOptions {
+    /** Custom socket.io factory, primarily used for injecting mocks in tests. */
+    ioFactory?: typeof socketIO;
+    /** Timeout in milliseconds for awaiting command acknowledgements. Defaults to 10000. */
+    ackTimeout?: number;
+}
+/** Configuration for filtering and deduplicating events in the event buffer. */
+export interface EventFilterConfig {
+    /** Event name patterns to include. Empty array means all events are included. Supports trailing `*` for prefix matching. */
+    include: string[];
+    /** Event name patterns to exclude (applied after include). Supports trailing `*` for prefix matching. */
+    exclude: string[];
+    /** Collapse duplicate events of the same type within this window in milliseconds. 0 disables deduplication. */
+    dedupeWindowMs: number;
+    /** Maximum number of events to retain before evicting the oldest. */
+    maxBufferSize: number;
+}
+/** Default event filter configuration. Excludes `fw:ack` events, dedupes within 200ms, and retains up to 500 events. */
+export declare const DEFAULT_EVENT_FILTER: EventFilterConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/types.js

@@ -0,0 +1,8 @@
+/** Default event filter configuration. Excludes `fw:ack` events, dedupes within 200ms, and retains up to 500 events. */
+export const DEFAULT_EVENT_FILTER = {
+    include: [],
+    exclude: ['fw:ack'],
+    dedupeWindowMs: 200,
+    maxBufferSize: 500,
+};
+//# sourceMappingURL=types.js.map

package/dist/mcp/workflow-executor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Workflow executor for MCP-side compilation and execution.
+ * Copies source to a temp file, compiles all workflows in-place, then dynamically imports and executes.
+ */
+import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+/** A single trace event captured during workflow execution. */
+export interface ExecutionTraceEvent {
+    /** The event type (e.g. "NODE_STARTED", "NODE_COMPLETED"). */
+    type: string;
+    /** Unix timestamp in milliseconds when the event was recorded. */
+    timestamp: number;
+    /** Additional event data. */
+    data?: Record<string, unknown>;
+}
+/** Result returned after executing a workflow from a file. */
+export interface ExecuteWorkflowResult {
+    /** The return value of the executed workflow function. */
+    result: unknown;
+    /** The name of the exported function that was executed. */
+    functionName: string;
+    /** Wall-clock execution time in milliseconds. */
+    executionTime: number;
+    /** Execution trace events, included when `includeTrace` is enabled. */
+    trace?: ExecutionTraceEvent[];
+}
+/**
+ * Compiles and executes a workflow from a TypeScript source file.
+ * Copies the source to a temp file, compiles all workflows in-place (preserving sibling
+ * functions for workflow composition), injects a trace-capturing debugger, and dynamically
+ * imports and runs the target workflow function.
+ * @param filePath - Path to the workflow `.ts` source file.
+ * @param params - Parameters to pass to the workflow function.
+ * @param options - Execution options.
+ * @param options.workflowName - Name of a specific exported workflow function to execute.
+ *   If omitted, the first exported function is used.
+ * @param options.production - Enable production mode (no debug events). Defaults to `!includeTrace`.
+ * @param options.includeTrace - Whether to capture and return execution trace events. Defaults to `true`.
+ * @returns The workflow result, function name, execution time, and optional trace.
+ * @throws If no exported workflow function is found in the compiled module.
+ */
+export declare function executeWorkflowFromFile(filePath: string, params?: Record<string, unknown>, options?: {
+    workflowName?: string;
+    production?: boolean;
+    includeTrace?: boolean;
+    mocks?: FwMockConfig;
+}): Promise<ExecuteWorkflowResult>;
+//# sourceMappingURL=workflow-executor.d.ts.map