@particlr/mcp

An MCP server that lets coding agents author particlr .prt particle effects headlessly, with a real feedback loop instead of blind JSON generation: validate against the actual parse/migrate/validate pipeline, simulate deterministically in Node, render frames to PNG with a CPU rasterizer, and iterate by patching — no browser, no GPU, no flakiness.

Everything is deterministic: the same document, seed, and dt sequence produce the same simulation state and the same pixels, so a diff between two renders is a real diff. Effects authored here play back byte-for-byte in @particlr/runtime (PixiJS v8/v7) and open in the particlr editor.

Setup

Requires Node >= 20. For Claude Code, add to .mcp.json (or for any MCP client, the equivalent stdio server config):

{
  "mcpServers": {
    "particlr": {
      "command": "npx",
      "args": ["-y", "@particlr/mcp"]
    }
  }
}

The loop

An agent authoring an effect works this cycle:

1. get_reference("authoring-guide") — how to make a .prt look good: units, layer recipes, blend idioms, common mistakes. "format-spec" and "schema" are the normative references.
2. list_presets / get_preset — 57 CC0 effects (explosions, fire, smoke, shields, trails, weather…) as a few-shot corpus. Pull the closest one and mutate it.
3. open_effect — validate and store the doc under a session handle.
4. patch_effect — iterate by sending only RFC 6902 diffs (replace / add / remove), all-or-nothing with rollback on any error.
5. simulate_effect — the cheap loop: per-layer live counts over time, peak vs capacity, spatial bounds, completion time, and a reproducible statehash.
6. render_effect — see it: a 16-frame auto-framed contact sheet PNG by default, or individual frames at chosen times. overrunSeconds renders past the duration to check loop seams.
7. get_effect — pull the canonical .prt text for delivery.

Tools

| Tool | What it does | |---|---| | validate_effect | Parse → migrate → validate; canonical doc or path-anchored errors | | simulate_effect | Deterministic headless sim: counts, bounds, completion, statehash | | render_effect | CPU-rasterize to PNG frame(s) or a contact sheet | | open_effect | Store a doc under a session handle for iteration | | patch_effect | Apply RFC 6902 ops to a stored doc, re-validate, rollback on failure | | get_effect | Fetch the canonical stored .prt text | | list_presets / get_preset | The shipped preset corpus | | get_reference | Authoring guide, format spec, or JSON Schema, inline |

What the renderer is (and isn't)

render_effect is a deterministic software rasterizer built for agent iteration: all builtin and embedded-PNG textures, all five blend modes, flipbooks, stretch/velocity-align, per-particle and connect-ribbon trails, and layer draw order. It is structurally faithful to the GPU preview, not pixel-identical to it. Two things it does not show: the dissolve module is not rasterized, and the emitter never moves headlessly, so world-space trails that depend on emitter motion read as local. Judge those in the editor — effects round-trip losslessly.

Session handles live only for the server process; export with get_effect before disconnecting.

License

MIT