@contextual-io/cli 0.7.1 → 0.8.0

package/dist/mcp/http-server.js

@@ -0,0 +1,242 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { createMcpLogHelpers } from "./logger.js";
+const jsonRpcErrorCode = -32_000;
+const createStreamableTransport = (callbacks) => new StreamableHTTPServerTransport({
+    onsessionclosed: callbacks.onSessionClosed,
+    onsessioninitialized: callbacks.onSessionInitialized,
+    sessionIdGenerator: () => randomUUID(),
+});
+const getHeaderValue = (value) => (Array.isArray(value)
+    ? value[0]
+    : value);
+const writeJsonRpcError = (response, statusCode, message) => {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json");
+    response.end(JSON.stringify({
+        error: {
+            code: jsonRpcErrorCode,
+            message,
+        },
+        id: null,
+        jsonrpc: "2.0",
+    }));
+};
+export const getHttpServerError = (error, port) => {
+    if (error && typeof error === "object" && "code" in error) {
+        const nodeError = error;
+        if (nodeError.code === "EADDRINUSE") {
+            return new Error(`Port ${port} is unavailable. Retry with --port.`);
+        }
+        if (nodeError.code === "EACCES") {
+            return new Error(`Port ${port} cannot be opened on 127.0.0.1.`);
+        }
+    }
+    return error instanceof Error
+        ? error
+        : new Error(`${error}`);
+};
+const sessionInactivityMs = 10 * 60 * 1000; // 10 minutes idle = cleanup
+const sessionCleanupIntervalMs = 60 * 1000; // check every minute
+export const createCtxlMcpHttpSessionManager = ({ createBridgeManager, createRuntime, createTransport = createStreamableTransport, verbose, }) => {
+    const { log, logError } = createMcpLogHelpers(verbose);
+    const sessions = new Map();
+    const closingSessions = new Set();
+    let sharedBridgeManager;
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [sessionId, session] of sessions.entries()) {
+            if (now - session.lastActivityAt > sessionInactivityMs) {
+                closeSession(sessionId, "inactivity_timeout").catch(() => { });
+            }
+        }
+    }, sessionCleanupIntervalMs);
+    const closeSession = async (sessionId, reason) => {
+        if (closingSessions.has(sessionId)) {
+            return;
+        }
+        const session = sessions.get(sessionId);
+        if (!session) {
+            return;
+        }
+        closingSessions.add(sessionId);
+        sessions.delete(sessionId);
+        log("session_closed", {
+            mcpSessionId: sessionId,
+            reason,
+        });
+        try {
+            await session.transport.close().catch(() => { });
+            await session.runtime.close().catch(() => { });
+        }
+        finally {
+            closingSessions.delete(sessionId);
+        }
+    };
+    const getSession = (request) => {
+        const sessionId = getHeaderValue(request.headers["mcp-session-id"]);
+        if (!sessionId) {
+            return {
+                error: {
+                    message: "Missing mcp-session-id header",
+                    statusCode: 400,
+                },
+            };
+        }
+        const session = sessions.get(sessionId);
+        if (!session) {
+            return {
+                error: {
+                    message: `Unknown mcp-session-id '${sessionId}'. Session may be stale after a server restart; reconnect your MCP client to initialize a new session.`,
+                    statusCode: 404,
+                },
+            };
+        }
+        session.lastActivityAt = Date.now();
+        return { session, sessionId };
+    };
+    return {
+        async closeAllSessions(reason) {
+            clearInterval(cleanupInterval);
+            const sessionIds = [...sessions.keys()];
+            await Promise.all(sessionIds.map(async (sessionId) => closeSession(sessionId, reason)));
+            await sharedBridgeManager?.closeAll().catch(() => { });
+            sharedBridgeManager = undefined;
+        },
+        async handleDelete(request, response) {
+            const current = getSession(request);
+            if ("error" in current) {
+                const error = current.error;
+                writeJsonRpcError(response, error.statusCode, error.message);
+                return;
+            }
+            await current.session.transport.handleRequest(request, response);
+        },
+        async handleGet(request, response) {
+            const current = getSession(request);
+            if ("error" in current) {
+                const error = current.error;
+                writeJsonRpcError(response, error.statusCode, error.message);
+                return;
+            }
+            await current.session.transport.handleRequest(request, response);
+        },
+        async handlePost(request, response) {
+            const sessionId = getHeaderValue(request.headers["mcp-session-id"]);
+            if (sessionId) {
+                const current = getSession(request);
+                if ("error" in current) {
+                    const error = current.error;
+                    writeJsonRpcError(response, error.statusCode, error.message);
+                    return;
+                }
+                await current.session.transport.handleRequest(request, response, request.body);
+                return;
+            }
+            if (!isInitializeRequest(request.body)) {
+                writeJsonRpcError(response, 400, "Expected initialize request");
+                return;
+            }
+            if (!sharedBridgeManager) {
+                sharedBridgeManager = createBridgeManager();
+            }
+            const runtime = createRuntime(sharedBridgeManager);
+            let route;
+            try {
+                route = await runtime.inspectConnectionRoute();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : `${error}`;
+                writeJsonRpcError(response, 500, `Connection route check failed: ${message}`);
+                return;
+            }
+            const { connectUrl, namespace, namespaceUrl, path, silo, url: routeUrl } = route;
+            log("route_check", { connectUrl, namespace, namespaceUrl, path, silo, url: routeUrl });
+            const transport = createTransport({
+                onSessionClosed(sessionIdValue) {
+                    closeSession(sessionIdValue, "session_terminated").catch(() => { });
+                },
+                onSessionInitialized(sessionIdValue) {
+                    sessions.set(sessionIdValue, {
+                        lastActivityAt: Date.now(),
+                        runtime,
+                        transport,
+                    });
+                    log("session_initialized", {
+                        mcpSessionId: sessionIdValue,
+                    });
+                },
+            });
+            // eslint-disable-next-line unicorn/prefer-add-event-listener
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    closeSession(transport.sessionId, "transport_closed").catch(() => { });
+                }
+            };
+            // eslint-disable-next-line unicorn/prefer-add-event-listener
+            transport.onerror = (error) => {
+                logError("transport_error", {
+                    ...(transport.sessionId && { mcpSessionId: transport.sessionId }),
+                    message: error.message,
+                });
+            };
+            await runtime.connect(transport);
+            await transport.handleRequest(request, response, request.body);
+        },
+        hasSession(sessionId) {
+            return sessions.has(sessionId);
+        },
+    };
+};
+export const startCtxlMcpHttpServer = async ({ host, port, ...sessionManagerOptions }) => {
+    const { log, logError } = createMcpLogHelpers(sessionManagerOptions.verbose);
+    const app = createMcpExpressApp({ host });
+    const sessionManager = createCtxlMcpHttpSessionManager(sessionManagerOptions);
+    const safeHandle = (handler) => async (request, response) => {
+        try {
+            await handler(request, response);
+        }
+        catch (error) {
+            logError("http_request_error", {
+                message: error instanceof Error ? error.message : `${error}`,
+                method: request.method ?? "UNKNOWN",
+            });
+            if (!response.headersSent) {
+                writeJsonRpcError(response, 500, "Internal server error");
+            }
+        }
+    };
+    app.post("/", safeHandle((request, response) => sessionManager.handlePost(request, response)));
+    app.get("/", safeHandle((request, response) => sessionManager.handleGet(request, response)));
+    app.delete("/", safeHandle((request, response) => sessionManager.handleDelete(request, response)));
+    const server = createServer(app);
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.removeListener("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.removeListener("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    }).catch((error) => {
+        throw getHttpServerError(error, port);
+    });
+    log("server_bound", { host, port });
+    return {
+        async close() {
+            server.closeAllConnections();
+            await Promise.all([
+                sessionManager.closeAllSessions("shutdown"),
+                new Promise(server.close),
+            ]);
+        },
+        sessionManager,
+    };
+};

package/dist/mcp/logger.d.ts

@@ -0,0 +1,4 @@
+export declare const createMcpLogHelpers: (verbose?: boolean) => {
+    log(event: string, ...args: unknown[]): void;
+    logError(event: string, ...args: unknown[]): void;
+};

package/dist/mcp/logger.js

@@ -0,0 +1,9 @@
+export const createMcpLogHelpers = (verbose) => ({
+    log(event, ...args) {
+        if (verbose)
+            console.log("[ctxl mcp] event=%s" + " %j".repeat(args.length), event, ...args);
+    },
+    logError(event, ...args) {
+        console.error("[ctxl mcp] event=%s" + " %j".repeat(args.length), event, ...args);
+    },
+});

package/dist/mcp/runtime.d.ts

@@ -0,0 +1,24 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { Config } from "../models/user-config.js";
+import type { BridgeManager } from "./bridge-manager.js";
+import { type DisambiguatorConfig } from "./server.js";
+import { type McpSocketRoute } from "./socket-bridge.js";
+export type CtxlMcpRuntime = {
+    close: () => Promise<void>;
+    connect: (transport: Transport) => Promise<void>;
+    inspectConnectionRoute: () => Promise<McpSocketRoute & {
+        silo: Config["silo"];
+    }>;
+};
+export type CtxlMcpRuntimeOptions = {
+    bridgeManager: BridgeManager;
+    config: Config;
+    disambiguator?: DisambiguatorConfig;
+    flowId?: string;
+    interfaceType: string;
+    toolPrefix?: string;
+    url?: string;
+    verbose?: boolean;
+    version: string;
+};
+export declare const createCtxlMcpRuntime: ({ bridgeManager, config, disambiguator, flowId: globalFlowId, interfaceType, toolPrefix, url, verbose, version, }: CtxlMcpRuntimeOptions) => CtxlMcpRuntime;

package/dist/mcp/runtime.js

@@ -0,0 +1,297 @@
+import { getSolutionAiApiEndpoint } from "../utils/endpoints.js";
+import { isInArray, makePrefixed } from "./contracts.js";
+import { createMcpLogHelpers } from "./logger.js";
+import { createCtxlMcpServer, toExposedDynamicToolName } from "./server.js";
+import { getMcpSocketRoute } from "./socket-bridge.js";
+const defaultMcpRoutePath = "/comms";
+const getMyDomain = (tenantId, silo) => `${tenantId}.my${silo === "prod" ? "" : `.${silo}`}.contextual.io`;
+const getFlowEditorUrl = (flowId, tenantId, silo) => `https://${flowId}.flow.${getMyDomain(tenantId, silo)}`;
+export const createCtxlMcpRuntime = ({ bridgeManager, config, disambiguator, flowId: globalFlowId, interfaceType, toolPrefix = "", url, verbose, version, }) => {
+    const { log } = createMcpLogHelpers(verbose);
+    const { tenantId } = config;
+    const routeUrl = url ?? `${getSolutionAiApiEndpoint(tenantId, config.silo)}${defaultMcpRoutePath}`;
+    const prefixed = makePrefixed(toolPrefix);
+    const hasDisambiguator = Boolean(disambiguator);
+    let manifestBridge;
+    let currentBridge;
+    let removeToolsListener;
+    const boundBridges = new Map();
+    const bridgeListenerRemovers = new Map();
+    const pendingBinds = new Map();
+    const getSocketRoute = () => getMcpSocketRoute({ url: routeUrl });
+    const visibleTools = () => {
+        const metaTools = [prefixed("list_sessions"), prefixed("info")];
+        const toolSource = manifestBridge ?? currentBridge;
+        const dynamicTools = toolSource
+            ? [...toolSource.dynamicTools.values()]
+                .map(tool => toExposedDynamicToolName(tool.name, toolPrefix))
+                .filter(toolName => !isInArray(metaTools, toolName))
+            : [];
+        return [...metaTools, ...dynamicTools];
+    };
+    const listDynamicTools = () => manifestBridge ? [...manifestBridge.dynamicTools.values()]
+        : currentBridge ? [...currentBridge.dynamicTools.values()]
+            : [];
+    const notifyCatalogUpdate = async (reason, force = false) => {
+        const tools = visibleTools();
+        log("tools_catalog", { force, reason, toolCount: tools.length, tools: tools.join(",") });
+        await mcpServer.notifyToolsChanged(force);
+    };
+    const subscribeToBridgeMulti = (managed) => {
+        bridgeListenerRemovers.get(managed.flowId)?.();
+        boundBridges.set(managed.flowId, managed);
+        const removeListener = bridgeManager.addListener(managed.flowId, {
+            onToolsChanged() {
+                notifyCatalogUpdate("bridge_tools_changed", true).catch(() => { });
+            },
+        });
+        bridgeListenerRemovers.set(managed.flowId, removeListener);
+    };
+    const ensureBound = async (flowId) => {
+        const existing = boundBridges.get(flowId);
+        if (existing?.session.getSnapshot().bindingState === "bound"
+            && existing.session.getSnapshot().connection?.flowId === flowId) {
+            log("ensure_bound_hit", { flowId, path: "cached" });
+            return existing;
+        }
+        const pending = pendingBinds.get(flowId);
+        if (pending) {
+            log("ensure_bound_hit", { flowId, path: "pending" });
+            return pending;
+        }
+        log("ensure_bound_start", { existingBound: [...boundBridges.keys()].join(",") || "none", flowId });
+        const bindPromise = (async () => {
+            try {
+                const managed = bridgeManager.get(flowId);
+                if (managed?.session.getSnapshot().bindingState === "bound"
+                    && managed.session.getSnapshot().connection?.flowId === flowId) {
+                    log("ensure_bound_hit", { flowId, path: "manager_get_bound" });
+                    subscribeToBridgeMulti(managed);
+                    await notifyCatalogUpdate("auto_bound_existing", true);
+                    return managed;
+                }
+                log("ensure_bound_acquire", { flowId });
+                const bridge = await bridgeManager.acquire(flowId);
+                const snapshot = bridge.session.getSnapshot();
+                log("ensure_bound_acquired", { bindingState: snapshot.bindingState, connectionFlowId: snapshot.connection?.flowId, flowId, serverState: snapshot.serverState });
+                if (snapshot.bindingState === "bound" && snapshot.connection?.flowId === flowId) {
+                    log("ensure_bound_hit", { flowId, path: "acquire_already_bound" });
+                    subscribeToBridgeMulti(bridge);
+                    await notifyCatalogUpdate("auto_bound_existing", true);
+                    return bridge;
+                }
+                if (snapshot.bindingState === "bound") {
+                    log("ensure_bound_unbind_previous", { flowId, previousFlowId: snapshot.connection?.flowId });
+                    await bridge.bridge.unbindSession();
+                    bridge.session.markUnbound();
+                }
+                if (bridge.session.getSnapshot().serverState !== "ready") {
+                    log("ensure_bound_fetch_manifest", { flowId, serverState: bridge.session.getSnapshot().serverState });
+                    const manifest = await bridge.bridge.requestManifest(interfaceType);
+                    for (const tool of manifest.definitions) {
+                        bridge.dynamicTools.set(tool.name, tool);
+                    }
+                    bridge.session.markReady();
+                }
+                log("ensure_bound_begin_bind", { flowId });
+                bridge.session.beginBind();
+                try {
+                    const result = await bridge.bridge.bindSession({ flowId });
+                    log("ensure_bound_success", { flowId: result.flowId, flowName: result.flowName });
+                    bridge.session.markBound({
+                        boundAt: result.boundAt,
+                        flowId: result.flowId,
+                        flowName: result.flowName,
+                    });
+                    subscribeToBridgeMulti(bridge);
+                    await notifyCatalogUpdate("auto_bound", true);
+                    return bridge;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : `${error}`;
+                    log("ensure_bound_failed", { error: message, flowId });
+                    bridge.session.markUnbound();
+                    throw error instanceof Error ? error : new Error(`${error}`);
+                }
+            }
+            finally {
+                pendingBinds.delete(flowId);
+            }
+        })();
+        pendingBinds.set(flowId, bindPromise);
+        return bindPromise;
+    };
+    const getAnyBridge = () => {
+        const candidates = [manifestBridge, currentBridge, boundBridges.values().next().value];
+        for (const bridge of candidates) {
+            if (bridge?.bridge.isConnected)
+                return bridge;
+        }
+        return bridgeManager.getAny();
+    };
+    const mcpServer = createCtxlMcpServer({
+        async callDynamicTool(toolName, args, disambiguatorValue) {
+            log("call_dynamic_tool", { disambiguatorValue: disambiguatorValue ?? "none", hasArgs: Object.keys(args).join(",") || "none", toolName });
+            if (disambiguatorValue) {
+                const bridge = await ensureBound(disambiguatorValue);
+                log("dynamic_tool_call", { flowId: bridge.flowId, tenantId, toolName });
+                return bridge.bridge.runTool({ args, name: toolName });
+            }
+            if (!currentBridge) {
+                throw new Error("No active session. Call list_sessions to find available flows.");
+            }
+            log("dynamic_tool_call", { tenantId, toolName });
+            return currentBridge.bridge.runTool({ args, name: toolName });
+        },
+        disambiguator,
+        globalDisambiguatorValue: globalFlowId,
+        handlers: {
+            async info() {
+                if (hasDisambiguator && boundBridges.size > 0) {
+                    const flows = [...boundBridges.entries()].map(([flowId, managed]) => {
+                        const snapshot = managed.session.getSnapshot();
+                        return {
+                            bindingState: snapshot.bindingState,
+                            flowId,
+                            ...(snapshot.connection && { flowName: snapshot.connection.flowName }),
+                            serverState: snapshot.serverState,
+                        };
+                    });
+                    return {
+                        flows,
+                        interfaceType,
+                        ...(globalFlowId && { globalFlowId }),
+                        tenantId,
+                    };
+                }
+                const bridgeSnapshot = currentBridge?.session.getSnapshot();
+                return {
+                    bindingState: bridgeSnapshot?.bindingState ?? "unbound",
+                    interfaceType,
+                    serverState: bridgeSnapshot?.serverState ?? "initializing",
+                    ...(bridgeSnapshot?.connection && {
+                        flow: {
+                            flowId: bridgeSnapshot.connection.flowId,
+                            flowName: bridgeSnapshot.connection.flowName,
+                        },
+                    }),
+                    ...(bridgeSnapshot?.lastError && { lastError: bridgeSnapshot.lastError }),
+                    tenantId,
+                };
+            },
+            async listSessions({ flowId: filterFlowId }) {
+                const resolvedFlowId = filterFlowId ?? globalFlowId;
+                const anyBridge = getAnyBridge();
+                const fetchSessions = async (bridge) => bridge.bridge.listSessions({ flowId: resolvedFlowId, interfaceType });
+                let serverResult;
+                if (anyBridge) {
+                    try {
+                        serverResult = await fetchSessions(anyBridge);
+                    }
+                    catch { /* no-op */ }
+                }
+                else {
+                    try {
+                        const bridge = await bridgeManager.acquire(resolvedFlowId ?? "_query");
+                        serverResult = await fetchSessions(bridge);
+                    }
+                    catch { /* no-op */ }
+                }
+                if (!serverResult) {
+                    return formatNoConnectionResult(filterFlowId);
+                }
+                const connectedFlows = getConnectedFlows(resolvedFlowId);
+                return formatListSessionsResult(serverResult, connectedFlows, filterFlowId);
+            },
+        },
+        isBound: () => currentBridge?.session.getSnapshot().bindingState === "bound",
+        listDynamicTools,
+        onToolCall(name) {
+            log("tool_call", { tenantId, toolName: name });
+        },
+        toolPrefix,
+        version,
+        visibleTools,
+    });
+    const getConnectedFlows = (filterFlowId) => {
+        const connected = [];
+        for (const managed of boundBridges.values()) {
+            const snapshot = managed.session.getSnapshot();
+            if (snapshot.bindingState !== "bound" || !snapshot.connection)
+                continue;
+            if (filterFlowId && snapshot.connection.flowId !== filterFlowId)
+                continue;
+            connected.push({ flowId: snapshot.connection.flowId, flowName: snapshot.connection.flowName });
+        }
+        if (currentBridge) {
+            const snapshot = currentBridge.session.getSnapshot();
+            if (snapshot.bindingState === "bound" && snapshot.connection) {
+                const alreadyIncluded = connected.some(c => c.flowId === snapshot.connection.flowId);
+                if (!alreadyIncluded && (!filterFlowId || snapshot.connection.flowId === filterFlowId)) {
+                    connected.push({ flowId: snapshot.connection.flowId, flowName: snapshot.connection.flowName });
+                }
+            }
+        }
+        return connected;
+    };
+    const formatListSessionsResult = (result, connectedFlows, filterFlowId) => {
+        if (result.sessions.length === 0 && connectedFlows.length === 0) {
+            const flowHint = filterFlowId
+                ? `Open the flow in your browser: ${getFlowEditorUrl(filterFlowId, tenantId, config.silo)}`
+                : `Open a flow in your browser at https://<flow-id>.flow.${getMyDomain(tenantId, config.silo)}`;
+            return {
+                message: `No available browser sessions found. ${flowHint}`,
+                sessions: [],
+            };
+        }
+        return {
+            ...(connectedFlows.length > 0 && { connectedFlows }),
+            sessions: result.sessions,
+        };
+    };
+    const formatNoConnectionResult = (filterFlowId) => {
+        const flowHint = filterFlowId
+            ? `Open the flow in your browser: ${getFlowEditorUrl(filterFlowId, tenantId, config.silo)}`
+            : `Open a flow in your browser at https://<flow-id>.flow.${getMyDomain(tenantId, config.silo)}`;
+        return {
+            message: `Not connected to the API. ${flowHint}`,
+            sessions: [],
+        };
+    };
+    return {
+        async close() {
+            for (const remover of bridgeListenerRemovers.values()) {
+                remover();
+            }
+            bridgeListenerRemovers.clear();
+            boundBridges.clear();
+            pendingBinds.clear();
+            removeToolsListener?.();
+            removeToolsListener = undefined;
+            currentBridge = undefined;
+            manifestBridge = undefined;
+            await mcpServer.server.close().catch(() => { });
+        },
+        async connect(transport) {
+            try {
+                const bridge = await bridgeManager.acquire(globalFlowId ?? "_manifest");
+                manifestBridge = bridge;
+                if (globalFlowId && hasDisambiguator) {
+                    await ensureBound(globalFlowId).catch(() => { });
+                }
+                else {
+                    currentBridge = bridge;
+                }
+            }
+            catch {
+                // Bridge unavailable — base tools still served, manifest loaded on first bind
+            }
+            await mcpServer.server.connect(transport);
+            await notifyCatalogUpdate("transport_connected", true);
+        },
+        async inspectConnectionRoute() {
+            const route = getSocketRoute();
+            return { ...route, silo: config.silo };
+        },
+    };
+};

package/dist/mcp/server.d.ts

@@ -0,0 +1,90 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { McpToolDefinition } from "../models/mcp.js";
+declare const defaultToolPrefix = "ctxl_";
+type DisambiguatorConfig = {
+    description: string;
+    key: string;
+};
+export { defaultToolPrefix };
+export type { DisambiguatorConfig };
+export type CtxlToolName = string;
+type ToolHandlerResult = Record<string, unknown>;
+export type CtxlToolHandlers = {
+    info: () => Promise<ToolHandlerResult>;
+    listSessions: (args: {
+        flowId?: string;
+    }) => Promise<ToolHandlerResult>;
+};
+type CreateCtxlMcpServerParams = {
+    callDynamicTool: (toolName: string, args: Record<string, unknown>, disambiguatorValue?: string) => Promise<unknown>;
+    disambiguator?: DisambiguatorConfig;
+    globalDisambiguatorValue?: string;
+    handlers: CtxlToolHandlers;
+    isBound: () => boolean;
+    listDynamicTools: () => McpToolDefinition[];
+    maxResponseBytes?: number;
+    onToolCall?: (name: CtxlToolName) => void;
+    toolPrefix?: string;
+    version: string;
+    visibleTools: () => CtxlToolName[];
+};
+export declare const toExposedDynamicToolName: (toolName: string, prefix: string) => string;
+export declare const createCtxlMcpServer: ({ callDynamicTool, disambiguator, globalDisambiguatorValue, handlers, isBound, listDynamicTools, maxResponseBytes, onToolCall, toolPrefix, version, visibleTools, }: CreateCtxlMcpServerParams) => {
+    debug: {
+        callTool: (toolName: string, args: Record<string, unknown>) => Promise<CallToolResult>;
+        listTools: () => Promise<{
+            [x: string]: unknown;
+            tools: {
+                inputSchema: {
+                    [x: string]: unknown;
+                    type: "object";
+                    properties?: {
+                        [x: string]: object;
+                    } | undefined;
+                    required?: string[] | undefined;
+                };
+                name: string;
+                description?: string | undefined;
+                outputSchema?: {
+                    [x: string]: unknown;
+                    type: "object";
+                    properties?: {
+                        [x: string]: object;
+                    } | undefined;
+                    required?: string[] | undefined;
+                } | undefined;
+                annotations?: {
+                    title?: string | undefined;
+                    readOnlyHint?: boolean | undefined;
+                    destructiveHint?: boolean | undefined;
+                    idempotentHint?: boolean | undefined;
+                    openWorldHint?: boolean | undefined;
+                } | undefined;
+                execution?: {
+                    taskSupport?: "required" | "optional" | "forbidden" | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "dark" | "light" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            }[];
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+            nextCursor?: string | undefined;
+        }>;
+    };
+    notifyToolsChanged(force?: boolean): Promise<void>;
+    server: McpServer;
+};