@particlr/mcp

Source: https://github.com/brac/particlr-mcp (MIT).

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"]
    }
  }
}

Related MCP server: clayform

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 — 71 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

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