@contextual-io/cli 0.7.1 → 0.8.1

package/dist/mcp/server.js

@@ -0,0 +1,308 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { isInArray, makePrefixed } from "./contracts.js";
+const defaultMaxResponseBytes = 512 * 1024;
+const defaultToolPrefix = "ctxl_";
+const baseToolNames = ["list_sessions", "info"];
+const emptyInputSchema = {
+    additionalProperties: false,
+    properties: {},
+    type: "object",
+};
+export { defaultToolPrefix };
+const toToolErrorResult = (message) => ({
+    content: [
+        {
+            text: message,
+            type: "text",
+        },
+    ],
+    isError: true,
+});
+const truncatePayload = (payload, maxBytes) => {
+    const serialized = JSON.stringify(payload);
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    if (bytes <= maxBytes) {
+        return payload;
+    }
+    return {
+        bytes,
+        preview: serialized.slice(0, 2000),
+        truncated: true,
+    };
+};
+const isRecord = (value) => (value !== null && typeof value === "object" && !Array.isArray(value));
+export const toExposedDynamicToolName = (toolName, prefix) => prefix && !toolName.startsWith(prefix) ? `${prefix}${toolName}` : toolName;
+const mapDynamicToolForExposure = (tool, prefix) => ({
+    ...tool,
+    name: toExposedDynamicToolName(tool.name, prefix),
+});
+const toToolSuccessResult = (payload, maxResponseBytes) => {
+    const bounded = truncatePayload(payload, maxResponseBytes);
+    const text = JSON.stringify(bounded);
+    const structuredContent = isRecord(bounded)
+        ? bounded
+        : undefined;
+    return {
+        content: [
+            {
+                text,
+                type: "text",
+            },
+        ],
+        ...(structuredContent && { structuredContent }),
+    };
+};
+const injectDisambiguator = (inputSchema, disambiguator) => {
+    const properties = inputSchema.properties ?? {};
+    if (disambiguator.key in properties) {
+        return inputSchema;
+    }
+    return {
+        ...inputSchema,
+        properties: {
+            [disambiguator.key]: {
+                description: disambiguator.description,
+                type: "string",
+            },
+            ...properties,
+        },
+        required: [disambiguator.key, ...(inputSchema.required ?? [])],
+    };
+};
+const isNullableAnyOf = (prop) => {
+    const variants = prop.anyOf ?? prop.oneOf;
+    if (!Array.isArray(variants) || variants.length !== 2)
+        return undefined;
+    const nullVariant = variants.find((v) => v.type === "null");
+    const innerVariant = variants.find((v) => v.type !== "null");
+    if (!nullVariant || !innerVariant)
+        return undefined;
+    return { inner: innerVariant };
+};
+const flattenNullableProperty = (prop) => {
+    const nullable = isNullableAnyOf(prop);
+    if (!nullable)
+        return prop;
+    const { inner } = nullable;
+    const description = (prop.description ?? inner.description);
+    if (inner.enum && Array.isArray(inner.enum)) {
+        const innerType = inner.type;
+        const nullableType = innerType
+            ? (Array.isArray(innerType) ? [...innerType, "null"] : [innerType, "null"])
+            : undefined;
+        return {
+            ...inner,
+            enum: [...inner.enum, null],
+            ...(nullableType && { type: nullableType }),
+            ...(description && { description }),
+        };
+    }
+    const innerType = inner.type;
+    const types = Array.isArray(innerType) ? [...innerType, "null"] : [innerType, "null"];
+    return {
+        ...inner,
+        type: types,
+        ...(description && { description }),
+    };
+};
+const normalizeSchemaForMcp = (inputSchema) => {
+    const properties = inputSchema.properties ?? {};
+    const normalizedProperties = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        normalizedProperties[key] = flattenNullableProperty(prop);
+    }
+    const allKeys = Object.keys(normalizedProperties);
+    return {
+        ...inputSchema,
+        additionalProperties: false,
+        properties: normalizedProperties,
+        required: allKeys,
+    };
+};
+const resolvePropertyType = (prop) => {
+    if (typeof prop.type === "string")
+        return prop.type;
+    if (Array.isArray(prop.type))
+        return prop.type.find((t) => t !== "null");
+    const nullable = isNullableAnyOf(prop);
+    if (nullable) {
+        const innerType = nullable.inner.type;
+        return typeof innerType === "string" ? innerType : undefined;
+    }
+    return undefined;
+};
+const isNullableProperty = (prop) => {
+    if (isNullableAnyOf(prop))
+        return true;
+    const { type } = prop;
+    if (Array.isArray(type) && type.includes("null"))
+        return true;
+    return false;
+};
+const coerceArgs = (args, schema) => {
+    const properties = schema.properties ?? {};
+    const coerced = { ...args };
+    for (const [key, prop] of Object.entries(properties)) {
+        const schemaProp = prop;
+        const value = coerced[key];
+        const targetType = resolvePropertyType(schemaProp);
+        const nullable = isNullableProperty(schemaProp);
+        if (value === undefined || value === null) {
+            coerced[key] = nullable ? null : value;
+            continue;
+        }
+        if ((targetType === "number" || targetType === "integer") && typeof value === "string") {
+            const parsed = Number(value);
+            if (!Number.isNaN(parsed)) {
+                coerced[key] = targetType === "integer" ? Math.trunc(parsed) : parsed;
+            }
+        }
+        if (targetType === "boolean" && typeof value === "string") {
+            if (value === "true") {
+                coerced[key] = true;
+            }
+            else if (value === "false") {
+                coerced[key] = false;
+            }
+        }
+    }
+    return coerced;
+};
+const getCatalogKey = (toolNames, dynamicTools, prefix) => {
+    const staticKey = [...toolNames].sort().join("|");
+    const dynamicKey = [...dynamicTools]
+        .map(tool => `${toExposedDynamicToolName(tool.name, prefix)}:${tool.description}`)
+        .sort()
+        .join("|");
+    return `${staticKey}::${dynamicKey}`;
+};
+const asRecord = (value) => isRecord(value)
+    ? value
+    : {};
+export const createCtxlMcpServer = ({ callDynamicTool, disambiguator, globalDisambiguatorValue, handlers, isBound, listDynamicTools, maxResponseBytes = defaultMaxResponseBytes, onToolCall, toolPrefix = "", version, visibleTools, }) => {
+    const injectDisambiguatorIntoSchemas = disambiguator && !globalDisambiguatorValue;
+    const prefixed = makePrefixed(toolPrefix);
+    const ctxlToolNames = baseToolNames.map(name => prefixed(name));
+    const mcpServer = new McpServer({
+        name: "ctxl-mcp",
+        version,
+    }, {
+        capabilities: {
+            tools: {
+                listChanged: true,
+            },
+        },
+    });
+    const toolDescriptors = {
+        [prefixed("info")]: {
+            description: "Return runtime state: tenant, interface type, connected flow details, and any recent errors.",
+            inputSchema: emptyInputSchema,
+        },
+        [prefixed("list_sessions")]: {
+            description: disambiguator
+                ? "List flows with available browser sessions. Returns flow IDs and names. Use only if the flow ID is unknown. Call a tool for a flow to initiate a session."
+                : "List flows with available browser sessions that can be connected to. Only shows flows where a browser is not already connected to another MCP client. If the desired flow is not listed, the user needs to open a new browser session for that flow.",
+            inputSchema: {
+                additionalProperties: false,
+                properties: {
+                    flowId: { description: "Filter to a specific flow by ID.", type: "string" },
+                },
+                type: "object",
+            },
+        },
+    };
+    const listTools = async () => {
+        const dynamicTools = listDynamicTools()
+            .map(tool => mapDynamicToolForExposure(tool, toolPrefix))
+            .filter(tool => !isInArray(ctxlToolNames, tool.name))
+            .map(({ annotations, description, inputSchema, name, outputSchema, title }) => {
+            let schema = inputSchema;
+            if (injectDisambiguatorIntoSchemas) {
+                schema = injectDisambiguator(schema, disambiguator);
+            }
+            schema = normalizeSchemaForMcp(schema);
+            return {
+                ...(annotations && { annotations }),
+                description,
+                inputSchema: schema,
+                name,
+                ...(outputSchema && { outputSchema }),
+                ...(title && { title }),
+            };
+        });
+        return {
+            tools: [
+                ...ctxlToolNames.map((name) => {
+                    const { description, inputSchema } = toolDescriptors[name];
+                    return { description, inputSchema, name };
+                }),
+                ...dynamicTools,
+            ],
+        };
+    };
+    const callTool = async (toolName, args) => {
+        const dynamicTool = listDynamicTools().find(tool => toExposedDynamicToolName(tool.name, toolPrefix) === toolName);
+        try {
+            if (isInArray(ctxlToolNames, toolName)) {
+                onToolCall?.(toolName);
+                switch (toolName) {
+                    case prefixed("info"): {
+                        return toToolSuccessResult(await handlers.info(), maxResponseBytes);
+                    }
+                    case prefixed("list_sessions"): {
+                        return toToolSuccessResult(await handlers.listSessions({
+                            flowId: args.flowId === undefined ? undefined : `${args.flowId}`,
+                        }), maxResponseBytes);
+                    }
+                }
+            }
+            if (!dynamicTool) {
+                return toToolErrorResult(`Unknown tool '${toolName}'`);
+            }
+            const originalSchema = dynamicTool.inputSchema;
+            const coercedArgs = coerceArgs(args, originalSchema);
+            if (disambiguator) {
+                const { key } = disambiguator;
+                const resolvedValue = globalDisambiguatorValue
+                    ?? (typeof coercedArgs[key] === "string" ? coercedArgs[key] : undefined);
+                if (!resolvedValue) {
+                    return toToolErrorResult(`Missing required parameter '${key}'. The user should know which flow they are working in. Use list_sessions if the flow ID is unknown.`);
+                }
+                const toolOwnsKey = !injectDisambiguatorIntoSchemas
+                    || (key in (originalSchema.properties ?? {}));
+                const { [key]: _, ...rest } = coercedArgs;
+                const forwardArgs = toolOwnsKey ? coercedArgs : rest;
+                const dynamicPayload = await callDynamicTool(dynamicTool.name, forwardArgs, resolvedValue);
+                return toToolSuccessResult(dynamicPayload, maxResponseBytes);
+            }
+            if (!isBound()) {
+                return toToolErrorResult("No active session. Call list_sessions to see available flows and pass a flowId to connect.");
+            }
+            const dynamicPayload = await callDynamicTool(dynamicTool.name, coercedArgs);
+            return toToolSuccessResult(dynamicPayload, maxResponseBytes);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : `${error}`;
+            return toToolErrorResult(message);
+        }
+    };
+    mcpServer.server.setRequestHandler(ListToolsRequestSchema, listTools);
+    mcpServer.server.setRequestHandler(CallToolRequestSchema, async ({ params: { arguments: rawArgs, name } }) => callTool(name, asRecord(rawArgs)));
+    let lastCatalogKey = getCatalogKey(visibleTools(), listDynamicTools(), toolPrefix);
+    return {
+        debug: {
+            callTool,
+            listTools,
+        },
+        async notifyToolsChanged(force = false) {
+            const nextCatalogKey = getCatalogKey(visibleTools(), listDynamicTools(), toolPrefix);
+            if (!force && nextCatalogKey === lastCatalogKey) {
+                return;
+            }
+            lastCatalogKey = nextCatalogKey;
+            mcpServer.sendToolListChanged();
+        },
+        server: mcpServer,
+    };
+};

package/dist/mcp/session.d.ts

@@ -0,0 +1,42 @@
+import type { McpBindFailureCode, McpDetachReason } from "../models/mcp.js";
+import type { McpSocketBridgeErrorCode } from "./socket-bridge.js";
+export type McpServerStateValue = "error" | "initializing" | "ready";
+export type McpBindingStateValue = "binding" | "bound" | "unbound";
+export type McpLastError = {
+    at: number;
+    code: McpSessionErrorCode;
+    message: string;
+};
+export type McpSessionErrorCode = "CONNECT_FAILED" | "MANIFEST_FAILED" | "SOCKET_DISCONNECTED" | McpBindFailureCode | McpDetachReason | McpSocketBridgeErrorCode;
+export type McpBoundConnection = {
+    boundAt: number;
+    flowId: string;
+    flowName: string;
+};
+export type McpSessionSnapshot = {
+    bindingState: McpBindingStateValue;
+    connection?: McpBoundConnection;
+    lastError?: McpLastError;
+    serverState: McpServerStateValue;
+};
+type ServerStateListener = (next: McpServerStateValue, previous: McpServerStateValue) => void;
+type BindingStateListener = (next: McpBindingStateValue, previous: McpBindingStateValue) => void;
+export declare class McpSessionState {
+    private bindingListeners;
+    private bindingState;
+    private connection?;
+    private lastError?;
+    private serverListeners;
+    private serverState;
+    beginBind(): void;
+    getSnapshot(): McpSessionSnapshot;
+    markBound(connection: McpBoundConnection): void;
+    markError(code: McpSessionErrorCode, message: string): void;
+    markReady(): void;
+    markUnbound(): void;
+    onBindingStateChange(listener: BindingStateListener): () => void;
+    onServerStateChange(listener: ServerStateListener): () => void;
+    private setBindingState;
+    private setServerState;
+}
+export {};

package/dist/mcp/session.js

@@ -0,0 +1,75 @@
+export class McpSessionState {
+    bindingListeners = new Set();
+    bindingState = "unbound";
+    connection;
+    lastError;
+    serverListeners = new Set();
+    serverState = "initializing";
+    beginBind() {
+        if (this.serverState !== "ready") {
+            throw new Error("Cannot bind: server is not ready");
+        }
+        this.setBindingState("binding");
+    }
+    getSnapshot() {
+        return {
+            bindingState: this.bindingState,
+            serverState: this.serverState,
+            ...(this.connection && { connection: this.connection }),
+            ...(this.lastError && { lastError: this.lastError }),
+        };
+    }
+    markBound(connection) {
+        this.connection = connection;
+        this.setBindingState("bound");
+    }
+    markError(code, message) {
+        this.lastError = {
+            at: Date.now(),
+            code,
+            message,
+        };
+        this.connection = undefined;
+        this.setBindingState("unbound");
+        this.setServerState("error");
+    }
+    markReady() {
+        this.setServerState("ready");
+    }
+    markUnbound() {
+        this.connection = undefined;
+        this.setBindingState("unbound");
+    }
+    onBindingStateChange(listener) {
+        this.bindingListeners.add(listener);
+        return () => {
+            this.bindingListeners.delete(listener);
+        };
+    }
+    onServerStateChange(listener) {
+        this.serverListeners.add(listener);
+        return () => {
+            this.serverListeners.delete(listener);
+        };
+    }
+    setBindingState(next) {
+        const previous = this.bindingState;
+        if (previous === next) {
+            return;
+        }
+        this.bindingState = next;
+        for (const listener of this.bindingListeners) {
+            listener(next, previous);
+        }
+    }
+    setServerState(next) {
+        const previous = this.serverState;
+        if (previous === next) {
+            return;
+        }
+        this.serverState = next;
+        for (const listener of this.serverListeners) {
+            listener(next, previous);
+        }
+    }
+}

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

@@ -0,0 +1,67 @@
+import { McpBindSessionResponse, McpCommandStatus, McpListSessionsResponse, McpManifestResponse, McpToolRegistrySync } from "../models/mcp.js";
+import { McpDetachedPayload, McpSessionAvailablePayload, McpSessionUnavailablePayload } from "./contracts.js";
+export type McpSocketBridgeErrorCode = "ALREADY_CONNECTED" | "BIND_FAILED" | "BIND_TIMEOUT" | "CONNECT_ERROR" | "DISCONNECTED_DURING_COMMAND" | "INVALID_CONNECT_ROUTE" | "LIST_SESSIONS_FAILED" | "MANIFEST_FETCH_FAILED" | "MANIFEST_TIMEOUT" | "MCP_ERROR" | "NOT_CONNECTED";
+export type McpSocketRoute = {
+    connectUrl: string;
+    namespace: "/mcp";
+    namespaceUrl: string;
+    path: string;
+    url: string;
+};
+type ConnectParams = {
+    interfaceType: string;
+    orgId: string;
+    token: string;
+    url: string;
+};
+type ConnectResult = {
+    connectedAt: number;
+};
+export declare const getMcpSocketRoute: ({ url }: Pick<ConnectParams, "url">) => McpSocketRoute;
+export type McpSocketBridgeHandlers = {
+    onCommandStatus?: (payload: McpCommandStatus) => void;
+    onDetached?: (payload: McpDetachedPayload) => void;
+    onDisconnected?: (reason: string) => void;
+    onSessionAvailable?: (payload: McpSessionAvailablePayload) => void;
+    onSessionUnavailable?: (payload: McpSessionUnavailablePayload) => void;
+    onToolRegistrySync?: (payload: McpToolRegistrySync) => void;
+};
+type RunToolParams = {
+    args: Record<string, unknown>;
+    name: string;
+    timeoutMs?: number;
+};
+export declare class McpSocketBridgeError extends Error {
+    readonly code: McpSocketBridgeErrorCode;
+    constructor(message: string, code: McpSocketBridgeErrorCode);
+}
+export declare class McpSocketBridge {
+    private boundFlowId?;
+    private commandQueue;
+    private handlers;
+    private pendingCommands;
+    private socket?;
+    constructor(handlers?: McpSocketBridgeHandlers);
+    get isConnected(): boolean;
+    bindSession({ flowId }: {
+        flowId: string;
+    }): Promise<McpBindSessionResponse>;
+    connect({ interfaceType, orgId, token, url }: ConnectParams): Promise<ConnectResult>;
+    disconnect(): Promise<{
+        detachedAt: number;
+    } | undefined>;
+    hasActiveSocket(): boolean;
+    listSessions({ flowId, interfaceType }: {
+        flowId?: string;
+        interfaceType: string;
+    }): Promise<McpListSessionsResponse>;
+    requestManifest(interfaceType: string): Promise<McpManifestResponse>;
+    runTool(params: RunToolParams): Promise<unknown>;
+    unbindSession(): Promise<void>;
+    private bindPersistentListeners;
+    private executeToolCommand;
+    private notifyRemoteDisconnect;
+    private rejectAllPendingCommands;
+    private requireSocket;
+}
+export {};