@nodetool-ai/websocket 0.7.0-rc.22 → 0.8.1

package/dist/mcp-server.js

@@ -1,796 +1,246 @@
 /**
  * MCP (Model Context Protocol) server for NodeTool.
  *
- * Exposes NodeTool workflows, assets, nodes, jobs, and collections
- * as MCP tools using the official TypeScript MCP SDK.
+ * The mount exposes the CodeAct action, direct image/discovery tools, and
+ * renderer steering tools on the CodeAct belt. A connected editor is reached
+ * through the shared `/ws` renderer registry.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { z } from "zod";
+import { MCP_GUEST_CONTRACT } from "@nodetool-ai/agents";
 import { createLogger } from "@nodetool-ai/config";
-import { Workflow, Job, Asset } from "@nodetool-ai/models";
-import { toAssetResponse, toJobResponse, toWorkflowResponse } from "./http-api.js";
-import { uiToolSchemas } from "@nodetool-ai/protocol";
-import { NodeRegistry, rankNodeMetadata } from "@nodetool-ai/node-sdk";
-import { registerBaseNodes } from "@nodetool-ai/base-nodes";
-import { registerElevenLabsNodes } from "@nodetool-ai/elevenlabs-nodes";
-import { registerTransformersJsNodes } from "@nodetool-ai/transformers-js-nodes";
-import { registerFalNodes } from "@nodetool-ai/fal-nodes";
-import { registerKieNodes } from "@nodetool-ai/kie-nodes";
-import { registerReplicateNodes } from "@nodetool-ai/replicate-nodes";
-import { PythonNodeExecutor, PythonStdioBridge } from "@nodetool-ai/runtime";
-import { WorkflowRunner } from "@nodetool-ai/kernel";
+import { registerAgentMcpTools } from "./mcp-agent-tools.js";
+/**
+ * Refusal message for a session that cannot be bound to a user. Names the fix,
+ * because the caller cannot see which mount answered them.
+ */
+export const MCP_SCOPE_REQUIRED_MESSAGE = "NodeTool MCP sessions must be bound to a user. This mount could not " +
+    "authenticate one. Fix: sign in so the mount can bind the session's user id, " +
+    "or run `nodetool mcp serve` for a single-user stdio mount.";
 const log = createLogger("nodetool.websocket.mcp-server");
-const GLOBAL_FRONTEND_SESSION_ID = "global-mcp";
-let activeFrontendTransport = null;
-let runtimeEnvironmentPromise = null;
-async function getUnifiedNodeMetadata(options) {
-    if (options?.registry) {
-        return options.registry
-            .listMetadata()
-            .sort((a, b) => a.node_type.localeCompare(b.node_type));
-    }
-    const runtime = await getRuntimeEnvironment(options);
-    return runtime.registry
-        .listMetadata()
-        .sort((a, b) => a.node_type.localeCompare(b.node_type));
-}
-function getRuntimeEnvironment(options) {
-    if (!runtimeEnvironmentPromise) {
-        runtimeEnvironmentPromise = (async () => {
-            const registry = new NodeRegistry();
-            registry.loadPythonMetadata({
-                roots: options?.metadataRoots,
-                maxDepth: options?.metadataMaxDepth ?? 8
-            });
-            registerBaseNodes(registry);
-            registerElevenLabsNodes(registry);
-            registerTransformersJsNodes(registry);
-            registerFalNodes(registry);
-            registerKieNodes(registry);
-            registerReplicateNodes(registry);
-            const pythonBridge = new PythonStdioBridge({
-                workerArgs: process.env["NODETOOL_WORKER_NAMESPACES"]
-                    ? ["--namespaces", process.env["NODETOOL_WORKER_NAMESPACES"]]
-                    : []
-            });
-            const logPythonBridgeDiagnostics = (context) => {
-                const loadErrors = pythonBridge.getLoadErrors?.() ?? [];
-                if (loadErrors.length === 0)
-                    return;
-                log.warn(`MCP Python bridge ${context} with ${loadErrors.length} load error(s)`);
-                for (const entry of loadErrors.slice(0, 10)) {
-                    log.warn(`[python-worker][load-error] ${entry.module} (${entry.phase}): ${entry.error}`);
-                }
-            };
-            let pythonBridgeReady = false;
-            pythonBridge.on("stderr", (msg) => {
-                for (const line of msg.split("\n")) {
-                    if (line.trim())
-                        log.debug(`[python-worker] ${line}`);
-                }
-            });
-            pythonBridge.on("exit", (code) => {
-                log.warn(`MCP Python worker exited with code ${code}`);
-                pythonBridgeReady = false;
-            });
-            const ensurePythonBridge = async () => {
-                log.info("MCP lazily starting Python bridge");
-                try {
-                    await pythonBridge.ensureConnected();
-                }
-                catch (err) {
-                    log.warn("MCP Python bridge lazy start failed", err instanceof Error ? err : new Error(String(err)));
-                    throw err;
-                }
-                pythonBridgeReady = true;
-                log.info("MCP Python bridge lazy start completed");
-                const meta = pythonBridge.getNodeMetadata();
-                log.info(`MCP Python bridge connected — ${meta.length} Python nodes`);
-                pythonBridge
-                    .getWorkerStatus?.()
-                    ?.then((status) => {
-                    log.info("MCP Python bridge status", {
-                        protocol_version: status.protocol_version,
-                        node_count: status.node_count,
-                        provider_count: status.provider_count,
-                        namespaces: status.namespaces,
-                        transport: status.transport,
-                        max_frame_size: status.max_frame_size,
-                        load_error_count: status.load_errors.length
-                    });
-                })
-                    .catch((err) => {
-                    log.warn("MCP failed to fetch Python bridge status", err instanceof Error ? err : new Error(String(err)));
-                });
-                logPythonBridgeDiagnostics("connected");
-            };
-            const resolveExecutor = (node) => {
-                if (registry.has(node.type)) {
-                    return registry.resolve(node);
-                }
-                if (pythonBridgeReady && pythonBridge.hasNodeType(node.type)) {
-                    const meta = pythonBridge
-                        .getNodeMetadata()
-                        .find((n) => n.node_type === node.type);
-                    const nodeRec = node;
-                    const props = (nodeRec.properties ?? nodeRec.data ?? {});
-                    return new PythonNodeExecutor(pythonBridge, node.type, props, Object.fromEntries((meta?.outputs ?? []).map((o) => [o.name, o.type.type])), meta?.required_settings ?? []);
-                }
-                if (registry.getMetadata(node.type) && !registry.has(node.type)) {
-                    const stderrSummary = pythonBridge.getRecentStderrSummary?.() ?? null;
-                    const loadErrors = pythonBridge.getLoadErrors?.() ?? [];
-                    const matchingLoadError = loadErrors.find((entry) => entry.module.includes(node.type) ||
-                        node.type.startsWith(entry.module.split(".").slice(2).join(".")));
-                    throw new Error(pythonBridgeReady
-                        ? `Python node "${node.type}" cannot execute: it is declared in metadata but was not loaded by the Python worker.${matchingLoadError ? ` Load error: ${matchingLoadError.module}: ${matchingLoadError.error}.` : stderrSummary ? ` Recent Python worker stderr: ${stderrSummary}` : " Check Python worker status/load errors for import failures."}`
-                        : `Python node "${node.type}" cannot execute: Python worker is not connected.${stderrSummary ? ` Recent Python worker stderr: ${stderrSummary}` : ""}`);
-                }
-                return registry.resolve(node);
-            };
-            return {
-                registry,
-                pythonBridge,
-                ensurePythonBridge,
-                resolveExecutor
-            };
-        })();
-    }
-    return runtimeEnvironmentPromise;
-}
 /**
- * Create a configured MCP server with all NodeTool tools registered.
+ * Create a configured MCP server: `execute_code`, `view_image`, the
+ * capabilities and sandbox resources, and the guest-contract instructions.
+ *
+ * Throws when `agentToolsScope` is missing — a session with no user binding
+ * would hold zero tools, which is a server that answers and cannot act.
  */
 export function createMcpServer(options) {
+    if (!options?.agentToolsScope) {
+        throw new Error(MCP_SCOPE_REQUIRED_MESSAGE);
+    }
     const server = new McpServer({
         name: "NodeTool API Server",
         version: "1.0.0"
-    });
-    for (const [toolName, schema] of Object.entries(uiToolSchemas)) {
-        server.tool(toolName, schema.description, schema.parameters, async (args) => {
-            const transport = activeFrontendTransport;
-            if (!transport || !transport.isAlive) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "No active NodeTool renderer is connected for frontend UI tools."
-                            })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            try {
-                const result = await transport.executeTool(GLOBAL_FRONTEND_SESSION_ID, `mcp-ui-${toolName}-${crypto.randomUUID()}`, toolName, args);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: typeof result === "string"
-                                ? result
-                                : JSON.stringify(result ?? null)
-                        }
-                    ]
-                };
-            }
-            catch (err) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: String(err) })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-        });
+    }, { instructions: MCP_GUEST_CONTRACT });
+    registerAgentMcpTools(server, options);
+    return server;
+}
+/**
+ * Create a stdio transport for CLI mode.
+ */
+export function createMcpStdioTransport() {
+    return new StdioServerTransport();
+}
+/** Connect stdio to the local API process when its MCP mount is available. */
+export async function forwardMcpStdioToLocalServer(url = getLocalMcpServerUrl(), stdio = createMcpStdioTransport()) {
+    const endpoint = new URL(url);
+    if (endpoint.hostname !== "127.0.0.1" && endpoint.hostname !== "localhost") {
+        throw new Error("The stdio MCP forwarder only connects to loopback");
     }
-    // ── Workflow tools ──────────────────────────────────────────────
-    server.tool("list_workflows", "List workflows with flexible filtering.", {
-        limit: z
-            .number()
-            .optional()
-            .default(100)
-            .describe("Maximum number of workflows to return"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ limit, user_id }) => {
-        try {
-            const [workflows, next] = await Workflow.paginate(user_id, { limit });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            workflows: workflows.map((workflow) => toWorkflowResponse(workflow)),
-                            next: next || null
-                        })
-                    }
-                ]
-            };
+    // An MCP handshake proves that the port belongs to a reachable NodeTool MCP
+    // mount. A health check alone could select an unrelated process on this port.
+    const probe = new Client({ name: "nodetool-mcp-probe", version: "1.0.0" });
+    const probeTransport = new StreamableHTTPClientTransport(endpoint);
+    try {
+        await probe.connect(probeTransport, { timeout: 5000 });
+        if (probe.getServerVersion()?.name !== "NodeTool API Server") {
+            return false;
         }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("get_workflow", "Get detailed information about a specific workflow.", {
-        workflow_id: z.string().describe("The workflow ID"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ workflow_id, user_id }) => {
-        try {
-            const workflow = await Workflow.find(user_id, workflow_id);
-            if (!workflow) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: "Workflow not found" })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(toWorkflowResponse(workflow))
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("run_workflow", "Run a workflow on the backend, optionally passing parameters.", {
-        workflow_id: z.string().describe("Workflow id to target."),
-        params: z
-            .record(z.string(), z.unknown())
-            .optional()
-            .default({})
-            .describe("Optional workflow run parameters."),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ workflow_id, params, user_id }) => {
-        try {
-            const workflow = await Workflow.find(user_id, workflow_id);
-            if (!workflow) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: "Workflow not found" })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            const runMode = workflow.run_mode ?? "workflow";
-            if (runMode !== "workflow") {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: `Workflow run mode "${runMode}" is not supported by the backend MCP runner.`
-                            })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            const graph = workflow.getGraph();
-            const runnableGraph = {
-                nodes: graph.nodes.map((node) => {
-                    const record = node;
-                    return {
-                        ...record,
-                        id: String(record.id ?? ""),
-                        type: String(record.type ?? ""),
-                        properties: (record.properties ?? record.data ?? {})
-                    };
-                }),
-                edges: graph.edges.map((edge) => {
-                    const record = edge;
-                    return {
-                        ...record,
-                        id: typeof record.id === "string" || record.id == null
-                            ? record.id
-                            : String(record.id),
-                        source: String(record.source ?? ""),
-                        target: String(record.target ?? ""),
-                        sourceHandle: String(record.sourceHandle ?? ""),
-                        targetHandle: String(record.targetHandle ?? ""),
-                        edge_type: record.edge_type === "control" ? "control" : "data"
-                    };
-                })
-            };
-            const runtime = await getRuntimeEnvironment(options);
-            const hasPythonNode = runnableGraph.nodes.some((node) => {
-                const nodeType = typeof node.type === "string" ? node.type : "";
-                return (nodeType !== "" &&
-                    Boolean(runtime.registry.getMetadata(nodeType)) &&
-                    !runtime.registry.has(nodeType));
-            });
-            if (hasPythonNode) {
-                await runtime.ensurePythonBridge();
-            }
-            const job = await Job.create({
-                workflow_id,
-                user_id,
-                status: "running",
-                params,
-                graph: runnableGraph
-            });
-            const runner = new WorkflowRunner(job.id, {
-                resolveExecutor: (node) => runtime.resolveExecutor(node)
-            });
-            const result = await runner.run({ job_id: job.id, workflow_id, params }, runnableGraph);
-            if (result.status === "completed") {
-                job.markCompleted();
-            }
-            else if (result.status === "cancelled") {
-                job.markCancelled();
-            }
-            else {
-                job.markFailed(result.error ?? "Workflow run failed");
-            }
-            await job.save();
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            job_id: job.id,
-                            workflow_id,
-                            status: result.status,
-                            outputs: result.outputs,
-                            error: result.error ?? null,
-                            message_count: result.messages.length,
-                            background: false
-                        })
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    // ── Asset tools ─────────────────────────────────────────────────
-    server.tool("list_assets", "List or search assets with flexible filtering options.", {
-        parent_id: z.string().optional().describe("Filter by parent asset ID"),
-        content_type: z.string().optional().describe("Filter by content type"),
-        limit: z
-            .number()
-            .optional()
-            .default(100)
-            .describe("Maximum number of assets to return"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ parent_id, content_type, limit, user_id }) => {
-        try {
-            const opts = { limit };
-            if (parent_id)
-                opts.parentId = parent_id;
-            if (content_type)
-                opts.contentType = content_type;
-            const [assets, next] = await Asset.paginate(user_id, opts);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            assets: assets.map((asset) => toAssetResponse(asset)),
-                            next: next || null
-                        })
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("get_asset", "Get detailed information about a specific asset.", {
-        asset_id: z.string().describe("The asset ID"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ asset_id, user_id }) => {
-        try {
-            const asset = await Asset.find(user_id, asset_id);
-            if (!asset) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: "Asset not found" })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(toAssetResponse(asset))
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (probeTransport.sessionId) {
+            await probeTransport.terminateSession().catch(() => undefined);
         }
-    });
-    // ── Node tools ──────────────────────────────────────────────────
-    server.tool("list_nodes", "List available nodes from installed packages.", {
-        namespace: z.string().optional().describe("Filter by namespace prefix"),
-        limit: z
-            .number()
-            .optional()
-            .default(200)
-            .describe("Maximum number of nodes to return")
-    }, async ({ namespace, limit }) => {
-        try {
-            let nodes = await getUnifiedNodeMetadata(options);
-            if (namespace) {
-                nodes = nodes.filter((n) => n.namespace.startsWith(namespace));
-            }
-            nodes.sort((a, b) => a.node_type.localeCompare(b.node_type));
-            const result = nodes.slice(0, limit).map((n) => ({
-                node_type: n.node_type,
-                title: n.title,
-                description: n.description,
-                namespace: n.namespace
-            }));
-            return {
-                content: [{ type: "text", text: JSON.stringify(result) }]
-            };
+        await probe.close();
+    }
+    const http = new StreamableHTTPClientTransport(endpoint);
+    http.onmessage = (message) => {
+        if ("result" in message && "protocolVersion" in message.result) {
+            const version = message.result.protocolVersion;
+            if (typeof version === "string")
+                http.setProtocolVersion(version);
         }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
+        void stdio.send(message);
+    };
+    http.onerror = (error) => {
+        log.warn("Local MCP HTTP transport failed", { error: error.message });
+    };
+    let initialization = Promise.resolve();
+    stdio.onmessage = (message) => {
+        const send = initialization.then(() => http.send(message));
+        if ("method" in message && message.method === "initialize") {
+            initialization = send;
         }
-    });
-    server.tool("search_nodes", "Search for nodes by name, description, or tags. Provider-specific nodes (openai.*, anthropic.*, etc.) are hidden by default; set include_provider_nodes:true to include them.", {
-        query: z.array(z.string()).describe("Search keywords"),
-        n_results: z.number().optional().default(10).describe("Maximum results"),
-        namespace: z
-            .string()
-            .optional()
-            .describe("Optional namespace prefix to scope the search (e.g. 'nodetool.control')."),
-        include_provider_nodes: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Include provider-specific nodes. Default false — set true only when the user named a provider.")
-    }, async ({ query, n_results, namespace, include_provider_nodes }) => {
-        try {
-            const nodes = await getUnifiedNodeMetadata(options);
-            const ranked = rankNodeMetadata(nodes, query, {
-                includeProviderNodes: include_provider_nodes,
-                namespacePrefix: namespace
+        void send.catch((error) => {
+            log.warn("Forwarding MCP request failed", {
+                error: error instanceof Error ? error.message : String(error)
             });
-            const matches = ranked.slice(0, n_results).map(({ meta, score }) => ({
-                node_type: meta.node_type,
-                title: meta.title,
-                description: meta.description,
-                namespace: meta.namespace,
-                score
-            }));
-            return {
-                content: [{ type: "text", text: JSON.stringify(matches) }]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("get_node_info", "Get detailed metadata for a node type.", {
-        node_type: z.string().describe("The fully-qualified node type")
-    }, async ({ node_type }) => {
-        try {
-            const nodes = await getUnifiedNodeMetadata(options);
-            const node = nodes.find((candidate) => candidate.node_type === node_type);
-            if (!node) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: "Node type not found" })
-                        }
-                    ],
-                    isError: true
-                };
-            }
-            return {
-                content: [{ type: "text", text: JSON.stringify(node) }]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    // ── Job tools ───────────────────────────────────────────────────
-    server.tool("list_jobs", "List jobs for user, optionally filtered by workflow.", {
-        workflow_id: z.string().optional().describe("Filter by workflow ID"),
-        limit: z
-            .number()
-            .optional()
-            .default(100)
-            .describe("Maximum number of jobs to return"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ workflow_id, limit, user_id }) => {
-        try {
-            const opts = { limit };
-            if (workflow_id)
-                opts.workflowId = workflow_id;
-            const [jobs, nextStartKey] = await Job.paginate(user_id, opts);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            jobs: jobs.map((job) => toJobResponse(job)),
-                            next_start_key: nextStartKey || null
-                        })
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("get_job", "Get a job by ID for user.", {
-        job_id: z.string().describe("The job ID"),
-        user_id: z.string().optional().default("1").describe("User ID")
-    }, async ({ job_id, user_id }) => {
-        try {
-            const job = await Job.find(user_id, job_id);
-            if (!job) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ error: "Job not found" })
-                        }
-                    ],
-                    isError: true
-                };
+            void stdio.close();
+        });
+    };
+    stdio.onclose = () => {
+        void (async () => {
+            if (http.sessionId) {
+                await http.terminateSession().catch(() => undefined);
             }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(toJobResponse(job))
-                    }
-                ]
-            };
-        }
-        catch (err) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: String(err) })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    // ── Collection tools (sqlite-vec) ───────────────────────────────
-    server.tool("list_collections", "List all vector database collections.", {
-        limit: z
-            .number()
-            .optional()
-            .default(50)
-            .describe("Maximum collections to return")
-    }, async ({ limit }) => {
-        try {
-            const { getVecStore } = await import("@nodetool-ai/vectorstore");
-            const store = await getVecStore();
-            const collections = await store.listCollections();
-            const result = await Promise.all(collections.slice(0, limit).map(async (c) => {
-                const count = await c.count();
-                const metadata = c.metadata ?? {};
-                let workflowName = null;
-                const workflowId = metadata.workflow;
-                if (workflowId) {
-                    const workflow = (await Workflow.get(workflowId));
-                    if (workflow)
-                        workflowName = workflow.name;
-                }
-                return {
-                    name: c.name,
-                    count,
-                    metadata,
-                    workflow_name: workflowName
-                };
-            }));
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ collections: result, count: result.length })
-                    }
-                ]
-            };
-        }
-        catch {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "Vector store not available" })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("get_collection", "Get details about a specific collection.", {
-        name: z.string().describe("Collection name")
-    }, async ({ name }) => {
-        try {
-            const { getVecStore } = await import("@nodetool-ai/vectorstore");
-            const store = await getVecStore();
-            const collection = await store.getCollection({ name });
-            const count = await collection.count();
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            name: collection.name,
-                            metadata: collection.metadata,
-                            count
-                        })
-                    }
-                ]
-            };
-        }
-        catch {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "Vector store not available" })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    server.tool("query_collection", "Query a collection for similar documents using semantic search.", {
-        name: z.string().describe("Collection name"),
-        query_texts: z
-            .array(z.string())
-            .describe("Query texts for semantic search"),
-        n_results: z.number().optional().default(10).describe("Number of results")
-    }, async ({ name, query_texts, n_results }) => {
-        try {
-            const { getVecStore } = await import("@nodetool-ai/vectorstore");
-            const store = await getVecStore();
-            const collection = await store.getCollection({ name });
-            const results = await collection.query({
-                queryTexts: query_texts,
-                nResults: n_results
-            });
-            return {
-                content: [{ type: "text", text: JSON.stringify(results) }]
-            };
-        }
-        catch {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: "Vector store not available" })
-                    }
-                ],
-                isError: true
-            };
-        }
-    });
-    return server;
+            await http.close();
+        })();
+    };
+    await http.start();
+    await stdio.start();
+    return true;
 }
 /**
- * Create a stdio transport for CLI mode.
+ * How long an HTTP session may sit idle before it is closed. Every session
+ * holds a transport, an `McpServer`, and that session's whole tool registry,
+ * and `onclose` only fires when the transport is explicitly closed — normally
+ * a DELETE. A client that simply goes away never sends one, so without this
+ * sweep the maps grow for the life of the process.
  */
-export function createMcpStdioTransport() {
-    return new StdioServerTransport();
-}
+export const MCP_SESSION_IDLE_TTL_MS = 30 * 60 * 1000;
+/** Concurrent sessions one user may hold; opening another closes their oldest. */
+export const MCP_MAX_SESSIONS_PER_USER = 8;
+/** Concurrent sessions across every user. A new one past this is refused. */
+export const MCP_MAX_SESSIONS = 256;
 // Per-session transport map for stateful HTTP MCP
 const sessionTransports = new Map();
-export function setMcpFrontendTransport(transport) {
-    activeFrontendTransport = transport;
+// The user each HTTP session was initialized for. A multi-user mount hands out
+// session ids over an authenticated channel, but the id alone must not be a
+// bearer credential: every later request is checked against the owner recorded
+// here.
+const sessionOwners = new Map();
+// When each session was last used, for idle eviction and for picking a user's
+// oldest session when they are over their cap.
+const sessionLastSeen = new Map();
+function forgetSession(sessionId) {
+    sessionTransports.delete(sessionId);
+    sessionOwners.delete(sessionId);
+    sessionLastSeen.delete(sessionId);
+}
+function touchSession(sessionId, now = Date.now()) {
+    if (sessionTransports.has(sessionId))
+        sessionLastSeen.set(sessionId, now);
 }
-export function clearMcpFrontendTransport(transport) {
-    if (activeFrontendTransport === transport) {
-        activeFrontendTransport = null;
+/**
+ * Drop a session and close its transport, which releases the `McpServer`
+ * behind it. `forgetSession` runs first so the transport's own `onclose`
+ * finds nothing left to do.
+ */
+function closeSession(sessionId) {
+    const transport = sessionTransports.get(sessionId);
+    forgetSession(sessionId);
+    void transport?.close().catch((err) => {
+        log.warn("Closing MCP session transport failed", {
+            sessionId,
+            error: err instanceof Error ? err.message : String(err)
+        });
+    });
+}
+/** Close every session idle for longer than the TTL. Lazy — runs per request,
+ * so an idle process holds no timer. */
+function sweepIdleSessions(now) {
+    for (const [sessionId, lastSeen] of sessionLastSeen) {
+        if (now - lastSeen > MCP_SESSION_IDLE_TTL_MS) {
+            log.debug("Evicting idle MCP session", { sessionId });
+            closeSession(sessionId);
+        }
+    }
+}
+/** Close a user's oldest sessions until opening one more keeps them at the cap. */
+function evictOverflowForUser(userId) {
+    const owned = [...sessionOwners]
+        .filter(([, owner]) => owner === userId)
+        .map(([sessionId]) => sessionId);
+    const overflow = owned.length - (MCP_MAX_SESSIONS_PER_USER - 1);
+    if (overflow <= 0)
+        return;
+    const oldestFirst = owned.sort((a, b) => (sessionLastSeen.get(a) ?? 0) - (sessionLastSeen.get(b) ?? 0));
+    for (const sessionId of oldestFirst.slice(0, overflow)) {
+        log.debug("Evicting oldest MCP session for user over cap", {
+            userId,
+            sessionId
+        });
+        closeSession(sessionId);
+    }
+}
+/** Close every open HTTP session. For shutdown, and for tests that need a
+ * clean process-wide session table. */
+export function closeAllMcpHttpSessions() {
+    for (const sessionId of [...sessionTransports.keys()]) {
+        closeSession(sessionId);
     }
 }
+/**
+ * True when the session exists and belongs to somebody other than the caller.
+ * A session with no recorded owner (stdio, or a mount that predates the
+ * binding) is left alone — the transport map is the authority there.
+ */
+function isForeignSession(sessionId, options) {
+    const owner = sessionOwners.get(sessionId);
+    if (owner === undefined)
+        return false;
+    return owner !== options?.agentToolsScope?.userId;
+}
+/**
+ * Answer as if the session did not exist. A 403 would confirm the id is real to
+ * a caller who guessed it; a 404 tells them nothing.
+ */
+function sessionNotFound() {
+    return new Response("Session not found", { status: 404 });
+}
+/** Refusal for an initialize the mount has no room for. Retryable: an idle
+ * session frees a slot on the next sweep. */
+function sessionsExhausted() {
+    return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+            code: -32002,
+            message: "This server is holding its maximum number of MCP sessions. " +
+                "Close an existing session with DELETE /mcp, or retry later."
+        }
+    }), {
+        status: 503,
+        headers: {
+            "content-type": "application/json",
+            "retry-after": "60"
+        }
+    });
+}
 export function getLocalMcpServerUrl() {
     const port = Number(process.env["PORT"] ?? 7777);
     const tlsEnabled = Boolean(process.env["TLS_CERT"] && process.env["TLS_KEY"]);
     const protocol = tlsEnabled ? "https" : "http";
     return `${protocol}://127.0.0.1:${port}/mcp`;
 }
+/** JSON-RPC refusal for an initialize the mount cannot scope to a user. */
+function scopeRefusal(challenge) {
+    const headers = new Headers({ "content-type": "application/json" });
+    if (challenge)
+        headers.set("WWW-Authenticate", challenge);
+    return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32001, message: MCP_SCOPE_REQUIRED_MESSAGE }
+    }), { status: 401, headers });
+}
 /**
  * Handle an MCP HTTP request at the /mcp path.
  * Uses WebStandardStreamableHTTPServerTransport for stateful sessions.
@@ -800,42 +250,85 @@ export async function handleMcpHttpRequest(request, options) {
     if (!url.pathname.startsWith("/mcp"))
         return null;
     const method = request.method;
+    const now = Date.now();
+    sweepIdleSessions(now);
     if (method === "POST") {
         // Check for existing session
         const sessionId = request.headers.get("mcp-session-id");
         if (sessionId && sessionTransports.has(sessionId)) {
+            if (isForeignSession(sessionId, options))
+                return sessionNotFound();
             const transport = sessionTransports.get(sessionId);
+            touchSession(sessionId, now);
             return transport.handleRequest(request);
         }
+        // A session id that is present but unknown must NOT fall through to the
+        // new-session path: that constructed a fresh transport + server per stale
+        // request (leaking both). Reject it — only an initialize request without a
+        // session id creates a new session.
+        if (sessionId) {
+            return sessionNotFound();
+        }
+        // A session this mount cannot bind to a user is refused here, at
+        // initialize, rather than answering with an empty surface.
+        if (!options?.agentToolsScope) {
+            log.warn("Refusing MCP session: no authenticated user to bind");
+            return scopeRefusal(options?.unauthorizedChallenge);
+        }
         // New session — create transport and server
+        const ownerUserId = options.agentToolsScope.userId;
+        // One user's clients cannot crowd out everyone else's: their oldest
+        // session goes first. The global cap is what is left after that, and it
+        // refuses rather than evicting a stranger's live session.
+        evictOverflowForUser(ownerUserId);
+        if (sessionTransports.size >= MCP_MAX_SESSIONS) {
+            log.warn("Refusing MCP session: server session cap reached", {
+                cap: MCP_MAX_SESSIONS
+            });
+            return sessionsExhausted();
+        }
         const transport = new WebStandardStreamableHTTPServerTransport({
             enableJsonResponse: true,
             sessionIdGenerator: () => crypto.randomUUID(),
             onsessioninitialized: (id) => {
                 sessionTransports.set(id, transport);
+                sessionOwners.set(id, ownerUserId);
+                sessionLastSeen.set(id, Date.now());
             }
         });
+        // Evict the session when the transport closes (client disconnect without an
+        // explicit DELETE) so sessionTransports — and the McpServer each entry keeps
+        // alive — does not grow unbounded over the process lifetime.
+        transport.onclose = () => {
+            if (transport.sessionId)
+                forgetSession(transport.sessionId);
+        };
         const server = createMcpServer(options);
         await server.connect(transport);
         return transport.handleRequest(request);
     }
     if (method === "GET") {
         const sessionId = request.headers.get("mcp-session-id");
-        if (sessionId && sessionTransports.has(sessionId)) {
+        if (sessionId &&
+            sessionTransports.has(sessionId) &&
+            !isForeignSession(sessionId, options)) {
             const transport = sessionTransports.get(sessionId);
+            touchSession(sessionId, now);
             return transport.handleRequest(request);
         }
-        return new Response("Session not found", { status: 404 });
+        return sessionNotFound();
     }
     if (method === "DELETE") {
         const sessionId = request.headers.get("mcp-session-id");
-        if (sessionId && sessionTransports.has(sessionId)) {
+        if (sessionId &&
+            sessionTransports.has(sessionId) &&
+            !isForeignSession(sessionId, options)) {
             const transport = sessionTransports.get(sessionId);
             const response = await transport.handleRequest(request);
-            sessionTransports.delete(sessionId);
+            forgetSession(sessionId);
             return response;
         }
-        return new Response("Session not found", { status: 404 });
+        return sessionNotFound();
     }
     return new Response("Method not allowed", { status: 405 });
 }