pixelate-mcp 0.3.0 → 0.3.1

package/README.md

@@ -1,46 +1,94 @@
 # pixelate-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that turns any image into
-**grid-perfect, true pixel art** — it auto-detects the native pixel grid and a
-sensible palette among other things like reauthoring of the image. Works in **Codex, Claude Desktop, and Cursor**.
+An [MCP](https://modelcontextprotocol.io) server that lets an AI coding agent
+(Claude Code, Codex, Cursor) drive the **PixelAOI** editor — see the canvas,
+paint pixel art onto it, run editor commands, pixelate images locally, and
+build node-based blueprint graphs.
 
-The heavy lifting runs in the cloud (Pixelate Cloud); this package is the small
-local connector that decodes your image and streams it to the service. You need
-a subscription key from **https://pixelaoi.pro**.
+Everything runs on **your machine**: the server talks to the editor over a
+localhost-only bridge (`127.0.0.1`). No cloud, no accounts, no API keys.
 
-## Use it
+## 1. Enable the bridge in PixelAOI
 
-Add to your MCP client config (Codex `~/.codex/config.toml`, Claude Desktop, or
-Cursor) — no install step needed, `npx` fetches it on demand:
+Open PixelAOI and click the **agent** pill in the bottom status bar. It shows
+`A:WAIT` while listening and `A:LIVE` once an agent connects.
 
+(Alternatively, launch the editor with the `PIXELAOI_AGENT_BRIDGE=1`
+environment variable set.)
+
+## 2. Add the server to your agent
+
+### Claude Code
+```
+claude mcp add pixelaoi -- npx -y pixelate-mcp
+```
+
+### Codex (`~/.codex/config.toml`)
 ```toml
-[mcp_servers.pixelate]
+[mcp_servers.pixelaoi]
 command = "npx"
 args = ["-y", "pixelate-mcp"]
-env = { PIXELATE_API_URL = "https://pixelate.pixelaoi.cloud", PIXELATE_API_KEY = "YOUR_KEY" }
 ```
 
-Then ask your agent something like *"pixelate ./hero.png and save it next to the
-original."*
+### Claude Desktop / Cursor (JSON config)
+```json
+{
+  "command": "npx",
+  "args": ["-y", "pixelate-mcp"]
+}
+```
+
+Restart the agent, make sure the editor is running with the bridge on, and
+ask it to draw something.
+
+## Tools
+
+Canvas:
+
+- **`get_state`** — canvas size, frames, layers, tool, palette, blueprint
+  status, and the list of runnable command names.
+- **`get_canvas_image`** — the composited current frame as a PNG.
+- **`run_command`** `{ action }` — run a headless command (`flip_h`,
+  `rotate_90`, `trim`, `undo`, `save`, ...); names come from
+  `get_state.commands`.
+- **`set_canvas_image`** `{ image_path | png_base64, as_new_document?, name? }`
+  — paint an image. Matching canvas size paints onto the open document;
+  otherwise it opens as a new one.
+- **`set_pixels`** `{ x, y, w, h, rgba_base64 }` — paint a raw RGBA block,
+  clipped to the canvas.
+- **`pixelate_image`** — turn any image (path, base64, or URL) into
+  grid-perfect pixel art using the editor's local engine (auto-detects the
+  native grid and palette), then paint it in.
+- **`extrude_animate`** — bake a 3D-extrusion turntable of the current canvas
+  across the timeline, one keyframe per frame.
+
+Blueprints (node graphs):
 
-## Tool: `pixelate_image`
+- **`blueprint_node_kinds`** — the full catalog of addable node kinds.
+- **`blueprint_list`** — nodes, links, and value-wire bindings of the active
+  graph.
+- **`blueprint_select_graph`** `{ graph }` — switch between Particle, Canvas,
+  Ai, and Layer graphs.
+- **`blueprint_add_node`** / **`blueprint_delete_node`** — add or remove
+  nodes.
+- **`blueprint_connect`** — wire node outputs into node inputs.
+- **`blueprint_connect_value`** — drive a node parameter with a value node.
+- **`blueprint_set_param`** / **`blueprint_set_data`** — set continuous
+  params or discrete node config.
+- **`blueprint_bake`** — run the graph and bake the result to the canvas.
 
-| arg | description |
-|-----|-------------|
-| `image_path` / `image_base64` / `image_url` | the source image (provide one) |
-| `auto` | auto-detect grid + palette (default `true`) |
-| `target_width` / `target_height` | output size when `auto` is off or no grid is found |
-| `colors` | palette size (omit to auto-pick) |
-| `seed` | determinism seed |
-| `output_path` | if set, saves the PNG there |
+## Example
 
-Returns the pixel art as an image, plus a short summary.
+> "Take ./hero.png, pixelate it, put it on the canvas, then bake a noise
+> texture behind it with a Canvas blueprint."
 
-## Requirements
+The agent calls `pixelate_image` (local engine), then builds
+CanvasNoise -> CanvasOutput with the blueprint tools and runs
+`blueprint_bake`.
 
-- Node.js ≥ 18
-- A `PIXELATE_API_KEY` (subscribe at https://pixelaoi.pro)
+## Config
 
-## License
+- `PIXELAOI_BRIDGE_HOST` (default `127.0.0.1`)
+- `PIXELAOI_BRIDGE_PORT` (default `48653`)
 
-MIT
+Get the editor at [pixelaoi.pro](https://pixelaoi.pro).

package/index.js

@@ -1,136 +1,467 @@
-#!/usr/bin/env node
-
-import { readFile, writeFile } from "node:fs/promises";
-import os from "node:os";
-import crypto from "node:crypto";
-import sharp from "sharp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-const API_URL = (process.env.PIXELATE_API_URL || "").replace(/\/+$/, "");
-const API_KEY = process.env.PIXELATE_API_KEY || "";
-if (!API_URL || !API_KEY) {
-  console.error("pixelate-mcp: set PIXELATE_API_URL and PIXELATE_API_KEY environment variables.");
-  process.exit(1);
-}
-
-// Stable per-machine id. A key binds to the first machine that uses it, so a
-// shared key won't work on someone else's device. Derived from host/user/home
-// (deterministic, no extra files); override with PIXELATE_MACHINE_ID if needed.
-let _uname = "";
-try { _uname = os.userInfo().username; } catch { /* ignore */ }
-const MACHINE_ID =
-  process.env.PIXELATE_MACHINE_ID ||
-  crypto.createHash("sha256").update([os.hostname(), _uname, os.homedir(), os.platform()].join("|")).digest("hex").slice(0, 24);
-
-const stripDataUrl = (s) => {
-  const i = s.indexOf(",");
-  return s.startsWith("data:") && i !== -1 ? s.slice(i + 1) : s;
-};
-const errText = (text) => ({ content: [{ type: "text", text }], isError: true });
-const usd = (cents) => `$${(cents / 100).toFixed(2)}`;
-// One-line billing summary from a /job done response (credits_cents may be null
-// for unlimited subscription keys).
-function billingLine(res) {
-  const price = res.price_cents != null ? `${usd(res.price_cents)}/image` : null;
-  if (res.credits_cents == null) return price ? ` Plan: unlimited (${price}).` : "";
-  const imgs = res.price_cents ? Math.floor(res.credits_cents / res.price_cents) : null;
-  return ` Charged ${price}; ${usd(res.credits_cents)} credit left${imgs != null ? ` (~${imgs} images)` : ""}.`;
-}
-
-async function jobReq(query, body) {
-  const headers = { "x-api-key": API_KEY, "x-machine-id": MACHINE_ID };
-  if (body) headers["content-type"] = "application/octet-stream";
-  const res = await fetch(`${API_URL}/job?${query}`, {
-    method: "POST",
-    headers,
-    body: body ?? undefined,
-  });
-  const j = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(`HTTP ${res.status}: ${j.error || "request failed"}`);
-  if (!j.success) throw new Error(j.error || "job error");
-  return j;
-}
-
-const server = new McpServer({ name: "pixelate-mcp", version: "0.3.0" });
-
-server.tool(
-  "pixelate_account",
-  "Show your Pixelate Cloud credit balance (how much you have left) and the cost per image.",
-  {},
-  async () => {
-    try {
-      const res = await fetch(`${API_URL}/account`, { headers: { "x-api-key": API_KEY, "x-machine-id": MACHINE_ID } });
-      const j = await res.json().catch(() => ({}));
-      if (!res.ok || !j.success) return errText(`account error (${res.status}): ${j.error || "unknown"}`);
-      const text =
-        j.plan === "subscription"
-          ? `Plan: unlimited subscription. Cost per image: ${usd(j.price_per_image_cents)} (not charged on your plan).`
-          : `Balance: $${j.credits_usd} (~${j.images_remaining} images left). Cost per image: $${j.price_per_image_usd}.`;
-      return { content: [{ type: "text", text }] };
-    } catch (e) {
-      return errText(`pixelate-mcp error: ${e?.message || e}`);
-    }
-  },
-);
-
-server.tool(
-  "pixelate_image",
-  "Convert an image into grid-perfect, true pixel art. Auto-detects the native pixel grid and a sensible palette. Provide exactly one of image_path, image_base64, or image_url.",
-  {
-    image_path: z.string().optional().describe("Local path to the source image (png/jpg/webp)."),
-    image_base64: z.string().optional().describe("Base64-encoded image (alternative to image_path)."),
-    image_url: z.string().optional().describe("URL to fetch the image from (alternative to image_path)."),
-    auto: z.boolean().optional().describe("Auto-detect native grid + palette (default true)."),
-    target_width: z.number().int().positive().optional().describe("Output width; used when auto is off or no grid is detected."),
-    target_height: z.number().int().positive().optional().describe("Output height; used when auto is off or no grid is detected."),
-    colors: z.number().int().positive().optional().describe("Palette size; omit to auto-pick."),
-    seed: z.number().int().optional().describe("Determinism seed (default 42)."),
-    output_path: z.string().optional().describe("If set, save the resulting PNG to this path."),
-  },
-  async (a) => {
-    try {
-      let buf;
-      if (a.image_base64) buf = Buffer.from(stripDataUrl(a.image_base64), "base64");
-      else if (a.image_path) buf = await readFile(a.image_path);
-      else if (a.image_url) buf = Buffer.from(await (await fetch(a.image_url)).arrayBuffer());
-      else return errText("Provide one of image_path, image_base64, or image_url.");
-
-      // Decode locally to raw RGBA (no Worker decode -> no decode CPU on the edge).
-      const { data, info } = await sharp(buf).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-
-      // Start: raw bytes go in the binary body; params in the query string.
-      const q = new URLSearchParams({ action: "start", w: String(info.width), h: String(info.height), auto: (a.auto ?? true) ? "1" : "0" });
-      if (a.colors) q.set("colors", String(a.colors));
-      if (a.seed != null) q.set("seed", String(a.seed));
-      if (a.target_width) q.set("tw", String(a.target_width));
-      if (a.target_height) q.set("th", String(a.target_height));
-
-      let res = await jobReq(q.toString(), data);
-      const jobId = res.job_id;
-      let guard = 0;
-      while (!res.done) {
-        if (++guard > 1000) return errText("pixelate-mcp: job did not converge");
-        res = await jobReq(`action=step&id=${encodeURIComponent(jobId)}`);
-      }
-
-      let summary = `Pixel art ${res.width}x${res.height}.`;
-      if (a.output_path) {
-        await writeFile(a.output_path, Buffer.from(res.image_base64, "base64"));
-        summary += ` Saved to ${a.output_path}.`;
-      }
-      summary += billingLine(res);
-      return {
-        content: [
-          { type: "text", text: summary },
-          { type: "image", data: res.image_base64, mimeType: "image/png" },
-        ],
-      };
-    } catch (e) {
-      return errText(`pixelate-mcp error: ${e?.message || e}`);
-    }
-  },
-);
-
-await server.connect(new StdioServerTransport());
+#!/usr/bin/env node
+import net from "node:net";
+import { readFile, writeFile } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const HOST = process.env.PIXELAOI_BRIDGE_HOST || "127.0.0.1";
+const PORT = Number(process.env.PIXELAOI_BRIDGE_PORT || 48653);
+
+
+let sock = null;
+let connected = false;
+let buffer = "";
+let nextId = 1;
+const pending = new Map();
+
+function teardown(err) {
+  if (sock) {
+    try { sock.destroy(); } catch {}
+  }
+  sock = null;
+  connected = false;
+  buffer = "";
+  for (const [, p] of pending) {
+    clearTimeout(p.timer);
+    p.reject(err || new Error("bridge disconnected"));
+  }
+  pending.clear();
+}
+
+function connect() {
+  if (connected && sock) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const s = net.createConnection({ host: HOST, port: PORT });
+    s.setNoDelay(true);
+    s.once("connect", () => {
+      sock = s;
+      connected = true;
+      resolve();
+    });
+    s.once("error", (e) => {
+      connected = false;
+      reject(
+        new Error(
+          `cannot reach the PixelAOI editor bridge at ${HOST}:${PORT} — open the editor and ` +
+            `click the "agent" pill in the bottom status bar to enable it ` +
+            `(or launch with PIXELAOI_AGENT_BRIDGE=1). (${e.code || e.message})`,
+        ),
+      );
+    });
+    s.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        const p = pending.get(msg.id);
+        if (!p) continue;
+        pending.delete(msg.id);
+        clearTimeout(p.timer);
+        if (msg.ok) p.resolve(msg.result);
+        else p.reject(new Error(msg.error || "bridge error"));
+      }
+    });
+    s.on("close", () => teardown(new Error("bridge connection closed")));
+  });
+}
+
+async function call(op, args, timeoutMs = 30000) {
+  await connect();
+  const id = nextId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`bridge op '${op}' timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    try {
+      sock.write(JSON.stringify({ id, op, args: args ?? null }) + "\n");
+    } catch (e) {
+      clearTimeout(timer);
+      pending.delete(id);
+      reject(e);
+    }
+  });
+}
+
+const errText = (e) => ({
+  content: [{ type: "text", text: `pixelaoi-mcp error: ${e?.message || e}` }],
+  isError: true,
+});
+const stripDataUrl = (s) => {
+  const i = s.indexOf(",");
+  return s.startsWith("data:") && i !== -1 ? s.slice(i + 1) : s;
+};
+
+const server = new McpServer({ name: "pixelate-mcp", version: "0.3.1" });
+
+server.tool(
+  "get_state",
+  "Get the PixelAOI editor state: canvas size, frame/layer counts, active tool, palette size, blueprint status, and the list of runnable command names.",
+  {},
+  async () => {
+    try {
+      const r = await call("state.get");
+      return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "get_canvas_image",
+  "See the current canvas: returns the composited current frame as a PNG image.",
+  {},
+  async () => {
+    try {
+      const r = await call("canvas.get");
+      return {
+        content: [
+          { type: "text", text: `Canvas ${r.width}x${r.height}.` },
+          { type: "image", data: r.png_base64, mimeType: "image/png" },
+        ],
+      };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "run_command",
+  "Run a headless editor command by name (e.g. flip_h, flip_v, rotate_90, trim, undo, redo, save). Call get_state first and read its `commands` list for the valid names.",
+  { action: z.string().describe("A command name from get_state.commands") },
+  async ({ action }) => {
+    try {
+      await call("command.run", { action });
+      return { content: [{ type: "text", text: `Ran '${action}'.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "set_canvas_image",
+  "Paint an image (e.g. a pixelated PNG) into the PixelAOI editor. If the image matches the current canvas size it paints onto the open document; if not, it opens as a NEW document (override with as_new_document). Provide exactly one of image_path or png_base64.",
+  {
+    image_path: z.string().optional().describe("Local path to a PNG/JPG/WEBP to paint."),
+    png_base64: z.string().optional().describe("Base64-encoded image (alternative to image_path)."),
+    as_new_document: z
+      .boolean()
+      .optional()
+      .describe("Force a new document (true) or paint onto the current canvas (false). Default: auto by size."),
+    name: z.string().optional().describe("Title for the new document, when one is created."),
+  },
+  async (a) => {
+    try {
+      let b64 = a.png_base64 ? stripDataUrl(a.png_base64) : undefined;
+      if (!b64 && a.image_path) b64 = (await readFile(a.image_path)).toString("base64");
+      if (!b64) return errText(new Error("provide image_path or png_base64"));
+      const args = { png_base64: b64 };
+      if (a.as_new_document != null) args.as_new_document = a.as_new_document;
+      if (a.name) args.name = a.name;
+      const r = await call("canvas.set_image", args, 60000);
+      return {
+        content: [{ type: "text", text: `Painted ${r.width}x${r.height} (${r.document} document).` }],
+      };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "set_pixels",
+  "Paint a raw RGBA block onto the current canvas at (x,y), clipped to the canvas bounds. rgba_base64 is base64 of exactly w*h*4 RGBA bytes (row-major, top-left origin).",
+  {
+    x: z.number().int().describe("Left edge on the canvas."),
+    y: z.number().int().describe("Top edge on the canvas."),
+    w: z.number().int().positive().describe("Block width in pixels."),
+    h: z.number().int().positive().describe("Block height in pixels."),
+    rgba_base64: z.string().describe("Base64 of w*h*4 RGBA bytes."),
+  },
+  async (a) => {
+    try {
+      await call("canvas.set_pixels", {
+        x: a.x,
+        y: a.y,
+        w: a.w,
+        h: a.h,
+        rgba_base64: stripDataUrl(a.rgba_base64),
+      });
+      return { content: [{ type: "text", text: `Painted ${a.w}x${a.h} at (${a.x},${a.y}).` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "pixelate_image",
+  "Turn an image into grid-perfect pixel art LOCALLY using the editor's built-in engine (auto-detects the native grid + palette), then paint it into PixelAOI. No cloud, no API key. Provide exactly one of image_path, png_base64, or image_url.",
+  {
+    image_path: z.string().optional().describe("Local path to the source image (png/jpg/webp)."),
+    png_base64: z.string().optional().describe("Base64-encoded image (alternative to image_path)."),
+    image_url: z.string().optional().describe("URL to fetch the image from."),
+    auto: z.boolean().optional().describe("Auto-detect native grid + palette (default true)."),
+    colors: z.number().int().positive().optional().describe("Force a palette size; omit for auto."),
+    target_width: z.number().int().positive().optional().describe("Force output width (when auto is off)."),
+    target_height: z.number().int().positive().optional().describe("Force output height (when auto is off)."),
+    seed: z.number().int().optional().describe("Determinism seed (default 42)."),
+    output_path: z.string().optional().describe("If set, also save the pixelated PNG here."),
+    paint: z.boolean().optional().describe("Paint the result into the editor (default true)."),
+    as_new_document: z.boolean().optional().describe("Force new doc (true) or paint onto current (false)."),
+    name: z.string().optional().describe("Name for the new document, if created."),
+  },
+  async (a) => {
+    try {
+      let b64 = a.png_base64 ? stripDataUrl(a.png_base64) : undefined;
+      if (!b64 && a.image_path) b64 = (await readFile(a.image_path)).toString("base64");
+      if (!b64 && a.image_url) b64 = Buffer.from(await (await fetch(a.image_url)).arrayBuffer()).toString("base64");
+      if (!b64) return errText(new Error("provide image_path, png_base64, or image_url"));
+
+      const pargs = { png_base64: b64 };
+      if (a.auto != null) pargs.auto = a.auto;
+      if (a.colors != null) pargs.colors = a.colors;
+      if (a.target_width != null) pargs.target_width = a.target_width;
+      if (a.target_height != null) pargs.target_height = a.target_height;
+      if (a.seed != null) pargs.seed = a.seed;
+      const r = await call("canvas.pixelate", pargs, 60000);
+
+      let summary = `Pixelated to ${r.width}x${r.height}.`;
+      if (a.output_path) {
+        await writeFile(a.output_path, Buffer.from(r.png_base64, "base64"));
+        summary += ` Saved to ${a.output_path}.`;
+      }
+      if (a.paint !== false) {
+        const sargs = { png_base64: r.png_base64 };
+        if (a.as_new_document != null) sargs.as_new_document = a.as_new_document;
+        if (a.name) sargs.name = a.name;
+        const p = await call("canvas.set_image", sargs, 60000);
+        summary += ` Painted into PixelAOI (${p.document} document).`;
+      }
+      return {
+        content: [
+          { type: "text", text: summary },
+          { type: "image", data: r.png_base64, mimeType: "image/png" },
+        ],
+      };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "extrude_animate",
+  "Animate the current canvas as a 3D extrusion turntable: extrudes the silhouette and rotates it across the timeline, baking one keyframe per frame. Builds the frames for you. Great for a heart that turns side to side.",
+  {
+    frames: z.number().int().min(2).max(64).optional().describe("Timeline frame count (default 16)."),
+    from_deg: z.number().optional().describe("Start Y rotation, degrees (default -35)."),
+    to_deg: z.number().optional().describe("End Y rotation, degrees (default 35)."),
+    depth: z.number().optional().describe("Extrude depth %, default 70."),
+    tint: z.boolean().optional().describe("Keep source colors (default true)."),
+    rot_x: z.number().optional().describe("Fixed X tilt, degrees (default 12)."),
+    ping_pong: z.boolean().optional().describe("Swing back and forth (default true) vs one-way sweep."),
+  },
+  async (a) => {
+    try {
+      const args = {};
+      for (const k of ["frames", "from_deg", "to_deg", "depth", "tint", "rot_x", "ping_pong"]) {
+        if (a[k] != null) args[k] = a[k];
+      }
+      const r = await call("canvas.extrude_animate", args, 60000);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Baked ${r.frames} animation frames (turn ${r.from_deg}° -> ${r.to_deg}°). Play the timeline to see it.`,
+          },
+        ],
+      };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_node_kinds",
+  "The COMPLETE catalog of node kinds that can be added to a blueprint graph, grouped by category (use these exact names with blueprint_add_node). This is the full set of addable nodes — NOT the nodes already in the graph (use blueprint_list for that). Defaults to the active graph; pass `graph` to query a specific kind before selecting it.",
+  {
+    graph: z
+      .enum(["Particle", "Canvas", "Ai", "Layer"])
+      .optional()
+      .describe("Graph kind to query; omit for the active graph."),
+  },
+  async ({ graph }) => {
+    try {
+      const r = await call("blueprint.node_kinds", graph ? { graph } : undefined);
+      return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_list",
+  "Inspect the active blueprint graph: its kind, nodes (id, kind, position), links, and per-param value-wire bindings.",
+  {},
+  async () => {
+    try {
+      const r = await call("blueprint.list");
+      return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_select_graph",
+  "Switch which blueprint graph is active (Particle, Canvas, Ai, or Layer) and return its summary. Call this before adding nodes so they land in the right graph.",
+  { graph: z.enum(["Particle", "Canvas", "Ai", "Layer"]).describe("Graph kind to make active.") },
+  async ({ graph }) => {
+    try {
+      const r = await call("blueprint.select_graph", { graph });
+      return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_add_node",
+  "Add a node to the active blueprint graph; returns the new node id. `kind` is a NodeKind name, e.g. (Canvas graph) CanvasNoise, CanvasGradient, CanvasShape, CanvasFilter, CanvasColorAdjust, PaletteMap, CanvasOutput; (Particle graph) Emitter, Forces, Lifetime. Use blueprint_list to see what's wireable.",
+  {
+    kind: z.string().describe("NodeKind name, e.g. CanvasNoise or CanvasOutput."),
+    x: z.number().int().optional().describe("Graph X position (default 60)."),
+    y: z.number().int().optional().describe("Graph Y position (default 60)."),
+  },
+  async ({ kind, x, y }) => {
+    try {
+      const args = { kind };
+      if (x != null) args.x = x;
+      if (y != null) args.y = y;
+      const r = await call("blueprint.add_node", args);
+      return { content: [{ type: "text", text: `Added ${kind} as node ${r.id}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_connect",
+  "Connect node `from`'s output into node `to`'s input in the active graph (validated by the graph's wiring rules).",
+  {
+    from: z.number().int().describe("Source node id."),
+    to: z.number().int().describe("Destination node id."),
+  },
+  async ({ from, to }) => {
+    try {
+      await call("blueprint.connect", { from, to });
+      return { content: [{ type: "text", text: `Connected ${from} -> ${to}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_connect_value",
+  "Wire a VALUE node (ValueConstant/ValueSine/ValueMath/…) to drive a parameter of another node — the 'value wire' / param-pin connection. `param` is a CanvasAnimParam name (e.g. NoiseScale); omit it to drive the target's primary param.",
+  {
+    from: z.number().int().describe("Value node id (the driver)."),
+    to: z.number().int().describe("Target node id whose param is driven."),
+    param: z.string().optional().describe("CanvasAnimParam to drive; omit for the target's primary param."),
+  },
+  async ({ from, to, param }) => {
+    try {
+      const args = { from, to };
+      if (param) args.param = param;
+      await call("blueprint.connect_value", args);
+      return { content: [{ type: "text", text: `Value-wired ${from} -> ${to}${param ? " (" + param + ")" : ""}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_set_data",
+  "Set a node's discrete config (blend mode, shape kind, source mode, sizes, etc.). First call blueprint_list, copy that node's `data` object, change the field(s) you want, and pass the whole object back here. The data shape must match the node's current one.",
+  {
+    id: z.number().int().describe("Node id."),
+    data: z.record(z.any()).describe("The node's full `data` object (from blueprint_list) with your edits."),
+  },
+  async ({ id, data }) => {
+    try {
+      await call("blueprint.set_data", { id, data });
+      return { content: [{ type: "text", text: `Updated data on node ${id}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_set_param",
+  "Set a continuous node parameter. `param` is a CanvasAnimParam name, e.g. NoiseScale, FilterStrength, GradientAngle, ShapeSize, ThresholdLevel, Hue, OffsetX, OffsetY, Rate, Speed, Lifetime. `value` is a number (clamped to the param's valid range).",
+  {
+    id: z.number().int().describe("Node id."),
+    param: z.string().describe("CanvasAnimParam name, e.g. NoiseScale."),
+    value: z.number().describe("New value (clamped to range)."),
+  },
+  async ({ id, param, value }) => {
+    try {
+      await call("blueprint.set_param", { id, param, value });
+      return { content: [{ type: "text", text: `Set ${param} = ${value} on node ${id}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_delete_node",
+  "Delete a node (and any links touching it) from the active graph.",
+  { id: z.number().int().describe("Node id to delete.") },
+  async ({ id }) => {
+    try {
+      await call("blueprint.delete_node", { id });
+      return { content: [{ type: "text", text: `Deleted node ${id}.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+server.tool(
+  "blueprint_bake",
+  "Run / bake the active blueprint graph to the canvas (or to a layer/timeline, depending on the graph's output node).",
+  {},
+  async () => {
+    try {
+      const r = await call("blueprint.bake", undefined, 60000);
+      return { content: [{ type: "text", text: `Baked the ${r.baked} graph.` }] };
+    } catch (e) {
+      return errText(e);
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixelate-mcp",
-  "version": "0.3.0",
-  "description": "MCP server: turn any image into grid-perfect pixel art via the Pixelate Cloud API. Works in Codex, Claude Desktop, Cursor.",
+  "version": "0.3.1",
+  "description": "MCP server to drive the PixelAOI editor: see the canvas, paint pixel art, pixelate images locally, run editor commands, and build node-based blueprints.",
   "type": "module",
   "bin": {
     "pixelate-mcp": "index.js"
@@ -11,17 +11,16 @@
     "README.md",
     "LICENSE"
   ],
+  "homepage": "https://pixelaoi.pro",
   "keywords": [
     "mcp",
     "model-context-protocol",
     "pixel-art",
+    "pixelaoi",
     "pixelate",
     "codex",
-    "claude",
-    "cursor",
-    "aseprite"
+    "claude"
   ],
-  "homepage": "https://pixelaoi.pro",
   "license": "MIT",
   "author": "PixelAOI",
   "engines": {
@@ -29,7 +28,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "sharp": "^0.33.5",
     "zod": "^3.23.8"
   }
 }