pixelate-mcp 0.3.1 → 0.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 PixelAOI
-
-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.
+MIT License
+
+Copyright (c) 2026 PixelAOI
+
+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

@@ -1,20 +1,19 @@
-# pixelate-mcp
+# PixelAOI MCP
 
-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.
+An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Claude
+Code, Codex, Cursor, Claude Desktop) work in the **PixelAOI** pixel-art editor:
+see the canvas, paint it, arrange layers, build animations, apply filters and
+adjustment layers, pixelate images, and wire Blueprint node graphs.
 
 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.
+localhost-only link (`127.0.0.1`). No cloud, no accounts, no API keys.
 
-## 1. Enable the bridge in PixelAOI
+## 1. Turn on the agent link in PixelAOI
 
-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.)
+Click **agent off** in PixelAOI's status bar (bottom right). It turns to
+**agent ready** while it waits, and **agent live** once your agent connects.
+Click it again to turn it off. (Or start PixelAOI with
+`PIXELAOI_AGENT_BRIDGE=1`.)
 
 ## 2. Add the server to your agent
 
@@ -33,62 +32,125 @@ args = ["-y", "pixelate-mcp"]
 ### Claude Desktop / Cursor (JSON config)
 ```json
 {
-  "command": "npx",
-  "args": ["-y", "pixelate-mcp"]
+  "mcpServers": {
+    "pixelaoi": { "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.
+Restart the agent, make sure PixelAOI says **agent ready**, and ask it to
+draw something. The server shows up as **PixelAOI**, with the PixelAOI mark
+(in colours for light and dark clients), and tells the agent how to work with
+the editor when it connects.
 
 ## 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):
-
-- **`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.
+Each tool has a title your client can show, and says whether it only reads or
+changes the document, so a client can let reads through and ask before
+changes. Every change is one undo step in PixelAOI (`run_command` `undo` takes
+it back).
+
+| Tool | Title | |
+|---|---|---|
+| `get_state` | Editor state | reads |
+| `get_canvas_image` | See the canvas | reads |
+| `run_command` | Run a command | changes |
+| `apply_filter` | Apply a filter | changes |
+| `layers` | Arrange layers | changes |
+| `adjustment_layer` | Adjustment layers | changes |
+| `set_canvas_image` | Paint an image | changes |
+| `set_pixels` | Paint pixels | changes |
+| `pixelate_image` | Pixelate an image | changes (may fetch a URL) |
+| `extrude_animate` | 3D turntable | changes |
+| `add_frame` | Add a frame | adds |
+| `select_frame` | Show a frame | adds |
+| `set_frame_duration` | Frame timing | changes |
+| `add_tag` | Tag frames | adds |
+| `save_document` | Save the project | changes |
+| `close_document` | Close the document | changes |
+| `blueprint_node_kinds` | Blueprint node kinds | reads |
+| `blueprint_list` | Read the Blueprint | reads |
+| `blueprint_select_graph` | Switch Blueprint graph | adds |
+| `blueprint_add_node` | Add a node | adds |
+| `blueprint_connect` | Connect nodes | adds |
+| `blueprint_connect_value` | Drive a parameter | adds |
+| `blueprint_set_param` | Set a parameter | changes |
+| `blueprint_set_data` | Set node data | changes |
+| `blueprint_delete_node` | Delete a node | changes |
+| `blueprint_bake` | Bake the Blueprint | changes |
+
+In more detail:
+
+- **`get_state`**: canvas size, frames, the layer stack (each layer's index and
+  uid, each folder's id), the selection, the tool, the palette, the Blueprint
+  editor's state, and the command names `run_command` takes.
+- **`get_canvas_image`**: the current frame as PixelAOI shows it, as a PNG.
+- **`run_command`** `{ action }`: a command by name (`flip_h`, `rotate_90`,
+  `trim`, `undo`, `save`, ...). A filter's name (`invert`, `blur`, ...)
+  applies it at once with its remembered settings.
+- **`apply_filter`** `{ name, params?, output?, frames? }`: a filter on the
+  active layer as one undo step: `blur`, `hsl_adjust`, `levels`, `outline`,
+  `drop_shadow`, `color_reduce`, ... `params` by the labels PixelAOI shows
+  (`{"Radius": 3}`, `{"Hue": 30}`) or in order; `output` `pixels` (default),
+  `new_layer` or `adjustment` (an adjustment layer doing it live, with
+  `affects` `layer` or `below`); `frames` `this` (default), `selected` or
+  `all`. A selection limits it. Curves takes points per channel,
+  `{"all": [[input, output], ...], "red": ...}`, and Gradient Map a ramp,
+  `{"stops": [[position, r, g, b], ...]}` (0-255, at most 16 points or stops).
+- **`adjustment_layer`** `{ action, kind?, params?, affects?, enabled?, item? }`:
+  layers with no art of their own that change what is under them, live: `add`,
+  `set`, `remove`, `bake`.
+- **`layers`** `{ action, items?, … }`: `select`, `move`, `group`, `ungroup`,
+  `new_folder`, `set` (`visible`, `locked`, `opacity`, `blend`, `draft`,
+  `clipping`, `expanded`, `name`), `delete`, `duplicate`, `merge`. A layer by
+  its index, `{layer: i}` or `{uid: "…"}`; a folder by `{folder: id}`; no
+  `items` means the selection.
+- **`set_canvas_image`** `{ image_path | png_base64, as_new_document?, name? }`:
+  paint an image; at the canvas's size it paints the open document, otherwise
+  it opens as a new one.
+- **`set_pixels`** `{ x, y, w, h, rgba_base64 }`: a raw RGBA block, clipped to
+  the canvas.
+- **`pixelate_image`**: any image (path, base64 or URL) into grid-perfect
+  pixel art with PixelAOI's own engine (it finds the native grid and palette),
+  then painted in.
+- **`extrude_animate`**: a 3D extrusion turntable of the canvas across the
+  timeline.
+- **`add_frame`**, **`select_frame`** `{ index }`, **`set_frame_duration`**
+  `{ index?, duration_ms }`, **`add_tag`** `{ name, from, to? }`: build an
+  animation (frames from 0; 10-10000 ms a frame).
+- **`save_document`** `{ path }`: save as a `.pxl` project at an absolute path;
+  **`close_document`**: close the tab once saved (refused while unsaved).
+- **Blueprints**: switch the graph (`Particle`, `Canvas`, `Ai`, `Layer`), list
+  the node kinds, add, wire (output to input, or a value node driving a
+  parameter), set parameters and node data, delete, and bake the result into
+  the document.
+
+PixelAOI refuses changes while one of its dialogs or a filter is open, or while
+you are drawing; the error says which, and the call can be made again after.
 
 ## Example
 
 > "Take ./hero.png, pixelate it, put it on the canvas, then bake a noise
 > texture behind it with a Canvas blueprint."
 
-The agent calls `pixelate_image` (local engine), then builds
-CanvasNoise -> CanvasOutput with the blueprint tools and runs
-`blueprint_bake`.
+The agent calls `pixelate_image`, then builds CanvasNoise → CanvasOutput with
+the Blueprint tools and runs `blueprint_bake`.
 
 ## Config
 
 - `PIXELAOI_BRIDGE_HOST` (default `127.0.0.1`)
 - `PIXELAOI_BRIDGE_PORT` (default `48653`)
 
+## If it can't connect
+
+The error says so and how to fix it: open PixelAOI and click **agent off** so
+it says **agent ready**. If the editor closes while the agent works, the next
+call reconnects once it is back.
+
+## As a Claude Desktop extension
+
+`manifest.json` and `icon.png` describe it as a Desktop Extension (its name,
+icon, tools, and the editor's port as a setting). Build the `.mcpb` with
+`npx @anthropic-ai/mcpb pack` in this folder, then open it with Claude Desktop.
+
 Get the editor at [pixelaoi.pro](https://pixelaoi.pro).

package/index.js

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
+// PixelAOI's MCP server: lets an AI agent (Claude Code, Codex, Cursor, Claude
+// Desktop) drive the PixelAOI editor running on this computer. It speaks MCP
+// over stdio and reaches the editor over its agent bridge, a localhost-only
+// TCP link (127.0.0.1:48653) that the user turns on from PixelAOI's status bar.
 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 VERSION = "0.6.0";
 const HOST = process.env.PIXELAOI_BRIDGE_HOST || "127.0.0.1";
 const PORT = Number(process.env.PIXELAOI_BRIDGE_PORT || 48653);
 
+// ── The bridge ─────────────────────────────────────────────────────────────
+// One JSON request per line ({id, op, args}), answered in order
+// ({id, ok, result | error}).
 
 let sock = null;
 let connected = false;
@@ -24,7 +32,7 @@ function teardown(err) {
   buffer = "";
   for (const [, p] of pending) {
     clearTimeout(p.timer);
-    p.reject(err || new Error("bridge disconnected"));
+    p.reject(err || new Error("the link to PixelAOI closed"));
   }
   pending.clear();
 }
@@ -34,18 +42,26 @@ function connect() {
   return new Promise((resolve, reject) => {
     const s = net.createConnection({ host: HOST, port: PORT });
     s.setNoDelay(true);
+    let opened = false;
     s.once("connect", () => {
+      opened = true;
       sock = s;
       connected = true;
       resolve();
     });
-    s.once("error", (e) => {
+    // Every error is handled: before the link opens it says how to turn it
+    // on; after, the link is torn down (an unhandled one would end the server).
+    s.on("error", (e) => {
+      if (opened) {
+        teardown(new Error(`the link to PixelAOI broke (${e.code || e.message})`));
+        return;
+      }
       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})`,
+          `can't reach PixelAOI at ${HOST}:${PORT} (${e.code || e.message}). Open PixelAOI and click ` +
+            `"agent off" in its status bar: it turns to "agent ready", then "agent live" once this is connected. ` +
+            `(Or start PixelAOI with PIXELAOI_AGENT_BRIDGE=1.)`,
         ),
       );
     });
@@ -67,10 +83,10 @@ function connect() {
         pending.delete(msg.id);
         clearTimeout(p.timer);
         if (msg.ok) p.resolve(msg.result);
-        else p.reject(new Error(msg.error || "bridge error"));
+        else p.reject(new Error(msg.error || "PixelAOI refused it"));
       }
     });
-    s.on("close", () => teardown(new Error("bridge connection closed")));
+    s.on("close", () => teardown(new Error("the link to PixelAOI closed")));
   });
 }
 
@@ -80,7 +96,7 @@ async function call(op, args, timeoutMs = 30000) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       pending.delete(id);
-      reject(new Error(`bridge op '${op}' timed out after ${timeoutMs}ms`));
+      reject(new Error(`PixelAOI didn't answer '${op}' within ${timeoutMs / 1000}s`));
     }, timeoutMs);
     pending.set(id, { resolve, reject, timer });
     try {
@@ -93,374 +109,605 @@ async function call(op, args, timeoutMs = 30000) {
   });
 }
 
-const errText = (e) => ({
-  content: [{ type: "text", text: `pixelaoi-mcp error: ${e?.message || e}` }],
-  isError: true,
-});
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const json = (head, value) => text(head ? `${head}\n${JSON.stringify(value, null, 2)}` : JSON.stringify(value, null, 2));
 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" });
+// ── The server ─────────────────────────────────────────────────────────────
+
+// The PixelAOI mark: Dark's colours for dark clients, Light's for light ones.
+const ICON_DARK =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAvUlEQVR42u3avQ3CMBCA0TPKIIxEQcUoUUrENBSwDSWbmAniE4qsIPy+AfLzJMvROeX8ftRodD+eSmwou35W7/sfYvAAAAAAAMDIpXvscqvNffQ6l7LnC2x9PksAAAAAAAAM3JTto6/Ls32Fed8XyJ5viWoeAAAAAAAAAEiSJMV35wLReW6f1fvcwacwAAAAAAAI5wI/e/7f+zvEEgAAAAAAAOYB/hO0BAAAAAAAgHnA/2UeYAkAAAAAAIDVPvCjNhDw4v7bAAAAAElFTkSuQmCC";
+const ICON_LIGHT =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAvklEQVR42u3avQ3CMBCA0TOih3lYJWV6RmAIepdswGDJBDABPqHICsLvGyA/T7IcnVNO9fqKRut8L7Gh7PpZve9/iMEDAAAAAAAjl+6x07w099FHPZc9X2Dr81kCAAAAAABg4I7ZPvq83NpXqPu+QPZ8UyzmAQAAAAAAAIAkSVJ8dy4Qnef2Wb3PHXwKAwAAAACAcC7ws+f/vb9DLAEAAAAAAGAe4D9BSwAAAAAAAJgH/F/mAZYAAAAAAAD42BuQGzL/MDRAkgAAAABJRU5ErkJggg==";
+
+const INSTRUCTIONS = `PixelAOI is a pixel-art editor running on this computer; these tools drive it. They reach it over a local link the user turns on in PixelAOI: its status bar says "agent off" until clicked, "agent ready" while it waits, "agent live" once you are connected. If a call can't reach it, ask the user to click that pill.
+- Start with get_state: the canvas size, the frames, the layer stack (with each layer's index and uid), the selection, the active tool and the command names run_command takes. Look with get_canvas_image before and after changes.
+- Every change is one undo step in the editor, with a name; run_command "undo" takes the last one back.
+- Frames count from 0. set_canvas_image and set_pixels paint the active layer of the frame on show; add_frame, select_frame, set_frame_duration and add_tag build animations.
+- Blueprints (node graphs): blueprint_select_graph, blueprint_node_kinds, blueprint_add_node, blueprint_connect / blueprint_connect_value, blueprint_set_param / blueprint_set_data, then blueprint_bake.
+- PixelAOI refuses changes while one of its dialogs or a filter is open, or while the user is drawing; the error says which. Ask the user to finish, then try again.`;
+
+const server = new McpServer(
+  {
+    name: "pixelaoi",
+    title: "PixelAOI",
+    version: VERSION,
+    description:
+      "Drive the PixelAOI pixel-art editor: see the canvas, paint it, arrange layers, build animations, apply filters and adjustment layers, and wire Blueprint node graphs.",
+    websiteUrl: "https://pixelaoi.pro",
+    icons: [
+      { src: ICON_DARK, mimeType: "image/png", sizes: ["64x64"], theme: "dark" },
+      { src: ICON_LIGHT, mimeType: "image/png", sizes: ["64x64"], theme: "light" },
+    ],
+  },
+  { instructions: INSTRUCTIONS },
+);
+
+// What a client may show before running a tool: whether it only reads, or
+// changes the document (every change is one undo step in PixelAOI), and
+// whether running it twice does the same as once. Nothing here reaches
+// beyond this computer, except pixelate_image given a URL.
+const READS = { readOnlyHint: true, openWorldHint: false };
+const ADDS = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const CHANGES = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+
+function tool(name, { title, description, input, annotations }, run) {
+  server.registerTool(
+    name,
+    { title, description, inputSchema: input ?? {}, annotations: { title, ...annotations } },
+    async (args) => {
+      try {
+        return await run(args ?? {});
+      } catch (e) {
+        return { content: [{ type: "text", text: `PixelAOI: ${e?.message || e}` }], isError: true };
+      }
+    },
+  );
+}
+
+// ── Seeing ─────────────────────────────────────────────────────────────────
 
-server.tool(
+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);
-    }
+  {
+    title: "Editor state",
+    description:
+      "What is open in PixelAOI: the canvas size, the frames and the one on show, the layer stack (layers and folders, top to bottom, with each layer's index and uid and each folder's id) and the selection, the active tool, the palette size, the Blueprint editor's state, and the command names run_command takes.",
+    annotations: READS,
   },
+  async () => json("", await call("state.get")),
 );
 
-server.tool(
+tool(
   "get_canvas_image",
-  "See the current canvas: returns the composited current frame as a PNG image.",
-  {},
+  {
+    title: "See the canvas",
+    description: "The current frame as PixelAOI shows it (every visible layer together), as a PNG.",
+    annotations: READS,
+  },
   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);
-    }
+    const r = await call("canvas.get");
+    return {
+      content: [
+        { type: "text", text: `The canvas, ${r.width}×${r.height}.` },
+        { type: "image", data: r.png_base64, mimeType: "image/png" },
+      ],
+    };
   },
 );
 
-server.tool(
+// ── Commands, filters, layers ──────────────────────────────────────────────
+
+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") },
+  {
+    title: "Run a command",
+    description:
+      "Run one of PixelAOI's commands by name: flip_h, flip_v, rotate_90, trim, undo, redo, save and the rest of get_state's commands list. A filter's name (invert, blur, ...) applies it at once with its remembered settings, as one undo step.",
+    input: { action: z.string().describe("A command name from get_state's commands.") },
+    annotations: CHANGES,
+  },
   async ({ action }) => {
-    try {
-      await call("command.run", { action });
-      return { content: [{ type: "text", text: `Ran '${action}'.` }] };
-    } catch (e) {
-      return errText(e);
-    }
+    await call("command.run", { action });
+    return text(`Ran ${action}.`);
+  },
+);
+
+tool(
+  "apply_filter",
+  {
+    title: "Apply a filter",
+    description:
+      "Apply a filter to the active layer, as one undo step named after it: invert, desaturate, posterize, brightness_contrast, hsl_adjust, levels, curves, gradient_map, palettize, blur, pixelate, outline, drop_shadow, despeckle, convolve, convolve_5x5, color_reduce, palette_variants (the user's variant on show; it has no settings). Settings the call leaves out keep the user's remembered (or default) values. A selection limits it, as in the editor. With output adjustment, every filter but color_reduce becomes an adjustment layer instead: the art stays as it is and the change can be edited or applied later (see adjustment_layer).",
+    input: {
+      name: z.string().describe("The filter, e.g. blur or hsl_adjust."),
+      params: z
+        .union([z.record(z.any()), z.array(z.number().int())])
+        .optional()
+        .describe(
+          'Settings by the labels PixelAOI shows ({"Radius": 3}, {"Hue": 30, "Saturation": -20}) or in order. Curves (an object only): {"all": [[input, output], ...], "red"/"green"/"blue": ...}, 0-255, at most 16 points a channel; channels left out keep the remembered curve. Gradient Map (an object only): {"stops": [[position, r, g, b], ...]}, 0-255, 1 to 16 stops. Palette Cycling (an object only, adjustment output only): {"runs": [{"colours": [[r, g, b], ...], "every": 1, "reverse": false}]}, at most 8 runs of 64 colours, every 1-16 frames a step. Convolve: "Divide by" 0 = Auto (the sum of the weights), 1 = the Divisor; giving a Divisor selects it. Outline and Drop Shadow take their colour as color: [r, g, b].',
+        ),
+      output: z
+        .enum(["pixels", "new_layer", "adjustment"])
+        .optional()
+        .describe("Change the layer (default), put the result on a new layer above it, or add an adjustment layer doing it live (every filter but color_reduce; palette_cycling only this way)."),
+      affects: z
+        .enum(["layer", "below"])
+        .optional()
+        .describe("output adjustment: only the layer under it (default), or everything under it in its folder."),
+      frames: z.enum(["this", "selected", "all"]).optional().describe("Which frames (default: the frame on show)."),
+    },
+    annotations: CHANGES,
+  },
+  async (a) => {
+    const args = { name: a.name };
+    if (a.params != null) args.params = a.params;
+    if (a.output) args.output = a.output;
+    if (a.affects) args.affects = a.affects;
+    if (a.frames) args.frames = a.frames;
+    const r = await call("filter.apply", args, 60000);
+    if (a.output === "adjustment") return text(`${r.undo_label}: adjustment layer ${r.layer} (uid ${r.uid}); the art is unchanged.`);
+    return text(r.undo_label ? `Applied ${r.ran} on ${r.frames_written} frame(s) (undo: ${r.undo_label}).` : `${r.ran} changed nothing (no undo step).`);
   },
 );
 
-server.tool(
+// A layer by its index (as get_state's stack lists it), {layer: index} or
+// {uid: "…"} (the uid as text, as the stack gives it: it is too big for a JS
+// number); a folder by {folder: id}.
+const stackItem = z.union([
+  z.number().int().nonnegative(),
+  z.object({ layer: z.number().int().nonnegative() }),
+  z.object({ uid: z.union([z.string(), z.number().int().nonnegative()]) }),
+  z.object({ folder: z.number().int().nonnegative() }),
+]);
+
+tool(
+  "layers",
+  {
+    title: "Arrange layers",
+    description:
+      "Arrange the layer stack: select, move, group, ungroup, new_folder, set, delete, duplicate or merge. Each change is one undo step and every frame follows. Name a layer by its index (as get_state's stack lists it), {layer: index} or {uid: '…'} (the uid text the stack gives, which survives moves); a folder by {folder: id}. Leaving out items acts on the current selection. Folders hold layers and folders (drawn together, then laid down at the folder's opacity) and may be empty. Locked layers and folders stay put, and nothing moves past a locked layer. Returns the stack (top to bottom) and the selection.",
+    input: {
+      action: z
+        .enum(["select", "move", "group", "ungroup", "new_folder", "set", "delete", "duplicate", "merge"])
+        .describe("select: choose items; move: put items at a place; group: items into a new folder where the topmost is; ungroup: a folder away, what it held staying; new_folder: an empty folder (default: above the focus); set: change items; delete; duplicate (each copy right above its original); merge: selected layers into the lowest."),
+      items: z.array(stackItem).optional().describe("What to act on (default: the selection)."),
+      focus: stackItem.optional().describe("select: the one painted and filtered (default: the last named)."),
+      above: stackItem.optional().describe("move / new_folder: right above this item, in its folder."),
+      below: stackItem.optional().describe("move / new_folder: right below this item, in its folder."),
+      into: z.number().int().nonnegative().nullable().optional().describe("move / new_folder: into this folder (its id), or null for the top level."),
+      position: z.enum(["top", "bottom"]).optional().describe("With into: the folder's top (default) or bottom."),
+      folder: z.number().int().nonnegative().optional().describe("ungroup: the folder's id."),
+      name: z.string().optional().describe("group / new_folder: the new folder's name; set: one item's name."),
+      visible: z.boolean().optional().describe("set: shown or hidden (a lighting map: used by lighting or not)."),
+      locked: z.boolean().optional().describe("set: locked or not."),
+      opacity: z.number().int().min(0).max(255).optional().describe("set: 0-255 (a folder's own opacity for a folder)."),
+      blend: z.string().optional().describe("set: a layer's blend mode by name (Normal, Multiply, Screen, Overlay, Soft Light, …)."),
+      draft: z.boolean().optional().describe("set: a layer left out of exports."),
+      clipping: z.boolean().optional().describe("set: a layer clipped to the one under it."),
+      expanded: z.boolean().optional().describe("set: a folder open or folded in the panel."),
+    },
+    annotations: CHANGES,
+  },
+  async (a) => {
+    const { action, ...rest } = a;
+    const args = {};
+    for (const [k, v] of Object.entries(rest)) if (v !== undefined) args[k] = v;
+    const r = await call(`layer.${action}`, args);
+    return json(r.undo_label ? `${r.undo_label} (one undo step).` : "Selected.", { stack: r.stack, selection: r.selection });
+  },
+);
+
+tool(
+  "adjustment_layer",
+  {
+    title: "Adjustment layers",
+    description:
+      "Adjustment layers: a layer with no art of its own that changes what is under it, live, and can be changed again or applied any time (the art under it stays as it is). add: a new one right above the layer in focus (its mask: the selection, else everything; one mask for every frame). set: change one's settings, its eye (enabled) or what it affects. remove: delete it. bake: apply it to the pixels of what it changes, in every frame, and remove it (refused while another adjustment under it changes the same layers: bake that one first). Kinds: invert, desaturate, posterize, brightness_contrast, hsl_adjust, levels, curves, gradient_map, palette_variants (a copy of the user's variant on show), palettize (snap to a copy of the active palette), palette_cycling (runs of colours stepping once a frame; give its runs as params), outline and drop_shadow (their colour as params color: [r, g, b]), blur, pixelate, despeckle, convolve, convolve_5x5. A new one takes the focus, and filters refuse an adjustment layer in focus: select an art layer before apply_filter. Its strength is the layer's opacity (layers set). Each call is one undo step. Returns the stack (top to bottom) and the selection.",
+    input: {
+      action: z.enum(["add", "set", "remove", "bake"]),
+      kind: z.string().optional().describe("add: what it does (levels, hsl_adjust, palettize, ...)."),
+      params: z
+        .union([z.record(z.any()), z.array(z.number().int())])
+        .optional()
+        .describe('add / set: settings as apply_filter takes them ({"Hue": 30}, Curves points, Gradient Map stops, Palette Cycling runs); set merges them into its own.'),
+      affects: z
+        .enum(["layer", "below"])
+        .optional()
+        .describe("add (default layer) / set: only the layer (or folder) right under it, or everything under it in its folder."),
+      enabled: z.boolean().optional().describe("set: its eye, on or off."),
+      item: stackItem.optional().describe("set / remove / bake: which adjustment layer (default: the one in focus)."),
+    },
+    annotations: CHANGES,
+  },
+  async (a) => {
+    const args = {};
+    for (const [k, v] of Object.entries(a)) if (v !== undefined) args[k] = v;
+    const r = await call("layer.adjustment", args, 60000);
+    return json(r.undo_label ? `${r.undo_label} (one undo step).` : "Nothing changed.", { stack: r.stack, selection: r.selection });
+  },
+);
+
+// ── Painting ───────────────────────────────────────────────────────────────
+
+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."),
+    title: "Paint an image",
+    description:
+      "Paint an image (a pixelated PNG, say) into PixelAOI. When it matches the canvas size it paints onto the open document; when not, it opens as a NEW document (as_new_document overrides that). Give exactly one of image_path or png_base64.",
+    input: {
+      image_path: z.string().optional().describe("Local path to a PNG/JPG/WEBP to paint."),
+      png_base64: z.string().optional().describe("Base64-encoded image (instead of image_path)."),
+      as_new_document: z.boolean().optional().describe("A new document (true) or onto the open canvas (false). Default: by size."),
+      name: z.string().optional().describe("The new document's name, when one is made."),
+    },
+    annotations: CHANGES,
   },
   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);
-    }
+    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) throw new Error("give 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 text(`Painted ${r.width}×${r.height} (${r.document} document).`);
   },
 );
 
-server.tool(
+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."),
+    title: "Paint pixels",
+    description:
+      "Paint a raw RGBA block onto the canvas at (x, y), clipped to the canvas. rgba_base64 is base64 of exactly w*h*4 RGBA bytes (row by row, from the top left).",
+    input: {
+      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."),
+    },
+    annotations: { ...CHANGES, idempotentHint: true },
   },
   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);
-    }
+    await call("canvas.set_pixels", { x: a.x, y: a.y, w: a.w, h: a.h, rgba_base64: stripDataUrl(a.rgba_base64) });
+    return text(`Painted ${a.w}×${a.h} at (${a.x}, ${a.y}).`);
   },
 );
 
-server.tool(
+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."),
+    title: "Pixelate an image",
+    description:
+      "Turn an image into grid-perfect pixel art with PixelAOI's own engine, on this computer (it finds the native grid and palette), then paint it into PixelAOI. No cloud and no key. Give exactly one of image_path, png_base64 or image_url.",
+    input: {
+      image_path: z.string().optional().describe("Local path to the source image (png/jpg/webp)."),
+      png_base64: z.string().optional().describe("Base64-encoded image (instead of image_path)."),
+      image_url: z.string().optional().describe("A URL to fetch the image from."),
+      auto: z.boolean().optional().describe("Find the native grid and palette (default true)."),
+      colors: z.number().int().positive().optional().describe("A palette size; leave out for auto."),
+      target_width: z.number().int().positive().optional().describe("The output width (when auto is off)."),
+      target_height: z.number().int().positive().optional().describe("The output height (when auto is off)."),
+      seed: z.number().int().optional().describe("Determinism seed (default 42)."),
+      output_path: z.string().optional().describe("Also save the pixelated PNG here."),
+      paint: z.boolean().optional().describe("Paint the result into PixelAOI (default true)."),
+      as_new_document: z.boolean().optional().describe("A new document (true) or onto the open canvas (false)."),
+      name: z.string().optional().describe("The new document's name, when one is made."),
+    },
+    annotations: { ...CHANGES, openWorldHint: true },
   },
   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);
+    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) throw new Error("give image_path, png_base64 or image_url");
+    const pargs = { png_base64: b64 };
+    for (const k of ["auto", "colors", "target_width", "target_height", "seed"]) if (a[k] != null) pargs[k] = a[k];
+    const r = await call("canvas.pixelate", pargs, 60000);
+    let summary = `Pixelated to ${r.width}×${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" },
+      ],
+    };
   },
 );
 
-server.tool(
+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."),
+    title: "3D turntable",
+    description:
+      "Animate the canvas as a 3D extrusion turntable: the silhouette is extruded and turned across the timeline, one frame per step, built for you. A heart that turns side to side, a coin that spins.",
+    input: {
+      frames: z.number().int().min(2).max(64).optional().describe("How many frames (default 16)."),
+      from_deg: z.number().optional().describe("Start turn, degrees (default -35)."),
+      to_deg: z.number().optional().describe("End turn, degrees (default 35)."),
+      depth: z.number().optional().describe("Extrusion depth %, default 70."),
+      tint: z.boolean().optional().describe("Keep the source's colours (default true)."),
+      rot_x: z.number().optional().describe("A fixed tilt, degrees (default 12)."),
+      ping_pong: z.boolean().optional().describe("Swing back and forth (default true), or one sweep."),
+    },
+    annotations: CHANGES,
   },
   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);
-    }
+    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 text(`Baked ${r.frames} frames (turning ${r.from_deg}° to ${r.to_deg}°). Play the timeline to see it.`);
   },
 );
 
-server.tool(
+// ── Blueprints ─────────────────────────────────────────────────────────────
+
+const GRAPH = z.enum(["Particle", "Canvas", "Ai", "Layer"]);
+
+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);
-    }
+    title: "Blueprint node kinds",
+    description:
+      "Every kind of node a Blueprint graph can take, by category (use these names with blueprint_add_node). This is the catalog, not the nodes in the graph (see blueprint_list). The active graph's, or another kind's with graph.",
+    input: { graph: GRAPH.optional().describe("The graph kind to ask about; the active graph's when left out.") },
+    annotations: READS,
   },
+  async ({ graph }) => json("", await call("blueprint.node_kinds", graph ? { graph } : undefined)),
 );
 
-server.tool(
+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);
-    }
+  {
+    title: "Read the Blueprint",
+    description: "The active Blueprint graph: its kind, its nodes (id, kind, position, data), its links and each parameter's value wire.",
+    annotations: READS,
   },
+  async () => json("", await call("blueprint.list")),
 );
 
-server.tool(
+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);
-    }
+  {
+    title: "Switch Blueprint graph",
+    description: "Make a Blueprint graph kind active (Particle, Canvas, Ai or Layer) and return its summary. Do this before adding nodes, so they land in the right graph.",
+    input: { graph: GRAPH.describe("The graph kind to make active.") },
+    annotations: { ...ADDS, idempotentHint: true },
   },
+  async ({ graph }) => json("", await call("blueprint.select_graph", { graph })),
 );
 
-server.tool(
+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)."),
+    title: "Add a node",
+    description:
+      "Add a node to the active Blueprint graph; returns its id. kind is a node kind's name, e.g. (Canvas graph) CanvasNoise, CanvasGradient, CanvasShape, CanvasFilter, CanvasColorAdjust, PaletteMap, CanvasOutput; (Particle graph) Emitter, Forces, Lifetime. See blueprint_node_kinds for them all.",
+    input: {
+      kind: z.string().describe("The node kind, 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)."),
+    },
+    annotations: ADDS,
   },
   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);
-    }
+    const args = { kind };
+    if (x != null) args.x = x;
+    if (y != null) args.y = y;
+    const r = await call("blueprint.add_node", args);
+    return text(`Added ${kind} as node ${r.id}.`);
   },
 );
 
-server.tool(
+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."),
+    title: "Connect nodes",
+    description: "Wire node from's output into node to's input in the active graph (checked against the graph's rules).",
+    input: {
+      from: z.number().int().describe("The source node's id."),
+      to: z.number().int().describe("The destination node's id."),
+    },
+    annotations: ADDS,
   },
   async ({ from, to }) => {
-    try {
-      await call("blueprint.connect", { from, to });
-      return { content: [{ type: "text", text: `Connected ${from} -> ${to}.` }] };
-    } catch (e) {
-      return errText(e);
-    }
+    await call("blueprint.connect", { from, to });
+    return text(`Connected ${from} → ${to}.`);
   },
 );
 
-server.tool(
+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."),
+    title: "Drive a parameter",
+    description:
+      "Wire a value node (ValueConstant, ValueSine, ValueMath, …) to drive a parameter of another node: a value wire. param is a parameter's name (e.g. NoiseScale); leave it out to drive the target's main one.",
+    input: {
+      from: z.number().int().describe("The value node's id (the driver)."),
+      to: z.number().int().describe("The node whose parameter it drives."),
+      param: z.string().optional().describe("The parameter to drive; the target's main one when left out."),
+    },
+    annotations: ADDS,
   },
   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);
-    }
+    const args = { from, to };
+    if (param) args.param = param;
+    await call("blueprint.connect_value", args);
+    return text(`Value-wired ${from} → ${to}${param ? ` (${param})` : ""}.`);
   },
 );
 
-server.tool(
+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."),
+    title: "Set node data",
+    description:
+      "Set a node's settings that aren't numbers (blend mode, shape kind, source mode, sizes, …). Call blueprint_list, copy that node's data object, change the fields you want, and pass the whole object back. Its shape must match the node's.",
+    input: {
+      id: z.number().int().describe("The node's id."),
+      data: z.record(z.any()).describe("The node's whole data object (from blueprint_list), with your changes."),
+    },
+    annotations: { ...CHANGES, idempotentHint: true },
   },
   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);
-    }
+    await call("blueprint.set_data", { id, data });
+    return text(`Updated node ${id}'s data.`);
   },
 );
 
-server.tool(
+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)."),
+    title: "Set a parameter",
+    description:
+      "Set a node's number parameter: NoiseScale, FilterStrength, GradientAngle, ShapeSize, ThresholdLevel, Hue, OffsetX, OffsetY, Rate, Speed, Lifetime, … The value is kept within the parameter's range.",
+    input: {
+      id: z.number().int().describe("The node's id."),
+      param: z.string().describe("The parameter, e.g. NoiseScale."),
+      value: z.number().describe("Its new value (kept within its range)."),
+    },
+    annotations: { ...CHANGES, idempotentHint: true },
   },
   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);
-    }
+    await call("blueprint.set_param", { id, param, value });
+    return text(`Set ${param} = ${value} on node ${id}.`);
   },
 );
 
-server.tool(
+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.") },
+  {
+    title: "Delete a node",
+    description: "Delete a node, and the links touching it, from the active graph.",
+    input: { id: z.number().int().describe("The node to delete.") },
+    annotations: CHANGES,
+  },
   async ({ id }) => {
-    try {
-      await call("blueprint.delete_node", { id });
-      return { content: [{ type: "text", text: `Deleted node ${id}.` }] };
-    } catch (e) {
-      return errText(e);
-    }
+    await call("blueprint.delete_node", { id });
+    return text(`Deleted node ${id}.`);
   },
 );
 
-server.tool(
+tool(
   "blueprint_bake",
-  "Run / bake the active blueprint graph to the canvas (or to a layer/timeline, depending on the graph's output node).",
-  {},
+  {
+    title: "Bake the Blueprint",
+    description: "Run the active Blueprint graph and bake what it makes into the document: the canvas, a layer or the timeline, as its output node says.",
+    annotations: CHANGES,
+  },
   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);
-    }
+    const r = await call("blueprint.bake", undefined, 60000);
+    return text(`Baked the ${r.baked} graph.`);
+  },
+);
+
+// ── Animation and files ────────────────────────────────────────────────────
+
+tool(
+  "add_frame",
+  {
+    title: "Add a frame",
+    description:
+      "Add a blank frame right after the one on show and show it, as the timeline's + does (one undo step). Paint it with set_canvas_image or set_pixels, which write the active layer of the frame on show.",
+    annotations: ADDS,
+  },
+  async () => {
+    const r = await call("frame.add");
+    return text(`Frame ${r.frame} of ${r.frames} added and on show.`);
+  },
+);
+
+tool(
+  "select_frame",
+  {
+    title: "Show a frame",
+    description: "Show a frame (from 0), as clicking it in the timeline does; the canvas and the painting tools then work on it.",
+    input: { index: z.number().int().min(0).describe("The frame, from 0.") },
+    annotations: { ...ADDS, idempotentHint: true },
+  },
+  async ({ index }) => {
+    await call("frame.select", { index });
+    return text(`Frame ${index} on show.`);
+  },
+);
+
+tool(
+  "set_frame_duration",
+  {
+    title: "Frame timing",
+    description: "How long a frame shows when the animation plays, 10 to 10000 milliseconds; the frame on show when index is left out.",
+    input: {
+      index: z.number().int().min(0).optional().describe("The frame, from 0; the one on show when left out."),
+      duration_ms: z.number().int().min(10).max(10000).describe("Milliseconds."),
+    },
+    annotations: { ...CHANGES, idempotentHint: true },
+  },
+  async ({ index, duration_ms }) => {
+    const r = await call("frame.set", { index, duration_ms });
+    return text(`Frame ${r.frame} shows for ${r.duration_ms} ms.`);
+  },
+);
+
+tool(
+  "add_tag",
+  {
+    title: "Tag frames",
+    description: "Tag a run of frames, from and to included (an animation such as idle or walk), as the timeline does.",
+    input: {
+      name: z.string().min(1).describe("The tag's name, e.g. idle."),
+      from: z.number().int().min(0).describe("The first frame, from 0."),
+      to: z.number().int().min(0).optional().describe("The last frame (from, when left out)."),
+    },
+    annotations: ADDS,
+  },
+  async ({ name, from, to }) => {
+    const r = await call("tag.add", { name, from, to });
+    return text(`Tag ${r.tag} '${r.name}' covers frames ${r.from}-${r.to}.`);
+  },
+);
+
+tool(
+  "save_document",
+  {
+    title: "Save the project",
+    description: "Save the open document as a PixelAOI project (.pxl) at an absolute path, without a dialog. It becomes the document's file, as Save As does.",
+    input: { path: z.string().describe("An absolute path ending in .pxl.") },
+    annotations: { ...CHANGES, idempotentHint: true },
+  },
+  async ({ path }) => {
+    const r = await call("document.save", { path });
+    return text(`Saved ${r.saved}.`);
+  },
+);
+
+tool(
+  "close_document",
+  {
+    title: "Close the document",
+    description:
+      "Close the open document's tab once it is saved (refused while it has unsaved changes: save_document first). The next tab comes up, or Home after the last.",
+    annotations: CHANGES,
+  },
+  async () => {
+    const r = await call("document.close");
+    return text(r.home ? "Closed; Home is up." : `Closed; ${r.documents} documents open.`);
   },
 );
 

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "pixelate-mcp",
-  "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"
-  },
-  "files": [
-    "index.js",
-    "README.md",
-    "LICENSE"
-  ],
-  "homepage": "https://pixelaoi.pro",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "pixel-art",
-    "pixelaoi",
-    "pixelate",
-    "codex",
-    "claude"
-  ],
-  "license": "MIT",
-  "author": "PixelAOI",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "pixelate-mcp",
+  "version": "0.6.0",
+  "description": "PixelAOI's MCP server: lets an AI agent (Claude Code, Codex, Cursor, Claude Desktop) see the PixelAOI canvas, paint it, arrange layers, build animations, apply filters, pixelate images on your machine and wire Blueprint node graphs.",
+  "type": "module",
+  "bin": {
+    "pixelate-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://pixelaoi.pro",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pixel-art",
+    "pixelaoi",
+    "pixelate",
+    "codex",
+    "claude"
+  ],
+  "license": "MIT",
+  "author": "PixelAOI",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^3.25.76"
+  }
+}