@scenoco-three/editor 0.4.0 → 0.5.0

package/dist/cli/index.js

@@ -1,99 +1,122 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { resolve } from 'node:path';
-import { parseArgs, parseList } from '../args.js';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { startEditorServer } from '../server.js';
-import { startMcpServer } from '../mcp.js';
-const USAGE = `scenoco-editor — open a scene/prefab and drive it from an MCP client
+import { createMcpServer, startMcpHttp } from '../mcp.js';
+const USAGE = `scenoco-editor — open a scene and drive it from an MCP client
 
 Usage:
-  scenoco-editor [scene|prefab] [--port <n>] [--no-open]
+  scenoco-editor [document] [options]
 
-With no file, the editor opens a picker listing the scenes/prefabs in the
-project's assets/ folder. Components are scanned from that assets/ folder and tag
-packages are read from its package.json — no --components/--packages needed.
+With no document, the editor opens a picker listing the project's scenes and
+prefabs. Tag packages are read from the project's package.json, so --modules is
+only for compiling against something other than what the project depends on.
 
 Options:
-  --port <n>   Fixed MCP server port — set this so the endpoint an MCP client
-               connects to is stable across restarts (the editor's own HTTP
-               server always takes a free port; it doesn't need to be fixed)
-  --no-open    Don't auto-open the editor in a browser
+  --root <dir>     Project root (default: the nearest one at or above the
+                   current directory)
+  --modules a,b    Packages whose tags the documents use, beyond three
+  --mcp-port <n>   Fixed MCP port (default 55470) — an MCP client is configured
+                   once with a URL, so this must not move between restarts
 
-Starts a local editor and an MCP server. The editor opens in your default
-browser; when you stop the server (Ctrl+C) it tells the page to close its own
-tab, so no stale tab is left behind. Point an MCP client at the printed
-endpoint; its tools — open_file, get_preview, run, pause, stop, get_telemetry —
-drive the live editor.`;
+The editor serves its own page and imports the project's generated modules, so
+what you see is the same scene the game loads. Its MCP tools **observe**: open,
+screenshot, telemetry, play/pause/stop, simulate. Documents are changed by
+editing the XML — in the editor, or in your own editor — and the watcher rebuilds.`;
+const DEFAULT_MCP_PORT = 55470;
 async function main(argv) {
-    const { positionals, options } = parseArgs(argv);
-    const file = positionals[0];
-    if (file === '-h' || file === '--help') {
+    if (argv.includes('-h') || argv.includes('--help')) {
         console.log(USAGE);
         return 0;
     }
-    // npm/npx rewrites process.cwd() to the nearest enclosing package.json when
-    // run from inside a workspace package without its own node_modules/.bin
-    // (e.g. `npx scenoco-editor` from examples/breakout/scenes). INIT_CWD still
-    // holds the shell's actual directory.
-    const cwd = process.env.INIT_CWD || process.cwd();
-    // Components default to assets/ and tag packages to the project's package.json
-    // deps (see startEditorServer); --components/--packages remain as optional
-    // overrides for non-standard layouts.
-    // The editor's HTTP server can float on any free port — the browser is pointed
-    // at whatever it gets. `--port` fixes the MCP endpoint instead, so an MCP
-    // client's configured URL stays valid across editor restarts.
+    const flag = (name) => {
+        const i = argv.indexOf(`--${name}`);
+        return i === -1 ? undefined : argv[i + 1];
+    };
+    const document = argv.find((a) => !a.startsWith('--') && argv[argv.indexOf(a) - 1]?.startsWith('--') !== true);
+    const modules = flag('modules')?.split(',').filter(Boolean);
+    // npm and npx rewrite `cwd` to the nearest enclosing package.json when run from inside a
+    // workspace package; `INIT_CWD` still holds the directory the shell was actually in.
+    const from = flag('root') ?? process.env.INIT_CWD ?? process.cwd();
+    const root = flag('root') ? resolve(from) : projectRootAt(from);
+    let closing = false;
     const editor = await startEditorServer({
-        cwd,
-        ...(parseList(options.components) ? { componentRoots: parseList(options.components) } : {}),
-        ...(parseList(options.packages) ? { packages: parseList(options.packages) } : {}),
-    });
-    const mcp = await startMcpServer(editor.bridge, {
-        ...(options.port ? { port: Number(options.port) } : {}),
+        root,
+        ...(modules ? { modules: ['three', ...modules] } : {}),
+        // Self-halt once every tab is closed, so a spawned editor never lingers holding its ports.
+        onIdle: () => {
+            if (closing)
+                return;
+            console.error('\n  no editor connected — shutting down so no stale process is left behind\n');
+            void shutdown();
+        },
     });
-    // With no file, open bare — the editor page shows a picker of the assets/ scenes.
-    const query = file ? `?file=${encodeURIComponent(resolve(cwd, file))}` : '';
-    const appUrl = `${editor.url}${query}`;
-    console.log(`\n  editor:  ${appUrl}`);
+    const mcpPort = Number(flag('mcp-port') ?? DEFAULT_MCP_PORT);
+    // A server per session: an MCP client that reconnects gets a fresh one rather than a 400.
+    const mcp = await startMcpHttp(() => createMcpServer(editor.bridge, () => editor.url), mcpPort);
+    const query = document ? `?path=${encodeURIComponent(document)}` : '';
+    const url = `${editor.url}${query}`;
+    console.log(`\n  editor:  ${url}`);
+    // The address to type into a phone on the same Wi-Fi — the touch controls only mean anything
+    // on a device with fingers.
     if (editor.networkUrl)
         console.log(`  wi-fi:   ${editor.networkUrl}${query}`);
-    console.log(`  mcp:     ${mcp.url}   ← add this to your MCP client (transport: http)`);
-    console.log(`\n  press Ctrl+C to stop\n`);
-    if (!('no-open' in options))
-        openBrowser(appUrl);
-    let closing = false;
+    console.log(`  mcp:     http://localhost:${mcpPort}   ← add this to your MCP client (transport: http)`);
+    console.log('\n  press Ctrl+C to stop\n');
     const shutdown = async () => {
         if (closing)
             return;
         closing = true;
-        // Tell the editor page to close its own tab, then give the notification a
-        // moment to reach the browser before we tear the socket down. Works in any
-        // browser/OS (the tab was opened with the platform's default `open`), though
-        // window.close() is best-effort — see the app's wsClient for the fallback.
-        editor.bridge.push({ push: 'shutdown' });
-        await new Promise((r) => setTimeout(r, 250).unref());
-        // Connected browsers keep WS/HMR/keep-alive sockets open, so `close()` can
-        // stall waiting for them to drain — cap it so Ctrl+C always exits promptly.
-        const deadline = new Promise((r) => setTimeout(r, 1500).unref());
-        await Promise.race([Promise.all([mcp.close().catch(() => { }), editor.close().catch(() => { })]), deadline]);
+        // A connected browser holds WebSocket and HMR sockets open, so `close()` can stall waiting
+        // for them to drain. Cap it, so Ctrl+C always exits promptly.
+        const deadline = new Promise((done) => setTimeout(done, 1500).unref());
+        await Promise.race([
+            Promise.all([mcp.close().catch(() => { }), editor.close().catch(() => { })]),
+            deadline,
+        ]);
         process.exit(0);
     };
     process.on('SIGINT', () => void shutdown());
     process.on('SIGTERM', () => void shutdown());
-    await new Promise(() => { }); // keep alive
-    return 0;
-}
-/** Open a URL in the default browser (best-effort, per platform). */
-function openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    try {
-        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    // Having reclaimed the previous session's port, give any tab left behind by an ungraceful exit
+    // a moment to reattach on its own retry loop — a restart should land in the tab that is
+    // already open rather than stack a second one beside it. On a fresh port nothing is waiting.
+    const reattached = editor.reusedPort && (await editor.bridge.waitForConnection(1500));
+    if (reattached) {
+        console.log('  reattached the editor tab already open — no new tab\n');
+        // That tab is still showing whatever it had open, so a named document has to be asked for.
+        if (document)
+            await editor.bridge.send({ id: 'cli-open', type: 'open', path: document }).catch(() => { });
+    }
+    else {
+        openBrowser(url);
     }
-    catch {
-        /* non-fatal: the URL is printed */
+    return new Promise(() => { }); // runs until interrupted
+}
+/**
+ * The project a bare `scenoco-editor` means: the nearest directory at or above `from` that holds
+ * a `tsconfig.json`.
+ *
+ * Running it from `src/` or `assets/scenes/` is the normal way to reach for an editor, and
+ * "no tsconfig.json here" is a poor answer when the project is one directory up. Falls back to
+ * `from` unchanged, so the error still names the place the person actually was.
+ */
+function projectRootAt(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        if (existsSync(join(dir, 'tsconfig.json')))
+            return dir;
+        if (dirname(dir) === dir)
+            return resolve(from);
     }
 }
-process.exitCode = await main(process.argv.slice(2)).catch((e) => {
-    console.error(e instanceof Error ? e.message : String(e));
-    return 1;
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(command, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
 });

package/dist/index.d.ts

@@ -1,3 +1,10 @@
-export { startEditorServer, type ServerOptions, type EditorServer, type EditorBridge } from './server.js';
-export { startMcpServer, buildMcpServer, type McpHandle } from './mcp.js';
-export { WS_PATH, commandId, type EditorCommand, type EditorResponse, type EditorResult, } from './protocol.js';
+/**
+ * `@scenoco-three/editor` — the programmatic API behind the `scenoco-editor` CLI.
+ *
+ * Serves the editor page, bridges it to an MCP server over a WebSocket, and exposes MCP tools
+ * that **observe**: open, screenshot, telemetry, play/pause/stop, simulate. Documents are changed
+ * by editing the XML; there is no remote edit tool, by decision.
+ */
+export { startEditorServer, applyEdits, type ServerOptions, type EditorServer, type EditorBridge, type Edit, } from './server.js';
+export { createMcpServer, startMcpHttp } from './mcp.js';
+export { WS_PATH, commandId, type EditorCommand, type EditorPush, type EditorResponse, type EditorResult, type PreviewFrame, type SimStep, } from './protocol.js';

package/dist/index.js

@@ -1,6 +1,10 @@
-// `@scenoco-three/editor` — programmatic API behind the `scenoco-editor` CLI.
-// Serves the editor app, bridges it to an MCP server over a WebSocket, and exposes
-// MCP tools (open_file / get_preview / run / pause / stop / get_telemetry).
-export { startEditorServer } from './server.js';
-export { startMcpServer, buildMcpServer } from './mcp.js';
+/**
+ * `@scenoco-three/editor` — the programmatic API behind the `scenoco-editor` CLI.
+ *
+ * Serves the editor page, bridges it to an MCP server over a WebSocket, and exposes MCP tools
+ * that **observe**: open, screenshot, telemetry, play/pause/stop, simulate. Documents are changed
+ * by editing the XML; there is no remote edit tool, by decision.
+ */
+export { startEditorServer, applyEdits, } from './server.js';
+export { createMcpServer, startMcpHttp } from './mcp.js';
 export { WS_PATH, commandId, } from './protocol.js';

package/dist/mcp.d.ts

@@ -1,16 +1,32 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { EditorBridge } from './server.js';
-export interface McpHandle {
-    /** The MCP endpoint URL to add to an MCP client. */
-    url: string;
-    close(): Promise<void>;
-}
 /**
- * Start a stateless MCP server (Streamable HTTP) whose tools relay to the live
- * editor over `bridge`. A fresh `McpServer` + transport is built per request.
+ * The MCP surface: **eyes, not hands.**
+ *
+ * Open a document, render it, drive it, read what happened. There is no tool here that writes to
+ * the user's source, and that is a decision rather than an omission. An agent already has file
+ * tools, and the editor's watcher rebuilds whatever it writes — so an edit tool would have been
+ * a second write path into someone's project that never passed through their editor, their diff
+ * or their undo. An agent holding one can reshape a scene while believing it is only looking at
+ * it.
+ *
+ * v1 shipped `patch`, `structural` and `save` tools alongside these. They are deleted.
+ *
+ * The one thing worth insisting on: `simulate` exists because a screenshot of frame zero says
+ * almost nothing about whether a game works. Drive it to the interesting moment, *then* look.
+ */
+export declare function createMcpServer(bridge: EditorBridge, editorUrl: () => string): McpServer;
+/**
+ * Serve the MCP over HTTP on a fixed port.
+ *
+ * Fixed on purpose: an MCP client is configured once with a URL, and a port that moved on every
+ * restart would need reconfiguring every time.
+ *
+ * **One transport per session**, created when a client initializes and kept until it goes away.
+ * A single shared transport looked simpler and allowed exactly one client ever: the first
+ * `initialize` claimed it, and every later one — a reconnect, a second client, a restarted
+ * agent — got a bare `400`, which reads like a crashed server rather than a design limit.
  */
-export declare function startMcpServer(bridge: EditorBridge, opts?: {
-    port?: number;
-}): Promise<McpHandle>;
-/** Build an McpServer whose tools relay to the editor. */
-export declare function buildMcpServer(bridge: EditorBridge): McpServer;
+export declare function startMcpHttp(makeServer: () => McpServer, port: number): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/mcp.js

@@ -1,150 +1,191 @@
+import { randomUUID } from 'node:crypto';
 import { createServer as createHttpServer } from 'node:http';
-import { createServer as createNetServer } from 'node:net';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { commandId } from './protocol.js';
 /**
- * Start a stateless MCP server (Streamable HTTP) whose tools relay to the live
- * editor over `bridge`. A fresh `McpServer` + transport is built per request.
+ * The MCP surface: **eyes, not hands.**
+ *
+ * Open a document, render it, drive it, read what happened. There is no tool here that writes to
+ * the user's source, and that is a decision rather than an omission. An agent already has file
+ * tools, and the editor's watcher rebuilds whatever it writes — so an edit tool would have been
+ * a second write path into someone's project that never passed through their editor, their diff
+ * or their undo. An agent holding one can reshape a scene while believing it is only looking at
+ * it.
+ *
+ * v1 shipped `patch`, `structural` and `save` tools alongside these. They are deleted.
+ *
+ * The one thing worth insisting on: `simulate` exists because a screenshot of frame zero says
+ * almost nothing about whether a game works. Drive it to the interesting moment, *then* look.
  */
-export async function startMcpServer(bridge, opts = {}) {
-    const port = opts.port ?? (await freePort());
-    const http = createHttpServer((req, res) => void handle(req, res, bridge));
-    await new Promise((resolve) => http.listen(port, resolve));
-    return {
-        url: `http://localhost:${port}/mcp`,
-        close: () => new Promise((resolve) => http.close(() => resolve())),
+export function createMcpServer(bridge, editorUrl) {
+    const mcp = new McpServer({ name: 'scenoco-editor', version: '2.0.0' });
+    /** Every tool needs a live page; saying so plainly beats a timeout. */
+    const send = async (command) => {
+        if (!bridge.connected()) {
+            throw new Error(`no editor page is open — visit ${editorUrl()} first, then retry`);
+        }
+        const response = await bridge.send(command);
+        if (!response.ok)
+            throw new Error(response.error);
+        return response.result;
     };
-}
-/** Build an McpServer whose tools relay to the editor. */
-export function buildMcpServer(bridge) {
-    const server = new McpServer({ name: 'scenoco-editor', version: '0.1.0' });
-    const relay = (cmd) => relayToEditor(bridge, cmd);
-    server.registerTool('open_file', { description: 'Open a scene (.scene.xml) or prefab (.prefab.xml) in the editor (edit mode).', inputSchema: { path: z.string() } }, ({ path }) => relay({ id: commandId(), type: 'open', path }));
-    server.registerTool('get_preview', {
-        description: 'Capture the current editor view as a PNG. Optionally frame a specific camera.',
+    const frameSchema = {
+        width: z.number().int().positive().describe('Captured image width in pixels'),
+        height: z.number().int().positive().describe('Captured image height in pixels'),
+        ui: z
+            .boolean()
+            .describe('Include the screen-space UI layer, framing the shot through the camera that hosts it'),
+    };
+    const POINT = '"y: 6; z: 12" — the document\'s own vector grammar; an omitted axis is 0';
+    mcp.registerTool('open', {
+        description: 'Open a scene or prefab document in the editor page.',
+        inputSchema: { path: z.string().describe('Project-relative path, e.g. assets/scenes/main.scene.xml') },
+    }, async ({ path }) => text(await send({ id: commandId(), type: 'open', path })));
+    mcp.registerTool('screenshot', {
+        description: 'Render one PNG of the open scene from a given viewpoint. Does not move the editor camera.',
         inputSchema: {
-            camera: z.string().optional().describe('Camera position "x y z"'),
-            lookAt: z.string().optional().describe('Look-at point "x y z"'),
+            camera: z.string().describe(`Where to look from: ${POINT}, or "fit" to frame the whole scene`),
+            lookAt: z.string().optional().describe(`What to look at: ${POINT}. Defaults to the origin`),
+            ...frameSchema,
         },
-    }, ({ camera, lookAt }) => relay({ id: commandId(), type: 'preview', ...(camera ? { camera } : {}), ...(lookAt ? { lookAt } : {}) }));
-    server.registerTool('playback', {
-        description: 'Control gameplay: play (run components/systems/physics), pause, or stop (back to edit mode).',
-        inputSchema: { state: z.enum(['play', 'pause', 'stop']) },
-    }, ({ state }) => relay({ id: commandId(), type: state === 'play' ? 'run' : state }));
-    server.registerTool('get_telemetry', { description: 'Current property values (JSON) for the node/components at a scene id.', inputSchema: { id: z.string() } }, ({ id }) => relay({ id: commandId(), type: 'telemetry', targetId: id }));
-    // A simulation command — one entry in the `simulate` batch. Loose (all fields
-    // optional) so the agent composes any step; only `do` is required.
-    const simStep = z.object({
-        do: z.enum(['play', 'pause', 'stop', 'step', 'tap', 'keyDown', 'keyUp', 'click', 'move', 'gamepad', 'preview', 'telemetry']),
-        key: z.string().optional().describe("tap/keyDown/keyUp: key name, e.g. 'Space', 'W', 'LeftArrow'"),
-        frames: z.number().int().optional(),
-        dt: z.number().optional(),
-        x: z.number().optional(),
-        y: z.number().optional(),
-        dx: z.number().optional(),
-        dy: z.number().optional(),
-        button: z.enum(['left', 'right', 'middle']).optional(),
-        index: z.number().int().optional(),
-        buttons: z.array(z.boolean()).optional(),
-        axes: z.array(z.number()).optional(),
-        camera: z.string().optional(),
-        lookAt: z.string().optional(),
-        id: z.string().optional(),
+    }, async ({ camera, lookAt, width, height, ui }) => image(await send({
+        id: commandId(),
+        type: 'preview',
+        camera,
+        ...(lookAt ? { lookAt } : {}),
+        frame: { width, height, ui },
+    })));
+    mcp.registerTool('telemetry', {
+        description: 'Read the live state at an id the document declares — transform, visibility, and each component’s public values.',
+        inputSchema: { id: z.string().describe('An id= from the open document') },
+    }, async ({ id }) => text(await send({ id: commandId(), type: 'telemetry', targetId: id })));
+    for (const [name, type] of [
+        ['play', 'run'],
+        ['pause', 'pause'],
+        ['stop', 'stop'],
+    ]) {
+        mcp.registerTool(name, { description: `${name[0].toUpperCase()}${name.slice(1)} the open scene.`, inputSchema: {} }, async () => text(await send({ id: commandId(), type })));
+    }
+    mcp.registerTool('simulate', {
+        description: 'Run a batch of steps against the live scene and collect what each produced. This is how ' +
+            'to find out whether a game works: drive it to the moment that matters, then capture. ' +
+            'Steps run in order.',
+        inputSchema: {
+            steps: z
+                .array(z.record(z.string(), z.unknown()))
+                .describe('Ordered steps. {"do":"play"} · {"do":"step","frames":30,"dt":0.0167} · ' +
+                '{"do":"press","key":"Space"} (a KeyCode member name) · {"do":"keyDown"/"keyUp","key":…} · ' +
+                '{"do":"click","x":100,"y":80} · {"do":"move","x":…,"y":…} · ' +
+                `{"do":"preview","camera":${JSON.stringify(POINT)}} · {"do":"telemetry","id":"ball"}`),
+            ...frameSchema,
+        },
+    }, async ({ steps, width, height, ui }) => {
+        const result = await send({
+            id: commandId(),
+            type: 'simulate',
+            steps: steps,
+            frame: { width, height, ui },
+        });
+        if (result.kind !== 'multi')
+            return text(result);
+        // Images and readings interleaved in the order they were captured, so a caller can line a
+        // frame up with the numbers that went with it.
+        return {
+            content: result.results.map((one) => one.kind === 'image'
+                ? { type: 'image', data: one.dataUrl.split(',')[1] ?? '', mimeType: 'image/png' }
+                : { type: 'text', text: JSON.stringify(one.kind === 'json' ? one.data : one, null, 2) }),
+        };
     });
-    server.registerTool('simulate', {
-        description: 'Drive gameplay: an ordered batch of steps; returns previews (images) and telemetry (JSON) in order. ' +
-            'Each step is one self-contained verb: { do: "play"|"pause"|"stop" | "step"(frames) | "tap"(key) | ' +
-            '"keyDown"(key) | "keyUp"(key) | "click"(x,y,button) | "move"(x,y,dx,dy) | "preview"(camera,lookAt) | "telemetry"(id) }. ' +
-            'Example: [{do:"play"},{do:"tap",key:"Space"},{do:"step",frames:90},{do:"preview"}].',
-        inputSchema: { commands: z.array(simStep) },
-    }, ({ commands }) => relay({ id: commandId(), type: 'simulate', steps: commands }));
-    return server;
+    return mcp;
 }
-/** Send a command to the editor and map its reply to MCP tool content. */
-async function relayToEditor(bridge, cmd) {
-    let response;
-    try {
-        response = await bridge.send(cmd);
-    }
-    catch (e) {
-        return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
-    }
-    if (!response.ok)
-        return { isError: true, content: [{ type: 'text', text: response.error }] };
-    return toContent(response.result);
+function text(result) {
+    const body = result.kind === 'json'
+        ? JSON.stringify(result.data, null, 2)
+        : result.kind === 'ok'
+            ? (result.info ?? 'ok')
+            : JSON.stringify(result);
+    return { content: [{ type: 'text', text: body }] };
 }
-function toContent(result) {
-    switch (result.kind) {
-        case 'image': {
-            const base64 = result.dataUrl.replace(/^data:image\/png;base64,/, '');
-            return { content: [{ type: 'image', data: base64, mimeType: 'image/png' }] };
-        }
-        case 'json':
-            return { content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }] };
-        case 'multi': {
-            // Flatten each capture's blocks, preserving step order.
-            const content = result.results.flatMap((r) => toContent(r).content);
-            return { content: content.length > 0 ? content : [{ type: 'text', text: 'ok' }] };
+function image(result) {
+    if (result.kind !== 'image')
+        throw new Error('the editor did not return an image');
+    return {
+        content: [{ type: 'image', data: result.dataUrl.split(',')[1] ?? '', mimeType: 'image/png' }],
+    };
+}
+/**
+ * Serve the MCP over HTTP on a fixed port.
+ *
+ * Fixed on purpose: an MCP client is configured once with a URL, and a port that moved on every
+ * restart would need reconfiguring every time.
+ *
+ * **One transport per session**, created when a client initializes and kept until it goes away.
+ * A single shared transport looked simpler and allowed exactly one client ever: the first
+ * `initialize` claimed it, and every later one — a reconnect, a second client, a restarted
+ * agent — got a bare `400`, which reads like a crashed server rather than a design limit.
+ */
+export async function startMcpHttp(makeServer, port) {
+    const sessions = new Map();
+    const http = createHttpServer((req, res) => {
+        void handle(req, res).catch((error) => {
+            res.statusCode = 500;
+            res.end(String(error instanceof Error ? error.message : error));
+        });
+    });
+    async function handle(req, res) {
+        const id = req.headers['mcp-session-id'];
+        const existing = typeof id === 'string' ? sessions.get(id) : undefined;
+        if (existing)
+            return existing.handleRequest(req, res, await body(req));
+        const parsed = await body(req);
+        if (!isInitialize(parsed)) {
+            res.statusCode = 400;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32000, message: 'unknown session — send `initialize` first' },
+            }));
+            return;
         }
-        case 'ok':
-        default:
-            return { content: [{ type: 'text', text: result.info ?? 'ok' }] };
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (session) => {
+                sessions.set(session, transport);
+            },
+        });
+        transport.onclose = () => {
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+        };
+        await makeServer().connect(transport);
+        return transport.handleRequest(req, res, parsed);
     }
+    await new Promise((done) => http.listen(port, done));
+    return {
+        close: async () => {
+            for (const transport of sessions.values())
+                await transport.close().catch(() => { });
+            sessions.clear();
+            await new Promise((done) => http.close(() => done()));
+        },
+    };
 }
-async function handle(req, res, bridge) {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Headers', 'content-type, mcp-session-id, mcp-protocol-version');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    if (req.method === 'OPTIONS') {
-        res.statusCode = 204;
-        res.end();
-        return;
-    }
-    if ((req.url ?? '').split('?')[0] !== '/mcp') {
-        res.statusCode = 404;
-        res.end('not found');
-        return;
+function isInitialize(parsed) {
+    return typeof parsed === 'object' && parsed !== null && parsed.method === 'initialize';
+}
+/** The request body, read once — the transport is handed the parsed value rather than the stream. */
+async function body(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf8');
+    try {
+        return raw ? JSON.parse(raw) : undefined;
     }
-    if (req.method !== 'POST') {
-        res.statusCode = 405;
-        res.setHeader('Allow', 'POST');
-        res.end(JSON.stringify({ error: 'this MCP endpoint is stateless — use POST' }));
-        return;
+    catch {
+        return undefined;
     }
-    const body = await readJson(req);
-    // Stateless: a fresh server + transport per request.
-    const server = buildMcpServer(bridge);
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
-    res.on('close', () => {
-        void transport.close();
-        void server.close();
-    });
-    await server.connect(transport);
-    await transport.handleRequest(req, res, body);
-}
-function readJson(req) {
-    return new Promise((resolve) => {
-        let data = '';
-        req.on('data', (c) => (data += c));
-        req.on('end', () => {
-            try {
-                resolve(data ? JSON.parse(data) : undefined);
-            }
-            catch {
-                resolve(undefined);
-            }
-        });
-    });
-}
-function freePort() {
-    return new Promise((res, rej) => {
-        const probe = createNetServer();
-        probe.on('error', rej);
-        probe.listen(0, () => {
-            const port = probe.address().port;
-            probe.close(() => res(port));
-        });
-    });
 }