Artisign MCP server

Artisign

An artificial artisan for UI design: agents build screens, a design system keeps them consistent.

Local-first UX design tool for AI agents. Agents design through MCP, the human reviews in the browser, state lives in plain files.

One Node process on 127.0.0.1. No database, no accounts, no hosting.

Status: Stable (1.0.1) — CLI, store, parser/model, the 24-tool MCP surface, browser preview with live reload/flows/comments, the design system (tokens, variants, drift warnings, promotetosystem), and packaging are all implemented. Artisign designs its own browser preview — see Designed with itself.

Why

1. Consistency across screens — the design system is first-class; screens store refs, never inline values
2. Token efficiency — tiered reads, field selection, diff mode on writes
3. Flows as first-class — click routes are data, not documentation
4. Render determinism — the preview renders the source, so preview equals output by construction

Install

Node.js ≥ 20.19, on macOS or Linux. Windows is not supported — the store's atomic writes (write temp file, then rename) and its path handling have never been verified there, so the tool is not shipped for it. package.json declares this via os, which makes npm install refuse the platform rather than fail somewhere later.

Two ways to run it, and the choice matters. npx artisign fetches the package on first use and needs no setup — the fastest way to try it, and enough for everything except the two screenshot tools. Installing it into a directory of your own is the other path, and the one to pick if you want screenshots:

mkdir artisign && cd artisign
npm install artisign

The commands below are written as npx artisign. With a local install, run ./node_modules/.bin/artisign instead — or npm install -g artisign and just artisign.

Canonical quickstart. The local install, from an empty directory to a connected agent. Start the daemon before registering the MCP server — the HTTP registration below runs against an already-running daemon:

mkdir artisign && cd artisign
npm install artisign
./node_modules/.bin/artisign start ./my-project
claude mcp add --transport http artisign "http://127.0.0.1:4711/mcp?project=/absolute/path/to/my-project"

The first two lines repeat the install above on purpose: the point of this block is that nothing has to be assembled from elsewhere. On the npx path, drop them and start with npx artisign start ./my-project instead — the screenshot tools are then unavailable, as described below.

Optional: screenshots. getscreenshot and inspectnode need a real browser, which is intentionally not bundled (npx artisign stays light without it). Playwright is an optional peer dependency — npm neither installs it nor its ~150 MB of browser binaries unless you ask for them by name. Two ways to do that:

1. Next to Artisign. In the directory you installed artisign into:

npm install --no-save playwright && npx playwright install chromium

--no-save matters: it installs the package without writing it into package.json or the lockfile, which is the whole point of Playwright being optional. Without the flag npm edits both files; with some npm versions a plain npm install playwright even reports up to date and installs nothing, because an optional peer counts as satisfied when absent.

1. Anywhere, named by ARTISIGNPLAYWRIGHTDIR. Install Playwright once into a directory of its own and point Artisign at it:

mkdir -p ~/.artisign-playwright && cd ~/.artisign-playwright
   npm init -y >/dev/null && npm install playwright && npx playwright install chromium
   export ARTISIGN_PLAYWRIGHT_DIR=~/.artisign-playwright   # in the shell that starts the daemon

Shortened. The full README is on GitHub.