@imgly/codesign-mcp 0.1.6 → 0.1.8

package/dist/engine/cesdk-adapter.d.ts

@@ -15,6 +15,10 @@ import type { EngineAdapter } from './session.js';
  * calls `create()` on the first slot (first edit), awaiting it then — by which
  * point init is usually already settled. The other methods receive the resolved
  * engine from EngineSession, so they never touch the promise.
+ *
+ * `engine` may also be a thunk `() => Promise<CreativeEngine>`: the stdio
+ * transport passes a lazy, slot-gated boot so no engine initializes until the
+ * first edit calls create().
  */
-export declare function cesdkAdapter(engine: CreativeEngine | Promise<CreativeEngine>): EngineAdapter<CreativeEngine>;
+export declare function cesdkAdapter(engine: CreativeEngine | Promise<CreativeEngine> | (() => CreativeEngine | Promise<CreativeEngine>)): EngineAdapter<CreativeEngine>;
 //# sourceMappingURL=cesdk-adapter.d.ts.map

package/dist/engine/cesdk-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cesdk-adapter.d.ts","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,GAC/C,aAAa,CAAC,cAAc,CAAC,CAc/B"}
+{"version":3,"file":"cesdk-adapter.d.ts","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EACF,cAAc,GACd,OAAO,CAAC,cAAc,CAAC,GACvB,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,GACnD,aAAa,CAAC,cAAc,CAAC,CAiB/B"}

package/dist/engine/cesdk-adapter.js

@@ -14,10 +14,17 @@ import { SCENE_ALLOWED_RESOURCE_SCHEMES } from './scene-resource-schemes.js';
  * calls `create()` on the first slot (first edit), awaiting it then — by which
  * point init is usually already settled. The other methods receive the resolved
  * engine from EngineSession, so they never touch the promise.
+ *
+ * `engine` may also be a thunk `() => Promise<CreativeEngine>`: the stdio
+ * transport passes a lazy, slot-gated boot so no engine initializes until the
+ * first edit calls create().
  */
 export function cesdkAdapter(engine) {
     return {
-        create: () => engine, // single-engine adapter: always the same instance (awaited lazily if a promise)
+        // Value/promise: always the same instance. Thunk: the stdio transport passes
+        // a lazy slot-gated boot (CODE-59) so nothing initializes until the first
+        // edit; EngineSession(size:1) calls create() only once, on that first edit.
+        create: () => (typeof engine === 'function' ? engine() : engine),
         reset: async (eng) => {
             eng.scene.create(); // wipes the active scene; design-unit patch from tools/engine.ts re-applies
         },

package/dist/engine/cesdk-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"cesdk-adapter.js","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAG7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAgD;IAEhD,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,gFAAgF;QACtG,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACnB,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,4EAA4E;QAClG,CAAC;QACD,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YACnC,MAAM,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QACD,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAC1B,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;YACrB,sBAAsB,EAAE,8BAA8B;SACvD,CAAC;KACL,CAAC;AACJ,CAAC","sourcesContent":["import type CreativeEngine from '@cesdk/engine';\nimport { SCENE_ALLOWED_RESOURCE_SCHEMES } from './scene-resource-schemes.js';\nimport type { EngineAdapter } from './session.js';\n\n/**\n * Adapts a `@cesdk/engine` CreativeEngine instance to the EngineSession's\n * generic EngineAdapter shape. One-to-one mapping; two quirks. First, `reset`\n * (CE.SDK has no `reset()` — we wipe by creating a new scene via the same\n * patched create path `ensureHeadlessEngine` installed for the design-unit fix).\n * Second, `saveToString` passes an explicit `allowedResourceSchemes`: the\n * engine default rejects our durable `workspace://` scheme, so an edit commit\n * of a scene referencing workspace assets would fail without it (see\n * scene-resource-schemes.ts, CODE-3).\n *\n * `engine` may be a Promise: the stdio transport defers engine init off the\n * MCP-handshake path and hands the in-flight promise here. EngineSession only\n * calls `create()` on the first slot (first edit), awaiting it then — by which\n * point init is usually already settled. The other methods receive the resolved\n * engine from EngineSession, so they never touch the promise.\n */\nexport function cesdkAdapter(\n  engine: CreativeEngine | Promise<CreativeEngine>\n): EngineAdapter<CreativeEngine> {\n  return {\n    create: () => engine, // single-engine adapter: always the same instance (awaited lazily if a promise)\n    reset: async (eng) => {\n      eng.scene.create(); // wipes the active scene; design-unit patch from tools/engine.ts re-applies\n    },\n    loadFromString: async (eng, scene) => {\n      await eng.scene.loadFromString(scene);\n    },\n    saveToString: async (eng) =>\n      eng.scene.saveToString({\n        allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES\n      })\n  };\n}\n"]}
+{"version":3,"file":"cesdk-adapter.js","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAG7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAGoD;IAEpD,OAAO;QACL,6EAA6E;QAC7E,0EAA0E;QAC1E,4EAA4E;QAC5E,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAChE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACnB,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,4EAA4E;QAClG,CAAC;QACD,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YACnC,MAAM,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QACD,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAC1B,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;YACrB,sBAAsB,EAAE,8BAA8B;SACvD,CAAC;KACL,CAAC;AACJ,CAAC","sourcesContent":["import type CreativeEngine from '@cesdk/engine';\nimport { SCENE_ALLOWED_RESOURCE_SCHEMES } from './scene-resource-schemes.js';\nimport type { EngineAdapter } from './session.js';\n\n/**\n * Adapts a `@cesdk/engine` CreativeEngine instance to the EngineSession's\n * generic EngineAdapter shape. One-to-one mapping; two quirks. First, `reset`\n * (CE.SDK has no `reset()` — we wipe by creating a new scene via the same\n * patched create path `ensureHeadlessEngine` installed for the design-unit fix).\n * Second, `saveToString` passes an explicit `allowedResourceSchemes`: the\n * engine default rejects our durable `workspace://` scheme, so an edit commit\n * of a scene referencing workspace assets would fail without it (see\n * scene-resource-schemes.ts, CODE-3).\n *\n * `engine` may be a Promise: the stdio transport defers engine init off the\n * MCP-handshake path and hands the in-flight promise here. EngineSession only\n * calls `create()` on the first slot (first edit), awaiting it then — by which\n * point init is usually already settled. The other methods receive the resolved\n * engine from EngineSession, so they never touch the promise.\n *\n * `engine` may also be a thunk `() => Promise<CreativeEngine>`: the stdio\n * transport passes a lazy, slot-gated boot so no engine initializes until the\n * first edit calls create().\n */\nexport function cesdkAdapter(\n  engine:\n    | CreativeEngine\n    | Promise<CreativeEngine>\n    | (() => CreativeEngine | Promise<CreativeEngine>)\n): EngineAdapter<CreativeEngine> {\n  return {\n    // Value/promise: always the same instance. Thunk: the stdio transport passes\n    // a lazy slot-gated boot (CODE-59) so nothing initializes until the first\n    // edit; EngineSession(size:1) calls create() only once, on that first edit.\n    create: () => (typeof engine === 'function' ? engine() : engine),\n    reset: async (eng) => {\n      eng.scene.create(); // wipes the active scene; design-unit patch from tools/engine.ts re-applies\n    },\n    loadFromString: async (eng, scene) => {\n      await eng.scene.loadFromString(scene);\n    },\n    saveToString: async (eng) =>\n      eng.scene.saveToString({\n        allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES\n      })\n  };\n}\n"]}

package/dist/engine/engine-capacity.d.ts

@@ -0,0 +1,16 @@
+import type { CodesignMcpToolRegistration } from '../server.js';
+/** Thrown from the slot-gated engine boot when all engine slots are held. */
+export declare class EngineCapacityError extends Error {
+    readonly max: number;
+    constructor(max: number);
+}
+/** The agent-facing capacity message, templated on the live cap. */
+export declare function capacityMessage(max: number): string;
+/**
+ * Wrap a tool registration so a thrown EngineCapacityError becomes a clean MCP
+ * isError result (the capacity message) instead of propagating as a protocol
+ * error. Other errors pass through untouched. Applied to every tool at the stdio
+ * composition root; a no-op for tools that never touch the engine.
+ */
+export declare function wrapEngineCapacity(reg: CodesignMcpToolRegistration): CodesignMcpToolRegistration;
+//# sourceMappingURL=engine-capacity.d.ts.map

package/dist/engine/engine-capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-capacity.d.ts","sourceRoot":"","sources":["../../src/engine/engine-capacity.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CAIjC;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,2BAA2B,GAC/B,2BAA2B,CAiB7B"}

package/dist/engine/engine-capacity.js

@@ -0,0 +1,48 @@
+/** Thrown from the slot-gated engine boot when all engine slots are held. */
+export class EngineCapacityError extends Error {
+    constructor(max) {
+        super(`engine capacity reached (max=${max})`);
+        this.max = max;
+        this.name = 'EngineCapacityError';
+    }
+}
+/** The agent-facing capacity message, templated on the live cap. */
+export function capacityMessage(max) {
+    return [
+        `Design engine capacity reached — ${max} of ${max} CE.SDK engines are already running on this machine.`,
+        `This is a temporary, machine-wide limit that prevents parallel design sessions from exhausting memory. Your request was valid — nothing is wrong with your code or inputs, and no design was created. A slot frees automatically as soon as another session finishes or closes.`,
+        ``,
+        `What to do:`,
+        `- Retry the exact same call after a short wait — resending it unchanged will succeed once a slot is free.`,
+        `- Do not modify your design code in response to this; the code is not the problem.`,
+        `- If you are running several design tasks at once, run them one at a time instead of in parallel.`,
+        ``,
+        `(The human can raise the limit by setting IMGLY_MAX_STDIO_ENGINES higher and restarting. Current limit: ${max}.)`
+    ].join('\n');
+}
+/**
+ * Wrap a tool registration so a thrown EngineCapacityError becomes a clean MCP
+ * isError result (the capacity message) instead of propagating as a protocol
+ * error. Other errors pass through untouched. Applied to every tool at the stdio
+ * composition root; a no-op for tools that never touch the engine.
+ */
+export function wrapEngineCapacity(reg) {
+    return {
+        ...reg,
+        call: async (args) => {
+            try {
+                return await reg.call(args);
+            }
+            catch (err) {
+                if (err instanceof EngineCapacityError) {
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text: capacityMessage(err.max) }]
+                    };
+                }
+                throw err;
+            }
+        }
+    };
+}
+//# sourceMappingURL=engine-capacity.js.map

package/dist/engine/engine-capacity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-capacity.js","sourceRoot":"","sources":["../../src/engine/engine-capacity.ts"],"names":[],"mappings":"AAYA,6EAA6E;AAC7E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAqB,GAAW;QAC9B,KAAK,CAAC,gCAAgC,GAAG,GAAG,CAAC,CAAC;QAD3B,QAAG,GAAH,GAAG,CAAQ;QAE9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO;QACL,oCAAoC,GAAG,OAAO,GAAG,sDAAsD;QACvG,iRAAiR;QACjR,EAAE;QACF,aAAa;QACb,2GAA2G;QAC3G,oFAAoF;QACpF,mGAAmG;QACnG,EAAE;QACF,2GAA2G,GAAG,IAAI;KACnH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAgC;IAEhC,OAAO;QACL,GAAG,GAAG;QACN,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACnB,IAAI,CAAC;gBACH,OAAO,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,mBAAmB,EAAE,CAAC;oBACvC,OAAO;wBACL,OAAO,EAAE,IAAI;wBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;qBAC5D,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// packages/codesign-mcp/src/engine/engine-capacity.ts\n//\n// The machine-wide engine cap (CODE-59) fails fast: when every slot is held, the\n// triggering tool call returns an MCP isError result carrying an agent-facing\n// message — NOT a thrown protocol error. This module owns that error type, the\n// message, and the wrapper that turns the throw into the result.\n//\n// The message is a deliberate design surface: it is read by an LLM, so it (a)\n// states the request/code is fine (stops the model rewriting its design), (b)\n// says it is retryable and how, (c) tells an orchestrator to reduce parallelism.\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\n/** Thrown from the slot-gated engine boot when all engine slots are held. */\nexport class EngineCapacityError extends Error {\n  constructor(readonly max: number) {\n    super(`engine capacity reached (max=${max})`);\n    this.name = 'EngineCapacityError';\n  }\n}\n\n/** The agent-facing capacity message, templated on the live cap. */\nexport function capacityMessage(max: number): string {\n  return [\n    `Design engine capacity reached — ${max} of ${max} CE.SDK engines are already running on this machine.`,\n    `This is a temporary, machine-wide limit that prevents parallel design sessions from exhausting memory. Your request was valid — nothing is wrong with your code or inputs, and no design was created. A slot frees automatically as soon as another session finishes or closes.`,\n    ``,\n    `What to do:`,\n    `- Retry the exact same call after a short wait — resending it unchanged will succeed once a slot is free.`,\n    `- Do not modify your design code in response to this; the code is not the problem.`,\n    `- If you are running several design tasks at once, run them one at a time instead of in parallel.`,\n    ``,\n    `(The human can raise the limit by setting IMGLY_MAX_STDIO_ENGINES higher and restarting. Current limit: ${max}.)`\n  ].join('\\n');\n}\n\n/**\n * Wrap a tool registration so a thrown EngineCapacityError becomes a clean MCP\n * isError result (the capacity message) instead of propagating as a protocol\n * error. Other errors pass through untouched. Applied to every tool at the stdio\n * composition root; a no-op for tools that never touch the engine.\n */\nexport function wrapEngineCapacity(\n  reg: CodesignMcpToolRegistration\n): CodesignMcpToolRegistration {\n  return {\n    ...reg,\n    call: async (args) => {\n      try {\n        return await reg.call(args);\n      } catch (err) {\n        if (err instanceof EngineCapacityError) {\n          return {\n            isError: true,\n            content: [{ type: 'text', text: capacityMessage(err.max) }]\n          };\n        }\n        throw err;\n      }\n    }\n  };\n}\n"]}

package/dist/engine/engine-slots.d.ts

@@ -0,0 +1,48 @@
+export interface SlotHandle {
+    /** Which numbered slot (0-based) this handle owns. */
+    readonly index: number;
+    /** Release the slot (unlink its file). Idempotent; best-effort. */
+    release(): Promise<void>;
+}
+export interface AcquireEngineSlotOptions {
+    /** Max concurrent engines. The (max)th acquire succeeds; the (max+1)th returns null. */
+    max: number;
+    /** Slot directory. Defaults to ~/.codesign/engine-slots. Override in tests. */
+    dir?: string;
+    /** Liveness probe for a slot's owner PID. Defaults to a real kill(pid,0). Injectable for tests. */
+    isPidAlive?: (pid: number) => boolean;
+    /** This process's PID, recorded in the claimed slot. Defaults to process.pid. */
+    pid?: number;
+}
+/**
+ * True if a process with `pid` is alive. `kill(pid, 0)` sends no signal; it only
+ * probes. ESRCH => no such process (dead). EPERM (exists, another user) or any
+ * other error => assume alive (conservative — never steal a slot we're unsure of).
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Claim one of `max` numbered slots. Returns a handle for the first free (or
+ * reclaimable-stale) slot, or null when all `max` are held by live owners.
+ */
+export declare function acquireEngineSlot(opts: AcquireEngineSlotOptions): Promise<SlotHandle | null>;
+export interface SlotGatedEngine<E> {
+    /**
+     * Boot the engine on first call, gated by a machine-wide slot. Memoized: later
+     * calls return the same engine. Throws EngineCapacityError at capacity (the
+     * memo is NOT cached, so a later retry re-attempts). A boot FAILURE is cached
+     * (a hard init error must not churn slots on retry) and its slot is released.
+     */
+    get(): Promise<E>;
+    /** Release the held slot (for the clean-shutdown path). Idempotent. */
+    release(): Promise<void>;
+}
+export declare function createSlotGatedEngine<E>(opts: {
+    max: number;
+    boot: () => Promise<E>;
+    dir?: string;
+    acquire?: (o: {
+        max: number;
+        dir?: string;
+    }) => Promise<SlotHandle | null>;
+}): SlotGatedEngine<E>;
+//# sourceMappingURL=engine-slots.d.ts.map

package/dist/engine/engine-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-slots.d.ts","sourceRoot":"","sources":["../../src/engine/engine-slots.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU5B;AA+ED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC;;;;;OAKG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,uEAAuE;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC5E,GAAG,eAAe,CAAC,CAAC,CAAC,CAmCrB"}

package/dist/engine/engine-slots.js

@@ -0,0 +1,182 @@
+// packages/codesign-mcp/src/engine/engine-slots.ts
+//
+// Machine-wide (per-user) semaphore bounding how many CE.SDK engines boot
+// concurrently across ALL independent codesign-mcp stdio processes. Each engine
+// costs ~82 MB idle / 200-300 MB active, so a handful stacked across parallel
+// sessions can OOM the machine (CODE-59). No in-process cap can bound the total —
+// each stdio server is its own process with its own singleton engine — so the
+// coordination point lives on the filesystem.
+//
+// Mechanism: N slot files slot-0..slot-(N-1) under ~/.codesign/engine-slots. A
+// slot is claimed by atomically creating its file with O_EXCL (open(path,'wx')).
+// The file records the owner PID; a slot whose PID is dead (process.kill(pid,0)
+// -> ESRCH) is reclaimed on the next acquire — the backstop for SIGKILL, where
+// the clean release path (CODE-53 shutdown) never runs. Reclaim renames the
+// stale file to a per-PID tombstone; rename() requires the source to exist, so
+// only one concurrent reclaimer of the SAME stale file wins (losers get ENOENT
+// and re-loop to see the new owner). Clean release unlinks.
+//
+// Scope: the slot dir is under the user's home, so the cap is really per-user —
+// which matches the OOM scenario (one user's many parallel sessions).
+//
+// Known limitations — both narrow, both at worst a TRANSIENT over-provision by
+// ~1 (never the unbounded, dozens-of-engines OOM this prevents), self-correcting
+// on process exit. Neither is fixable with portable fs primitives: O_EXCL create
+// is the only atomic mutual-exclusion primitive, and it cannot reclaim an
+// already-occupied name, so every content-blind removal (unlink OR rename) has a
+// TOCTOU. A single-process broker (the deferred "Approach C") is the real fix if
+// hard multi-process correctness is ever required.
+//   1. PID reuse: a dead owner's PID could be recycled by an unrelated live
+//      process, making a stale slot look alive until that PID exits.
+//   2. Concurrent-reclaim straggler: rename() is content-blind, so if reclaimer
+//      B's rename syscall lags reclaimer A's full reclaim+recreate cycle, B's
+//      rename can steal A's already-recreated FRESH file and both end up owning
+//      the slot. rename() closes the common simultaneous case; this residual
+//      needs adversarial sub-millisecond syscall reordering across processes.
+// (A tombstone orphaned by SIGKILL between rename and its cleanup unlink is inert
+// litter — acquire only ever touches exact `slot-<i>` paths, never `*.dead.*`.)
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { EngineCapacityError } from './engine-capacity.js';
+const DEFAULT_SLOT_DIR = join(homedir(), '.codesign', 'engine-slots');
+/**
+ * True if a process with `pid` is alive. `kill(pid, 0)` sends no signal; it only
+ * probes. ESRCH => no such process (dead). EPERM (exists, another user) or any
+ * other error => assume alive (conservative — never steal a slot we're unsure of).
+ */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+/**
+ * Claim one of `max` numbered slots. Returns a handle for the first free (or
+ * reclaimable-stale) slot, or null when all `max` are held by live owners.
+ */
+export async function acquireEngineSlot(opts) {
+    const dir = opts.dir ?? DEFAULT_SLOT_DIR;
+    const alive = opts.isPidAlive ?? isPidAlive;
+    const pid = opts.pid ?? process.pid;
+    await mkdir(dir, { recursive: true });
+    for (let i = 0; i < opts.max; i++) {
+        const handle = await tryClaimSlot(join(dir, `slot-${i}`), i, pid, alive);
+        if (handle)
+            return handle;
+    }
+    return null;
+}
+async function tryClaimSlot(path, index, pid, alive) {
+    // Two attempts: create; if occupied-but-dead, reclaim and retry the create.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fh = await open(path, 'wx'); // O_CREAT | O_EXCL — atomic claim
+            try {
+                await fh.writeFile(JSON.stringify({ pid, bootedAt: Date.now() }));
+            }
+            finally {
+                await fh.close();
+            }
+            return makeHandle(path, index);
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (!(await ownerIsDead(path, alive)))
+                return null; // held by a live owner
+            // Reclaim atomically: rename the stale file aside. rename() requires the
+            // source to exist, so only ONE concurrent reclaimer of the same slot
+            // succeeds; the losers get ENOENT and re-loop to see the new owner. An
+            // unconditional unlink+recreate would instead let a second reclaimer
+            // delete the first's fresh file and double-occupy the slot.
+            const tomb = `${path}.dead.${pid}`;
+            try {
+                await rename(path, tomb);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    continue; // lost the reclaim; retry the slot
+                throw e;
+            }
+            await unlink(tomb).catch(() => { }); // best-effort tombstone cleanup
+            // slot path is now free; loop retries the exclusive create
+        }
+    }
+    return null; // lost the reclaim race — treat as taken, move on
+}
+/**
+ * Is the slot file's recorded owner provably dead? Only a slot with a readable,
+ * valid PID that is not alive is reclaimable. Empty/malformed/unreadable => treat
+ * as ALIVE (return false) so we never steal a slot a peer just created with
+ * O_EXCL but has not finished writing yet.
+ */
+async function ownerIsDead(path, alive) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let pid;
+    try {
+        pid = JSON.parse(raw).pid;
+    }
+    catch {
+        return false;
+    }
+    return typeof pid === 'number' && !alive(pid);
+}
+function makeHandle(path, index) {
+    let released = false;
+    return {
+        index,
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            await unlink(path).catch(() => { }); // ENOENT etc. — best-effort
+        }
+    };
+}
+export function createSlotGatedEngine(opts) {
+    const acquire = opts.acquire ?? acquireEngineSlot;
+    let engine;
+    let handle;
+    const boot = async () => {
+        const h = await acquire({
+            max: opts.max,
+            ...(opts.dir !== undefined ? { dir: opts.dir } : {})
+        });
+        if (!h) {
+            engine = undefined; // capacity is retryable — don't memoize the rejection
+            throw new EngineCapacityError(opts.max);
+        }
+        handle = h;
+        try {
+            return await opts.boot();
+        }
+        catch (err) {
+            // Hard init failure: free the slot (don't hold it for a dead engine). Keep
+            // the rejected memo so retries don't churn slots on a permanent failure.
+            await h.release().catch(() => { });
+            handle = undefined;
+            throw err;
+        }
+    };
+    return {
+        get: () => (engine ??= boot()),
+        release: async () => {
+            const h = handle;
+            handle = undefined;
+            engine = undefined;
+            if (h)
+                await h.release();
+        }
+    };
+}
+//# sourceMappingURL=engine-slots.js.map

package/dist/engine/engine-slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-slots.js","sourceRoot":"","sources":["../../src/engine/engine-slots.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/engine/engine-slots.ts\n//\n// Machine-wide (per-user) semaphore bounding how many CE.SDK engines boot\n// concurrently across ALL independent codesign-mcp stdio processes. Each engine\n// costs ~82 MB idle / 200-300 MB active, so a handful stacked across parallel\n// sessions can OOM the machine (CODE-59). No in-process cap can bound the total —\n// each stdio server is its own process with its own singleton engine — so the\n// coordination point lives on the filesystem.\n//\n// Mechanism: N slot files slot-0..slot-(N-1) under ~/.codesign/engine-slots. A\n// slot is claimed by atomically creating its file with O_EXCL (open(path,'wx')).\n// The file records the owner PID; a slot whose PID is dead (process.kill(pid,0)\n// -> ESRCH) is reclaimed on the next acquire — the backstop for SIGKILL, where\n// the clean release path (CODE-53 shutdown) never runs. Reclaim renames the\n// stale file to a per-PID tombstone; rename() requires the source to exist, so\n// only one concurrent reclaimer of the SAME stale file wins (losers get ENOENT\n// and re-loop to see the new owner). Clean release unlinks.\n//\n// Scope: the slot dir is under the user's home, so the cap is really per-user —\n// which matches the OOM scenario (one user's many parallel sessions).\n//\n// Known limitations — both narrow, both at worst a TRANSIENT over-provision by\n// ~1 (never the unbounded, dozens-of-engines OOM this prevents), self-correcting\n// on process exit. Neither is fixable with portable fs primitives: O_EXCL create\n// is the only atomic mutual-exclusion primitive, and it cannot reclaim an\n// already-occupied name, so every content-blind removal (unlink OR rename) has a\n// TOCTOU. A single-process broker (the deferred \"Approach C\") is the real fix if\n// hard multi-process correctness is ever required.\n//   1. PID reuse: a dead owner's PID could be recycled by an unrelated live\n//      process, making a stale slot look alive until that PID exits.\n//   2. Concurrent-reclaim straggler: rename() is content-blind, so if reclaimer\n//      B's rename syscall lags reclaimer A's full reclaim+recreate cycle, B's\n//      rename can steal A's already-recreated FRESH file and both end up owning\n//      the slot. rename() closes the common simultaneous case; this residual\n//      needs adversarial sub-millisecond syscall reordering across processes.\n// (A tombstone orphaned by SIGKILL between rename and its cleanup unlink is inert\n// litter — acquire only ever touches exact `slot-<i>` paths, never `*.dead.*`.)\nimport { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { EngineCapacityError } from './engine-capacity.js';\n\nconst DEFAULT_SLOT_DIR = join(homedir(), '.codesign', 'engine-slots');\n\nexport interface SlotHandle {\n  /** Which numbered slot (0-based) this handle owns. */\n  readonly index: number;\n  /** Release the slot (unlink its file). Idempotent; best-effort. */\n  release(): Promise<void>;\n}\n\nexport interface AcquireEngineSlotOptions {\n  /** Max concurrent engines. The (max)th acquire succeeds; the (max+1)th returns null. */\n  max: number;\n  /** Slot directory. Defaults to ~/.codesign/engine-slots. Override in tests. */\n  dir?: string;\n  /** Liveness probe for a slot's owner PID. Defaults to a real kill(pid,0). Injectable for tests. */\n  isPidAlive?: (pid: number) => boolean;\n  /** This process's PID, recorded in the claimed slot. Defaults to process.pid. */\n  pid?: number;\n}\n\n/**\n * True if a process with `pid` is alive. `kill(pid, 0)` sends no signal; it only\n * probes. ESRCH => no such process (dead). EPERM (exists, another user) or any\n * other error => assume alive (conservative — never steal a slot we're unsure of).\n */\nexport function isPidAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    return (err as NodeJS.ErrnoException).code !== 'ESRCH';\n  }\n}\n\n/**\n * Claim one of `max` numbered slots. Returns a handle for the first free (or\n * reclaimable-stale) slot, or null when all `max` are held by live owners.\n */\nexport async function acquireEngineSlot(\n  opts: AcquireEngineSlotOptions\n): Promise<SlotHandle | null> {\n  const dir = opts.dir ?? DEFAULT_SLOT_DIR;\n  const alive = opts.isPidAlive ?? isPidAlive;\n  const pid = opts.pid ?? process.pid;\n  await mkdir(dir, { recursive: true });\n  for (let i = 0; i < opts.max; i++) {\n    const handle = await tryClaimSlot(join(dir, `slot-${i}`), i, pid, alive);\n    if (handle) return handle;\n  }\n  return null;\n}\n\nasync function tryClaimSlot(\n  path: string,\n  index: number,\n  pid: number,\n  alive: (pid: number) => boolean\n): Promise<SlotHandle | null> {\n  // Two attempts: create; if occupied-but-dead, reclaim and retry the create.\n  for (let attempt = 0; attempt < 2; attempt++) {\n    try {\n      const fh = await open(path, 'wx'); // O_CREAT | O_EXCL — atomic claim\n      try {\n        await fh.writeFile(JSON.stringify({ pid, bootedAt: Date.now() }));\n      } finally {\n        await fh.close();\n      }\n      return makeHandle(path, index);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;\n      if (!(await ownerIsDead(path, alive))) return null; // held by a live owner\n      // Reclaim atomically: rename the stale file aside. rename() requires the\n      // source to exist, so only ONE concurrent reclaimer of the same slot\n      // succeeds; the losers get ENOENT and re-loop to see the new owner. An\n      // unconditional unlink+recreate would instead let a second reclaimer\n      // delete the first's fresh file and double-occupy the slot.\n      const tomb = `${path}.dead.${pid}`;\n      try {\n        await rename(path, tomb);\n      } catch (e) {\n        if ((e as NodeJS.ErrnoException).code === 'ENOENT') continue; // lost the reclaim; retry the slot\n        throw e;\n      }\n      await unlink(tomb).catch(() => {}); // best-effort tombstone cleanup\n      // slot path is now free; loop retries the exclusive create\n    }\n  }\n  return null; // lost the reclaim race — treat as taken, move on\n}\n\n/**\n * Is the slot file's recorded owner provably dead? Only a slot with a readable,\n * valid PID that is not alive is reclaimable. Empty/malformed/unreadable => treat\n * as ALIVE (return false) so we never steal a slot a peer just created with\n * O_EXCL but has not finished writing yet.\n */\nasync function ownerIsDead(\n  path: string,\n  alive: (pid: number) => boolean\n): Promise<boolean> {\n  let raw: string;\n  try {\n    raw = await readFile(path, 'utf8');\n  } catch {\n    return false;\n  }\n  let pid: unknown;\n  try {\n    pid = (JSON.parse(raw) as { pid?: unknown }).pid;\n  } catch {\n    return false;\n  }\n  return typeof pid === 'number' && !alive(pid);\n}\n\nfunction makeHandle(path: string, index: number): SlotHandle {\n  let released = false;\n  return {\n    index,\n    release: async () => {\n      if (released) return;\n      released = true;\n      await unlink(path).catch(() => {}); // ENOENT etc. — best-effort\n    }\n  };\n}\n\n// ── Slot-gated lazy engine ──────────────────────────────────────────────────\n\nexport interface SlotGatedEngine<E> {\n  /**\n   * Boot the engine on first call, gated by a machine-wide slot. Memoized: later\n   * calls return the same engine. Throws EngineCapacityError at capacity (the\n   * memo is NOT cached, so a later retry re-attempts). A boot FAILURE is cached\n   * (a hard init error must not churn slots on retry) and its slot is released.\n   */\n  get(): Promise<E>;\n  /** Release the held slot (for the clean-shutdown path). Idempotent. */\n  release(): Promise<void>;\n}\n\nexport function createSlotGatedEngine<E>(opts: {\n  max: number;\n  boot: () => Promise<E>;\n  dir?: string;\n  acquire?: (o: { max: number; dir?: string }) => Promise<SlotHandle | null>;\n}): SlotGatedEngine<E> {\n  const acquire = opts.acquire ?? acquireEngineSlot;\n  let engine: Promise<E> | undefined;\n  let handle: SlotHandle | undefined;\n\n  const boot = async (): Promise<E> => {\n    const h = await acquire({\n      max: opts.max,\n      ...(opts.dir !== undefined ? { dir: opts.dir } : {})\n    });\n    if (!h) {\n      engine = undefined; // capacity is retryable — don't memoize the rejection\n      throw new EngineCapacityError(opts.max);\n    }\n    handle = h;\n    try {\n      return await opts.boot();\n    } catch (err) {\n      // Hard init failure: free the slot (don't hold it for a dead engine). Keep\n      // the rejected memo so retries don't churn slots on a permanent failure.\n      await h.release().catch(() => {});\n      handle = undefined;\n      throw err;\n    }\n  };\n\n  return {\n    get: () => (engine ??= boot()),\n    release: async () => {\n      const h = handle;\n      handle = undefined;\n      engine = undefined;\n      if (h) await h.release();\n    }\n  };\n}\n"]}

package/dist/engine/uri-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"uri-resolver.js","sourceRoot":"","sources":["../../src/engine/uri-resolver.ts"],"names":[],"mappings":"AAOA,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAc5C;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA2B,EAC3B,UAA4B;IAE5B,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,CACpD,GAAG,CAAC,UAAU,CAAC,oBAAoB,CAAC;QAClC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAChE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CACzB,CAAC;AACJ,CAAC","sourcesContent":["//\n// Registers a CE.SDK URI resolver that rewrites `workspace://<relpath>` asset\n// URIs (stored durably in scenes) to the HTTP `/r/` URL the engine can fetch.\n// Everything else delegates to CE.SDK's default resolver. Used by the headless\n// node engine; the browser viewer mirrors this logic in viewer.js.\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\n\nconst WORKSPACE_URI_PREFIX = 'workspace://';\n\n/** The minimal slice of CreativeEngine this module needs — keeps it testable. */\nexport interface UriResolvableEngine {\n  editor: {\n    setURIResolver(\n      resolver: (\n        uri: string,\n        defaultResolver: (uri: string) => string\n      ) => string\n    ): void;\n  };\n}\n\n/**\n * Make the engine resolve `workspace://…` asset URIs to the `/r/` HTTP route.\n * Scenes persist the durable `workspace://` form; this rewrites it to a live\n * fetch URL at load time, so a design survives a process restart / rewind.\n */\nexport function registerWorkspaceUriResolver(\n  engine: UriResolvableEngine,\n  urlBuilder: ViewerUrlBuilder\n): void {\n  engine.editor.setURIResolver((uri, defaultResolver) =>\n    uri.startsWith(WORKSPACE_URI_PREFIX)\n      ? urlBuilder.forResource(uri.slice(WORKSPACE_URI_PREFIX.length))\n      : defaultResolver(uri)\n  );\n}\n"]}
+{"version":3,"file":"uri-resolver.js","sourceRoot":"","sources":["../../src/engine/uri-resolver.ts"],"names":[],"mappings":"AAOA,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAc5C;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA2B,EAC3B,UAA4B;IAE5B,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,CACpD,GAAG,CAAC,UAAU,CAAC,oBAAoB,CAAC;QAClC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAChE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CACzB,CAAC;AACJ,CAAC","sourcesContent":["//\n// Registers a CE.SDK URI resolver that rewrites `workspace://<relpath>` asset\n// URIs (stored durably in scenes) to the HTTP `/r/` URL the engine can fetch.\n// Everything else delegates to CE.SDK's default resolver. Used by the headless\n// node engine; the browser editor mirrors this logic in editor.js.\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\n\nconst WORKSPACE_URI_PREFIX = 'workspace://';\n\n/** The minimal slice of CreativeEngine this module needs — keeps it testable. */\nexport interface UriResolvableEngine {\n  editor: {\n    setURIResolver(\n      resolver: (\n        uri: string,\n        defaultResolver: (uri: string) => string\n      ) => string\n    ): void;\n  };\n}\n\n/**\n * Make the engine resolve `workspace://…` asset URIs to the `/r/` HTTP route.\n * Scenes persist the durable `workspace://` form; this rewrites it to a live\n * fetch URL at load time, so a design survives a process restart / rewind.\n */\nexport function registerWorkspaceUriResolver(\n  engine: UriResolvableEngine,\n  urlBuilder: ViewerUrlBuilder\n): void {\n  engine.editor.setURIResolver((uri, defaultResolver) =>\n    uri.startsWith(WORKSPACE_URI_PREFIX)\n      ? urlBuilder.forResource(uri.slice(WORKSPACE_URI_PREFIX.length))\n      : defaultResolver(uri)\n  );\n}\n"]}

package/dist/server.d.ts

@@ -22,6 +22,29 @@ export interface CodesignMcpToolRegistration {
         isError?: boolean;
     }>;
 }
+/**
+ * One prompt (slash command) the server exposes via prompts/list +
+ * prompts/get. Mirrors `CodesignMcpToolRegistration`'s caller-supplied shape.
+ */
+export interface CodesignMcpPromptRegistration {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    get: (args: Record<string, string> | undefined) => {
+        description?: string;
+        messages: Array<{
+            role: 'user' | 'assistant';
+            content: {
+                type: 'text';
+                text: string;
+            };
+        }>;
+    };
+}
 export interface CodesignMcpServerOptions {
     /**
      * Asset bundle. Keys are forward-slash paths under one of:
@@ -34,6 +57,8 @@ export interface CodesignMcpServerOptions {
     resourceScheme?: string;
     /** Tools to expose via tools/list + tools/call. */
     tools?: CodesignMcpToolRegistration[];
+    /** MCP prompts (slash commands). Advertised only when at least one is passed. */
+    prompts?: CodesignMcpPromptRegistration[];
     /**
      * Build identity reported as `serverInfo.version` on `initialize`. A client
      * (the deploy smoketest) can assert it to confirm it's talking to the

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;QAC/B,OAAO,EAAE,KAAK,CACV;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAC9B;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CACpD,CAAC;QACF,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,2BAA2B,EAAE,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,MAAM,CAmIR"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAcnE;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;QAC/B,OAAO,EAAE,KAAK,CACV;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAC9B;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CACpD,CAAC;QACF,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,KAAK;QACjD,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;YAC3B,OAAO,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,CAAC;SACzC,CAAC,CAAC;KACJ,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,2BAA2B,EAAE,CAAC;IACtC,iFAAiF;IACjF,OAAO,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAC1C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,MAAM,CA2JR"}

package/dist/server.js

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { rewriteSkillLinks } from './cross-ref.js';
 import { buildSkillReadTools } from './skill-tools.js';
 const DOC_FILE = /^docs\/([^/]+)\/(.+)$/;
@@ -31,7 +31,7 @@ export function createCodesignMcpServer(opts) {
         '',
         'Design tools (after reading the handbook):',
         '- `edit({ parent, code, title?, note? })` — mutate the canvas; `parent` is REQUIRED (revision id, or null for a new design).',
-        '- `preview({ blockId, revision? })` — render a block to an inline image.',
+        '- `preview({ blockId, revision })` — render a block to an inline image. `revision` is required (the id `edit` returned).',
         '- `export({ target, format, revision, blockId })` — render a block to pdf/image and write it into the workspace.',
         '- `save({ revision, outPath? })` — write a self-contained `.zip` archive (scene + assets) of a revision into the workspace.',
         '',
@@ -40,7 +40,7 @@ export function createCodesignMcpServer(opts) {
         '- `history({ revision })` — walk back to the root; how you re-ground after a rewind.',
         '- `inspect({ revision })` — read one revision in full, including the code that produced it (patterns, not block ids).',
         '- `rename({ revision, title })` — rename a design.',
-        '- `open_editor({ revision? })` — URL the human can open to view the design.',
+        '- `view({ revision })` — URL the human can open to view the design.',
         '- `asset_search({ sourceId?, query? })` — browse asset sources; apply results in `edit`.'
     ]
         .concat(hasAssetGenerate
@@ -64,7 +64,11 @@ export function createCodesignMcpServer(opts) {
         rewrittenContent.set(uri, rewriteSkillLinks(content, doc, scheme));
     }
     const server = new Server({ name: 'codesign', version: opts.buildId ?? 'dev' }, {
-        capabilities: { resources: {}, tools: {} },
+        capabilities: {
+            resources: {},
+            tools: {},
+            ...(opts.prompts && opts.prompts.length > 0 ? { prompts: {} } : {})
+        },
         instructions
     });
     // `resources/list` advertises only the per-skill SKILL.md (the entry
@@ -114,6 +118,22 @@ export function createCodesignMcpServer(opts) {
         }
         return await t.call(req.params.arguments ?? {});
     });
+    if (opts.prompts && opts.prompts.length > 0) {
+        const prompts = new Map(opts.prompts.map((p) => [p.name, p]));
+        server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: Array.from(prompts.values()).map((p) => ({
+                name: p.name,
+                ...(p.description ? { description: p.description } : {}),
+                ...(p.arguments ? { arguments: p.arguments } : {})
+            }))
+        }));
+        server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+            const p = prompts.get(req.params.name);
+            if (!p)
+                throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${req.params.name}`);
+            return p.get(req.params.arguments);
+        });
+    }
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport {\n  CallToolRequestSchema,\n  ErrorCode,\n  ListResourcesRequestSchema,\n  ListToolsRequestSchema,\n  McpError,\n  ReadResourceRequestSchema\n} from '@modelcontextprotocol/sdk/types.js';\nimport { rewriteSkillLinks } from './cross-ref.js';\nimport { buildSkillReadTools } from './skill-tools.js';\n\n/**\n * One tool the server exposes via tools/list + tools/call. Caller-supplied so\n * the engine-bound implementations live near the surface that owns the engine\n * (the demo passes its existing `createDesignTools` output adapted to this\n * shape; an external bootstrap could pass server-side equivalents).\n */\nexport interface CodesignMcpToolRegistration {\n  name: string;\n  description?: string;\n  /** JSON Schema describing the tool's input arguments. */\n  inputSchema: unknown;\n  call: (args: unknown) => Promise<{\n    content: Array<\n      | { type: 'text'; text: string }\n      | { type: 'image'; data: string; mimeType: string }\n    >;\n    isError?: boolean;\n  }>;\n}\n\nexport interface CodesignMcpServerOptions {\n  /**\n   * Asset bundle. Keys are forward-slash paths under one of:\n   *   \"docs/<doc>/SKILL.md\"          — entry point for handbook / api / guide\n   *   \"docs/<doc>/<file>\"            — sub-files reachable via the doc tools\n   * Values are file contents.\n   */\n  assets: Record<string, string>;\n  /** URI scheme for resources. Default: \"codesign\". */\n  resourceScheme?: string;\n  /** Tools to expose via tools/list + tools/call. */\n  tools?: CodesignMcpToolRegistration[];\n  /**\n   * Build identity reported as `serverInfo.version` on `initialize`. A client\n   * (the deploy smoketest) can assert it to confirm it's talking to the\n   * just-deployed build, not a stale container. Default `'dev'`.\n   */\n  buildId?: string;\n}\n\nconst DOC_FILE = /^docs\\/([^/]+)\\/(.+)$/;\n\nexport function createCodesignMcpServer(\n  opts: CodesignMcpServerOptions\n): Server {\n  const scheme = opts.resourceScheme ?? 'codesign';\n  const assets = opts.assets;\n\n  // `instructions` is intentionally short — it tells the model what the\n  // server is and STRONGLY directs it to call `codesign_read_codesign_system`\n  // before its first edit. Skills are now first-class tools (not MCP\n  // resources buried in an XML block), so discovery happens via tools/list\n  // on every host without needing ReadMcpResourceTool support.\n  //\n  // Why short: Claude Code wraps MCP `instructions` in a <system-reminder>\n  // and truncates long ones mid-stream. Keeping `instructions` under ~1.5 KB\n  // ensures the whole pointer survives any sane truncation.\n  //\n  // The asset-generation hint is included only when an `asset_generate` tool\n  // is actually registered (Local hides it without an API_KEY), so we never\n  // advertise a tool the model can't see in tools/list.\n  const hasAssetGenerate = (opts.tools ?? []).some(\n    (t) => t.name === 'asset_generate'\n  );\n  const instructions = [\n    'This is the **codesign** MCP server. It hosts a CE.SDK CreativeEngine and a persistent design workspace (revision DAG) for vector design + print-quality PDF output.',\n    '',\n    '**Required first step** — before any `edit`, call `handbook` (no args). It teaches the mandatory `parent` argument, dirty-on-throw safety, rewind recovery via `list`/`history`, the typeface schema setFont requires, and the runtime quirks that bite first attempts. Skipping it produces broken output.',\n    '',\n    'Reference docs, on demand:',\n    '- `api({ path?, offset?, limit? })` — CE.SDK TypeScript signatures.',\n    '- `guide({ path? })` — CE.SDK Vanilla JS reference docs / topic guides.',\n    '',\n    'Design tools (after reading the handbook):',\n    '- `edit({ parent, code, title?, note? })` — mutate the canvas; `parent` is REQUIRED (revision id, or null for a new design).',\n    '- `preview({ blockId, revision? })` — render a block to an inline image.',\n    '- `export({ target, format, revision, blockId })` — render a block to pdf/image and write it into the workspace.',\n    '- `save({ revision, outPath? })` — write a self-contained `.zip` archive (scene + assets) of a revision into the workspace.',\n    '',\n    'Workspace tools (for resuming + navigating across designs):',\n    '- `list()` — every design in the workspace, newest first.',\n    '- `history({ revision })` — walk back to the root; how you re-ground after a rewind.',\n    '- `inspect({ revision })` — read one revision in full, including the code that produced it (patterns, not block ids).',\n    '- `rename({ revision, title })` — rename a design.',\n    '- `open_editor({ revision? })` — URL the human can open to view the design.',\n    '- `asset_search({ sourceId?, query? })` — browse asset sources; apply results in `edit`.'\n  ]\n    .concat(\n      hasAssetGenerate\n        ? [\n            '',\n            'Asset generation:',\n            \"- `asset_generate({ kind: 'image', prompt, width?, height? })` — opt-in (Local needs API_KEY); Hosted is cost-gated.\"\n          ]\n        : []\n    )\n    .join('\\n');\n\n  // Build the resource map up-front: URI → rewritten markdown body. Cross-refs\n  // inside doc content are rewritten to absolute MCP URIs so the model never\n  // has to resolve a relative path against a doc dir.\n  const rewrittenContent = new Map<string, string>();\n  for (const [key, content] of Object.entries(assets)) {\n    const m = key.match(DOC_FILE);\n    if (!m) continue;\n    const [, doc, rest] = m;\n    const uri = `${scheme}://docs/${doc}/${rest}`;\n    rewrittenContent.set(uri, rewriteSkillLinks(content, doc, scheme));\n  }\n\n  const server = new Server(\n    { name: 'codesign', version: opts.buildId ?? 'dev' },\n    {\n      capabilities: { resources: {}, tools: {} },\n      instructions\n    }\n  );\n\n  // `resources/list` advertises only the per-skill SKILL.md (the entry\n  // point), not the 392 nested cesdk-guide files. Sub-files stay readable\n  // via `resources/read` against any cached URI, but skill content discovery\n  // happens through the codesign_read_* tools — those are the universal\n  // surface across MCP hosts.\n  server.setRequestHandler(ListResourcesRequestSchema, async () => ({\n    resources: Array.from(rewrittenContent.keys())\n      .filter((uri) => uri.endsWith('/SKILL.md'))\n      .map((uri) => ({\n        uri,\n        mimeType: 'text/markdown',\n        name: uri.replace(`${scheme}://`, '')\n      }))\n  }));\n\n  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {\n    const text = rewrittenContent.get(req.params.uri);\n    if (text === undefined) {\n      throw new McpError(\n        ErrorCode.InvalidParams,\n        `Unknown resource: ${req.params.uri}`\n      );\n    }\n    return {\n      contents: [{ uri: req.params.uri, mimeType: 'text/markdown', text }]\n    };\n  });\n\n  // Tools registered with the server: caller-supplied design tools + the\n  // auto-generated skill-read tools (one per skill in the asset bundle).\n  // The skill tools always come first so Level 1 wording in the design tool\n  // descriptions (\"call codesign_read_codesign_system first\") points at\n  // something the model already sees in tools/list.\n  const tools = new Map<string, CodesignMcpToolRegistration>();\n  for (const t of buildSkillReadTools(assets)) tools.set(t.name, t);\n  for (const t of opts.tools ?? []) tools.set(t.name, t);\n\n  server.setRequestHandler(ListToolsRequestSchema, async () => ({\n    tools: Array.from(tools.values()).map((t) => ({\n      name: t.name,\n      description: t.description,\n      inputSchema: t.inputSchema as never\n    }))\n  }));\n\n  server.setRequestHandler(CallToolRequestSchema, async (req) => {\n    const t = tools.get(req.params.name);\n    if (!t) {\n      throw new McpError(\n        ErrorCode.InvalidParams,\n        `Unknown tool: ${req.params.name}`\n      );\n    }\n    return await t.call(req.params.arguments ?? {});\n  });\n\n  return server;\n}\n"]}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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","sourcesContent":["import { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport {\n  CallToolRequestSchema,\n  ErrorCode,\n  GetPromptRequestSchema,\n  ListPromptsRequestSchema,\n  ListResourcesRequestSchema,\n  ListToolsRequestSchema,\n  McpError,\n  ReadResourceRequestSchema\n} from '@modelcontextprotocol/sdk/types.js';\nimport { rewriteSkillLinks } from './cross-ref.js';\nimport { buildSkillReadTools } from './skill-tools.js';\n\n/**\n * One tool the server exposes via tools/list + tools/call. Caller-supplied so\n * the engine-bound implementations live near the surface that owns the engine\n * (the demo passes its existing `createDesignTools` output adapted to this\n * shape; an external bootstrap could pass server-side equivalents).\n */\nexport interface CodesignMcpToolRegistration {\n  name: string;\n  description?: string;\n  /** JSON Schema describing the tool's input arguments. */\n  inputSchema: unknown;\n  call: (args: unknown) => Promise<{\n    content: Array<\n      | { type: 'text'; text: string }\n      | { type: 'image'; data: string; mimeType: string }\n    >;\n    isError?: boolean;\n  }>;\n}\n\n/**\n * One prompt (slash command) the server exposes via prompts/list +\n * prompts/get. Mirrors `CodesignMcpToolRegistration`'s caller-supplied shape.\n */\nexport interface CodesignMcpPromptRegistration {\n  name: string;\n  description?: string;\n  arguments?: Array<{\n    name: string;\n    description?: string;\n    required?: boolean;\n  }>;\n  get: (args: Record<string, string> | undefined) => {\n    description?: string;\n    messages: Array<{\n      role: 'user' | 'assistant';\n      content: { type: 'text'; text: string };\n    }>;\n  };\n}\n\nexport interface CodesignMcpServerOptions {\n  /**\n   * Asset bundle. Keys are forward-slash paths under one of:\n   *   \"docs/<doc>/SKILL.md\"          — entry point for handbook / api / guide\n   *   \"docs/<doc>/<file>\"            — sub-files reachable via the doc tools\n   * Values are file contents.\n   */\n  assets: Record<string, string>;\n  /** URI scheme for resources. Default: \"codesign\". */\n  resourceScheme?: string;\n  /** Tools to expose via tools/list + tools/call. */\n  tools?: CodesignMcpToolRegistration[];\n  /** MCP prompts (slash commands). Advertised only when at least one is passed. */\n  prompts?: CodesignMcpPromptRegistration[];\n  /**\n   * Build identity reported as `serverInfo.version` on `initialize`. A client\n   * (the deploy smoketest) can assert it to confirm it's talking to the\n   * just-deployed build, not a stale container. Default `'dev'`.\n   */\n  buildId?: string;\n}\n\nconst DOC_FILE = /^docs\\/([^/]+)\\/(.+)$/;\n\nexport function createCodesignMcpServer(\n  opts: CodesignMcpServerOptions\n): Server {\n  const scheme = opts.resourceScheme ?? 'codesign';\n  const assets = opts.assets;\n\n  // `instructions` is intentionally short — it tells the model what the\n  // server is and STRONGLY directs it to call `codesign_read_codesign_system`\n  // before its first edit. Skills are now first-class tools (not MCP\n  // resources buried in an XML block), so discovery happens via tools/list\n  // on every host without needing ReadMcpResourceTool support.\n  //\n  // Why short: Claude Code wraps MCP `instructions` in a <system-reminder>\n  // and truncates long ones mid-stream. Keeping `instructions` under ~1.5 KB\n  // ensures the whole pointer survives any sane truncation.\n  //\n  // The asset-generation hint is included only when an `asset_generate` tool\n  // is actually registered (Local hides it without an API_KEY), so we never\n  // advertise a tool the model can't see in tools/list.\n  const hasAssetGenerate = (opts.tools ?? []).some(\n    (t) => t.name === 'asset_generate'\n  );\n  const instructions = [\n    'This is the **codesign** MCP server. It hosts a CE.SDK CreativeEngine and a persistent design workspace (revision DAG) for vector design + print-quality PDF output.',\n    '',\n    '**Required first step** — before any `edit`, call `handbook` (no args). It teaches the mandatory `parent` argument, dirty-on-throw safety, rewind recovery via `list`/`history`, the typeface schema setFont requires, and the runtime quirks that bite first attempts. Skipping it produces broken output.',\n    '',\n    'Reference docs, on demand:',\n    '- `api({ path?, offset?, limit? })` — CE.SDK TypeScript signatures.',\n    '- `guide({ path? })` — CE.SDK Vanilla JS reference docs / topic guides.',\n    '',\n    'Design tools (after reading the handbook):',\n    '- `edit({ parent, code, title?, note? })` — mutate the canvas; `parent` is REQUIRED (revision id, or null for a new design).',\n    '- `preview({ blockId, revision })` — render a block to an inline image. `revision` is required (the id `edit` returned).',\n    '- `export({ target, format, revision, blockId })` — render a block to pdf/image and write it into the workspace.',\n    '- `save({ revision, outPath? })` — write a self-contained `.zip` archive (scene + assets) of a revision into the workspace.',\n    '',\n    'Workspace tools (for resuming + navigating across designs):',\n    '- `list()` — every design in the workspace, newest first.',\n    '- `history({ revision })` — walk back to the root; how you re-ground after a rewind.',\n    '- `inspect({ revision })` — read one revision in full, including the code that produced it (patterns, not block ids).',\n    '- `rename({ revision, title })` — rename a design.',\n    '- `view({ revision })` — URL the human can open to view the design.',\n    '- `asset_search({ sourceId?, query? })` — browse asset sources; apply results in `edit`.'\n  ]\n    .concat(\n      hasAssetGenerate\n        ? [\n            '',\n            'Asset generation:',\n            \"- `asset_generate({ kind: 'image', prompt, width?, height? })` — opt-in (Local needs API_KEY); Hosted is cost-gated.\"\n          ]\n        : []\n    )\n    .join('\\n');\n\n  // Build the resource map up-front: URI → rewritten markdown body. Cross-refs\n  // inside doc content are rewritten to absolute MCP URIs so the model never\n  // has to resolve a relative path against a doc dir.\n  const rewrittenContent = new Map<string, string>();\n  for (const [key, content] of Object.entries(assets)) {\n    const m = key.match(DOC_FILE);\n    if (!m) continue;\n    const [, doc, rest] = m;\n    const uri = `${scheme}://docs/${doc}/${rest}`;\n    rewrittenContent.set(uri, rewriteSkillLinks(content, doc, scheme));\n  }\n\n  const server = new Server(\n    { name: 'codesign', version: opts.buildId ?? 'dev' },\n    {\n      capabilities: {\n        resources: {},\n        tools: {},\n        ...(opts.prompts && opts.prompts.length > 0 ? { prompts: {} } : {})\n      },\n      instructions\n    }\n  );\n\n  // `resources/list` advertises only the per-skill SKILL.md (the entry\n  // point), not the 392 nested cesdk-guide files. Sub-files stay readable\n  // via `resources/read` against any cached URI, but skill content discovery\n  // happens through the codesign_read_* tools — those are the universal\n  // surface across MCP hosts.\n  server.setRequestHandler(ListResourcesRequestSchema, async () => ({\n    resources: Array.from(rewrittenContent.keys())\n      .filter((uri) => uri.endsWith('/SKILL.md'))\n      .map((uri) => ({\n        uri,\n        mimeType: 'text/markdown',\n        name: uri.replace(`${scheme}://`, '')\n      }))\n  }));\n\n  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {\n    const text = rewrittenContent.get(req.params.uri);\n    if (text === undefined) {\n      throw new McpError(\n        ErrorCode.InvalidParams,\n        `Unknown resource: ${req.params.uri}`\n      );\n    }\n    return {\n      contents: [{ uri: req.params.uri, mimeType: 'text/markdown', text }]\n    };\n  });\n\n  // Tools registered with the server: caller-supplied design tools + the\n  // auto-generated skill-read tools (one per skill in the asset bundle).\n  // The skill tools always come first so Level 1 wording in the design tool\n  // descriptions (\"call codesign_read_codesign_system first\") points at\n  // something the model already sees in tools/list.\n  const tools = new Map<string, CodesignMcpToolRegistration>();\n  for (const t of buildSkillReadTools(assets)) tools.set(t.name, t);\n  for (const t of opts.tools ?? []) tools.set(t.name, t);\n\n  server.setRequestHandler(ListToolsRequestSchema, async () => ({\n    tools: Array.from(tools.values()).map((t) => ({\n      name: t.name,\n      description: t.description,\n      inputSchema: t.inputSchema as never\n    }))\n  }));\n\n  server.setRequestHandler(CallToolRequestSchema, async (req) => {\n    const t = tools.get(req.params.name);\n    if (!t) {\n      throw new McpError(\n        ErrorCode.InvalidParams,\n        `Unknown tool: ${req.params.name}`\n      );\n    }\n    return await t.call(req.params.arguments ?? {});\n  });\n\n  if (opts.prompts && opts.prompts.length > 0) {\n    const prompts = new Map(opts.prompts.map((p) => [p.name, p]));\n    server.setRequestHandler(ListPromptsRequestSchema, async () => ({\n      prompts: Array.from(prompts.values()).map((p) => ({\n        name: p.name,\n        ...(p.description ? { description: p.description } : {}),\n        ...(p.arguments ? { arguments: p.arguments } : {})\n      }))\n    }));\n    server.setRequestHandler(GetPromptRequestSchema, async (req) => {\n      const p = prompts.get(req.params.name);\n      if (!p)\n        throw new McpError(\n          ErrorCode.InvalidParams,\n          `Unknown prompt: ${req.params.name}`\n        );\n      return p.get(req.params.arguments);\n    });\n  }\n\n  return server;\n}\n"]}