paintress
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
To install: paste this repository's URL into your agent and ask it to install paintress. Agents that need a precise procedure will find one at the end of this file.
What it is
paintress is a UI design tool for AI agents. You describe a screen in chat, the agent draws it into a design file, and you watch it appear in your browser — no canvas to drag, no design app to learn.
You point instead of describing: click any element in the viewer and it gets a short number (#1), so "make #1 blue" changes exactly that element.
Designs are plain JSON files inside your project, so they diff and commit like code.
The agent does the reading and writing, through MCP tools or the CLI. The browser viewer is for looking, clicking and marking.
Part | Purpose |
MCP tools | paintress_viewer, paintress_new, paintress_doc_info, paintress_query, paintress_get, paintress_update, paintress_insert, paintress_delete, paintress_move, paintress_batch, paintress_validate, paintress_convert, paintress_preset, paintress_project, paintress_font, paintress_audit, paintress_establish, paintress_adjust, paintress_component, paintress_render, paintress_screenshot, paintress_marks |
CLI | the same operations plus the viewer process, for use without an agent |
Viewer | local web server: renders a document, highlights changes, hands back clicked nodes as |
Screenshot | PNG of a canvas or one board; scale 0.2–2 (default 0.8), either edge capped to 8192px |
Related MCP server: gitcad
Files and formats
New files are .ptr — paintress's own flavor of the same JSON design document. Existing .pen files open, edit and render unchanged; only the extension differs.
Two project-level files keep a project consistent. They live at the registered project root — the directory you watch, not the folder of an individual design file — and they belong in version control next to the designs. paintress_project (and the viewer's designSystem block) returns their exact paths and reports any nested duplicate that would split the design system:
File | Holds |
| design tokens (colors, radii, spacing, font sizes, font families), preset groups and the font registry |
| reusable components (nodes marked |
Requirements
Node.js 22 or newer.
Install
npm install -g paintressThen register it with the agent(s) you use:
paintress doctor # what is installed and which clients already have the entry
paintress install # write the MCP entry into every detected client config
paintress install pi cursor # or only the ones you nameinstall merges a single entry, preserves everything else in the file, and writes a *.bak-<timestamp> backup before touching it. Running it twice changes nothing.
CLI
paintress mcp start the stdio MCP server
paintress new <file> [--name n] [--width n] [--height n] [--fill c]
[--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
create a design file (one empty board)
paintress info <file> document summary
paintress convert <file.pen> [out.ptr] [--force] convert .pen to .ptr (source untouched)
paintress query <file> [--type t] [--name n|--regex] find nodes
paintress get <file> <id> [--depth n] read a node subtree
paintress update <file> <id> '<patch-json>' shallow-merge attributes
paintress insert <file> <parent> '<node-json>' insert a child node
paintress delete <file> <id> remove a node
paintress move <file> <id> <parent> [--index n] reparent a node
paintress batch <file> '<ops-json>' several operations at once
paintress validate <file> check against the format spec
paintress preset list|set|remove|seed|set-group|remove-group ...
tokens, groups and the starter scale
paintress font list|add|remove|default ... project font registry
paintress audit <file> read-only design-system audit
paintress establish <file> [--apply] propose tokens / preset groups (dry-run by default)
paintress adjust <file> --key k --value v [--apply] preview or apply a design-system adjustment
paintress component list|insert|add ... project component library
paintress render <file> <out.html> write the canvas as HTML
paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name] render to PNG (default 0.8)
paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
ensure the viewer is running (idempotent, returns at once)
paintress ping | status | stop viewer control
paintress watch <name> <dir> [--depth n] | unwatch <name> register a directory to browse
paintress attach <name> keep the viewer alive while an agent works
paintress install [client...] [--dry-run] write MCP config entries
paintress doctor show client configuration state
paintress mcp-config <client> print the config snippet for one clientViewer
paintress web
paintress watch demo ./demo
# open http://localhost:6033/demopaintress web is idempotent and returns immediately: if a viewer is already running it prints that process's pid / port / http, otherwise it starts one and opens the viewer window on it. Either way the command is safe to run before every drawing session — there is never a second instance, and the window is opened by the program, in the desktop browser (--foreground keeps the process attached to your shell when you want its log; paintress stop is how you replace a running viewer, e.g. on another port). Under WSL the window lands in the Windows browser, never in a browser inside the distro.
The port is not a constant you should memorize: it is chosen at startup and reported back. The default is 6033; if that port is unusable the viewer walks 6033 → 6133 → 6233 on 127.0.0.1, and if none of them can be reached from the host it re-binds the same three ports on 0.0.0.0 (six candidates, first usable one wins, otherwise it fails with the full attempt table). Under WSL this matters: Windows can reserve a port for Hyper-V, in which case localhost forwarding is never created and the human's browser sees "connection refused" while everything inside the distro works — the fallback then hands you http://<wsl-ip>:6033/ instead. The http / access.url field is authoritative: print it, do not rebuild it. --port pins one port and never jumps (a busy port is an error), --bind loopback|all pins the interface.
Agents get the same guarantee from the MCP side: paintress_viewer ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks. Its result carries the same url / access block, so an agent that started the viewer on a fallback port tells the human the address that actually works.
A design file that has a sibling Markdown file of the same name (home.ptr → home.md) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note: what the design is for, what is still open, which requirement it answers. The note is a plain Markdown file next to the design — write it yourself or let the agent write it; the panel is read-only.
The rail in the top-right corner holds the project's design system. Presets are the project's colors, corner radii, spacing and font values: the agent references them ($color-brand) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". Nodes can also reference a whole preset group; groups are shown read-only in the panel. Components is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists. A font badge next to the version shows how many families loaded; when one is missing its tooltip names the substitute.
Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, Ctrl/Cmd+0 returns to 100%, Shift+1 fits the window, and Ctrl/Cmd+K quickly switches design files. Selecting a node opens a read-only inspector. Files with more than one board get a board strip; the active board can be exported as PNG at 0.5x / 1x / 2x (1x means its design pixels; the file is <design>-<board>@<scale>x.png and is scaled back when either edge exceeds 8192px). Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with paintress_marks; each mark carries the file and node id, so a shorthand resolves to one element in one file.
Projects are named after their directory path (c-thun/raybend), so the URL reads like the path: http://localhost:6033/c-thun/raybend?file=design/editor.pen. Project rows have an × on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and Stop server in the sidebar footer shuts the viewer process down — both ask for confirmation first.
The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens your browser on that agent's own project — nothing for the agent to run twice, nothing for you to open by hand; projects appear and leave with a short animation as agents come and go. When the last project is gone or the server is stopped (the sidebar's Stop server, an idle exit), the page counts down ten seconds and closes its own window — you never have to close the tab by hand. A browser that nobody is looking at no longer keeps the process alive.
When npm has a newer release than the running one, the version badge in the header grows a second line in rust red; clicking it opens the upgrade prompt (one copyable sentence) and the GitHub link. The check is client-optional on the daemon side: if npm is unreachable, the badge simply stays as it is.
The toolbar's right side has two viewer-only controls. Canvas background switches Light / Gray / Dark for the design surface without touching the rest of the UI. Language switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new design file into a watched directory, updates every open viewer without a reload.
Design system
One source of truth per project, so a change lands everywhere instead of on one screen:
Tokens live in
__preset.ptrand are referenced as$color-brand— never pasted. Kinds:color,radius,spacing,fontSize,font.Preset groups apply a set of token references to one node type; a node opts in with
preset: "card".Components live in
__components.ptr; the agent copies one in, so a design is not rebuilt from scratch.Fonts are registered per family with a source (
webCSS URL, a projectcss/file, asystemfont, orbundlefor app-only fonts) and, when the source cannot be verified, a design-timepreview. Every read reports which families loaded and which fell back.
paintress_preset seed (dry-run by default) fills a coherent starter scale — 27 tokens, 6 preset groups and the two web fonts. audit finds drift, establish proposes tokens from repeated values, and adjust shows the blast radius before changing anything.
Environment variables
Variable | Effect |
| Browser executable used for screenshots and PNG export |
| State directory (daemon registry, Chromium font cache); default |
|
|
|
|
|
|
| Port the |
|
|
MCP clients
paintress install writes these; the same entries can be added by hand.
Client | Config file | Top-level key |
Claude Desktop |
|
|
Cursor |
|
|
VS Code |
|
|
Windsurf |
|
|
Codex |
|
|
pi |
|
|
OpenCode |
|
|
paintress mcp-config cursor # print the exact snippet instead of editing filesSkill
skills/paintress/SKILL.md is a short instruction file for agents: when to reach for these tools, to bring the viewer up before drawing (idempotently), how #1 markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.
Documentation
specs/PLAN.md— roadmap and open questionsformat/spec.yaml— the design file format specformat/README.md— how the format layers relate.agents/memory/ARCHITECTURE.md— design decisions and their rationale.agents/implementations/— per-change records with measurements
paintress also opens existing .pen design files as-is; paintress convert turns one into .ptr when you ask for it.
Release (maintainers)
Publishing is tag-driven: a v* tag makes .github/workflows/publish.yml first check that ci passed for the same commit, then build, verify the package contents and run npm publish --provenance through OIDC trusted publishing. Tests run once, in ci.yml; publishing does not re-run them. Do not publish from a laptop.
pnpm release patch # 0.3.1 → 0.3.2
pnpm release minor # 0.3.1 → 0.4.0
pnpm release major # 0.3.1 → 1.0.0
pnpm release patch --dry-run # print the plan only
pnpm release --retag # after a failed release: move the unpublished tag and re-publishThe script refuses to run on a dirty worktree or a non-default branch, verifies the tag is free, runs typecheck (server + ui), the test suite, the build and the package-contents check, then commits chore(release): vX.Y.Z, tags it, pushes branch + tag, and finally waits until the version is actually on npm (a green run that published nothing is reported as a failure, not a success).
--prepare-only stops after the local commit and tag; --no-wait returns right after the push; --local publishes from this machine as an emergency path and skips the CI checks. --retag is the recovery path after a failed release: once it confirms the version is not on npm yet, it moves the existing tag to the current commit and re-publishes under the same version number; an already published version is refused.
License
MIT
Installation guide for AI agents
You are an agent asked to install paintress on this machine. Work through the steps in order and report what you found, what you reused, and what you changed.
Detection comes first. Several agents can share one machine. A previous agent may already have installed paintress globally and registered it for itself. Installing a second copy is a bug, not thoroughness.
0. Detect
Check | Command | What it tells you |
Binary on PATH |
| a usable install already exists |
Global npm package |
| installed globally via npm |
Project-local |
| installed inside the current project |
Client configs |
| which agents already have an entry, and its state |
Rules:
Any hit means reuse. Do not install again; go to step 2.
Report the resolved path and version:
paintress --versionprints the package version (ornpm ls -g --depth=0 paintress).Only when every check is empty do you install (step 1).
If the install succeeded but command -v paintress still finds nothing (some version managers need a new shell), call it by full path — do not install a second copy:
"$(npm prefix -g)/bin/paintress" doctor1. Install (only if step 0 found nothing)
npm install -g paintressIf global installs are not permitted in this environment:
npm install paintress # project-local; call it through npx paintress ...
npx -y paintress@latest ... # no install at all; slower on first runPrefer the global install. It is what makes the entry in every client config reusable by the next agent.
2. Register the MCP server for the agent you are running in
paintress doctor # list detected clients and their state
paintress install --dry-run # preview the writes
paintress install <client-id> # write only the client you are running inClient ids: claude, cursor, vscode, windsurf, codex, pi, opencode. Use paintress install without arguments to cover every detected client.
OpenCode has two config layouts in the wild. install follows whatever the existing file already uses and falls back to the current mcp.servers shape for a new file; force it with --opencode-layout legacy or --opencode-layout v2.
What the write does:
adds or refreshes one entry named
paintress(mcpServers.paintress, orservers.paintressfor VS Code, or[mcp_servers.paintress]for Codex);leaves every other key, server and comment structure in the file alone;
writes
*.bak-<timestamp>next to the file before replacing it;is idempotent: an identical entry reports
noopand nothing is written;uses the bare command
paintresswhen it resolves on PATH, otherwise the absolute path of the binary.
If your client is not in that list
The entry is small and nearly the same everywhere, so adapt it by hand:
Find where the client keeps its MCP servers — its own docs, an
/mcpcommand, or a "configure MCP servers" menu item.Match the shape. Most clients use a
mcpServersobject holdingcommand+args; VS Code usesserverswith"type": "stdio"; OpenCode puts a singlecommandarray undermcp.servers(older builds: undermcp) with"type": "local"; Codex uses a TOML table.Print the closest snippet and edit it:
paintress mcp-config cursor # JSON with mcpServers
paintress mcp-config vscode # JSON with servers + type: stdio
paintress mcp-config opencode # JSON with mcp.servers + command array
paintress mcp-config codex # TOML tableTo make a client first-class (so doctor and install cover it), add one spec to src/integrations/clients.ts — id, label, format, rootPath, optional typeValue / commandForm / extraFields, and configPath(home, platform, env) — plus one test in test/integrations.spec.ts. No other file needs to change.
3. Install the skill (recommended)
mkdir -p <your-skill-dir>/paintress
cp "$(npm root -g)/paintress/skills/paintress/SKILL.md" <your-skill-dir>/paintress/SKILL.mdUse the skill directory your harness actually reads (~/.pi/agent/skills/, ~/.claude/skills/, .cursor/skills/, …). If your harness has no skill mechanism, load the file into context once and keep the tool list.
4. Verify
paintress doctor # entry present, command resolvable
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcpThe second command must answer with a result containing "serverInfo": {"name": "paintress", …}. After a session restart, paintress_doc_info on any design file is the end-to-end check.
5. Multi-agent rules
One global install serves every agent on the machine. Do not create per-agent copies.
Each agent adds its own config entry. Never rewrite another agent's file, and never remove entries you did not add.
If
doctorreportsnoop, another agent already registered it correctly — stop there and say so.Report the outcome as: reused / installed / registered (which client) / skipped (why).
6. Uninstall
npm uninstall -g paintressThen delete the paintress entry from each client config, or restore the newest *.bak-<timestamp> next to it.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Design canvas for agents: create, edit, render and export Figma-shaped designs over MCP.
Live, editable canvas for AI agents — author graphs via MCP, then watch and reroute runs live.
Agent-Native design tool - create and edit visual designs with agent assistance
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to control pen plotters via MCP tools for text layout, SVG/DXF import, G-code generation, device control, and vision calibration.16-

gitcadofficial
AlicenseNot gradedqualityDmaintenanceEnables agents to create and manipulate 3D CAD models using natural language via MCP, with git-based versioning and manufacturing output generation.2Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to directly view, understand, and modify local Sketch/Figma design files, including writing code, applying semantic edits, and exporting assets, all through a local MCP server without uploading data.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to execute editable-3D design programs, inspect their geometry, and replay or revise native project files through MCP tools.1Apache 2.0