@cuylabs/agent-excalidraw-toolkit

Domain logic for AI agents to programmatically author Excalidraw diagrams: types, Zod schemas, session state, element factories, tool functions, and Canvas Server.

Features

• Zero Excalidraw dependency: generates Excalidraw-compatible JSON without importing the Excalidraw package
• Zod schemas as source of truth: every tool parameter is a Zod schema with rich descriptions, auto-converted to MCP input schemas
• Session-based state: multi-scene model with immutable element mutations and built-in scene switching
• Pure tool functions: stateless functions that accept validated params and a Session reference
• Compound tools: higher-level builders like createLabeledShape, createRow, createGrid, createConnectedPair
• Layout tools: align, distribute, and compute relative positions for groups of elements
• Canvas Server: optional Express 5 + WebSocket server for real-time browser preview
• Library-only package: does not ship the React browser UI; @cuylabs/mcp-excalidraw serves @cuylabs/agent-excalidraw-canvas-ui when --canvas is enabled
• File I/O: native .excalidraw JSON read/write

Installation

pnpm add @cuylabs/agent-excalidraw-toolkit

Quick Start

import { Session } from "@cuylabs/agent-excalidraw-toolkit";
import {
  createShape,
  createLabeledShape,
  exportToFile,
} from "@cuylabs/agent-excalidraw-toolkit/tools";
import { CreateShapeSchema } from "@cuylabs/agent-excalidraw-toolkit/schemas";

// Create a session
const session = new Session({ defaultSceneName: "architecture" });

// Add a shape
createShape(
  {
    type: "rectangle",
    x: 100,
    y: 100,
    width: 200,
    height: 100,
    style: { background_color: "#a5d8ff" },
  },
  session,
);

// Compound tool: shape with centered label
createLabeledShape(
  {
    shape_type: "rectangle",
    x: 400,
    y: 100,
    width: 200,
    height: 100,
    label: "Database",
  },
  session,
);

// Export to file
await exportToFile({ file_path: "./diagram.excalidraw" }, session);

Package Exports

| Export Path | Contents | | ------------------------------------------- | --------------------------------------------------------------------------------------------- | | @cuylabs/agent-excalidraw-toolkit | Session, types, element factories, geometry utilities | | @cuylabs/agent-excalidraw-toolkit/schemas | All Zod schemas and inferred TypeScript param types | | @cuylabs/agent-excalidraw-toolkit/tools | All tool functions (creation, mutation, query, compound, layout, file I/O, viewport, session) | | @cuylabs/agent-excalidraw-toolkit/server | CanvasServer class (Express 5 + WebSocket) |

The Canvas Server accepts a frontendDir option when you want it to serve a browser app. The published MCP server wires that option to @cuylabs/agent-excalidraw-canvas-ui automatically.

Tool Functions

Creation (8)

createShape, batchCreate, addRectangle, addEllipse, addDiamond, addText, addArrow, addLine

Mutation (13)

updateElement, deleteElements, moveElement, resizeElement, setStyleProperties, groupElements, ungroupElements, lockElements, unlockElements, removeElements, duplicateElement, batchUpdate, clearCanvas

Query (6)

getScene, getElement, findElements, getSceneBounds, summariseScene, getElementCounts

Compound (6)

createLabeledShape, createRow, createColumn, createGrid, createConnectedPair, createIconLabel

File I/O (4)

exportToFile, importFromFile, saveScene, loadScene

Viewport (3)

setViewport, zoomToFit, zoomToElement

Layout (4)

getGroupBounds, alignElements, distributeElements, computePosition

Session (5)

listScenes, createScene, setCurrentScene, getCurrentScene, closeScene

License

Apache 2.0