# @particlr/mcp

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

An MCP server that lets coding agents author [particlr](https://particlr.com)
`.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`](https://www.npmjs.com/package/@particlr/runtime)
(PixiJS v8/v7) and open in the [particlr editor](https://particlr.com).

## Setup

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

```json
{
  "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` — 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

| 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](https://particlr.com) — effects round-trip losslessly.

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

## License

MIT