@contextual-io/cli 0.7.1 → 0.8.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @contextual-io/cli
 $ ctxl COMMAND
 running command...
 $ ctxl (--version)
-@contextual-io/cli/0.7.1 linux-x64 node-v25.9.0
+@contextual-io/cli/0.8.0 linux-x64 node-v25.9.0
 $ ctxl --help [COMMAND]
 USAGE
   $ ctxl COMMAND
@@ -39,6 +39,8 @@ USAGE
 * [`ctxl config login`](#ctxl-config-login)
 * [`ctxl config use CONFIG-ID`](#ctxl-config-use-config-id)
 * [`ctxl help [COMMAND]`](#ctxl-help-command)
+* [`ctxl mcp <COMMAND>`](#ctxl-mcp-command)
+* [`ctxl mcp serve [INTERFACE]`](#ctxl-mcp-serve-interface)
 * [`ctxl records <COMMAND>`](#ctxl-records-command)
 * [`ctxl records add [URI]`](#ctxl-records-add-uri)
 * [`ctxl records create [URI]`](#ctxl-records-create-uri)
@@ -259,6 +261,55 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.36/src/commands/help.ts)_
 
+## `ctxl mcp <COMMAND>`
+
+Manage local MCP server commands. Start with 'ctxl mcp serve' to run the local MCP bridge.
+
+```
+USAGE
+  $ ctxl mcp <COMMAND>
+
+DESCRIPTION
+  Manage local MCP server commands. Start with 'ctxl mcp serve' to run the local MCP bridge.
+
+EXAMPLES
+  $ ctxl mcp
+
+  $ ctxl mcp flow-editor --flow my-flow-id
+```
+
+## `ctxl mcp serve [INTERFACE]`
+
+Start a local MCP HTTP server that connects to SolutionAI for a given interface type. By default it binds to http://localhost:5051/. The server fetches the full tool manifest from SolutionAI and serves all tools immediately. Pass a flowId with each tool call to target a specific flow, or use list_sessions to discover available flows.
+
+```
+USAGE
+  $ ctxl mcp serve [INTERFACE] [-C <value>] [-f <value>] [-p <value>] [-t] [-V]
+
+ARGUMENTS
+  [INTERFACE]  [default: flow-editor] Interface type to scope tools for. Available interfaces depend on your platform
+               version.
+
+FLAGS
+  -V, --verbose           emit verbose MCP runtime diagnostics
+  -f, --flow=<value>      pre-filter session listing to a specific flow ID
+  -p, --port=<value>      local HTTP port (default: 5051)
+  -t, --[no-]tool-prefix  prefix all MCP tool names with ctxl_
+
+GLOBAL FLAGS
+  -C, --config-id=<value>  Specify config id to use for call.
+
+DESCRIPTION
+  Start a local MCP HTTP server that connects to SolutionAI for a given interface type. By default it binds to
+  http://localhost:5051/. The server fetches the full tool manifest from SolutionAI and serves all tools immediately.
+  Pass a flowId with each tool call to target a specific flow, or use list_sessions to discover available flows.
+
+EXAMPLES
+  $ ctxl mcp serve
+
+  $ ctxl mcp serve flow-editor --flow my-flow-id
+```
+
 ## `ctxl records <COMMAND>`
 
 Manage records.

package/dist/base.js

@@ -123,7 +123,13 @@ export class BaseConfigCommand extends Command {
             let { message } = err;
             if (err instanceof ZodError) {
                 const flattened = z.flattenError(err);
-                message = flattened.formErrors.join("\n");
+                const fieldErrors = Object.entries(flattened.fieldErrors)
+                    .flatMap(([field, errors]) => (errors ?? []).map((error) => `${field}: ${error}`));
+                const combinedErrors = [
+                    ...flattened.formErrors,
+                    ...fieldErrors,
+                ];
+                message = combinedErrors.join("\n") || err.message;
             }
             if (!/See more help with/.test(message)) {
                 message += "\nSee more help with --help";

package/dist/commands/mcp/index.d.ts

@@ -0,0 +1,9 @@
+import { BaseConfigCommand } from "../../base.js";
+export default class Mcp extends BaseConfigCommand<typeof Mcp> {
+    static args: {};
+    static description: string;
+    static examples: string[];
+    static flags: {};
+    static usage: string[];
+    run(): Promise<void>;
+}

package/dist/commands/mcp/index.js

@@ -0,0 +1,16 @@
+import { BaseConfigCommand } from "../../base.js";
+export default class Mcp extends BaseConfigCommand {
+    static args = {};
+    static description = "Manage local MCP server commands. Start with 'ctxl mcp serve' to run the local MCP bridge.";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> flow-editor --flow my-flow-id",
+    ];
+    static flags = {};
+    static usage = [
+        "<%= command.id %> <COMMAND>",
+    ];
+    async run() {
+        await this.showHelp();
+    }
+}

package/dist/commands/mcp/serve.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from "../../base.js";
+export default class McpServe extends BaseCommand<typeof McpServe> {
+    static args: {
+        interface: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        flow: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        port: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "tool-prefix": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private resolveToken;
+}

package/dist/commands/mcp/serve.js

@@ -0,0 +1,124 @@
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base.js";
+import { createBridgeManager } from "../../mcp/bridge-manager.js";
+import { startCtxlMcpHttpServer } from "../../mcp/http-server.js";
+import { createCtxlMcpRuntime } from "../../mcp/runtime.js";
+import { defaultToolPrefix } from "../../mcp/server.js";
+const defaultHost = "127.0.0.1";
+const defaultPort = 5051;
+const getLocalhostAddress = (port) => `http://localhost:${port}/`;
+export default class McpServe extends BaseCommand {
+    static args = {
+        interface: Args.string({
+            default: "flow-editor",
+            description: "Interface type to scope tools for. Available interfaces depend on your platform version.",
+            required: false,
+        }),
+    };
+    static description = [
+        "Start a local MCP HTTP server that connects to SolutionAI for a given interface type.",
+        `By default it binds to ${getLocalhostAddress(defaultPort)}.`,
+        "The server fetches the full tool manifest from SolutionAI and serves all tools immediately.",
+        "Pass a flowId with each tool call to target a specific flow, or use list_sessions to discover available flows.",
+    ].join(" ");
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> flow-editor --flow my-flow-id",
+    ];
+    static flags = {
+        flow: Flags.string({
+            char: "f",
+            description: "pre-filter session listing to a specific flow ID",
+        }),
+        port: Flags.integer({
+            char: "p",
+            description: `local HTTP port (default: ${defaultPort})`,
+        }),
+        "tool-prefix": Flags.boolean({
+            allowNo: true,
+            char: "t",
+            default: false,
+            description: `prefix all MCP tool names with ${defaultToolPrefix}`,
+        }),
+        url: Flags.string({
+            description: "override MCP route URL (http/https)",
+            hidden: true,
+        }),
+        verbose: Flags.boolean({
+            allowNo: false,
+            char: "V",
+            description: "emit verbose MCP runtime diagnostics",
+        }),
+    };
+    async run() {
+        const port = this.flags.port ?? defaultPort;
+        const toolPrefix = this.flags["tool-prefix"] ? defaultToolPrefix : "";
+        const interfaceType = this.args.interface;
+        const config = await this.currentConfig();
+        const server = await startCtxlMcpHttpServer({
+            createBridgeManager: () => createBridgeManager({
+                config,
+                interfaceType,
+                resolveToken: () => this.resolveToken(),
+                url: this.flags.url,
+                verbose: this.flags.verbose,
+            }),
+            createRuntime: (bridgeManager) => createCtxlMcpRuntime({
+                bridgeManager,
+                config,
+                disambiguator: {
+                    description: "The ID of the flow to operate on. The user should know which flow they are working in. Use list_sessions only if the flow ID is unknown.",
+                    key: "flowId",
+                },
+                flowId: this.flags.flow,
+                interfaceType,
+                toolPrefix,
+                url: this.flags.url,
+                verbose: this.flags.verbose,
+                version: this.config.version,
+            }),
+            host: defaultHost,
+            port,
+            verbose: this.flags.verbose,
+        });
+        this.log(`MCP server running at ${getLocalhostAddress(port)} (interface: ${interfaceType})`);
+        let isShuttingDown = false;
+        let settleShutdown;
+        const shutdownComplete = new Promise((resolve) => {
+            settleShutdown = resolve;
+        });
+        const shutdown = async () => {
+            if (isShuttingDown) {
+                return;
+            }
+            isShuttingDown = true;
+            this.log("\nMCP server stopping...");
+            setTimeout(() => {
+                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+                process.exit(0);
+            }, 2000).unref();
+            await server.close();
+            settleShutdown?.();
+        };
+        const onSignal = () => {
+            if (isShuttingDown) {
+                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+                process.exit(0);
+                return;
+            }
+            // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+            shutdown().catch(() => process.exit(1));
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        process.on("SIGQUIT", onSignal);
+        await shutdownComplete;
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+        process.removeListener("SIGQUIT", onSignal);
+    }
+    async resolveToken() {
+        const { bearerToken } = await this.currentConfig();
+        return bearerToken;
+    }
+}

package/dist/mcp/bridge-manager.d.ts

@@ -0,0 +1,29 @@
+import type { McpToolDefinition } from "../models/mcp.js";
+import type { Config } from "../models/user-config.js";
+import { McpSessionState } from "./session.js";
+import { McpSocketBridge } from "./socket-bridge.js";
+export type ManagedBridge = {
+    readonly bridge: McpSocketBridge;
+    readonly dynamicTools: Map<string, McpToolDefinition>;
+    readonly flowId: string;
+    readonly session: McpSessionState;
+};
+type BridgeListener = {
+    onToolsChanged: () => void;
+};
+export type BridgeManagerOptions = {
+    config: Config;
+    interfaceType: string;
+    resolveToken: () => Promise<string>;
+    url?: string;
+    verbose?: boolean;
+};
+export type BridgeManager = {
+    acquire: (flowId: string) => Promise<ManagedBridge>;
+    addListener: (flowId: string, listener: BridgeListener) => () => void;
+    closeAll: () => Promise<void>;
+    get: (flowId: string) => ManagedBridge | undefined;
+    getAny: () => ManagedBridge | undefined;
+};
+export declare const createBridgeManager: ({ config, interfaceType, resolveToken, url, verbose, }: BridgeManagerOptions) => BridgeManager;
+export {};

package/dist/mcp/bridge-manager.js

@@ -0,0 +1,260 @@
+import { getSolutionAiApiEndpoint } from "../utils/endpoints.js";
+import { createMcpLogHelpers } from "./logger.js";
+import { McpSessionState } from "./session.js";
+import { getMcpSocketRoute, McpSocketBridge } from "./socket-bridge.js";
+/* eslint-disable no-await-in-loop */
+const reconnectMaxAttempts = 3;
+const reconnectBaseDelayMs = 2000;
+const reconnectCooldownMs = 30_000;
+const defaultMcpRoutePath = "/comms";
+const abortableSleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted) {
+        resolve();
+        return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+export const createBridgeManager = ({ config, interfaceType, resolveToken, url, verbose, }) => {
+    const { log, logError } = createMcpLogHelpers(verbose);
+    const { tenantId } = config;
+    const bridges = new Map();
+    const listeners = new Map();
+    const reconnectAborts = new Map();
+    const autoRebindTimers = new Map();
+    const lastReconnectAts = new Map();
+    let closed = false;
+    const getRouteUrl = () => url ?? `${getSolutionAiApiEndpoint(tenantId, config.silo)}${defaultMcpRoutePath}`;
+    const getRoute = () => getMcpSocketRoute({ url: getRouteUrl() });
+    const notifyListeners = (flowId) => {
+        const flowListeners = listeners.get(flowId);
+        if (!flowListeners)
+            return;
+        for (const listener of flowListeners) {
+            listener.onToolsChanged();
+        }
+    };
+    const syncDynamicTools = (managed, payload, replace) => {
+        if (replace) {
+            managed.dynamicTools.clear();
+        }
+        if (payload) {
+            for (const tool of payload) {
+                managed.dynamicTools.set(tool.name, tool);
+            }
+        }
+        notifyListeners(managed.flowId);
+    };
+    const attemptReconnect = async (flowId) => {
+        const abort = new AbortController();
+        reconnectAborts.set(flowId, abort);
+        const managed = bridges.get(flowId);
+        if (!managed)
+            return;
+        try {
+            for (let attempt = 1; attempt <= reconnectMaxAttempts; attempt++) {
+                if (abort.signal.aborted || closed)
+                    return;
+                const delay = reconnectBaseDelayMs * 2 ** (attempt - 1);
+                await abortableSleep(delay, abort.signal);
+                if (abort.signal.aborted || closed)
+                    return;
+                log("reconnect_attempt", { attempt, flowId, maxAttempts: reconnectMaxAttempts, tenantId });
+                try {
+                    const token = await resolveToken();
+                    const route = getRoute();
+                    await managed.bridge.connect({
+                        interfaceType,
+                        orgId: tenantId,
+                        token,
+                        url: route.url,
+                    });
+                    if (abort.signal.aborted || closed) {
+                        await managed.bridge.disconnect().catch(() => { });
+                        return;
+                    }
+                    const manifest = await managed.bridge.requestManifest(interfaceType);
+                    syncDynamicTools(managed, manifest.definitions, true);
+                    managed.session.markReady();
+                    lastReconnectAts.set(flowId, Date.now());
+                    log("reconnect_success", { attempt, flowId, tenantId, toolCount: manifest.definitions.length });
+                    return;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : `${error}`;
+                    logError("reconnect_attempt_failed", { attempt, flowId, message, tenantId });
+                }
+            }
+            logError("reconnect_exhausted", { flowId, maxAttempts: reconnectMaxAttempts, tenantId });
+            managed.session.markError("SOCKET_DISCONNECTED", "Reconnection failed after all retry attempts.");
+        }
+        finally {
+            const current = reconnectAborts.get(flowId);
+            if (current === abort) {
+                reconnectAborts.delete(flowId);
+            }
+        }
+    };
+    const createManagedBridge = (flowId) => {
+        const session = new McpSessionState();
+        const dynamicTools = new Map();
+        const bridge = new McpSocketBridge({
+            onCommandStatus({ commandId, status, toolName }) {
+                log("command_status", { commandId, flowId, status, toolName });
+            },
+            onDetached({ mcpSessionId, reason }) {
+                const previousConnection = session.getSnapshot().connection;
+                session.markUnbound();
+                log("remote_detached", { flowId, mcpSessionId, reason, tenantId });
+                if (reason === "target-disconnected" && previousConnection && !closed) {
+                    const timer = setTimeout(() => {
+                        autoRebindTimers.delete(flowId);
+                        if (closed || session.getSnapshot().bindingState === "bound")
+                            return;
+                        log("auto_rebind_attempt", { flowId, tenantId });
+                        session.beginBind();
+                        bridge.bindSession({ flowId: previousConnection.flowId })
+                            .then((result) => {
+                            session.markBound({ boundAt: result.boundAt, flowId: result.flowId, flowName: result.flowName });
+                            notifyListeners(flowId);
+                            log("auto_rebind_success", { flowId: result.flowId, tenantId });
+                        })
+                            .catch(() => {
+                            session.markUnbound();
+                        });
+                    }, 3000);
+                    autoRebindTimers.set(flowId, timer);
+                }
+            },
+            onDisconnected(reason) {
+                session.markUnbound();
+                const { serverState } = session.getSnapshot();
+                if (serverState !== "ready" || closed) {
+                    logError("socket_disconnected", { flowId, reason, tenantId });
+                    return;
+                }
+                const lastReconnectAt = lastReconnectAts.get(flowId) ?? 0;
+                const canReconnect = Date.now() - lastReconnectAt > reconnectCooldownMs;
+                if (canReconnect) {
+                    log("reconnect_start", { flowId, reason, tenantId });
+                    attemptReconnect(flowId).catch(() => {
+                        session.markError("SOCKET_DISCONNECTED", `Reconnection failed after socket disconnect (${reason})`);
+                    });
+                    return;
+                }
+                logError("socket_disconnected", { flowId, reason, tenantId });
+                session.markError("SOCKET_DISCONNECTED", `Socket disconnected (${reason})`);
+            },
+            onSessionAvailable({ flowId: sessionFlowId, flowName }) {
+                log("session_available", { flowId: sessionFlowId, flowName });
+            },
+            onSessionUnavailable({ flowId: sessionFlowId, reason }) {
+                log("session_unavailable", { flowId: sessionFlowId, reason });
+            },
+            onToolRegistrySync({ action, definitions, mcpSessionId, replace: shouldReplace, tools }) {
+                log("tool_registry_received", {
+                    action,
+                    definitionCount: definitions.length,
+                    flowId,
+                    mcpSessionId,
+                    replace: shouldReplace === true,
+                    toolCount: tools.length,
+                });
+                if (action === "clear") {
+                    log("tool_registry_clear_skipped", { flowId, mcpSessionId });
+                    notifyListeners(managed.flowId);
+                    return;
+                }
+                syncDynamicTools(managed, definitions, shouldReplace === true);
+            },
+        });
+        const managed = { bridge, dynamicTools, flowId, session };
+        return managed;
+    };
+    return {
+        async acquire(flowId) {
+            // Exact match by flowId
+            const existing = bridges.get(flowId);
+            if (existing && existing.bridge.isConnected) {
+                return existing;
+            }
+            // Reuse any connected bridge that's already bound to this flow
+            for (const [key, managed] of bridges.entries()) {
+                if (managed.bridge.isConnected && managed.session.getSnapshot().connection?.flowId === flowId) {
+                    if (key !== flowId) {
+                        bridges.delete(key);
+                        bridges.set(flowId, managed);
+                    }
+                    return managed;
+                }
+            }
+            // No reusable bridge — create and connect a new one
+            const managed = existing ?? createManagedBridge(flowId);
+            if (!existing) {
+                bridges.set(flowId, managed);
+            }
+            const token = await resolveToken();
+            const route = getRoute();
+            log("bridge_connect_start", { flowId, tenantId });
+            await managed.bridge.connect({
+                interfaceType,
+                orgId: tenantId,
+                token,
+                url: route.url,
+            });
+            try {
+                const manifest = await managed.bridge.requestManifest(interfaceType);
+                syncDynamicTools(managed, manifest.definitions, true);
+                managed.session.markReady();
+                log("bridge_connect_ready", { flowId, tenantId, toolCount: manifest.definitions.length });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : `${error}`;
+                logError("bridge_manifest_failed", { flowId, message, tenantId });
+                managed.session.markError("MANIFEST_FAILED", message);
+            }
+            return managed;
+        },
+        addListener(flowId, listener) {
+            let flowListeners = listeners.get(flowId);
+            if (!flowListeners) {
+                flowListeners = new Set();
+                listeners.set(flowId, flowListeners);
+            }
+            flowListeners.add(listener);
+            return () => {
+                flowListeners.delete(listener);
+                if (flowListeners.size === 0) {
+                    listeners.delete(flowId);
+                }
+            };
+        },
+        async closeAll() {
+            closed = true;
+            for (const abort of reconnectAborts.values()) {
+                abort.abort();
+            }
+            reconnectAborts.clear();
+            for (const timer of autoRebindTimers.values()) {
+                clearTimeout(timer);
+            }
+            autoRebindTimers.clear();
+            await Promise.all([...bridges.values()].map((managed) => managed.bridge.disconnect().catch(() => { })));
+            bridges.clear();
+            listeners.clear();
+        },
+        get(flowId) {
+            return bridges.get(flowId);
+        },
+        getAny() {
+            for (const managed of bridges.values()) {
+                if (managed.bridge.isConnected) {
+                    return managed;
+                }
+            }
+        },
+    };
+};

package/dist/mcp/contracts.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export declare const makePrefixed: <P extends string>(prefix: P) => <T extends string>(tool: T) => `${P}${T}`;
+export declare const isInArray: <T extends string>(haystack: T[], needle: string) => needle is T;
+export declare const McpDetachedPayload: z.ZodObject<{
+    detachedAt: z.ZodNumber;
+    mcpSessionId: z.ZodString;
+    reason: z.ZodEnum<{
+        "target-disconnected": "target-disconnected";
+        "mcp-disconnected": "mcp-disconnected";
+        "manual-detach": "manual-detach";
+    }>;
+}, z.core.$strip>;
+export type McpDetachedPayload = z.infer<typeof McpDetachedPayload>;
+export declare const McpErrorPayload: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;
+export type McpErrorPayload = z.infer<typeof McpErrorPayload>;
+export declare const McpToolErrorPayload: z.ZodObject<{
+    commandId: z.ZodOptional<z.ZodString>;
+    error: z.ZodObject<{
+        data: z.ZodOptional<z.ZodUnknown>;
+        message: z.ZodString;
+        code: z.ZodEnum<{
+            INTERNAL_ERROR: "INTERNAL_ERROR";
+            NOT_ATTACHED: "NOT_ATTACHED";
+            UNKNOWN_TOOL: "UNKNOWN_TOOL";
+            COMMAND_IN_FLIGHT: "COMMAND_IN_FLIGHT";
+            TIMEOUT: "TIMEOUT";
+            UNAUTHORIZED: "UNAUTHORIZED";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type McpToolErrorPayload = z.infer<typeof McpToolErrorPayload>;
+export declare const McpSessionAvailablePayload: z.ZodObject<{
+    flowId: z.ZodString;
+    flowName: z.ZodString;
+}, z.core.$strip>;
+export type McpSessionAvailablePayload = z.infer<typeof McpSessionAvailablePayload>;
+export declare const McpSessionUnavailablePayload: z.ZodObject<{
+    flowId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type McpSessionUnavailablePayload = z.infer<typeof McpSessionUnavailablePayload>;

package/dist/mcp/contracts.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { McpDetachReason as McpDetachReasonSchema, McpSessionId, McpToolError, McpToolErrorCode, } from "../models/mcp.js";
+export const makePrefixed = (prefix) => (tool) => `${prefix}${tool}`;
+export const isInArray = (haystack, needle) => haystack.includes(needle);
+// Schemas for socket events that don't have a direct model equivalent.
+export const McpDetachedPayload = z.object({
+    detachedAt: z.number().int(),
+    mcpSessionId: McpSessionId,
+    reason: McpDetachReasonSchema,
+});
+export const McpErrorPayload = z.object({
+    error: z.string(),
+});
+export const McpToolErrorPayload = z.object({
+    commandId: z.string().optional(),
+    error: McpToolError.extend({
+        code: McpToolErrorCode,
+    }),
+});
+export const McpSessionAvailablePayload = z.object({
+    flowId: z.string(),
+    flowName: z.string(),
+});
+export const McpSessionUnavailablePayload = z.object({
+    flowId: z.string(),
+    reason: z.string(),
+});

package/dist/mcp/http-server.d.ts

@@ -0,0 +1,45 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { BridgeManager } from "./bridge-manager.js";
+import type { CtxlMcpRuntime } from "./runtime.js";
+type McpRequest = IncomingMessage & {
+    body?: unknown;
+};
+type McpResponse = ServerResponse;
+type HttpSessionTransport = Pick<StreamableHTTPServerTransport, "close" | "handleRequest" | "sessionId"> & {
+    onclose?: (() => void) | undefined;
+    onerror?: ((error: Error) => void) | undefined;
+};
+type TransportFactory = (callbacks: {
+    onSessionClosed: (sessionId: string) => void;
+    onSessionInitialized: (sessionId: string) => void;
+}) => HttpSessionTransport;
+type SessionManagerOptions = {
+    createBridgeManager: () => BridgeManager;
+    createRuntime: (bridgeManager: BridgeManager) => CtxlMcpRuntime;
+    createTransport?: TransportFactory;
+    verbose?: boolean;
+};
+type StartHttpServerOptions = SessionManagerOptions & {
+    host: string;
+    port: number;
+};
+export declare const getHttpServerError: (error: unknown, port: number) => Error;
+export declare const createCtxlMcpHttpSessionManager: ({ createBridgeManager, createRuntime, createTransport, verbose, }: SessionManagerOptions) => {
+    closeAllSessions(reason: string): Promise<void>;
+    handleDelete(request: McpRequest, response: McpResponse): Promise<void>;
+    handleGet(request: McpRequest, response: McpResponse): Promise<void>;
+    handlePost(request: McpRequest, response: McpResponse): Promise<void>;
+    hasSession(sessionId: string): boolean;
+};
+export declare const startCtxlMcpHttpServer: ({ host, port, ...sessionManagerOptions }: StartHttpServerOptions) => Promise<{
+    close(): Promise<void>;
+    sessionManager: {
+        closeAllSessions(reason: string): Promise<void>;
+        handleDelete(request: McpRequest, response: McpResponse): Promise<void>;
+        handleGet(request: McpRequest, response: McpResponse): Promise<void>;
+        handlePost(request: McpRequest, response: McpResponse): Promise<void>;
+        hasSession(sessionId: string): boolean;
+    };
+}>;
+export {};