@particlr/mcp

@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:

• 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.
• 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.
• open_effect — validate and store the doc under a session handle.
• patch_effect — iterate by sending only RFC 6902 diffs (replace / add / remove), all-or-nothing with rollback on any error.
• simulate_effect — the cheap loop: per-layer live counts over time, peak vs capacity, spatial bounds, completion time, and a reproducible statehash.
• 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.
• 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