@pebbly/aseprite-ai-artist 0.1.0

package/dist/tools/craft.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { fail, hexColor, ok, targetShape } from "./kit.js";
+/**
+ * Operations that encode pixel-art craft rather than Aseprite mechanics.
+ *
+ * `recolor` exists because "make this darker" done naively — subtract from every
+ * channel — produces the muddy, plastic look that reads instantly as generated.
+ * A real shadow shifts hue toward the ambient (cool) and loses a little
+ * saturation; a highlight warms. That rule is applied here, in one place, so
+ * every skill and every agent gets it for free.
+ */
+export function registerCraftTools(server, live) {
+    server.registerTool("recolor", {
+        title: "Recolor",
+        description: "Change colours in a region by intent, staying palette-legal. Ops:\n" +
+            "• 'shade' — darken or lighten with proper hue shifting (shadows cool, highlights warm). Use this instead of picking a darker hex by hand.\n" +
+            "• 'snap' — pull off-palette pixels onto the nearest palette colour by perceptual (CIELAB) distance.\n" +
+            "• 'replace' — swap one exact colour for another.\n" +
+            "• 'hue_shift' — rotate hue, e.g. to make a colour variant of a finished sprite.\n" +
+            "• 'desaturate' — drop toward grey, useful for a value check.\n" +
+            "Operates on a region's distinct colours in one pass, so a 64×64 recolour is one undo step, not four thousand.",
+        inputSchema: {
+            op: z.enum(["shade", "snap", "replace", "hue_shift", "desaturate"]),
+            ...targetShape,
+            region: z
+                .object({
+                x: z.number().int(),
+                y: z.number().int(),
+                width: z.number().int().positive(),
+                height: z.number().int().positive(),
+            })
+                .optional()
+                .describe("Omit to affect the whole cel."),
+            selectionOnly: z.boolean().default(false),
+            amount: z
+                .number()
+                .min(-1)
+                .max(1)
+                .default(-0.2)
+                .describe("For 'shade': negative darkens, positive lightens. One ramp step is roughly 0.15."),
+            degrees: z.number().min(-180).max(180).default(30).describe("For 'hue_shift'."),
+            strength: z.number().min(0).max(1).default(1).describe("For 'desaturate'."),
+            from: hexColor.optional().describe("For 'replace'."),
+            to: hexColor.optional().describe("For 'replace'."),
+            clampToPalette: z
+                .boolean()
+                .default(true)
+                .describe("Snap the result back onto the palette. Turn off only when growing the palette deliberately."),
+        },
+        outputSchema: {
+            sprite: z.string(),
+            op: z.string(),
+            pixelsChanged: z.number().int(),
+            mapping: z
+                .array(z.object({ from: z.string(), to: z.string(), pixels: z.number().int() }))
+                .describe("Exactly which colour became which, and how many pixels each move touched."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            if (args.op === "replace" && (!args.from || !args.to)) {
+                return fail(new Error("op 'replace' needs both `from` and `to`."));
+            }
+            const data = await live.call("recolor.apply", args);
+            const mapping = data.mapping ?? [];
+            return ok(data, `${String(data.pixelsChanged ?? 0)} pixel(s) recoloured. ${mapping
+                .slice(0, 8)
+                .map((m) => `${m.from}→${m.to}`)
+                .join(", ")}`);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("validate", {
+        title: "Validate",
+        description: "Lint a sprite against pixel-art rules and report concrete, located problems. Checks: off-palette colours, orphan/stray pixels, broken or doubled outlines, banding, unintentional anti-aliasing on a hard-edged sprite, odd-pixel asymmetry, empty layers, untagged frames, inconsistent frame timing, and cross-frame volume drift in an animation. " +
+            "Run this before telling the user a sprite is finished. It answers 'is this actually done' with evidence rather than optimism.",
+        inputSchema: {
+            sprite: targetShape.sprite,
+            checks: z
+                .array(z.enum([
+                "palette",
+                "strays",
+                "outline",
+                "banding",
+                "antialiasing",
+                "layers",
+                "animation",
+                "export_readiness",
+            ]))
+                .optional()
+                .describe("Omit to run everything."),
+            strict: z
+                .boolean()
+                .default(false)
+                .describe("Treat style warnings as failures. Use when the user asked for a specific discipline."),
+        },
+        outputSchema: {
+            sprite: z.string(),
+            passed: z.boolean(),
+            score: z.number().int().min(0).max(100),
+            findings: z.array(z.object({
+                check: z.string(),
+                severity: z.enum(["error", "warning", "note"]),
+                message: z.string(),
+                layer: z.string().nullish(),
+                frame: z.number().int().nullish(),
+                at: z
+                    .object({ x: z.number().int(), y: z.number().int() })
+                    .nullish()
+                    .describe("Where to look, when the problem has a location."),
+                count: z.number().int().nullish(),
+            })),
+            summary: z.string(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            const data = await live.call("validate.run", args);
+            const errors = data.findings.filter((f) => f.severity === "error");
+            const warnings = data.findings.filter((f) => f.severity === "warning");
+            const passed = errors.length === 0 && (!args.strict || warnings.length === 0);
+            const score = Math.max(0, 100 - errors.length * 15 - warnings.length * 5);
+            const summary = passed
+                ? `Clean${warnings.length > 0 ? ` (${warnings.length} style note(s))` : ""}.`
+                : `${errors.length} error(s), ${warnings.length} warning(s). Fix the errors before calling this done.`;
+            return ok({ ...data, passed, score, summary }, [
+                summary,
+                ...data.findings
+                    .slice(0, 15)
+                    .map((f) => `[${f.severity}] ${f.check}: ${f.message}` +
+                    (f.at ? ` at (${f.at.x},${f.at.y})` : "") +
+                    (f.layer ? ` on '${f.layer}'` : "") +
+                    (f.frame ? ` frame ${f.frame}` : "")),
+            ].join("\n"));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+//# sourceMappingURL=craft.js.map

package/dist/tools/craft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft.js","sourceRoot":"","sources":["../../src/tools/craft.ts"],"names":[],"mappings":"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"}

package/dist/tools/draw.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LiveClient } from "../bridge/client.js";
+export declare function registerDrawTools(server: McpServer, live: LiveClient): void;

package/dist/tools/draw.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { fail, hexColor, ok, targetShape } from "./kit.js";
+const pointWithColor = z.object({
+    x: z.number().int(),
+    y: z.number().int(),
+    color: hexColor.optional().describe("Per-pixel colour. Falls back to the op's `color`."),
+});
+const rectShape = z.object({
+    x: z.number().int(),
+    y: z.number().int(),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+});
+/**
+ * One batch tool instead of a dozen primitives.
+ *
+ * Two reasons. First, an agent drawing a 32×32 sprite one primitive per tool
+ * call burns a round trip per stroke and fills its own context with acks.
+ * Second — and this is the part that matters to the person watching — every op
+ * in a batch lands inside a single Aseprite transaction, so one Ctrl+Z undoes
+ * "the agent's last edit" rather than one of forty stray pixels.
+ */
+const drawOp = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("pixels"),
+        color: hexColor.optional(),
+        points: z.array(pointWithColor).min(1).max(20000),
+    }),
+    z.object({
+        kind: z.literal("line"),
+        color: hexColor,
+        from: z.object({ x: z.number().int(), y: z.number().int() }),
+        to: z.object({ x: z.number().int(), y: z.number().int() }),
+        thickness: z.number().int().positive().max(64).default(1),
+    }),
+    z.object({
+        kind: z.literal("polyline"),
+        color: hexColor,
+        points: z.array(z.object({ x: z.number().int(), y: z.number().int() })).min(2),
+        closed: z.boolean().default(false),
+        fill: hexColor.optional().describe("Fill colour; only meaningful when closed."),
+    }),
+    z.object({
+        kind: z.literal("rect"),
+        color: hexColor.describe("Outline colour."),
+        rect: rectShape,
+        fill: hexColor.optional().describe("Omit for an outline only."),
+    }),
+    z.object({
+        kind: z.literal("ellipse"),
+        color: hexColor,
+        rect: rectShape.describe("Bounding box of the ellipse."),
+        fill: hexColor.optional(),
+    }),
+    z.object({
+        kind: z.literal("fill"),
+        color: hexColor,
+        at: z.object({ x: z.number().int(), y: z.number().int() }),
+        tolerance: z.number().int().min(0).max(255).default(0),
+        contiguous: z.boolean().default(true),
+    }),
+    z.object({
+        kind: z.literal("replace"),
+        from: hexColor,
+        to: hexColor,
+        region: rectShape.optional(),
+    }),
+    z.object({
+        kind: z.literal("dither"),
+        rect: rectShape,
+        colorA: hexColor,
+        colorB: hexColor,
+        pattern: z.enum(["checker", "bayer2", "bayer4", "bayer8", "noise"]).default("bayer4"),
+        ratio: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(0.5)
+            .describe("0 = all colorA, 1 = all colorB."),
+    }),
+    z.object({
+        kind: z.literal("gradient"),
+        rect: rectShape,
+        from: hexColor,
+        to: hexColor,
+        direction: z.enum(["vertical", "horizontal", "diagonal", "radial"]).default("vertical"),
+        steps: z
+            .number()
+            .int()
+            .min(2)
+            .max(64)
+            .default(4)
+            .describe("Banded, not smooth — a smooth gradient is not pixel art."),
+        dither: z.boolean().default(false).describe("Dither the band boundaries."),
+    }),
+    z.object({
+        kind: z.literal("clear"),
+        region: rectShape.optional().describe("Omit to clear the whole cel."),
+    }),
+    z.object({
+        kind: z.literal("blit"),
+        from: rectShape,
+        to: z.object({ x: z.number().int(), y: z.number().int() }),
+        fromFrame: z.number().int().positive().optional(),
+        fromLayer: z.string().optional(),
+        flipHorizontal: z.boolean().default(false),
+        flipVertical: z.boolean().default(false),
+        skipTransparent: z.boolean().default(true),
+    }),
+]);
+export function registerDrawTools(server, live) {
+    server.registerTool("draw", {
+        title: "Draw",
+        description: "Apply a batch of drawing operations to one cel, as a single undoable action. Ops: pixels, line, polyline, rect, ellipse, fill, replace, dither, gradient, clear, blit. " +
+            "Batch aggressively — a whole sprite in one call is normal and correct, and it means the user can undo your work with one Ctrl+Z. " +
+            "Set `paletteLock` (default true) to snap every colour to the sprite's palette by perceptual distance before anything is written, so you cannot silently widen a curated palette. " +
+            "Ops run in array order, so paint fills before outlines and outlines before highlights.",
+        inputSchema: {
+            ...targetShape,
+            ops: z.array(drawOp).min(1).max(512).describe("Applied in order, in one transaction."),
+            paletteLock: z
+                .boolean()
+                .default(true)
+                .describe("Snap every colour to the nearest palette entry (CIELAB ΔE). Set false only when the user asked to introduce new colours."),
+            selectionOnly: z
+                .boolean()
+                .default(false)
+                .describe("Clip every op to the current selection."),
+            createCel: z
+                .boolean()
+                .default(true)
+                .describe("Create the cel if the target layer/frame has none."),
+            label: z
+                .string()
+                .optional()
+                .describe("Name shown in Aseprite's undo history. Describe the intent, e.g. 'shade helmet'."),
+        },
+        outputSchema: {
+            sprite: z.string(),
+            layer: z.string(),
+            frame: z.number().int(),
+            opsApplied: z.number().int(),
+            pixelsChanged: z.number().int(),
+            colorsSnapped: z
+                .array(z.object({ from: z.string(), to: z.string(), deltaE: z.number() }))
+                .describe("Colours palette-lock moved, and how far. A large ΔE means the palette lacks that colour."),
+            bounds: z
+                .object({ x: z.number().int(), y: z.number().int(), width: z.number().int(), height: z.number().int() })
+                .nullish()
+                .describe("Bounding box actually touched."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        try {
+            const data = await live.call("draw.batch", args);
+            const snapped = data.colorsSnapped ?? [];
+            const far = snapped.filter((s) => s.deltaE > 12);
+            const summary = [
+                `${String(data.opsApplied ?? args.ops.length)} op(s), ${String(data.pixelsChanged ?? 0)} pixel(s) changed on '${String(data.layer)}' frame ${String(data.frame)}.`,
+            ];
+            if (far.length > 0) {
+                summary.push(`Palette lock moved ${far.length} colour(s) a long way (ΔE > 12): ${far
+                    .slice(0, 5)
+                    .map((s) => `${s.from}→${s.to}`)
+                    .join(", ")}. Extend the palette if you meant those colours.`);
+            }
+            summary.push("Now call look to see the result before moving on.");
+            return ok(data, summary.join(" "));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("select", {
+        title: "Selection",
+        description: "Read or change the active selection. Ops: 'get', 'none', 'all', 'rect', 'ellipse', 'color' (select every pixel matching a colour), 'invert', 'grow', 'shrink'. A selection scopes draw, transform and recolor, which is usually cheaper and safer than masking by hand.",
+        inputSchema: {
+            op: z.enum(["get", "none", "all", "rect", "ellipse", "color", "invert", "grow", "shrink"]),
+            ...targetShape,
+            rect: rectShape.optional(),
+            color: hexColor.optional().describe("For op 'color'."),
+            tolerance: z.number().int().min(0).max(255).default(0),
+            contiguous: z.boolean().default(false).describe("For op 'color'."),
+            amount: z.number().int().positive().default(1).describe("Pixels, for grow/shrink."),
+            mode: z
+                .enum(["replace", "add", "subtract", "intersect"])
+                .default("replace")
+                .describe("How this selection combines with the existing one."),
+        },
+        outputSchema: {
+            sprite: z.string(),
+            empty: z.boolean(),
+            bounds: z
+                .object({ x: z.number().int(), y: z.number().int(), width: z.number().int(), height: z.number().int() })
+                .nullish(),
+            pixelCount: z.number().int(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            const data = await live.call("select.apply", args);
+            return ok(data);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("transform", {
+        title: "Transform",
+        description: "Move, flip, rotate or scale pixels on ONE cel — the target layer's image on the target frame. Ops: 'translate', 'flip', 'rotate', 'scale', 'outline', 'crop_to_content'. " +
+            "To transform part of a cel, crop the region out with `draw` op 'blit' first; there is no selection-scoped transform. " +
+            "Rotation is only clean at 90° multiples — arbitrary angles destroy pixel art, so anything else needs `allowLossy`. " +
+            "Scaling is nearest-neighbour and integer-only for the same reason.",
+        inputSchema: {
+            op: z.enum(["translate", "flip", "rotate", "scale", "outline", "crop_to_content"]),
+            ...targetShape,
+            dx: z.number().int().default(0),
+            dy: z.number().int().default(0),
+            axis: z.enum(["horizontal", "vertical"]).optional().describe("For 'flip'."),
+            angle: z.number().default(90).describe("Degrees, clockwise. For 'rotate'."),
+            factor: z.number().int().min(1).max(16).default(2).describe("For 'scale'."),
+            color: hexColor.optional().describe("Outline colour, for 'outline'."),
+            thickness: z.number().int().positive().max(8).default(1),
+            allowLossy: z
+                .boolean()
+                .default(false)
+                .describe("Permit a non-90° rotation or non-integer scale. Ask the user first."),
+        },
+        outputSchema: {
+            sprite: z.string(),
+            op: z.string(),
+            pixelsChanged: z.number().int(),
+            bounds: z
+                .object({ x: z.number().int(), y: z.number().int(), width: z.number().int(), height: z.number().int() })
+                .nullish(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            if (args.op === "rotate" && args.angle % 90 !== 0 && !args.allowLossy) {
+                return fail(new Error(`A ${args.angle}° rotation resamples every pixel and will destroy the sprite's crispness. Use a multiple of 90, or confirm with the user and pass allowLossy: true.`));
+            }
+            const data = await live.call("transform.apply", args);
+            return ok(data);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+//# sourceMappingURL=draw.js.map

package/dist/tools/draw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.js","sourceRoot":"","sources":["../../src/tools/draw.ts"],"names":[],"mappings":"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"}

package/dist/tools/escape.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LiveClient } from "../bridge/client.js";
+/**
+ * The escape hatch.
+ *
+ * A compact tool surface has a cost: something a user wants will eventually sit
+ * outside it. Rather than let that become a reason to grow the surface to 120
+ * tools, this runs Lua directly in Aseprite — and is off unless the operator
+ * turns it on, because it is arbitrary code execution inside the app that holds
+ * the user's unsaved work.
+ */
+export declare function registerEscapeTools(server: McpServer, live: LiveClient, enabled: boolean): void;

package/dist/tools/escape.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { fail, ok, targetShape } from "./kit.js";
+/**
+ * The escape hatch.
+ *
+ * A compact tool surface has a cost: something a user wants will eventually sit
+ * outside it. Rather than let that become a reason to grow the surface to 120
+ * tools, this runs Lua directly in Aseprite — and is off unless the operator
+ * turns it on, because it is arbitrary code execution inside the app that holds
+ * the user's unsaved work.
+ */
+export function registerEscapeTools(server, live, enabled) {
+    if (!enabled)
+        return;
+    server.registerTool("run_lua", {
+        title: "Run Lua in Aseprite",
+        description: "Execute a Lua script inside the running Aseprite session and return its result. " +
+            "This is an escape hatch for operations the typed tools do not cover — prefer a typed tool whenever one fits, because this bypasses palette locking, undo labelling and every safety check. " +
+            "The script runs with full Aseprite API access against the user's open document. Wrap mutations in app.transaction so the user can undo them in one step. " +
+            "Return a value to receive it as JSON.",
+        inputSchema: {
+            ...targetShape,
+            script: z.string().min(1).max(60_000).describe("Lua source. `sprite` is bound to the target sprite."),
+            label: z.string().optional().describe("Undo-history label for any mutation."),
+            timeoutMs: z.number().int().min(100).max(120_000).default(20_000),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            result: z.unknown().nullish(),
+            stdout: z.string(),
+            durationMs: z.number().int(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const data = await live.call("lua.run", args);
+            return ok(data);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+//# sourceMappingURL=escape.js.map

package/dist/tools/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../src/tools/escape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,IAAgB,EAAE,OAAgB;IACvF,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,MAAM,CAAC,YAAY,CACjB,SAAS,EACT;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,kFAAkF;YAClF,6LAA6L;YAC7L,2JAA2J;YAC3J,uCAAuC;QACzC,WAAW,EAAE;YACX,GAAG,WAAW;YACd,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,qDAAqD,CAAC;YACrG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YAC7E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;SAClE;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;YACf,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE;YAC7B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;YAClB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;SAC7B;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,IAAI;SACpB;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAA0B,SAAS,EAAE,IAAI,CAAC,CAAC;YACvE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/kit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Small helpers shared by every tool module.
+ *
+ * The house style for this server: one tool per *noun*, an `op` enum for the
+ * verbs, and a batch array wherever an agent would otherwise loop. Ninety
+ * single-purpose tools is a schema the model pays for on every single turn
+ * whether it draws anything or not; see docs/adr/0003-compact-tool-surface.md.
+ */
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const hexColor: z.ZodString;
+/** Every tool that touches a document accepts this; omitted means "active". */
+export declare const targetShape: {
+    sprite: z.ZodOptional<z.ZodString>;
+    layer: z.ZodOptional<z.ZodString>;
+    frame: z.ZodOptional<z.ZodNumber>;
+};
+export declare function ok(structured: Record<string, unknown>, summary?: string): CallToolResult;
+export declare function okWithImage(structured: Record<string, unknown>, image: {
+    data: string;
+    mimeType: string;
+}, summary: string): CallToolResult;
+/**
+ * Errors are returned as tool results, not thrown as protocol errors: the model
+ * has to see them to recover, and a JSON-RPC error is swallowed by most hosts.
+ * `doNotFallBackToDisk` rides along so a disconnected session cannot quietly
+ * become an edit to the file on disk that the user never sees.
+ */
+export declare function fail(err: unknown): CallToolResult;

package/dist/tools/kit.js

@@ -0,0 +1,85 @@
+/**
+ * Small helpers shared by every tool module.
+ *
+ * The house style for this server: one tool per *noun*, an `op` enum for the
+ * verbs, and a batch array wherever an agent would otherwise loop. Ninety
+ * single-purpose tools is a schema the model pays for on every single turn
+ * whether it draws anything or not; see docs/adr/0003-compact-tool-surface.md.
+ */
+import { z } from "zod";
+import { LiveError } from "../lib/protocol.js";
+export const hexColor = z
+    .string()
+    .regex(/^#?([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #rrggbb or #rrggbbaa")
+    .describe("Colour as #rrggbb or #rrggbbaa.");
+/** Every tool that touches a document accepts this; omitted means "active". */
+export const targetShape = {
+    sprite: z
+        .string()
+        .optional()
+        .describe("Which sprite: its id as '#7' (what every result reports back, and the only unambiguous form — two unsaved documents are both called 'Sprite'), its filename, or its display name. Omit to use the sprite Aseprite has focused."),
+    layer: z.string().optional().describe("Layer name. Omit to use the active layer."),
+    frame: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("1-based frame number. Omit to use the active frame."),
+};
+export function ok(structured, summary) {
+    return {
+        content: [{ type: "text", text: summary ?? compactSummary(structured) }],
+        structuredContent: structured,
+    };
+}
+export function okWithImage(structured, image, summary) {
+    return {
+        content: [
+            { type: "text", text: summary },
+            { type: "image", data: image.data, mimeType: image.mimeType },
+        ],
+        structuredContent: structured,
+    };
+}
+/**
+ * Errors are returned as tool results, not thrown as protocol errors: the model
+ * has to see them to recover, and a JSON-RPC error is swallowed by most hosts.
+ * `doNotFallBackToDisk` rides along so a disconnected session cannot quietly
+ * become an edit to the file on disk that the user never sees.
+ */
+export function fail(err) {
+    const live = err instanceof LiveError ? err : null;
+    const code = live?.code ?? "aseprite_error";
+    const message = err instanceof Error ? err.message : String(err);
+    const details = live?.details ?? {};
+    const lines = [`${code}: ${message}`];
+    if (details.remediation)
+        lines.push(`Fix: ${String(details.remediation)}`);
+    if (details.doNotFallBackToDisk) {
+        lines.push("Do not retry this as a file edit — the user's open Aseprite window would not show it.");
+    }
+    return {
+        isError: true,
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: { ok: false, code, message, details },
+    };
+}
+function compactSummary(structured) {
+    const keys = Object.keys(structured);
+    if (keys.length === 0)
+        return "Done.";
+    const parts = [];
+    for (const key of keys.slice(0, 6)) {
+        const value = structured[key];
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value))
+            parts.push(`${key}=${value.length}`);
+        else if (typeof value === "object")
+            continue;
+        else
+            parts.push(`${key}=${String(value)}`);
+    }
+    return parts.length > 0 ? parts.join(" ") : "Done.";
+}
+//# sourceMappingURL=kit.js.map

package/dist/tools/kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.js","sourceRoot":"","sources":["../../src/tools/kit.ts"],"names":[],"mappings":"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"}

package/dist/tools/look.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LiveClient } from "../bridge/client.js";
+/**
+ * The "see your own work" tool. Drawing without looking is how an agent ends up
+ * confidently reporting a finished sprite that is a smear of misplaced pixels.
+ */
+export declare function registerLookTools(server: McpServer, live: LiveClient): void;