@zeroroot-ai/gibson-mcp 0.1.0

package/dist/helpers/index.js

@@ -0,0 +1,24 @@
+import { componentizeTools } from "./componentize.js";
+import { helperContext } from "./context.js";
+import { delegationTools } from "./delegate.js";
+import { findingTools } from "./findings.js";
+import { knowledgeTools } from "./knowledge.js";
+import { platformToolHelpers } from "./tools.js";
+export * from "./context.js";
+export * from "./coverage.js";
+export { componentizeTools } from "./componentize.js";
+export { delegationTools } from "./delegate.js";
+export { findingTools, gibsonFindingsBackend, localFindingsBackend, taskFindingsBackend } from "./findings.js";
+export { knowledgeTools } from "./knowledge.js";
+export { platformToolHelpers } from "./tools.js";
+/**
+ * One tool per SDK helper (gibson#1706, decision 2), for whatever this
+ * posture can reach. A helper whose grant is absent registers no tool
+ * rather than a tool that always fails.
+ */
+export function helperTools(ctx) {
+    return [...findingTools(ctx), ...knowledgeTools(ctx), ...delegationTools(ctx), ...componentizeTools(ctx), ...platformToolHelpers(ctx)];
+}
+export function helperToolsFor(gibson, cwd, env) {
+    return helperTools(helperContext(gibson, cwd, env));
+}

package/dist/helpers/knowledge.d.ts

@@ -0,0 +1,16 @@
+import type { ToolDefinition } from "../registry.js";
+import type { HelperContext } from "./context.js";
+/**
+ * Memory and knowledge (gibson#1593, decisions 9 and 10).
+ *
+ * `remember` is `Observe(MemoryObservation)`: the memory lands in the tenant
+ * World as a Timeline event and the projector writes the graph node. It
+ * exists only where a mission is open, because the World is written under a
+ * mission.
+ *
+ * `recall` reads the graph. Under a task grant it reads as the task, as a
+ * checked-in component it reads as the component. The model decides when a
+ * lookup is worth a round trip, and the query it writes beats anything
+ * derived from the prompt.
+ */
+export declare function knowledgeTools(ctx: HelperContext): ToolDefinition[];

package/dist/helpers/knowledge.js

@@ -0,0 +1,161 @@
+import { formatKnowledgeForPrompt, isSeamUnavailable, observe, remember, WorldEntityKind } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { defineTool } from "../tool.js";
+import { failure, json, text } from "../tools/result.js";
+/**
+ * Memory and knowledge (gibson#1593, decisions 9 and 10).
+ *
+ * `remember` is `Observe(MemoryObservation)`: the memory lands in the tenant
+ * World as a Timeline event and the projector writes the graph node. It
+ * exists only where a mission is open, because the World is written under a
+ * mission.
+ *
+ * `recall` reads the graph. Under a task grant it reads as the task, as a
+ * checked-in component it reads as the component. The model decides when a
+ * lookup is worth a round trip, and the query it writes beats anything
+ * derived from the prompt.
+ */
+export function knowledgeTools(ctx) {
+    const out = [];
+    const { knowledge, live } = ctx.gibson;
+    if (knowledge) {
+        out.push(defineTool({
+            name: "recall",
+            description: "Search this tenant's Gibson knowledge graph for memories, prior findings, targets and " +
+                "security facts recorded by earlier sessions and runs. Use it before you start on an " +
+                "unfamiliar area, or to check whether something was already recorded.",
+            input: {
+                query: z.string().describe("What to look for, in natural language."),
+                limit: z.number().int().min(1).max(50).optional().describe("Maximum hits. Defaults to 10."),
+                node_types: z.array(z.string()).optional().describe('Restrict to node types, e.g. ["Observation"] for memories or ["Finding"].'),
+            },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => {
+                let hits;
+                try {
+                    hits = await knowledge.query({ text: args.query, topK: args.limit ?? 10, ...(args.node_types ? { nodeTypes: args.node_types } : {}) });
+                }
+                catch (e) {
+                    if (isSeamUnavailable(e)) {
+                        return text("recall unavailable", "The Gibson knowledge graph is not available on this daemon (gibson#1186). Continue without prior context.");
+                    }
+                    return failure("recall failed", e.message);
+                }
+                if (hits.length === 0)
+                    return text("no matches", `Nothing in the tenant graph matches "${args.query}".`);
+                return text(`${hits.length} match${hits.length === 1 ? "" : "es"}`, formatKnowledgeForPrompt(hits));
+            },
+        }), defineTool({
+            name: "similar_findings",
+            description: "Findings in this tenant's graph that are semantically similar to a known finding.",
+            input: { finding_id: z.string().describe("The finding to search from."), limit: z.number().int().min(1).max(50).optional().describe("Maximum hits. Defaults to 5.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await knowledge.similarFindings(args.finding_id, args.limit ?? 5)),
+        }), defineTool({
+            name: "related_findings",
+            description: "Findings reachable from a given finding through the graph's edges.",
+            input: { finding_id: z.string().describe("The finding to traverse from.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await knowledge.relatedFindings(args.finding_id)),
+        }), defineTool({
+            name: "similar_attacks",
+            description: "Attack patterns in the graph that are semantically similar to a piece of content.",
+            input: { content: z.string().describe("Text to match attack patterns against."), limit: z.number().int().min(1).max(50).optional().describe("Maximum hits. Defaults to 5.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await knowledge.similarAttacks(args.content, args.limit ?? 5)),
+        }), defineTool({
+            name: "attack_chains",
+            description: "Multi-hop attack paths that start from a MITRE technique.",
+            input: { technique_id: z.string().describe("MITRE technique id, e.g. T1190."), max_depth: z.number().int().min(1).max(10).optional().describe("Hops to follow. Defaults to 3.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await knowledge.attackChains(args.technique_id, args.max_depth ?? 3)),
+        }));
+    }
+    if (live) {
+        const harness = live.harness;
+        out.push(defineTool({
+            name: "remember",
+            description: "Keep a fact for later sessions, in this tenant's Gibson knowledge graph. Use it for a " +
+                "convention, a decision, a layout fact or a gotcha you would want back next time. Not for " +
+                "progress notes. A security finding goes to submit_finding instead.",
+            input: {
+                text: z.string().describe("The fact, in one or two sentences."),
+                kind: z.string().optional().describe('A short category: "convention", "decision", "layout", "gotcha".'),
+                tags: z.array(z.string()).optional().describe("Lower-case labels that help recall."),
+                source_ref: z.string().optional().describe("Where it came from: a path, a URL, or a work id."),
+            },
+            handler: async (args) => {
+                try {
+                    await remember(harness, { text: args.text, kind: args.kind, tags: args.tags, sourceRef: args.source_ref });
+                }
+                catch (e) {
+                    return failure("remember failed", e.message);
+                }
+                return text("remembered", `Recorded in the tenant graph under mission ${live.missionId}.`);
+            },
+        }), defineTool({
+            name: "observe",
+            description: "Write a typed observation to the tenant World: an entity the platform should know about, " +
+                "an edge between two of them, or a lifecycle event. Use remember for a plain fact and " +
+                "submit_finding for a vulnerability.",
+            input: { observation: z.record(z.string(), z.unknown()).describe("An Observation object: a memory, an entity, an edge, or a lifecycle entity.") },
+            handler: async (args) => {
+                try {
+                    await observe(harness, args.observation);
+                }
+                catch (e) {
+                    return failure("observe failed", e.message);
+                }
+                return text("observed", `Recorded in the World under mission ${live.missionId}.`);
+            },
+        }), defineTool({
+            name: "world_view",
+            description: "Read this mission's slice of the tenant World: the hosts, domains, credentials, accounts " +
+                "and findings the platform knows about the target. Pass handles from a previous call in " +
+                "focus to zoom into entities.",
+            input: { focus: z.array(z.string()).optional().describe("Entity handles from an earlier world_view call.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => {
+                try {
+                    const res = await harness.client.worldView({ context: harness.context, focus: args.focus ?? [] });
+                    if (res.error)
+                        return failure("world_view refused", res.error.message);
+                    if (res.entities.length === 0)
+                        return text("empty slice", "The World holds nothing for this target yet.");
+                    const lines = res.entities.map((e) => {
+                        const attrs = Object.entries(e.attributes).map(([k, v]) => `${k}=${v}`).join(", ");
+                        return `- [${e.handle}] ${WorldEntityKind[e.kind] ?? e.kind} ${e.label}${attrs ? ` (${attrs})` : ""}`;
+                    });
+                    return text(`${res.entities.length} entit${res.entities.length === 1 ? "y" : "ies"}${res.truncated ? " (truncated)" : ""}`, lines.join("\n"));
+                }
+                catch (e) {
+                    return failure("world_view failed", e.message);
+                }
+            },
+        }), defineTool({
+            name: "run_history",
+            description: "Earlier runs of this mission's target, so a session can see what previous runs already did.",
+            input: {},
+            annotations: { readOnlyHint: true },
+            handler: async () => json(await (ctx.gibson.knowledge ?? knowledge).runHistory()),
+        }), defineTool({
+            name: "application_findings",
+            description: "The findings of one Application, with the lifecycle context that decides how much each " +
+                "one matters: whether the affected place is reachable, whether it is exposed, and what a " +
+                "previous triage pass decided. An empty priority means no pass has decided yet, never " +
+                "that the finding is unimportant.",
+            input: {
+                application: z.string().describe("The Application's key. Required: the read is scoped to one Application."),
+                statuses: z.array(z.string()).optional().describe('Lifecycle statuses to keep: "open", "fixing", "fixed", "verified". Omit for every status.'),
+                limit: z.number().int().min(1).optional().describe("Bound on one read. The server caps it either way."),
+            },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => json(await (ctx.gibson.knowledge ?? knowledge).applicationFindings({
+                application: args.application,
+                ...(args.statuses ? { statuses: args.statuses } : {}),
+                ...(args.limit ? { limit: args.limit } : {}),
+            })),
+        }));
+    }
+    return out;
+}

package/dist/helpers/tools.d.ts

@@ -0,0 +1,113 @@
+import type { ToolDefinition } from "../registry.js";
+import type { HelperContext } from "./context.js";
+export interface ToolOutcome {
+    output: unknown;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+export declare function formatToolResult(name: string, result: ToolOutcome): {
+    [x: string]: unknown;
+    content: ({
+        type: "text";
+        text: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "audio";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        uri: string;
+        name: string;
+        type: "resource_link";
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+        }[] | undefined;
+        title?: string | undefined;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        };
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+};
+/**
+ * The generic tool and plugin surface. `gibson_call_tool` stays even where
+ * discovery works: discovery answers `Unimplemented` on some daemons
+ * (gibson#1186), and an operator may know a tool by name.
+ */
+export declare function platformToolHelpers(ctx: HelperContext): ToolDefinition[];

package/dist/helpers/tools.js

@@ -0,0 +1,80 @@
+import { callGibsonTool, listGibsonPlugins, listGibsonTools, parseMaybeJSON, queryGibsonPlugin } from "@zeroroot-ai/sdk";
+import { z } from "zod";
+import { defineTool } from "../tool.js";
+import { failure, text } from "../tools/result.js";
+export function formatToolResult(name, result) {
+    if (result.error) {
+        return failure(`${name} failed`, `Gibson tool ${name} failed [${result.error.code}]: ${result.error.message}${result.error.retryable ? " (retryable)" : ""}`);
+    }
+    const body = typeof result.output === "string" ? result.output : JSON.stringify(result.output, null, 2);
+    return text(name, body ?? "(no output)");
+}
+/**
+ * The generic tool and plugin surface. `gibson_call_tool` stays even where
+ * discovery works: discovery answers `Unimplemented` on some daemons
+ * (gibson#1186), and an operator may know a tool by name.
+ */
+export function platformToolHelpers(ctx) {
+    if (!ctx.gibson.session)
+        return [];
+    const component = ctx.gibson.session.clients.component;
+    return [
+        defineTool({
+            name: "gibson_call_tool",
+            description: "Invoke a Gibson tool by name through the harness. Use this when you know a tool's name " +
+                "but it is not in your tool list. Gibson tool discovery is not available on every daemon.",
+            input: {
+                name: z.string().describe("Registered Gibson tool name."),
+                input: z.record(z.string(), z.unknown()).describe("Input object matching the tool's input schema."),
+                timeout_ms: z.number().int().min(1).optional().describe("Per-call timeout in milliseconds."),
+            },
+            handler: async (args) => formatToolResult(args.name, await callGibsonTool(component, { name: args.name, input: args.input, ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}) })),
+        }),
+        defineTool({
+            name: "list_gibson_tools",
+            description: "List the Gibson tools available to this tenant, with the input message type each one expects.",
+            input: {},
+            annotations: { readOnlyHint: true },
+            handler: async () => {
+                const discovery = await listGibsonTools(component);
+                if (discovery.unavailable)
+                    return text("discovery unavailable", `Tool discovery is unavailable: ${discovery.unavailable}.`);
+                if (discovery.tools.length === 0)
+                    return text("no tools", "No Gibson tools are registered for this tenant.");
+                const lines = discovery.tools.map((t) => `- ${t.name} (${t.version}): ${t.description || "no description"}${t.inputMessageType ? `\n    input: ${t.inputMessageType}` : ""}`);
+                return text(`${discovery.tools.length} tool${discovery.tools.length === 1 ? "" : "s"}`, lines.join("\n"));
+            },
+        }),
+        defineTool({
+            name: "list_gibson_plugins",
+            description: "List the Gibson plugins in the catalog, annotated with this tenant's enablement and health.",
+            input: {},
+            annotations: { readOnlyHint: true },
+            handler: async () => {
+                const plugins = await listGibsonPlugins(component);
+                if (plugins.length === 0)
+                    return text("no plugins", "The catalog holds no plugins for this tenant.");
+                const lines = plugins.map((p) => `- ${p.name} (${p.version}): ${p.description || "no description"} [${p.enabled ? "enabled" : "disabled"}, ${p.healthStatus || "health unknown"}]`);
+                return text(`${plugins.length} plugin${plugins.length === 1 ? "" : "s"}`, lines.join("\n"));
+            },
+        }),
+        defineTool({
+            name: "query_plugin",
+            description: "Call a method on a tenant Gibson plugin (a connector or an integration) through the harness.",
+            input: {
+                plugin: z.string().describe("Plugin name."),
+                method: z.string().describe("Method name."),
+                params: z.record(z.string(), z.unknown()).optional().describe("Method parameters."),
+            },
+            handler: async (args) => formatToolResult(`${args.plugin}.${args.method}`, await queryGibsonPlugin(component, { plugin: args.plugin, method: args.method, params: args.params ?? {} })),
+        }),
+        defineTool({
+            name: "parse_gibson_output",
+            description: "Decode a Gibson `*_json` string field. A tool is free to return a bare string, so a value " +
+                "that does not parse comes back as the raw text rather than an error.",
+            input: { raw: z.string().describe("The raw string field.") },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => text("", JSON.stringify(parseMaybeJSON(args.raw) ?? null, null, 2)),
+        }),
+    ];
+}

package/dist/http.d.ts

@@ -0,0 +1,57 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { Listen } from "./flags.js";
+import { type Log } from "./log.js";
+/**
+ * The streamable-HTTP transport on localhost: the sandbox path. One process
+ * serves for the life of the sandbox; each MCP client session (one per Claude
+ * Code process) gets its own protocol server over the shared tool registry.
+ *
+ *   POST /mcp        a new session starts with `initialize`; later requests
+ *                    carry `mcp-session-id`
+ *   GET  /mcp        the session's notification stream
+ *   DELETE /mcp      ends a session
+ *   GET  /healthz    liveness and the current posture, as JSON
+ *
+ * DNS-rebinding protection is on: only the loopback host names are accepted.
+ */
+export interface HttpSurface {
+    attach(transport: Transport): Promise<unknown>;
+    /** Small JSON for /healthz. */
+    health(): Record<string, unknown>;
+    /**
+     * The per-turn grant control endpoint (gibson#1706, decision 14). The
+     * driver calls it before it feeds Claude a message, and every tool call
+     * that follows runs under that dispatch's grant. Absent outside a member
+     * sandbox, and then `/turn` answers 404 like any other unknown route.
+     */
+    turn?: TurnRoute;
+}
+/**
+ * `POST /turn {job_id, grant, callback_endpoint?, insecure?}` puts a turn in
+ * force. `DELETE /turn` ends it, and later calls fall back to the base
+ * grant. `GET /turn` reports the turn in force.
+ */
+export interface TurnRoute {
+    set(turn: {
+        jobId: string;
+        grant: string;
+        endpoint?: string;
+        insecure?: boolean;
+    }): void;
+    clear(): void;
+    current(): {
+        jobId: string;
+        endpoint: string;
+    } | undefined;
+}
+export interface HttpHandle {
+    url: string;
+    host: string;
+    port: number;
+    sessions(): number;
+    close(): Promise<void>;
+}
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+export declare function serveHttp(surface: HttpSurface, listen: Listen, log: Log): Promise<HttpHandle>;

package/dist/http.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { TAG } from "./log.js";
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+export async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        const buf = c;
+        size += buf.byteLength;
+        if (size > MAX_BODY_BYTES)
+            throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+        chunks.push(buf);
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw)
+        return undefined;
+    return JSON.parse(raw);
+}
+export function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
+    res.end(text);
+}
+export async function serveHttp(surface, listen, log) {
+    const sessions = new Map();
+    let allowedHosts = [];
+    const handleMcp = async (req, res) => {
+        const header = req.headers["mcp-session-id"];
+        const sid = Array.isArray(header) ? header[0] : header;
+        if (sid) {
+            const transport = sessions.get(sid);
+            if (!transport) {
+                sendJson(res, 404, { error: "unknown MCP session; start a new one with initialize" });
+                return;
+            }
+            await transport.handleRequest(req, res);
+            return;
+        }
+        if (req.method !== "POST") {
+            sendJson(res, 400, { error: "a new MCP session starts with a POST initialize request" });
+            return;
+        }
+        const body = await readJsonBody(req);
+        if (!isInitializeRequest(body)) {
+            sendJson(res, 400, { error: "a new MCP session starts with initialize; later requests carry mcp-session-id" });
+            return;
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+                sessions.set(id, transport);
+                log(`${TAG} http: session ${id} opened (${sessions.size} open)`);
+            },
+            onsessionclosed: (id) => {
+                sessions.delete(id);
+                log(`${TAG} http: session ${id} closed (${sessions.size} open)`);
+            },
+            enableDnsRebindingProtection: true,
+            allowedHosts,
+        });
+        transport.onclose = () => {
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+        };
+        await surface.attach(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    const handleTurn = async (turn, req, res) => {
+        if (req.method === "GET") {
+            const current = turn.current();
+            return sendJson(res, 200, current ? { job_id: current.jobId, endpoint: current.endpoint } : { job_id: null });
+        }
+        if (req.method === "DELETE") {
+            turn.clear();
+            return sendJson(res, 200, { job_id: null });
+        }
+        if (req.method !== "POST")
+            return sendJson(res, 405, { error: "POST to set a turn, DELETE to end it, GET to read it" });
+        const body = (await readJsonBody(req));
+        const jobId = typeof body?.job_id === "string" ? body.job_id : "";
+        const grant = typeof body?.grant === "string" ? body.grant : "";
+        if (!jobId || !grant) {
+            return sendJson(res, 400, { error: "job_id and grant are both required: a turn is one dispatch's grant, and a grant with no job attributes the work to nothing" });
+        }
+        const endpoint = typeof body?.callback_endpoint === "string" ? body.callback_endpoint : undefined;
+        turn.set({ jobId, grant, ...(endpoint ? { endpoint } : {}), ...(typeof body?.insecure === "boolean" ? { insecure: body.insecure } : {}) });
+        const current = turn.current();
+        return sendJson(res, 200, { job_id: jobId, endpoint: current?.endpoint ?? endpoint ?? "" });
+    };
+    const server = createServer((req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? "/", `http://${listen.host}:${listen.port || 0}`);
+            try {
+                if (url.pathname === "/turn" && surface.turn)
+                    return await handleTurn(surface.turn, req, res);
+                if (url.pathname === "/mcp")
+                    return await handleMcp(req, res);
+                if (url.pathname === "/healthz" && req.method === "GET")
+                    return sendJson(res, 200, { ok: true, sessions: sessions.size, ...surface.health() });
+                sendJson(res, 404, { error: `no route ${req.method} ${url.pathname}` });
+            }
+            catch (e) {
+                log(`${TAG} http: ${req.method} ${url.pathname}: ${e.message}`);
+                if (!res.headersSent)
+                    sendJson(res, 500, { error: e.message });
+                else
+                    res.end();
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(listen.port, listen.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    const host = addr.family === "IPv6" ? `[${addr.address}]` : addr.address;
+    allowedHosts = [`${host}:${addr.port}`, `localhost:${addr.port}`, `127.0.0.1:${addr.port}`, `[::1]:${addr.port}`, host, "localhost", "127.0.0.1", "[::1]"];
+    return {
+        url: `http://${host}:${addr.port}/mcp`,
+        host: addr.address,
+        port: addr.port,
+        sessions: () => sessions.size,
+        close: async () => {
+            for (const t of sessions.values())
+                await t.close().catch(() => { });
+            sessions.clear();
+            await new Promise((resolve) => server.close(() => resolve()));
+            server.closeAllConnections?.();
+        },
+    };
+}