Files
2026-11-17 13:34:18 -07:00

4.2 KiB

AniCraft for AI assistants (MCP)

anicraft-cli mcp is a Model Context Protocol server. Any MCP client (an AI assistant, an editor, a script) can then open a document, draw, animate, look at frames and export through the same commands the app uses.

anicraft-cli mcp                      # a new, empty document
anicraft-cli mcp scene.anicraft       # open a document
anicraft-cli mcp --sample             # the sample animation
anicraft-cli mcp --bridge 9878        # the AniCraft window you have open (below)

Headless or live

Without --bridge the server edits a document of its own, with no window: good for pipelines and batch work. Save it (file.save) to keep the result.

With --bridge <port> the same tools act on the AniCraft window you have open, started with anicraft --control <port>: every edit appears there at once, and Ctrl+Z undoes it (docs/control-protocol.md, ADR 0104). The server starts even when AniCraft isn't open (an assistant starts its servers when it starts) and connects on the first tool call; until AniCraft is open with remote control, the tools answer with how to start it. Close and reopen AniCraft whenever you like: the next call reconnects, with no need to restart the assistant. It finds the run's token in control.json in AniCraft's settings folder, so there is nothing to copy.

The server talks MCP's stdio transport: JSON-RPC 2.0, one message per line on stdin and stdout. It speaks protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05.

Connecting a client

Most clients take a server entry like this one (use the full path to anicraft-cli):

{
  "mcpServers": {
    "anicraft": {
      "command": "/path/to/anicraft-cli",
      "args": ["mcp", "/path/to/scene.anicraft"]
    }
  }
}

For live editing, start AniCraft with --control 9878 (a desktop shortcut is handy) and use:

{
  "mcpServers": {
    "anicraft": {
      "command": "C:\\path\\to\\anicraft-cli.exe",
      "args": ["mcp", "--bridge", "9878"]
    }
  }
}

Tools

Tool What it does
anicraft_commands Lists the commands (id, label, menu, shortcut, params), optionally filtered by words such as tween or export.
anicraft_run Runs one command with its params.
anicraft_run_script Runs several commands in order; stops at the first error and says which step failed.
anicraft_document Describes the document: stage, scenes, layers and keyframes, library, and the current scene, frame, layer and selection.
anicraft_render Returns a frame of the current scene as a PNG picture, exactly as exported.

The assistant sees one tool per job, not one per command: the command list is long and grows with every release, and anicraft_commands lets it find what it needs. Frames in params are 0-based, as everywhere in the engine (the CLI's own --frame flags are 1-based, as in the timeline).

Saved commands (ADR 0097) run through anicraft_run too: macro.run with {"path": …} (a saved command's file) or {"steps": [{"cmd", "params"}]} runs the steps as one undo step, and unlike anicraft_run_script a failing step leaves the document as it was. macro.history and macro.save turn the session's undo steps into a saved command.

Safety

  • Everything runs through the engine's commands, so params are checked and every edit can be undone with edit.undo.
  • Commands that would lose unsaved work or replace a file refuse until their params include "confirm": true (ADR 0004). The server's instructions ask the assistant to check with you before confirming.
  • Commands read and write files with your permissions, at the paths the assistant gives (open, save, import, export), as with the CLI. Only connect clients you trust with those files.
  • A failing command comes back as a tool result marked as an error, so the assistant can read the message and try again; it never stops the server.
  • Live (--bridge): an edit whose answer was lost (AniCraft closed mid-call) is never sent again, since it may have been made; the assistant is told to check with anicraft_document. While you are dragging, the assistant's edits wait until you let go, so the two stay separate undo steps.