@ikenga/pkg-studio 0.2.0

package/mcp/dist/index.js

@@ -0,0 +1,1535 @@
+#!/usr/bin/env node
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/sidecar-client.ts
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve as resolvePath } from "node:path";
+function defaultSidecarPath() {
+  if (process.env.STUDIO_SIDECAR_PATH)
+    return process.env.STUDIO_SIDECAR_PATH;
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolvePath(here, "../../sidecars/project/dist/sidecar.js");
+}
+
+class SidecarUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SidecarUnavailableError";
+  }
+}
+
+class SidecarRpcError extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "SidecarRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+class SidecarClient {
+  child = null;
+  rl = null;
+  nextId = 1;
+  pending = new Map;
+  listeners = new Set;
+  respawnAttempts = 0;
+  respawning = false;
+  sidecarPath;
+  env;
+  maxRespawnAttempts;
+  deadReason = null;
+  shuttingDown = false;
+  constructor(opts = {}) {
+    this.sidecarPath = opts.sidecarPath ?? defaultSidecarPath();
+    this.env = { ...process.env, ...opts.env ?? {} };
+    this.maxRespawnAttempts = opts.maxRespawnAttempts ?? 3;
+  }
+  start() {
+    if (this.child)
+      return;
+    this.spawnChild();
+  }
+  onEvent(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+  async call(method, params, opts = {}) {
+    if (this.deadReason && !this.child) {
+      throw new SidecarUnavailableError(this.deadReason);
+    }
+    if (!this.child)
+      this.spawnChild();
+    const child = this.child;
+    if (!child || !child.stdin || child.stdin.destroyed) {
+      throw new SidecarUnavailableError("sidecar stdin not writable");
+    }
+    const id = this.nextId++;
+    const req = { jsonrpc: "2.0", id, method, params };
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`sidecar call '${method}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => resolve(v),
+        reject,
+        timer
+      });
+      try {
+        child.stdin.write(JSON.stringify(req) + `
+`);
+      } catch (e) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(new SidecarUnavailableError(`sidecar write failed: ${e.message}`));
+      }
+    });
+  }
+  async stop() {
+    this.shuttingDown = true;
+    if (!this.child)
+      return;
+    try {
+      this.child.stdin?.end();
+    } catch {}
+    await new Promise((resolve) => {
+      const t = setTimeout(() => {
+        try {
+          this.child?.kill("SIGTERM");
+        } catch {}
+        resolve();
+      }, 1500);
+      this.child?.once("exit", () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+  spawnChild() {
+    if (!existsSync(this.sidecarPath)) {
+      this.deadReason = `sidecar binary not found at ${this.sidecarPath}`;
+      process.stderr.write(`[studio-mcp] ${this.deadReason}
+`);
+      return;
+    }
+    process.stderr.write(`[studio-mcp] spawning sidecar: node ${this.sidecarPath}
+`);
+    const child = spawn(process.execPath, [this.sidecarPath], {
+      env: this.env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    this.child = child;
+    this.deadReason = null;
+    child.stderr?.on("data", (b) => {
+      process.stderr.write(b);
+    });
+    const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    this.rl = rl;
+    rl.on("line", (line) => {
+      const trimmed = line.trim();
+      if (!trimmed)
+        return;
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch {
+        process.stderr.write(`[studio-mcp] sidecar emitted non-JSON line: ${trimmed.slice(0, 200)}
+`);
+        return;
+      }
+      this.routeMessage(msg);
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`[studio-mcp] sidecar spawn error: ${err.message}
+`);
+    });
+    child.on("exit", (code, signal) => {
+      process.stderr.write(`[studio-mcp] sidecar exited code=${code} signal=${signal}
+`);
+      const reason = `sidecar exited (code=${code} signal=${signal})`;
+      for (const [, p] of this.pending) {
+        clearTimeout(p.timer);
+        p.reject(new SidecarUnavailableError(reason));
+      }
+      this.pending.clear();
+      this.child = null;
+      this.rl?.close();
+      this.rl = null;
+      if (this.shuttingDown)
+        return;
+      this.attemptRespawn();
+    });
+  }
+  routeMessage(msg) {
+    if ("method" in msg && msg.method === "event" && "params" in msg) {
+      const params = msg.params;
+      for (const l of this.listeners) {
+        try {
+          l(params);
+        } catch (err) {
+          process.stderr.write(`[studio-mcp] event listener threw: ${err.message}
+`);
+        }
+      }
+      return;
+    }
+    const resp = msg;
+    if (resp.id == null || typeof resp.id !== "number")
+      return;
+    const slot = this.pending.get(resp.id);
+    if (!slot)
+      return;
+    this.pending.delete(resp.id);
+    clearTimeout(slot.timer);
+    if (resp.error) {
+      slot.reject(new SidecarRpcError(resp.error.code, resp.error.message, resp.error.data));
+    } else {
+      slot.resolve(resp.result);
+    }
+  }
+  async attemptRespawn() {
+    if (this.respawning)
+      return;
+    this.respawning = true;
+    try {
+      while (this.respawnAttempts < this.maxRespawnAttempts) {
+        this.respawnAttempts++;
+        const backoff = Math.min(2000 * 2 ** (this.respawnAttempts - 1), 8000);
+        process.stderr.write(`[studio-mcp] sidecar respawn attempt ${this.respawnAttempts}/${this.maxRespawnAttempts} in ${backoff}ms
+`);
+        await new Promise((r) => setTimeout(r, backoff));
+        if (this.shuttingDown)
+          return;
+        this.spawnChild();
+        if (this.child) {
+          this.respawnAttempts = 0;
+          return;
+        }
+      }
+      this.deadReason = `sidecar respawn gave up after ${this.maxRespawnAttempts} attempts`;
+      process.stderr.write(`[studio-mcp] ${this.deadReason}
+`);
+    } finally {
+      this.respawning = false;
+    }
+  }
+}
+
+// src/catalog.ts
+import { existsSync as existsSync2, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { dirname as dirname2, join, resolve as resolvePath2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { createRequire } from "node:module";
+function studioPkgRoot() {
+  const here = dirname2(fileURLToPath2(import.meta.url));
+  return resolvePath2(here, "..", "..");
+}
+function resolveArchetypesPkgSkills() {
+  try {
+    const req = createRequire(import.meta.url);
+    const manifest = req.resolve("@ikenga/studio-archetypes/manifest.json");
+    return join(dirname2(manifest), "skills");
+  } catch {
+    return null;
+  }
+}
+function archetypeSkillRoots(pkgRoot = studioPkgRoot()) {
+  const roots = [];
+  const push = (dir) => {
+    if (dir && existsSync2(dir) && !roots.includes(dir))
+      roots.push(dir);
+  };
+  push(join(pkgRoot, "skills"));
+  push(resolveArchetypesPkgSkills());
+  push(resolvePath2(pkgRoot, "..", "..", "skills", "studio-archetypes", "skills"));
+  return roots;
+}
+function walkForFiles(root, filename, maxDepth = 6) {
+  const hits = [];
+  if (!existsSync2(root))
+    return hits;
+  function recurse(dir, depth) {
+    if (depth > maxDepth)
+      return;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(dir, e);
+      let s;
+      try {
+        s = statSync(full);
+      } catch {
+        continue;
+      }
+      if (s.isDirectory()) {
+        recurse(full, depth + 1);
+      } else if (s.isFile() && e === filename) {
+        hits.push(full);
+      }
+    }
+  }
+  recurse(root, 0);
+  return hits;
+}
+function safeParseJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    process.stderr.write(`[studio-mcp][catalog] failed to parse ${path}: ${e.message}
+`);
+    return null;
+  }
+}
+function loadBuiltinBlocks(pkgRoot = studioPkgRoot()) {
+  const entries = [];
+  const seen = new Set;
+  for (const skillsDir of archetypeSkillRoots(pkgRoot)) {
+    let skillNames;
+    try {
+      skillNames = readdirSync(skillsDir);
+    } catch {
+      continue;
+    }
+    for (const skill of skillNames) {
+      const blocksDir = join(skillsDir, skill, "blocks");
+      if (!existsSync2(blocksDir))
+        continue;
+      for (const file of walkForFiles(blocksDir, "block.json")) {
+        const body = safeParseJson(file);
+        if (!body)
+          continue;
+        const block_id = body.block_id ?? body.id;
+        if (!block_id || seen.has(block_id))
+          continue;
+        seen.add(block_id);
+        entries.push({
+          block_id,
+          kind: body.kind,
+          name: body.name,
+          tags: Array.isArray(body.tags) ? body.tags : undefined,
+          source: "builtin",
+          path: file,
+          body
+        });
+      }
+    }
+  }
+  return entries;
+}
+function loadBuiltinArchetypes(pkgRoot = studioPkgRoot()) {
+  const entries = [];
+  const seen = new Set;
+  for (const skillsDir of archetypeSkillRoots(pkgRoot)) {
+    let skillNames;
+    try {
+      skillNames = readdirSync(skillsDir);
+    } catch {
+      continue;
+    }
+    for (const skill of skillNames) {
+      if (!skill.startsWith("archetype-"))
+        continue;
+      const file = join(skillsDir, skill, "archetype.json");
+      if (!existsSync2(file))
+        continue;
+      const body = safeParseJson(file);
+      if (!body)
+        continue;
+      const archetype_id = body.archetype_id ?? body.id;
+      if (!archetype_id || seen.has(archetype_id))
+        continue;
+      seen.add(archetype_id);
+      entries.push({
+        archetype_id,
+        name: body.name,
+        source: "builtin",
+        path: file,
+        body
+      });
+    }
+  }
+  return entries;
+}
+function loadCustomBlocks(projectRoot) {
+  const customDir = join(projectRoot, "blocks", "custom");
+  const entries = [];
+  for (const file of walkForFiles(customDir, "block.json")) {
+    const body = safeParseJson(file);
+    if (!body)
+      continue;
+    const block_id = body.block_id ?? body.id;
+    if (!block_id)
+      continue;
+    entries.push({
+      block_id,
+      kind: body.kind,
+      name: body.name,
+      tags: Array.isArray(body.tags) ? body.tags : undefined,
+      source: "custom",
+      path: file,
+      body
+    });
+  }
+  return entries;
+}
+function loadCustomArchetypes(projectRoot) {
+  const customDir = join(projectRoot, "archetypes");
+  const entries = [];
+  if (!existsSync2(customDir))
+    return entries;
+  for (const file of walkForFiles(customDir, "archetype.json")) {
+    const body = safeParseJson(file);
+    if (!body)
+      continue;
+    const archetype_id = body.archetype_id ?? body.id;
+    if (!archetype_id)
+      continue;
+    entries.push({
+      archetype_id,
+      name: body.name,
+      source: "custom",
+      path: file,
+      body
+    });
+  }
+  return entries;
+}
+
+class Catalog {
+  builtinBlocks;
+  builtinArchetypes;
+  customBlocksByProject = new Map;
+  customArchetypesByProject = new Map;
+  constructor() {
+    this.builtinBlocks = loadBuiltinBlocks();
+    this.builtinArchetypes = loadBuiltinArchetypes();
+  }
+  refreshForProject(projectId, projectRoot) {
+    this.customBlocksByProject.set(projectId, loadCustomBlocks(projectRoot));
+    this.customArchetypesByProject.set(projectId, loadCustomArchetypes(projectRoot));
+  }
+  dropProject(projectId) {
+    this.customBlocksByProject.delete(projectId);
+    this.customArchetypesByProject.delete(projectId);
+  }
+  listBlocks(opts = {}) {
+    const merged = [
+      ...this.builtinBlocks,
+      ...opts.projectId ? this.customBlocksByProject.get(opts.projectId) ?? [] : []
+    ];
+    return merged.filter((b) => {
+      if (opts.kind && b.kind !== opts.kind)
+        return false;
+      if (opts.tags && opts.tags.length > 0) {
+        const have = new Set(b.tags ?? []);
+        if (!opts.tags.some((t) => have.has(t)))
+          return false;
+      }
+      return true;
+    });
+  }
+  getBlock(block_id, projectId) {
+    return this.listBlocks({ projectId }).find((b) => b.block_id === block_id);
+  }
+  listArchetypes(opts = {}) {
+    return [
+      ...this.builtinArchetypes,
+      ...opts.projectId ? this.customArchetypesByProject.get(opts.projectId) ?? [] : []
+    ];
+  }
+  getArchetype(archetype_id, projectId) {
+    return this.listArchetypes({ projectId }).find((a) => a.archetype_id === archetype_id);
+  }
+  writeCustomBlock(projectRoot, projectId, block) {
+    const block_id = block.block_id ?? block.id;
+    if (!block_id)
+      throw new Error("block.block_id is required");
+    const dir = join(projectRoot, "blocks", "custom", block_id);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "block.json");
+    writeFileSync(file, JSON.stringify(block, null, 2) + `
+`, "utf8");
+    this.refreshForProject(projectId, projectRoot);
+    const found = this.getBlock(block_id, projectId);
+    if (!found)
+      throw new Error(`failed to register block ${block_id} after write`);
+    return found;
+  }
+  deleteCustomBlock(projectRoot, projectId, block_id) {
+    const entry = this.getBlock(block_id, projectId);
+    if (!entry)
+      return { ok: false, reason: "not-found" };
+    if (entry.source === "builtin")
+      return { ok: false, reason: "cannot-delete-builtin" };
+    try {
+      const dir = dirname2(entry.path);
+      rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      return { ok: false, reason: e.message };
+    }
+    this.refreshForProject(projectId, projectRoot);
+    return { ok: true };
+  }
+  writeCustomArchetype(projectRoot, projectId, archetype) {
+    const archetype_id = archetype.archetype_id ?? archetype.id;
+    if (!archetype_id)
+      throw new Error("archetype.archetype_id is required");
+    const dir = join(projectRoot, "archetypes", archetype_id);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "archetype.json");
+    writeFileSync(file, JSON.stringify(archetype, null, 2) + `
+`, "utf8");
+    this.refreshForProject(projectId, projectRoot);
+    const found = this.getArchetype(archetype_id, projectId);
+    if (!found)
+      throw new Error(`failed to register archetype ${archetype_id} after write`);
+    return found;
+  }
+  deleteCustomArchetype(projectRoot, projectId, archetype_id) {
+    const entry = this.getArchetype(archetype_id, projectId);
+    if (!entry)
+      return { ok: false, reason: "not-found" };
+    if (entry.source === "builtin")
+      return { ok: false, reason: "cannot-delete-builtin" };
+    try {
+      const dir = dirname2(entry.path);
+      rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      return { ok: false, reason: e.message };
+    }
+    this.refreshForProject(projectId, projectRoot);
+    return { ok: true };
+  }
+}
+
+// src/tools/project.ts
+async function callSidecar(sidecar, method, params) {
+  try {
+    const r = await sidecar.call(method, params);
+    return r;
+  } catch (e) {
+    if (e instanceof SidecarUnavailableError) {
+      return { ok: false, error: "sidecar-unavailable", message: e.message };
+    }
+    if (e instanceof SidecarRpcError) {
+      return { ok: false, error: "sidecar-rpc-error", message: `${e.code}: ${e.message}` };
+    }
+    return { ok: false, error: "internal-error", message: e.message };
+  }
+}
+function projectTools(sidecar, registry) {
+  return [
+    {
+      name: "project.open",
+      description: "Open a project on disk. Returns projectId + parsed Project.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Absolute or cwd-relative project root path." }
+        },
+        required: ["path"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const r = await callSidecar(sidecar, "project.open", { path: args.path });
+        if (r.ok) {
+          const rec = r;
+          if (typeof rec.projectId === "string") {
+            registry.set(rec.projectId, {
+              path: args.path,
+              project: rec.project
+            });
+          }
+        }
+        return r;
+      }
+    },
+    {
+      name: "project.close",
+      description: "Close an open project; releases its FS watcher + LRU entries.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const r = await callSidecar(sidecar, "project.close", { projectId: args.projectId });
+        if (r.ok)
+          registry.delete(args.projectId);
+        return r;
+      }
+    },
+    {
+      name: "project.list",
+      description: "List previously-opened projects (most recent first).",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      async handler() {
+        return callSidecar(sidecar, "project.list", undefined);
+      }
+    },
+    {
+      name: "project.create",
+      description: "Scaffold a new project on disk from an archetype id, then open it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          archetype_id: { type: "string" },
+          path: { type: "string", description: "Project root directory to create." },
+          name: { type: "string", description: "Human-readable project title." }
+        },
+        required: ["archetype_id", "path", "name"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const r = await callSidecar(sidecar, "project.create", {
+          archetype_id: args.archetype_id,
+          path: args.path,
+          name: args.name
+        });
+        if (r.ok) {
+          const rec = r;
+          if (typeof rec.projectId === "string") {
+            registry.set(rec.projectId, {
+              path: args.path,
+              project: rec.project
+            });
+          }
+        }
+        return r;
+      }
+    },
+    {
+      name: "project.info",
+      description: "Fetch live project info: parsed Project + LRU openCells + queueDepth.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        return callSidecar(sidecar, "project.info", { projectId: args.projectId });
+      }
+    }
+  ];
+}
+
+// src/tools/storyboard.ts
+function storyboardTools(sidecar) {
+  return [
+    {
+      name: "storyboard.read",
+      description: "Read the full storyboard for an open project. Returns the parsed Project + cell index.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.read", { projectId: args.projectId })
+    },
+    {
+      name: "storyboard.read_cell",
+      description: "Read a single cell by id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.read_cell", { projectId: args.projectId, cellId: args.cellId })
+    },
+    {
+      name: "storyboard.read_fountain",
+      description: "Read the project's Fountain screenplay source at <root>/script.fountain. Returns { exists, text }. `exists:false` (empty text) means the project has no script.fountain on disk yet — not an error.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.read_fountain", { projectId: args.projectId })
+    },
+    {
+      name: "storyboard.read_cell_content",
+      description: "Read a cell's authored source file (the markup at its content_path). Returns { html, content_path, exists }. `exists:false` (empty html) means the cell has no source written yet.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.read_cell_content", {
+        projectId: args.projectId,
+        cellId: args.cellId
+      })
+    },
+    {
+      name: "storyboard.write_cell_content",
+      description: "Persist a cell's authored source file (the FULL edited html) to its content_path and bump last_edited (the project FS watcher surfaces the change). This is the durable save seam for the cell editor.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          html: { type: "string" }
+        },
+        required: ["projectId", "cellId", "html"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.write_cell_content", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        html: args.html
+      })
+    },
+    {
+      name: "storyboard.write_cell",
+      description: "Overwrite a cell. Emits cells/changed on success.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cell: { type: "object", additionalProperties: true }
+        },
+        required: ["projectId", "cell"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.write_cell", { projectId: args.projectId, cell: args.cell })
+    },
+    {
+      name: "storyboard.create_cell",
+      description: "Create a new cell. Emits cells/changed on success.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cell: { type: "object", additionalProperties: true }
+        },
+        required: ["projectId", "cell"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.create_cell", { projectId: args.projectId, cell: args.cell })
+    },
+    {
+      name: "storyboard.delete_cell",
+      description: "Delete a cell by id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.delete_cell", { projectId: args.projectId, cellId: args.cellId })
+    },
+    {
+      name: "storyboard.list_cells",
+      description: "List cells in an open project. Optional beat_id + rung filters.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          beat_id: { type: "string" },
+          rung: { type: "string", enum: ["0_beat_sheet", "1_lofi", "2_hifi"] }
+        },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.list_cells", {
+        projectId: args.projectId,
+        beat_id: args.beat_id,
+        rung: args.rung
+      })
+    },
+    {
+      name: "storyboard.upsert_beat",
+      description: "Insert or update a beat (script-level) on the project.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          beat: { type: "object", additionalProperties: true }
+        },
+        required: ["projectId", "beat"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.upsert_beat", { projectId: args.projectId, beat: args.beat })
+    },
+    {
+      name: "storyboard.upsert_rung",
+      description: "Insert or update a per-rung block (beatsheet/lofi/hifi) on a cell. Defaults to the cell's own rung when rungKey is omitted.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          rung: { type: "object", additionalProperties: true },
+          rungKey: { type: "string", enum: ["0_beat_sheet", "1_lofi", "2_hifi"] }
+        },
+        required: ["projectId", "cellId", "rung"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.upsert_rung", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        rung: args.rung,
+        rungKey: args.rungKey
+      })
+    },
+    {
+      name: "storyboard.set_approved",
+      description: "Flip the approved boolean on a cell.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          approved: { type: "boolean" }
+        },
+        required: ["projectId", "cellId", "approved"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "storyboard.set_approved", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        approved: args.approved
+      })
+    }
+  ];
+}
+
+// src/tools/anchor.ts
+function anchorTools(sidecar) {
+  return [
+    {
+      name: "anchor.list",
+      description: "List all anchors in the project.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "anchor.list", { projectId: args.projectId })
+    },
+    {
+      name: "anchor.create",
+      description: "Create a new anchor (project-scoped reusable asset reference).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          anchor: { type: "object", additionalProperties: true }
+        },
+        required: ["projectId", "anchor"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "anchor.create", { projectId: args.projectId, anchor: args.anchor })
+    },
+    {
+      name: "anchor.delete",
+      description: "Delete an anchor by id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          anchorId: { type: "string" }
+        },
+        required: ["projectId", "anchorId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "anchor.delete", { projectId: args.projectId, anchorId: args.anchorId })
+    }
+  ];
+}
+
+// src/tools/asset.ts
+function assetTools(sidecar) {
+  return [
+    {
+      name: "asset.list",
+      description: "List assets in a project. Optional `kind` filter (image, video, audio, font).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          kind: { type: "string" }
+        },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "asset.list", { projectId: args.projectId, kind: args.kind })
+    },
+    {
+      name: "asset.import",
+      description: "Import an asset from a URL or local path into the project assets dir.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          source: { type: "string", description: "URL or absolute path of the source asset." },
+          kind: { type: "string" }
+        },
+        required: ["projectId", "source"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "asset.import", {
+        projectId: args.projectId,
+        source: args.source,
+        kind: args.kind
+      })
+    },
+    {
+      name: "asset.resolve",
+      description: "Resolve an AssetRef (project-relative asset id) to an absolute on-disk path + metadata.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          assetId: { type: "string" }
+        },
+        required: ["projectId", "assetId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "asset.resolve", { projectId: args.projectId, assetId: args.assetId })
+    }
+  ];
+}
+
+// src/tools/composition.ts
+function compositionTools(sidecar, _registry) {
+  return [
+    {
+      name: "composition.render",
+      description: "Enqueue a render for a cell. The sidecar resolves the engine via G23 (auto by content_path extension) and validates against G2 capabilities BEFORE enqueueing. Returns { ok:true, recordId, engine } or a structured failure.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          engine: { type: "string", description: 'Optional. "auto" or undefined triggers G23 resolution.' },
+          variant: { type: "string" },
+          range: {
+            type: "object",
+            properties: { start_ms: { type: "number" }, end_ms: { type: "number" } },
+            additionalProperties: false
+          },
+          aspect_ratio: { type: "string", enum: ["16:9", "9:16", "1:1"] },
+          resolution: {
+            type: "object",
+            properties: { w: { type: "number" }, h: { type: "number" } },
+            required: ["w", "h"],
+            additionalProperties: false
+          }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "render.enqueue", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        engine: args.engine,
+        variant: args.variant,
+        range: args.range,
+        aspect_ratio: args.aspect_ratio,
+        resolution: args.resolution
+      })
+    },
+    {
+      name: "composition.preview",
+      description: "Generate a preview frame URL for a cell. Sidecar resolves the engine (G23) and calls adapter.preview.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          engine: { type: "string" }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "composition.preview", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        engine: args.engine
+      })
+    },
+    {
+      name: "composition.validate",
+      description: "Run the resolved engine's `validate` against a cell. Returns Diagnostic[] under `diagnostics`.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cellId: { type: "string" },
+          engine: { type: "string" }
+        },
+        required: ["projectId", "cellId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "composition.validate", {
+        projectId: args.projectId,
+        cellId: args.cellId,
+        engine: args.engine
+      })
+    }
+  ];
+}
+
+// src/tools/render.ts
+function renderTools(sidecar) {
+  return [
+    {
+      name: "render.list_engines",
+      description: "Return the G2 capability matrix for every renderer adapter known to the sidecar registry. No open project required.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      handler: () => callSidecar(sidecar, "render.list_engines", {})
+    },
+    {
+      name: "render.status",
+      description: "Look up a render record by id from the sidecar queue.",
+      inputSchema: {
+        type: "object",
+        properties: { recordId: { type: "string" } },
+        required: ["recordId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "render.status", { recordId: args.recordId })
+    },
+    {
+      name: "render.cancel",
+      description: "Cancel a queued or running render (aborts the in-flight adapter or marks a queued row cancelled).",
+      inputSchema: {
+        type: "object",
+        properties: { recordId: { type: "string" } },
+        required: ["recordId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "render.cancel", { recordId: args.recordId })
+    },
+    {
+      name: "render.list",
+      description: "List render records from the sidecar queue. Optional projectId + status filters.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          status: { type: "string", enum: ["queued", "running", "done", "failed", "cancelled"] }
+        },
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "render.list", { projectId: args.projectId, status: args.status })
+    },
+    {
+      name: "render.read_bytes",
+      description: "Read a finished render's MP4 off disk, base64-encoded, so a UI can preview it as a blob: URL in-pane (file:// is unloadable from a sandboxed srcdoc pane). Returns { ok:true, base64, mime, sizeBytes, path }. Keyed on the render record id.",
+      inputSchema: {
+        type: "object",
+        properties: { recordId: { type: "string" } },
+        required: ["recordId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "render.read_bytes", { recordId: args.recordId })
+    }
+  ];
+}
+
+// src/tools/export.ts
+function exportTools(sidecar) {
+  return [
+    {
+      name: "export.compose",
+      description: "Compose a project's rendered cells into a single deliverable MP4 (concat + transitions + narration/music mix). Selection defaults to all cells in beat order; pass `rung` to restrict to one rung or `cellIds` for an explicit ordered subset. Returns { ok:true, exportId, outputPath, reveal:true }. The export runs serially in the sidecar — poll export.status for completion.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          rung: { type: "number", description: "Optional. 0|1|2 — restrict to one rung." },
+          cellIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional. Explicit cell uids, in export order (wins over rung)."
+          },
+          music_preset: {
+            type: "string",
+            enum: ["none", "silent", "ambient", "upbeat"],
+            description: "Music bed. none/silent ship now; ambient/upbeat fall back to silent until bed asset files exist (assets/music/<preset>.mp3)."
+          },
+          outputPath: {
+            type: "string",
+            description: "Optional. Absolute or project-relative output path; defaults to exports/<ISO-8601>.mp4."
+          },
+          engine: {
+            type: "string",
+            description: "Optional. Preferred render-engine subfolder to pull cell MP4s from."
+          }
+        },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "export.compose", {
+        projectId: args.projectId,
+        rung: args.rung,
+        cellIds: args.cellIds,
+        music_preset: args.music_preset,
+        outputPath: args.outputPath,
+        engine: args.engine
+      })
+    },
+    {
+      name: "export.status",
+      description: "Fetch the status of a single export by id. Returns { ok:true, record: { exportId, projectId, status, outputPath?, error? } }.",
+      inputSchema: {
+        type: "object",
+        properties: { exportId: { type: "string" } },
+        required: ["exportId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "export.status", { exportId: args.exportId })
+    },
+    {
+      name: "export.list",
+      description: "List export records (most recent first). Optionally scope to one project. Returns { ok:true, exports: [...] }.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "export.list", { projectId: args.projectId })
+    },
+    {
+      name: "export.read_bytes",
+      description: "Read a finished export's MP4 off disk, base64-encoded, for in-pane composed playback as a blob: URL. Returns { ok:true, base64, mime, sizeBytes, path }. Keyed on the export id.",
+      inputSchema: {
+        type: "object",
+        properties: { exportId: { type: "string" } },
+        required: ["exportId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "export.read_bytes", { exportId: args.exportId })
+    },
+    {
+      name: "export.check_bed",
+      description: "Pre-flight audio-bed check: does a real music-bed file exist on disk for the chosen preset? Returns { ok:true, hasBed, willBeSilent, byDesign, path? }. none/silent are silent by design; ambient/upbeat need assets/music/<preset>.mp3.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          music_preset: { type: "string", enum: ["none", "silent", "ambient", "upbeat"] }
+        },
+        required: ["projectId"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "export.check_bed", {
+        projectId: args.projectId,
+        music_preset: args.music_preset
+      })
+    }
+  ];
+}
+
+// src/tools/block.ts
+function blockTools(catalog, registry) {
+  return [
+    {
+      name: "block.list",
+      description: "List blocks in the catalog. Filters: kind, tags (OR-match). Project-scoped custom blocks merge in when projectId is supplied.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          kind: { type: "string" },
+          tags: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.projectId;
+        if (projectId) {
+          const open = registry.get(projectId);
+          if (open)
+            catalog.refreshForProject(projectId, open.path);
+        }
+        const blocks = catalog.listBlocks({
+          projectId,
+          kind: args.kind,
+          tags: args.tags
+        });
+        return {
+          ok: true,
+          blocks: blocks.map((b) => ({
+            block_id: b.block_id,
+            kind: b.kind,
+            name: b.name,
+            tags: b.tags ?? [],
+            source: b.source
+          }))
+        };
+      }
+    },
+    {
+      name: "block.get",
+      description: "Fetch the full block.json body by id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          block_id: { type: "string" },
+          projectId: { type: "string" }
+        },
+        required: ["block_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.projectId;
+        if (projectId) {
+          const open = registry.get(projectId);
+          if (open)
+            catalog.refreshForProject(projectId, open.path);
+        }
+        const b = catalog.getBlock(args.block_id, projectId);
+        if (!b)
+          return { ok: false, error: "block-not-found", message: args.block_id };
+        return { ok: true, block: b.body, source: b.source };
+      }
+    },
+    {
+      name: "block.instantiate",
+      description: "Instantiate a block into a concrete cell JSON given bindings. Does NOT write to disk — pipe the result into storyboard.write_cell.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          block_id: { type: "string" },
+          bindings: { type: "object", additionalProperties: true },
+          projectId: { type: "string" }
+        },
+        required: ["block_id", "bindings"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.projectId;
+        const b = catalog.getBlock(args.block_id, projectId);
+        if (!b)
+          return { ok: false, error: "block-not-found", message: args.block_id };
+        const template = b.body.template ?? {};
+        const merged = { ...template, ...args.bindings ?? {}, block_id: b.block_id };
+        return { ok: true, cell: merged };
+      }
+    },
+    {
+      name: "block.create_custom",
+      description: "Write a custom block under the project blocks/custom/ dir. Requires an open project.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          block: { type: "object", additionalProperties: true },
+          project_id: { type: "string" }
+        },
+        required: ["block", "project_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.project_id;
+        const open = registry.get(projectId);
+        if (!open)
+          return { ok: false, error: "project-not-open", message: `projectId ${projectId} is not open` };
+        try {
+          const entry = catalog.writeCustomBlock(open.path, projectId, args.block);
+          return { ok: true, block_id: entry.block_id, path: entry.path };
+        } catch (e) {
+          return { ok: false, error: "internal-error", message: e.message };
+        }
+      }
+    },
+    {
+      name: "block.delete",
+      description: 'Delete a custom block. Built-in blocks return { ok:false, error:"cannot-delete-builtin" }.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          block_id: { type: "string" },
+          project_id: { type: "string" }
+        },
+        required: ["block_id", "project_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.project_id;
+        const open = registry.get(projectId);
+        if (!open)
+          return { ok: false, error: "project-not-open", message: `projectId ${projectId} is not open` };
+        const r = catalog.deleteCustomBlock(open.path, projectId, args.block_id);
+        if (r.ok)
+          return { ok: true };
+        if (r.reason === "cannot-delete-builtin")
+          return { ok: false, error: "cannot-delete-builtin" };
+        if (r.reason === "not-found")
+          return { ok: false, error: "block-not-found" };
+        return { ok: false, error: "internal-error", message: r.reason };
+      }
+    }
+  ];
+}
+
+// src/tools/archetype.ts
+function archetypeTools(catalog, registry, sidecar) {
+  return [
+    {
+      name: "archetype.list",
+      description: "List archetypes in the catalog. Project-scoped custom archetypes merge in when projectId is supplied.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" } },
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.projectId;
+        if (projectId) {
+          const open = registry.get(projectId);
+          if (open)
+            catalog.refreshForProject(projectId, open.path);
+        }
+        const archetypes = catalog.listArchetypes({ projectId });
+        return {
+          ok: true,
+          archetypes: archetypes.map((a) => ({
+            archetype_id: a.archetype_id,
+            name: a.name,
+            source: a.source
+          }))
+        };
+      }
+    },
+    {
+      name: "archetype.get",
+      description: "Fetch the full archetype.json body by id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          archetype_id: { type: "string" },
+          projectId: { type: "string" }
+        },
+        required: ["archetype_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.projectId;
+        if (projectId) {
+          const open = registry.get(projectId);
+          if (open)
+            catalog.refreshForProject(projectId, open.path);
+        }
+        const a = catalog.getArchetype(args.archetype_id, projectId);
+        if (!a)
+          return { ok: false, error: "archetype-not-found", message: args.archetype_id };
+        return { ok: true, archetype: a.body, source: a.source };
+      }
+    },
+    {
+      name: "archetype.instantiate_into_project",
+      description: "Scaffold an archetype into an already-open project. Forwards to the sidecar, which materializes the archetype chain into the project cells. Returns archetype-not-found (WP-09) if no definition exists yet.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          archetype_id: { type: "string" },
+          project_id: { type: "string" }
+        },
+        required: ["archetype_id", "project_id"],
+        additionalProperties: false
+      },
+      handler: (args) => callSidecar(sidecar, "archetype.instantiate_into_project", {
+        projectId: args.project_id,
+        archetypeId: args.archetype_id
+      })
+    },
+    {
+      name: "archetype.save_custom",
+      description: "Write a custom archetype under the project archetypes/ dir.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          archetype: { type: "object", additionalProperties: true },
+          project_id: { type: "string" }
+        },
+        required: ["archetype", "project_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.project_id;
+        const open = registry.get(projectId);
+        if (!open)
+          return { ok: false, error: "project-not-open", message: `projectId ${projectId} is not open` };
+        try {
+          const entry = catalog.writeCustomArchetype(open.path, projectId, args.archetype);
+          return { ok: true, archetype_id: entry.archetype_id, path: entry.path };
+        } catch (e) {
+          return { ok: false, error: "internal-error", message: e.message };
+        }
+      }
+    },
+    {
+      name: "archetype.delete",
+      description: 'Delete a custom archetype. Built-ins return { ok:false, error:"cannot-delete-builtin" }.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          archetype_id: { type: "string" },
+          project_id: { type: "string" }
+        },
+        required: ["archetype_id", "project_id"],
+        additionalProperties: false
+      },
+      async handler(args) {
+        const projectId = args.project_id;
+        const open = registry.get(projectId);
+        if (!open)
+          return { ok: false, error: "project-not-open", message: `projectId ${projectId} is not open` };
+        const r = catalog.deleteCustomArchetype(open.path, projectId, args.archetype_id);
+        if (r.ok)
+          return { ok: true };
+        if (r.reason === "cannot-delete-builtin")
+          return { ok: false, error: "cannot-delete-builtin" };
+        if (r.reason === "not-found")
+          return { ok: false, error: "archetype-not-found" };
+        return { ok: false, error: "internal-error", message: r.reason };
+      }
+    }
+  ];
+}
+
+// src/tools/index.ts
+function buildTools(opts) {
+  const { sidecar, catalog, registry } = opts;
+  return [
+    ...projectTools(sidecar, registry),
+    ...storyboardTools(sidecar),
+    ...anchorTools(sidecar),
+    ...assetTools(sidecar),
+    ...compositionTools(sidecar, registry),
+    ...renderTools(sidecar),
+    ...exportTools(sidecar),
+    ...blockTools(catalog, registry),
+    ...archetypeTools(catalog, registry, sidecar)
+  ];
+}
+
+// src/index.ts
+var NAME = "studio-mcp";
+var VERSION = "0.0.0";
+
+class InMemoryRegistry {
+  map = new Map;
+  set(projectId, entry) {
+    this.map.set(projectId, entry);
+  }
+  get(projectId) {
+    return this.map.get(projectId);
+  }
+  delete(projectId) {
+    return this.map.delete(projectId);
+  }
+  values() {
+    return this.map.values();
+  }
+  keys() {
+    return this.map.keys();
+  }
+}
+async function main() {
+  const sidecar = new SidecarClient;
+  const catalog = new Catalog;
+  const registry = new InMemoryRegistry;
+  sidecar.start();
+  const tools = buildTools({ sidecar, catalog, registry });
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, logging: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    const tool = byName.get(name);
+    if (!tool) {
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+    try {
+      const result = await tool.handler(args ?? {});
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        isError: result.ok === false
+      };
+    } catch (err) {
+      if (err instanceof McpError)
+        throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [{ type: "text", text: JSON.stringify({ ok: false, error: "internal-error", message: msg }) }],
+        isError: true
+      };
+    }
+  });
+  sidecar.onEvent((evt) => {
+    server.sendLoggingMessage({
+      level: "info",
+      logger: "studio-mcp/sidecar-event",
+      data: evt
+    }).catch((err) => {
+      process.stderr.write(`[studio-mcp] failed to forward event: ${err.message}
+`);
+    });
+  });
+  process.stderr.write(`[studio-mcp] ready name=${NAME} pid=${process.pid}
+`);
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+  const shutdown = async (sig) => {
+    process.stderr.write(`[studio-mcp] received ${sig}, shutting down
+`);
+    try {
+      await sidecar.stop();
+    } catch {}
+    try {
+      await server.close();
+    } catch {}
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+main().catch((err) => {
+  process.stderr.write(`[studio-mcp] fatal: ${err.stack ?? String(err)}
+`);
+  process.exit(1);
+});