@sajou/mcp-server 0.6.0

package/dist/state/store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Server-authoritative in-memory state store.
+ *
+ * This is the single source of truth for the scene state. MCP tools read
+ * and mutate this store directly — no HTTP round-trip to a browser needed.
+ * Connected browsers receive updates via SSE.
+ */
+/** Full server state — same shape as the client state-sync snapshot. */
+export interface ServerState {
+    scene: Record<string, unknown>;
+    choreographies: Record<string, unknown>;
+    wiring: Record<string, unknown>;
+    bindings: Record<string, unknown>;
+    shaders: Record<string, unknown>;
+    p5: Record<string, unknown>;
+    signalSources: Record<string, unknown>;
+    editor: Record<string, unknown>;
+}
+/** Get the current state version. */
+export declare function getStateVersion(): number;
+/** Get the timestamp of the last mutation (or null if pristine). */
+export declare function getLastMutationAt(): number | null;
+/** Get a full snapshot of the entire state. */
+export declare function getFullState(): Readonly<ServerState>;
+/** Get the scene section. */
+export declare function getSceneSnapshot(): Record<string, unknown>;
+/** Get choreographies section. */
+export declare function getChoreographies(): Record<string, unknown>;
+/** Get wiring section. */
+export declare function getWiring(): Record<string, unknown>;
+/** Get bindings section. */
+export declare function getBindings(): Record<string, unknown>;
+/** Get shaders section. */
+export declare function getShaders(): Record<string, unknown>;
+/** Get p5 section. */
+export declare function getP5(): Record<string, unknown>;
+/** Get signal sources section. */
+export declare function getSignalSources(): Record<string, unknown>;
+/** Get editor section. */
+export declare function getEditor(): Record<string, unknown>;
+/** Replace the entire state (used when the browser pushes a full snapshot). */
+export declare function setFullState(snapshot: Record<string, unknown>): void;
+/** Replace a single section of the state. */
+export declare function setSection(key: keyof ServerState, value: Record<string, unknown>): void;
+/** Mutate the state in-place and notify. Used by mutations.ts. */
+export declare function mutate(fn: (s: ServerState) => void): void;
+/** Reset to empty state (e.g. "New scene"). */
+export declare function resetState(): void;
+/** Subscribe to state changes. Returns an unsubscribe function. */
+export declare function subscribe(fn: (version: number) => void): () => void;
+//# sourceMappingURL=store.d.ts.map

package/dist/state/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAmED,qCAAqC;AACrC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEpD;AAED,6BAA6B;AAC7B,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1D;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE3D;AAED,0BAA0B;AAC1B,wBAAgB,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnD;AAED,4BAA4B;AAC5B,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErD;AAED,2BAA2B;AAC3B,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpD;AAED,sBAAsB;AACtB,wBAAgB,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/C;AAED,kCAAkC;AAClC,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1D;AAED,0BAA0B;AAC1B,wBAAgB,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnD;AAMD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYpE;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAGvF;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAGzD;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,IAAI,IAAI,CAGjC;AAMD,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAGnE"}

package/dist/state/store.js

@@ -0,0 +1,149 @@
+/**
+ * Server-authoritative in-memory state store.
+ *
+ * This is the single source of truth for the scene state. MCP tools read
+ * and mutate this store directly — no HTTP round-trip to a browser needed.
+ * Connected browsers receive updates via SSE.
+ */
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+/** The in-memory state. Initialised with empty sections. */
+let state = createEmptyState();
+/** Monotonically increasing version counter. */
+let stateVersion = 0;
+/** Timestamp of last mutation. */
+let lastMutationAt = null;
+/** Subscriber callbacks notified on every mutation. */
+const subscribers = new Set();
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Create a fresh empty state. */
+function createEmptyState() {
+    return {
+        scene: {
+            dimensions: { width: 960, height: 640 },
+            background: { color: "#1a1a2e" },
+            layers: [
+                { id: "background", name: "Background", order: 0, visible: true },
+                { id: "midground", name: "Midground", order: 1, visible: true },
+                { id: "foreground", name: "Foreground", order: 2, visible: true },
+            ],
+            entities: [],
+            positions: [],
+            routes: [],
+            zoneTypes: [],
+            lighting: null,
+            particles: [],
+        },
+        choreographies: { choreographies: [] },
+        wiring: { wires: [] },
+        bindings: { bindings: [] },
+        shaders: { shaders: [] },
+        p5: { sketches: [] },
+        signalSources: { sources: [] },
+        editor: {},
+    };
+}
+/** Increment version, update timestamp, notify subscribers. */
+function notifyChange() {
+    stateVersion++;
+    lastMutationAt = Date.now();
+    for (const fn of subscribers) {
+        try {
+            fn(stateVersion);
+        }
+        catch {
+            // Subscriber errors must not crash the store.
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API — reads
+// ---------------------------------------------------------------------------
+/** Get the current state version. */
+export function getStateVersion() {
+    return stateVersion;
+}
+/** Get the timestamp of the last mutation (or null if pristine). */
+export function getLastMutationAt() {
+    return lastMutationAt;
+}
+/** Get a full snapshot of the entire state. */
+export function getFullState() {
+    return state;
+}
+/** Get the scene section. */
+export function getSceneSnapshot() {
+    return state.scene;
+}
+/** Get choreographies section. */
+export function getChoreographies() {
+    return state.choreographies;
+}
+/** Get wiring section. */
+export function getWiring() {
+    return state.wiring;
+}
+/** Get bindings section. */
+export function getBindings() {
+    return state.bindings;
+}
+/** Get shaders section. */
+export function getShaders() {
+    return state.shaders;
+}
+/** Get p5 section. */
+export function getP5() {
+    return state.p5;
+}
+/** Get signal sources section. */
+export function getSignalSources() {
+    return state.signalSources;
+}
+/** Get editor section. */
+export function getEditor() {
+    return state.editor;
+}
+// ---------------------------------------------------------------------------
+// Public API — writes
+// ---------------------------------------------------------------------------
+/** Replace the entire state (used when the browser pushes a full snapshot). */
+export function setFullState(snapshot) {
+    state = {
+        scene: snapshot["scene"] ?? state.scene,
+        choreographies: snapshot["choreographies"] ?? state.choreographies,
+        wiring: snapshot["wiring"] ?? state.wiring,
+        bindings: snapshot["bindings"] ?? state.bindings,
+        shaders: snapshot["shaders"] ?? state.shaders,
+        p5: snapshot["p5"] ?? state.p5,
+        signalSources: snapshot["signalSources"] ?? state.signalSources,
+        editor: snapshot["editor"] ?? state.editor,
+    };
+    notifyChange();
+}
+/** Replace a single section of the state. */
+export function setSection(key, value) {
+    state[key] = value;
+    notifyChange();
+}
+/** Mutate the state in-place and notify. Used by mutations.ts. */
+export function mutate(fn) {
+    fn(state);
+    notifyChange();
+}
+/** Reset to empty state (e.g. "New scene"). */
+export function resetState() {
+    state = createEmptyState();
+    notifyChange();
+}
+// ---------------------------------------------------------------------------
+// Pub/sub
+// ---------------------------------------------------------------------------
+/** Subscribe to state changes. Returns an unsubscribe function. */
+export function subscribe(fn) {
+    subscribers.add(fn);
+    return () => { subscribers.delete(fn); };
+}
+//# sourceMappingURL=store.js.map

package/dist/state/store.js.map

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

package/dist/tools/create-binding.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP tool: create_binding
+ *
+ * Creates an entity binding — connects a choreography's output to an entity property.
+ * Bindings are the Level 2 dynamic wiring: they define how choreography results
+ * affect visual properties on placed entities.
+ */
+import { z } from "zod";
+export declare const name = "create_binding";
+export declare const description: string;
+export declare const inputSchema: z.ZodObject<{
+    targetEntityId: z.ZodString;
+    property: z.ZodString;
+    sourceChoreographyId: z.ZodString;
+    sourceType: z.ZodOptional<z.ZodEnum<["float", "point2D", "bool", "enum", "event", "color", "int"]>>;
+    sourceField: z.ZodOptional<z.ZodString>;
+    mapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    action: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    transition: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    targetEntityId: string;
+    property: string;
+    sourceChoreographyId: string;
+    action?: Record<string, unknown> | undefined;
+    sourceType?: "float" | "point2D" | "bool" | "enum" | "event" | "color" | "int" | undefined;
+    mapping?: Record<string, unknown> | undefined;
+    sourceField?: string | undefined;
+    transition?: Record<string, unknown> | undefined;
+}, {
+    targetEntityId: string;
+    property: string;
+    sourceChoreographyId: string;
+    action?: Record<string, unknown> | undefined;
+    sourceType?: "float" | "point2D" | "bool" | "enum" | "event" | "color" | "int" | undefined;
+    mapping?: Record<string, unknown> | undefined;
+    sourceField?: string | undefined;
+    transition?: Record<string, unknown> | undefined;
+}>;
+export declare function handler(params: z.infer<typeof inputSchema>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=create-binding.d.ts.map

package/dist/tools/create-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-binding.d.ts","sourceRoot":"","sources":["../../src/tools/create-binding.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,IAAI,mBAAmB,CAAC;AAErC,eAAO,MAAM,WAAW,QAKmG,CAAC;AAE5H,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDtB,CAAC;AAEH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAsB7D"}

package/dist/tools/create-binding.js

@@ -0,0 +1,82 @@
+/**
+ * MCP tool: create_binding
+ *
+ * Creates an entity binding — connects a choreography's output to an entity property.
+ * Bindings are the Level 2 dynamic wiring: they define how choreography results
+ * affect visual properties on placed entities.
+ */
+import { z } from "zod";
+import { addBinding } from "../state/mutations.js";
+export const name = "create_binding";
+export const description = "Create a binding between a choreography and an entity property. " +
+    "Bindings connect choreography outputs to entity visual properties (position, rotation, opacity, animation state, etc.). " +
+    "Example: bind a 'tool_call' choreography's output to agent-1's 'animation.state' property, " +
+    "so when the choreography runs, the agent switches to a 'working' animation. " +
+    "The binding specifies which choreography provides the data, which entity receives it, and which property is controlled.";
+export const inputSchema = z.object({
+    targetEntityId: z
+        .string()
+        .describe("The semanticId of the target entity (e.g. 'agent-1', 'door-kitchen'). " +
+        "This must match a placed entity's semanticId in the scene."),
+    property: z
+        .string()
+        .describe("The entity property to bind to. Available properties: " +
+        "'position' (point2D), 'position.x'/'position.y' (float), " +
+        "'rotation' (float, degrees), 'scale'/'scale.x'/'scale.y' (float), " +
+        "'opacity' (float, 0-1), 'visible' (bool), 'tint' (color), " +
+        "'animation.state' (enum — switches animation), 'animation.speed' (float), " +
+        "'zIndex' (int), " +
+        "'moveTo:waypoint' (event — move entity to a waypoint), " +
+        "'followRoute' (event — entity follows a route), " +
+        "'teleportTo' (event — instant move)."),
+    sourceChoreographyId: z
+        .string()
+        .describe("The ID of the choreography that provides the data for this binding."),
+    sourceType: z
+        .enum(["float", "point2D", "bool", "enum", "event", "color", "int"])
+        .optional()
+        .describe("The type of data the choreography outputs. Defaults to 'event'. " +
+        "Must be compatible with the target property's accepted types."),
+    sourceField: z
+        .string()
+        .optional()
+        .describe("Specific field to extract from the signal payload (e.g. 'velocity', 'value'). " +
+        "If omitted, auto-detected from context."),
+    mapping: z
+        .record(z.unknown())
+        .optional()
+        .describe("Optional value mapping function. Example: { fn: 'linear', inputRange: [0, 100], outputRange: [0, 1] }."),
+    action: z
+        .record(z.unknown())
+        .optional()
+        .describe("Optional action config for event→action bindings. " +
+        "Example for moveTo: { waypoint: 'workstation-1', animationDuring: 'walk', animationOnArrival: 'idle', duration: 1000 }."),
+    transition: z
+        .record(z.unknown())
+        .optional()
+        .describe("Optional transition config for smooth property changes. " +
+        "Example: { targetValue: 0.5, durationMs: 300, easing: 'easeOut' }."),
+});
+export async function handler(params) {
+    addBinding({
+        targetEntityId: params.targetEntityId,
+        property: params.property,
+        sourceChoreographyId: params.sourceChoreographyId,
+        sourceType: params.sourceType ?? "event",
+        sourceField: params.sourceField,
+        mapping: params.mapping,
+        action: params.action,
+        transition: params.transition,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ok: true,
+                }),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=create-binding.js.map

package/dist/tools/create-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-binding.js","sourceRoot":"","sources":["../../src/tools/create-binding.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,MAAM,CAAC,MAAM,IAAI,GAAG,gBAAgB,CAAC;AAErC,MAAM,CAAC,MAAM,WAAW,GACtB,kEAAkE;IAClE,0HAA0H;IAC1H,6FAA6F;IAC7F,8EAA8E;IAC9E,yHAAyH,CAAC;AAE5H,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,QAAQ,CACP,wEAAwE;QACxE,4DAA4D,CAC7D;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,wDAAwD;QACxD,2DAA2D;QAC3D,oEAAoE;QACpE,4DAA4D;QAC5D,4EAA4E;QAC5E,kBAAkB;QAClB,yDAAyD;QACzD,kDAAkD;QAClD,sCAAsC,CACvC;IACH,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,CAAC,qEAAqE,CAAC;IAClF,UAAU,EAAE,CAAC;SACV,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;SACnE,QAAQ,EAAE;SACV,QAAQ,CACP,kEAAkE;QAClE,+DAA+D,CAChE;IACH,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,gFAAgF;QAChF,yCAAyC,CAC1C;IACH,OAAO,EAAE,CAAC;SACP,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CACP,wGAAwG,CACzG;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CACP,oDAAoD;QACpD,yHAAyH,CAC1H;IACH,UAAU,EAAE,CAAC;SACV,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnB,QAAQ,EAAE;SACV,QAAQ,CACP,0DAA0D;QAC1D,oEAAoE,CACrE;CACJ,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAmC;IAEnC,UAAU,CAAC;QACT,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,OAAO;QACxC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,EAAE,EAAE,IAAI;iBACT,CAAC;aACH;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/create-choreography.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MCP tool: create_choreography
+ *
+ * Creates a choreography definition with steps in the scene-builder.
+ * A choreography is a sequence of animation actions that execute when
+ * a matching signal arrives.
+ */
+import { z } from "zod";
+export declare const name = "create_choreography";
+export declare const description: string;
+export declare const inputSchema: z.ZodObject<{
+    on: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<["move", "fly", "flash", "spawn", "destroy", "wait", "playSound", "setAnimation", "parallel", "onArrive", "onInterrupt"]>;
+        entity: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodString>;
+        delay: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        easing: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        action: "move" | "fly" | "flash" | "spawn" | "destroy" | "wait" | "playSound" | "setAnimation" | "parallel" | "onArrive" | "onInterrupt";
+        params?: Record<string, unknown> | undefined;
+        entity?: string | undefined;
+        duration?: number | undefined;
+        target?: string | undefined;
+        delay?: number | undefined;
+        easing?: string | undefined;
+    }, {
+        action: "move" | "fly" | "flash" | "spawn" | "destroy" | "wait" | "playSound" | "setAnimation" | "parallel" | "onArrive" | "onInterrupt";
+        params?: Record<string, unknown> | undefined;
+        entity?: string | undefined;
+        duration?: number | undefined;
+        target?: string | undefined;
+        delay?: number | undefined;
+        easing?: string | undefined;
+    }>, "many">;
+    defaultTargetEntityId: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    interrupts: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    on: string;
+    steps: {
+        action: "move" | "fly" | "flash" | "spawn" | "destroy" | "wait" | "playSound" | "setAnimation" | "parallel" | "onArrive" | "onInterrupt";
+        params?: Record<string, unknown> | undefined;
+        entity?: string | undefined;
+        duration?: number | undefined;
+        target?: string | undefined;
+        delay?: number | undefined;
+        easing?: string | undefined;
+    }[];
+    when?: Record<string, unknown> | undefined;
+    interrupts?: boolean | undefined;
+    defaultTargetEntityId?: string | undefined;
+}, {
+    on: string;
+    steps: {
+        action: "move" | "fly" | "flash" | "spawn" | "destroy" | "wait" | "playSound" | "setAnimation" | "parallel" | "onArrive" | "onInterrupt";
+        params?: Record<string, unknown> | undefined;
+        entity?: string | undefined;
+        duration?: number | undefined;
+        target?: string | undefined;
+        delay?: number | undefined;
+        easing?: string | undefined;
+    }[];
+    when?: Record<string, unknown> | undefined;
+    interrupts?: boolean | undefined;
+    defaultTargetEntityId?: string | undefined;
+}>;
+export declare function handler(params: z.infer<typeof inputSchema>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=create-choreography.d.ts.map

package/dist/tools/create-choreography.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-choreography.d.ts","sourceRoot":"","sources":["../../src/tools/create-choreography.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,IAAI,wBAAwB,CAAC;AAE1C,eAAO,MAAM,WAAW,QAMuC,CAAC;AAuDhE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BtB,CAAC;AAEH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAgC7D"}

package/dist/tools/create-choreography.js

@@ -0,0 +1,118 @@
+/**
+ * MCP tool: create_choreography
+ *
+ * Creates a choreography definition with steps in the scene-builder.
+ * A choreography is a sequence of animation actions that execute when
+ * a matching signal arrives.
+ */
+import { z } from "zod";
+import { addChoreography } from "../state/mutations.js";
+export const name = "create_choreography";
+export const description = "Create a choreography — a sequence of animation steps triggered by a signal. " +
+    "Choreographies are the core of sajou's animation system. When a signal of the matching type " +
+    "arrives, the choreography's steps execute in order, animating entities on the scene. " +
+    "After creating a choreography, wire it to a signal type using create_wire (signal-type → choreographer). " +
+    "Example: a 'tool_call' signal triggers a choreography that moves an agent entity to a workstation, " +
+    "plays a working animation, then flashes a result indicator.";
+const stepSchema = z.object({
+    action: z
+        .enum(["move", "fly", "flash", "spawn", "destroy", "wait", "playSound", "setAnimation", "parallel", "onArrive", "onInterrupt"])
+        .describe("The animation action to perform. " +
+        "'move' — animate entity along a path to target position. " +
+        "'fly' — instant arc movement to target. " +
+        "'flash' — brief visual highlight on the entity. " +
+        "'spawn' — create a new entity instance at a position. " +
+        "'destroy' — remove an entity from the scene. " +
+        "'wait' — pause the sequence for a duration. " +
+        "'playSound' — trigger an audio cue. " +
+        "'setAnimation' — change the entity's animation state (e.g. 'idle' → 'walk'). " +
+        "'parallel' — run child steps simultaneously. " +
+        "'onArrive' — execute child steps when entity reaches destination. " +
+        "'onInterrupt' — execute child steps if choreography is interrupted."),
+    entity: z
+        .string()
+        .optional()
+        .describe("Target entity semanticId (e.g. 'agent-1', 'door-kitchen'). " +
+        "Can use signal references like 'signal.payload.from' to dynamically resolve. " +
+        "If omitted, uses the choreography's defaultTargetEntityId."),
+    target: z
+        .string()
+        .optional()
+        .describe("Target position or waypoint name for movement actions (e.g. 'workstation-1', 'patrol-route')."),
+    delay: z
+        .number()
+        .optional()
+        .describe("Delay in milliseconds before this step starts."),
+    duration: z
+        .number()
+        .optional()
+        .describe("Duration in milliseconds for timed actions (move, wait)."),
+    easing: z
+        .string()
+        .optional()
+        .describe("Easing function: 'linear', 'easeIn', 'easeOut', 'easeInOut', 'arc'."),
+    params: z
+        .record(z.unknown())
+        .optional()
+        .describe("Additional parameters specific to the action type. " +
+        "For 'flash': { color: '#ff0', intensity: 0.8 }. " +
+        "For 'setAnimation': { state: 'walk' }. " +
+        "For 'spawn': { entityId: 'arrow', x: 100, y: 200 }. " +
+        "For 'playSound': { sound: 'click' }."),
+});
+export const inputSchema = z.object({
+    on: z
+        .string()
+        .describe("Signal type that triggers this choreography (e.g. 'tool_call', 'agent_state_change', 'task_dispatch'). " +
+        "This is the default trigger — the actual wiring is done via create_wire."),
+    steps: z
+        .array(stepSchema)
+        .min(1)
+        .describe("Ordered list of animation steps to execute when triggered."),
+    defaultTargetEntityId: z
+        .string()
+        .optional()
+        .describe("Default entity semanticId for steps that don't specify their own entity. " +
+        "Useful when most steps target the same actor."),
+    when: z
+        .record(z.unknown())
+        .optional()
+        .describe("Optional payload filter — choreography only triggers when signal payload matches. " +
+        "Example: { field: 'toolName', operator: 'eq', value: 'Read' } triggers only for Read tool calls."),
+    interrupts: z
+        .boolean()
+        .optional()
+        .describe("If true, this choreography can interrupt a running one on the same entity. Default: false."),
+});
+export async function handler(params) {
+    const choreographyId = crypto.randomUUID();
+    addChoreography({
+        id: choreographyId,
+        on: params.on,
+        steps: params.steps.map((s) => ({
+            action: s.action,
+            entity: s.entity,
+            target: s.target,
+            delay: s.delay,
+            duration: s.duration,
+            easing: s.easing,
+            params: s.params ?? {},
+        })),
+        defaultTargetEntityId: params.defaultTargetEntityId,
+        when: params.when,
+        interrupts: params.interrupts ?? false,
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ok: true,
+                    choreographyId,
+                    hint: `Choreography created. Wire it to a signal type with create_wire: { fromZone: 'signal-type', fromId: '${params.on}', toZone: 'choreographer', toId: '${choreographyId}' }`,
+                }),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=create-choreography.js.map

package/dist/tools/create-choreography.js.map

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