p5loom

MCP server

p5loom ships a Model Context Protocol server. Any MCP client can validate a spec, see what it draws, change its controls, and get the picture back as SVG. It also serves the spec reference, the JSON Schema and the examples as resources, and three prompts for common tasks. The server has no dependencies.

Connect from your computerStandard input and output

Desktop and IDE clients run the server as a process. It is trusted as the user who starts it, so no token is needed. For Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "p5loom": {
      "command": "node",
      "args": ["/path/to/p5loom/bin/p5loom-mcp.mjs"]
    }
  }
}

For Claude Code:

claude mcp add p5loom -- node /path/to/p5loom/bin/p5loom-mcp.mjs

Cursor, VS Code and other clients take the same command and arguments in their own MCP settings.

Over HTTP, openNo token, this computer only

For a client that wants a URL on this machine. The server binds to 127.0.0.1 and refuses to start without a token on any other address.

node /path/to/p5loom/bin/p5loom-mcp.mjs --http 7340
# open: no token, 127.0.0.1 only. Point a local client at http://127.0.0.1:7340/mcp
Over HTTP, with a tokenRequired for any other address

Set a token and every request must present it as Authorization: Bearer <token>. A request without it gets 401 and a WWW-Authenticate challenge that points at the discovery document. Tokens are stored as SHA-256 digests and compared in constant time. A token must be at least 24 characters.

export P5LOOM_MCP_TOKEN="$(node /path/to/p5loom/bin/p5loom-mcp.mjs --new-token)"
node /path/to/p5loom/bin/p5loom-mcp.mjs --http 7340 --host 0.0.0.0
# every request now needs: Authorization: Bearer <that token>

Several callers, each with its own token, so one can be revoked without affecting the others. The name appears in the audit log.

P5LOOM_MCP_TOKENS="ci=<token-a>,laptop=<token-b>" node bin/p5loom-mcp.mjs --http 7340 --host 0.0.0.0 --rate 60 --burst 10
Rate limitsEvery HTTP caller

Each caller has a bucket: a burst of --burst requests (default 30) that refills at --rate a minute (default 120). A caller over its limit gets 429 with Retry-After. Other callers are not affected. Stdio is not rate limited, because the local user is already trusted.

Audit trailOne line per tool call, on stderr

Each call writes who (the caller's name, or stdio, or open), which tool, whether it succeeded, and how long it took. Arguments are never written, so a spec or a token in a request does not reach the log.

Tools9 tools, all pure
ToolWhat it does
p5loom_referenceThe p5loom spec format in one page: fields, element types, coordinates, colours, controls, bindings and limits. Read this before writing a spec.
p5loom_element_typesThe element types a spec can use, with the fields each one takes.
p5loom_validateCheck a spec without drawing it. Returns valid true, or the list of problems with the field that caused each one.
p5loom_list_controlsThe controls a spec declares, with their types, ranges, options and default values.
p5loom_resolveThe spec that would actually be drawn for the given control values: bindings replaced, hidden elements removed. Use it to see what a control change does.
p5loom_describeThe text description a screen reader would read for this picture, with counts of each element and of the generated dots.
p5loom_render_svgDraw the picture as an SVG document (returned as text). Save it as a .svg file or embed it in a page. Uses the same plan as the browser, so the picture matches.
p5loom_list_examplesThe example pictures that ship with p5loom, with a title and a line on what each one teaches.
p5loom_get_exampleA complete example spec by id. Start from one of these when writing a new picture.
Resources12 documents to read
URIWhat it is
p5loom://referenceThe p5loom spec format in one page.
p5loom://schemaJSON Schema (draft 2020-12) for version 1 specs.
p5loom://examples/sunriseRandom dots for stars, a sun on the horizon, and a ground that hides what sits under it. The picture at the top of this site.
p5loom://examples/<id>Each example spec, by id.
Prompts3 tasks
PromptWhat it does
make-chartTurn a table of data into a p5loom chart: a data table, axes with a zero baseline, and the right element for the question.
design-controlsDecide what in a picture should be adjustable, declare those controls, and bind the fields that follow them.
review-specCheck a spec against the format, the limits and the picture it is meant to draw, and say what to change.

Pasted material is fenced as data inside each prompt, so text in it cannot change the instructions.

SafetyData in, pictures out