@synkit/nexus 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @synkit/nexus
+
+> Drive the [Nexus](https://nexus.synkit.net) procedural-design tool from any AI agent that speaks MCP.
+
+`@synkit/nexus` is a [Model Context Protocol](https://modelcontextprotocol.io) server. It bridges your agent (Claude Code, Claude Desktop, Cursor, any MCP client) to a Nexus editor tab running in your browser, so the agent can read the canvas, create generators, tune parameters, save snapshots — all the things you'd otherwise do by hand in the inspector.
+
+```
+┌──────────────┐  stdio   ┌────────────────┐   ws://127.0.0.1   ┌──────────────────┐
+│  Your agent  │ <──────> │  MCP server    │ <────────────────> │  Nexus editor    │
+│  (MCP host)  │          │  (this pkg)    │                    │  (browser tab)   │
+└──────────────┘          └────────────────┘                    └──────────────────┘
+```
+
+The server is a thin router: it tells the agent what tools are available, forwards each call to the editor over a local WebSocket, and returns the result. The actual logic — every layer mutation, every snapshot, every store read — lives in the editor.
+
+## Install
+
+You don't install anything ahead of time. Your MCP client invokes `@synkit/nexus` via `npx`, which fetches and runs the latest version on demand.
+
+### Claude Code
+
+```bash
+claude mcp add nexus -- npx @synkit/nexus
+```
+
+Then restart Claude Code.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (create if missing):
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "npx",
+      "args": ["@synkit/nexus"]
+    }
+  }
+}
+```
+
+Restart Cursor.
+
+### Claude Desktop
+
+Add to your config file:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "npx",
+      "args": ["@synkit/nexus"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+### Other MCP clients
+
+Any client that speaks the stdio MCP transport works. Invoke `npx @synkit/nexus` as the server command.
+
+## Open the editor
+
+The agent needs a Nexus tab to connect to.
+
+1. Go to [nexus.synkit.net](https://nexus.synkit.net) (or your local dev build).
+2. Open the **MCP** menu from the top bar — you'll see your agent connect once the bridge is running.
+
+The first time an HTTPS page (`nexus.synkit.net`) reaches the local bridge, Chrome will show a **Private Network Access** prompt asking you to allow the connection. Approve it once; subsequent sessions auto-allow.
+
+## What the agent can do
+
+| Tool | What it does |
+|------|--------------|
+| `ping` | Health check — confirms the editor is connected. |
+| `get_canvas_state` | Full read-only snapshot of every layer (id, type, bounds, parameters, library). |
+| `list_generator_types` | The canonical generator type strings. |
+| `add_layer` | Create a new layer (any generator or shape type). |
+| `list_array_variant_presets` | Built-in shape presets for Array generators. |
+| `add_array_variants` | Inject preset shapes into an Array's library. |
+| `set_array_variants` | Replace an Array's library wholesale with curated shapes. |
+| `update_layer_param` | Change one parameter on one layer. |
+| `update_layer_params` | Change many parameters on one layer in a single render. |
+| `bulk_update_layers` | Apply ops across many layers in a single store mutation — the fast path for grid configurations. |
+| `duplicate_layer` | Clone a layer by id. |
+| `set_layer_bounds` | Move and/or resize a layer (partial bounds OK). |
+| `remove_layer` | Delete a layer. |
+| `save_canvas_snapshot` | Save the current canvas to a named localStorage slot. |
+| `restore_canvas_snapshot` | Restore a saved snapshot as a single undo checkpoint. |
+| `list_canvas_snapshots` | Enumerate saved snapshots. |
+| `delete_canvas_snapshot` | Delete a named snapshot. |
+
+Each tool has a long-form description visible to the agent — you can ask "what can you do with the canvas" and it'll enumerate.
+
+## Configuration
+
+| Env var | Default | Notes |
+|---------|---------|-------|
+| `NEXUS_MCP_PORT` | `7811` | Port the WebSocket bridge listens on (always bound to `127.0.0.1`). |
+| `NEXUS_MCP_ALLOWED_ORIGINS` | _(unset)_ | Comma-separated extra origins allowed to reach the bridge. Localhost + `*.synkit.net` are allowed by default; set this if you're hosting Nexus on a custom domain. Example: `https://my-nexus.example.com,https://staging.example.com`. |
+
+## Security
+
+- **Localhost-only.** The bridge binds to `127.0.0.1`. Random sites on the internet can't reach it. Anyone with code running on your machine who can open a localhost socket can drive your editor — but at that point they could already do anything else with your account too.
+- **Origin allowlist.** Browser-side requests are CORS-locked to `localhost`, `127.0.0.1`, and `*.synkit.net`. A drive-by site (`https://evil.com`) gets the preflight back without `Access-Control-Allow-Origin`, so the request is blocked — even if you accidentally accepted Chrome's Private Network Access prompt for that origin. Extend the list with `NEXUS_MCP_ALLOWED_ORIGINS` if you host Nexus elsewhere.
+- **No auth.** The bridge has no token. If you share a screen-recording or your machine is otherwise compromised, anyone with shell access can run `curl http://127.0.0.1:7811/call`.
+- **Single-tenant.** At most one editor tab connects at a time. Opening a second tab disconnects the first.
+- **You control sessions.** The Nexus editor has a Disconnect button in the MCP menu — it closes the WebSocket and refuses to reconnect until you click Resume. Use this if you want to step away with the editor open but no agent attached.
+
+## Development
+
+If you're hacking on the server itself (rather than just using it):
+
+```bash
+git clone https://github.com/synkit/nexus.git
+cd nexus/mcp
+npm install
+npm run dev          # tsx watch + stdio
+npm run bridge       # bridge only, no MCP stdio — for curl/wscat
+npm run typecheck    # tsc --noEmit
+npm run build        # tsup → ./dist
+```
+
+The Nexus-side handlers live in `src/lib/agentic/tool-registry.ts` (in the main repo). Add a handler there, add a catalog entry in `mcp/src/index.ts`, done.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,549 @@
+#!/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
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/bridge.ts
+import { WebSocketServer, WebSocket } from "ws";
+import { createServer } from "http";
+
+// src/protocol.ts
+var BRIDGE_PROTOCOL_VERSION = 2;
+
+// src/bridge.ts
+var DEFAULT_ALLOWED_ORIGIN_PATTERNS = [
+  // Localhost — any port. Matches dev (http://localhost:3000), preview
+  // builds, custom-port hosting on the user's own machine.
+  /^https?:\/\/localhost(?::\d+)?$/,
+  /^https?:\/\/127\.0\.0\.1(?::\d+)?$/,
+  // Production + subdomains. *.synkit.net catches staging /
+  // preview deploys without an explicit allowlist entry per env.
+  /^https:\/\/nexus\.synkit\.net$/,
+  /^https:\/\/[\w-]+\.synkit\.net$/
+];
+function parseExtraAllowedOrigins(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function isOriginAllowed(origin, extraAllowed) {
+  if (extraAllowed.includes(origin)) return true;
+  return DEFAULT_ALLOWED_ORIGIN_PATTERNS.some((rx) => rx.test(origin));
+}
+var NexusBridge = class {
+  httpServer;
+  wss;
+  nexus = null;
+  pending = /* @__PURE__ */ new Map();
+  nextId = 0;
+  log;
+  // Parsed once at construction. Empty array when env var is unset.
+  extraAllowedOrigins;
+  constructor(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    this.log = opts.log ?? ((...a) => console.error("[bridge]", ...a));
+    this.extraAllowedOrigins = parseExtraAllowedOrigins(
+      process.env.NEXUS_MCP_ALLOWED_ORIGINS
+    );
+    if (this.extraAllowedOrigins.length > 0) {
+      this.log(
+        `allowing extra origins: ${this.extraAllowedOrigins.join(", ")}`
+      );
+    }
+    this.httpServer = createServer((req, res) => this.handleHttp(req, res));
+    this.wss = new WebSocketServer({ noServer: true });
+    this.wss.on("error", (err) => this.log("WS server error:", err));
+    this.httpServer.on("upgrade", (req, socket, head) => {
+      this.wss.handleUpgrade(
+        req,
+        socket,
+        head,
+        (ws) => this.handleConnect(ws)
+      );
+    });
+    this.httpServer.listen(opts.port, host);
+  }
+  /** Send a tool-call to Nexus and resolve with its result. Rejects
+   *  if Nexus is not connected, the call times out, or Nexus returns
+   *  an error message. */
+  async callTool(name, params, timeoutMs = 8e3) {
+    if (!this.isConnected()) {
+      throw new Error(
+        "Nexus is not connected to the MCP bridge. Open the editor at http://localhost:3000 with NEXT_PUBLIC_NEXUS_MCP=1 set (see mcp/README.md)."
+      );
+    }
+    const id = `c${++this.nextId}`;
+    const msg = { type: "tool-call", id, name, params };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Tool '${name}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timeout });
+      this.nexus.send(JSON.stringify(msg));
+    });
+  }
+  isConnected() {
+    return this.nexus !== null && this.nexus.readyState === WebSocket.OPEN;
+  }
+  close() {
+    this.nexus?.close();
+    this.wss.close();
+    this.httpServer.close();
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timeout);
+      p.reject(new Error("Bridge closed"));
+    }
+    this.pending.clear();
+  }
+  /**
+   * HTTP handler. Three endpoints:
+   *   GET  /health         → connection status (which client is up,
+   *                          how many in-flight pending calls)
+   *   POST /call           → {"name", "params"} → calls the tool
+   *                          via Nexus, returns the result (or 4xx
+   *                          if Nexus isn't connected / tool errs)
+   *   *                    → 404
+   *
+   * Body must be JSON. We tolerate empty params (treated as {}) so
+   * `curl -X POST .../call -d '{"name":"ping"}'` works without a
+   * params field.
+   *
+   * CORS + Private Network Access:
+   *   Every response carries permissive CORS headers + the PNA opt-in
+   *   header `Access-Control-Allow-Private-Network: true`. Without
+   *   PNA, Chrome treats HTTPS→localhost requests as cross-origin
+   *   private-network requests and (depending on policy) blocks them
+   *   or forces a user-consent prompt every session. With PNA, the
+   *   prompt happens at most once.
+   *
+   *   We mirror Origin back rather than fix an allowlist — the bridge
+   *   only ever binds to 127.0.0.1, so the threat surface is "another
+   *   process on the user's own machine," which could already drive
+   *   the editor with curl. Permissive Origin doesn't broaden that.
+   */
+  handleHttp(req, res) {
+    const url = req.url ?? "/";
+    const origin = req.headers.origin;
+    const originAllowed = typeof origin === "string" && origin.length > 0 && isOriginAllowed(origin, this.extraAllowedOrigins);
+    const setCorsHeaders = () => {
+      if (originAllowed) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+      } else if (typeof origin === "string" && origin.length > 0) {
+        this.log(`rejecting origin: ${origin}`);
+      }
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader(
+        "Access-Control-Allow-Headers",
+        "content-type, authorization"
+      );
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+      res.setHeader("Access-Control-Max-Age", "600");
+    };
+    if (req.method === "OPTIONS") {
+      setCorsHeaders();
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+    setCorsHeaders();
+    if (req.method === "GET" && url === "/health") {
+      res.statusCode = 200;
+      res.setHeader("content-type", "application/json");
+      res.end(
+        JSON.stringify({
+          ok: true,
+          nexusConnected: this.isConnected(),
+          pendingCalls: this.pending.size,
+          protocolVersion: BRIDGE_PROTOCOL_VERSION
+        })
+      );
+      return;
+    }
+    if (req.method === "POST" && url === "/call") {
+      let body = "";
+      req.setEncoding("utf8");
+      req.on("data", (chunk) => {
+        body += chunk;
+        if (body.length > 1e6) {
+          req.destroy();
+        }
+      });
+      req.on("end", async () => {
+        let parsed;
+        try {
+          parsed = body.length > 0 ? JSON.parse(body) : {};
+        } catch {
+          res.statusCode = 400;
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify({ error: "Invalid JSON body" }));
+          return;
+        }
+        if (typeof parsed.name !== "string" || parsed.name.length === 0) {
+          res.statusCode = 400;
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify({ error: "`name` is required (string)" }));
+          return;
+        }
+        const params = typeof parsed.params === "object" && parsed.params !== null ? parsed.params : {};
+        try {
+          const result = await this.callTool(parsed.name, params);
+          res.statusCode = 200;
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify({ ok: true, result }));
+        } catch (e) {
+          res.statusCode = 200;
+          res.setHeader("content-type", "application/json");
+          res.end(
+            JSON.stringify({
+              ok: false,
+              error: e instanceof Error ? e.message : String(e)
+            })
+          );
+        }
+      });
+      return;
+    }
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ error: "Not found" }));
+  }
+  handleConnect(ws) {
+    if (this.nexus && this.nexus.readyState === WebSocket.OPEN) {
+      this.log("replacing existing Nexus connection (likely reload)");
+      this.nexus.close(1e3, "replaced by new connection");
+    }
+    this.nexus = ws;
+    this.log("Nexus connected");
+    ws.on("message", (raw) => this.handleMessage(ws, raw.toString()));
+    ws.on("close", () => {
+      if (this.nexus === ws) {
+        this.nexus = null;
+        this.log("Nexus disconnected");
+      }
+    });
+    ws.on("error", (err) => this.log("WS connection error:", err));
+  }
+  handleMessage(ws, raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch (e) {
+      this.log("ignoring malformed message:", e.message);
+      return;
+    }
+    if (msg.type === "hello") {
+      if (msg.protocolVersion !== BRIDGE_PROTOCOL_VERSION) {
+        this.log(
+          `protocol version mismatch (Nexus=${msg.protocolVersion}, bridge=${BRIDGE_PROTOCOL_VERSION}). Will try to continue.`
+        );
+      }
+      this.log("hello from", msg.client, "capabilities:", msg.capabilities);
+      return;
+    }
+    if (msg.type === "tool-result") {
+      const pending = this.pending.get(msg.id);
+      if (!pending) {
+        this.log("tool-result for unknown id:", msg.id);
+        return;
+      }
+      clearTimeout(pending.timeout);
+      this.pending.delete(msg.id);
+      if (msg.error) pending.reject(new Error(msg.error.message));
+      else pending.resolve(msg.result);
+      return;
+    }
+    this.log("unexpected message type from Nexus:", msg.type);
+  }
+};
+
+// src/index.ts
+var DEFAULT_PORT = 7811;
+var port = Number(process.env.NEXUS_MCP_PORT ?? DEFAULT_PORT);
+var log = (...args) => console.error("[nexus-mcp]", ...args);
+var bridge = new NexusBridge({ port, log });
+log(`WebSocket bridge listening on 127.0.0.1:${port}`);
+var server = new Server(
+  { name: "nexus-mcp", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "ping",
+      description: "Health check for the Nexus bridge. Returns { ok, layerCount, timestamp }. Use this FIRST to confirm the editor is connected before attempting other tools.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "get_canvas_state",
+      description: "Return the current state of the Nexus canvas \u2014 every layer with its id, name, type, kind, parent, bounds, rotation, visibility, locked flag, and parameters. Read-only. ALWAYS call this before making changes so you know what's already on the canvas and can reference existing layer ids.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "list_generator_types",
+      description: "List the available generator types you can add to the canvas. Returns the literal strings the editor accepts (e.g. 'node-machine', 'array', 'typeset'). Call this if the user asks for a generator by a casual name and you need to map it to the canonical type.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "add_layer",
+      description: "Add a new layer to the Nexus canvas. Returns the new layer's id. Use list_generator_types first if you're unsure of the type string \u2014 passing a wrong type errors out instead of silently failing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            description: "Canonical layer type (e.g. 'array', 'typeset', 'node-machine', 'rect', 'ellipse')."
+          },
+          bounds: {
+            type: "object",
+            description: "Optional. Layer-local bounds rect on the infinite canvas. Any omitted field uses the store's default.",
+            properties: {
+              x: { type: "number" },
+              y: { type: "number" },
+              width: { type: "number" },
+              height: { type: "number" }
+            },
+            additionalProperties: false
+          }
+        },
+        required: ["type"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "list_array_variant_presets",
+      description: "List the built-in shape presets you can inject into an array generator's library via add_array_variants. Returns [{ key, name }] \u2014 pass the keys to add_array_variants's `shapes` parameter.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "add_array_variants",
+      description: "Inject preset shape variants into an array generator's library (the 'palette' of shapes it stamps across cells). Pass `shapes` as a list of preset keys (call list_array_variant_presets to enumerate). Omit `shapes` to add every preset at once \u2014 useful when the user asks for 'lots of options'. If the array has no library yet, one is created in 'random' mode with a default Library Box below the generator. Variants default to white fill.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          arrayLayerId: { type: "string" },
+          shapes: { type: "array", items: { type: "string" } },
+          fill: { type: "string" }
+        },
+        required: ["arrayLayerId"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "set_array_variants",
+      description: "REPLACE an array generator's variant library with the supplied preset shapes (NOT append). Use this for curated themes \u2014 e.g. one array with just rounded shapes, another with just polygons. shapes is required. Optional `mode` flips the library mode at the same time: pass 'random' for sources where light-ramp doesn't work (e.g. pure black silhouettes), 'light' for grayscale ramps, 'mosaic' for tile-grid sampling.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          arrayLayerId: { type: "string" },
+          shapes: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1
+          },
+          mode: {
+            type: "string",
+            enum: ["light", "random", "mosaic"]
+          },
+          fill: { type: "string" }
+        },
+        required: ["arrayLayerId", "shapes"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "update_layer_param",
+      description: "Update a single parameter on a layer (any of the inspector knobs visible in get_canvas_state.parameters). Common keys on array layers: cellSize, colorMode (preserve | palette | fixed | gradient | sample | luma), overrideColor, paletteRandom, paletteCount, palette0..7, gradientStart, gradientEnd, gradientAngle, rotationJitter, scaleJitter, glow, glowStrength, glowRadius, sourceContrast, sourceGamma, sourceInvert. Value type follows the parameter (number, string, boolean).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          key: { type: "string" },
+          value: {}
+        },
+        required: ["id", "key"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "update_layer_params",
+      description: "Set MANY params on ONE layer in a single store mutation \u2014 collapses N param edits into 1 React render. Reach for this whenever you'd otherwise fire 2+ update_layer_param calls on the same layer (palette setup, jitter group, glow config). Render cost for an array layer is ~10-30ms per rebuild, so batching compounds fast. `params` is an object map of { key: value }; pass null to clear an optional field.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          params: {
+            type: "object",
+            additionalProperties: true,
+            description: "Object map of { paramKey: value } pairs to merge."
+          }
+        },
+        required: ["id", "params"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "bulk_update_layers",
+      description: "Apply many ops across many layers in ONE store mutation \u2014 the heavy machinery for compositions that touch multiple cells. Each op carries a layer `id` and may include `params` (merged into parameters) and/or `bounds` (partial x/y/width/height overwrite). All ops land inside a single zustand set() \u2192 one render pass for the entire batch. For a 6-cell grid configured with 8 params each, this is the difference between ~500ms of churn (48 individual calls) and ~30ms (one bulk). Mismatched ids skip silently \u2014 we apply what we can rather than rejecting the whole batch. NOT for interactive drags \u2014 this skips the keyframe-aware code path that set_layer_bounds uses.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ops: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                params: { type: "object", additionalProperties: true },
+                bounds: {
+                  type: "object",
+                  properties: {
+                    x: { type: "number" },
+                    y: { type: "number" },
+                    width: { type: "number" },
+                    height: { type: "number" }
+                  },
+                  additionalProperties: false
+                }
+              },
+              required: ["id"],
+              additionalProperties: false
+            }
+          }
+        },
+        required: ["ops"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "duplicate_layer",
+      description: "Duplicate a layer by id. Returns the new layer's id so subsequent set_layer_bounds calls can position the copy. The duplicate lands in the same spot as the original; move it explicitly if you don't want overlap.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "set_layer_bounds",
+      description: "Move and/or resize a layer. `bounds` is a partial \u2014 any omitted field keeps its current value. To move a layer, pass just { x, y }; to resize, pass just { width, height }.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          bounds: {
+            type: "object",
+            properties: {
+              x: { type: "number" },
+              y: { type: "number" },
+              width: { type: "number" },
+              height: { type: "number" }
+            },
+            additionalProperties: false
+          }
+        },
+        required: ["id", "bounds"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "remove_layer",
+      description: "Remove a layer by id. Idempotent \u2014 returns existed=false if the layer was already gone.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: "save_canvas_snapshot",
+      description: "Save the current canvas (layers + selection + viewport) to localStorage under a named slot. Use BEFORE risky experiments so you can come back. Survives tab reloads. Slot name defaults to 'default'.",
+      inputSchema: {
+        type: "object",
+        properties: { slot: { type: "string" } },
+        additionalProperties: false
+      }
+    },
+    {
+      name: "restore_canvas_snapshot",
+      description: "Restore a previously-saved snapshot by slot name. Overwrites the entire layer tree as a single undo checkpoint, so Ctrl+Z reverts the restore. Slot defaults to 'default'.",
+      inputSchema: {
+        type: "object",
+        properties: { slot: { type: "string" } },
+        additionalProperties: false
+      }
+    },
+    {
+      name: "list_canvas_snapshots",
+      description: "List every named canvas snapshot in localStorage with savedAt timestamp and layer count. Use to enumerate experiments before restoring.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      }
+    },
+    {
+      name: "delete_canvas_snapshot",
+      description: "Delete a named snapshot. Idempotent.",
+      inputSchema: {
+        type: "object",
+        properties: { slot: { type: "string" } },
+        required: ["slot"],
+        additionalProperties: false
+      }
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    const result = await bridge.callTool(
+      name,
+      args ?? {}
+    );
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(result, null, 2) }
+      ]
+    };
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Error: ${e.message}` }],
+      isError: true
+    };
+  }
+});
+var shutdown = () => {
+  log("shutting down");
+  bridge.close();
+  process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+log("stdio transport connected \u2014 ready for Claude");

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@synkit/nexus",
+  "version": "0.1.1",
+  "description": "MCP server that lets any AI agent drive the Nexus design tool over a local WebSocket bridge.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "nexus-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "bridge": "tsx src/bridge-only.ts",
+    "test-tools": "tsx src/test-tools.ts",
+    "tool": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nexus",
+    "synkit",
+    "agentic",
+    "design",
+    "procedural",
+    "ai",
+    "claude"
+  ],
+  "homepage": "https://nexus.synkit.net",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synkit/nexus.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/synkit/nexus/issues"
+  },
+  "license": "MIT",
+  "author": "Synkit",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5"
+  }
+}