# Pixl

**Open-source MCP server for designing mobile UIs.** Pixl plugs into whatever AI coding host you already use (Claude Code, Cursor, …) and turns it into a guided mobile-UI design tool. Your host's model does the generating — Pixl supplies the taste it lacks: a locked design-system **token contract**, a **linter** that rejects off-standard output, and a **local browser preview** with a phone-frame gallery and a draggable user-journey flow map. Everything runs locally.

> Status: **v0.1, feature-complete** — MCP server, workspace, live preview, design-system presets + token contract, screen generation with the taste linter, and the draggable user-journey flow canvas.

## How it fits together

```
host (Claude Code / Cursor) ──MCP stdio──▶ pixl-mcp (Node/TS)
                                             │  owns .pixl/ workspace, runs linter
                                             ▼
                            localhost:4321  Vite + React preview
                              ├── Screen gallery (phone frames, live-reload)
                              └── Flow canvas (dotted bg, draggable)
```

State lives in a `.pixl/` folder in your project: `tokens.json`, `design/*.md`, `screens/*.html`, `flow.json`.

## Install

Pixl **auto-starts** when your host connects: it creates the `.pixl/` workspace, boots the preview, and opens `localhost:4321` in your browser. No `pixl_init` call needed — just point your host at it and start asking for screens.

**npx (recommended):**

Cursor — `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "pixl": { "command": "npx", "args": ["-y", "pixl-mcp"] } } }
```

Claude Code:

```bash
claude mcp add pixl -- npx -y pixl-mcp
```

**Docker** (no Node needed; fully isolated). `-p 4321:4321` forwards the preview; the `sh -c` wrapper reaps any prior container so relaunches don't clash on the port:

```json
{
  "mcpServers": {
    "pixl": {
      "command": "sh",
      "args": [
        "-c",
        "docker rm -f pixl-mcp >/dev/null 2>&1; exec docker run --rm -i --name pixl-mcp -p 4321:4321 -v \"$PWD\":/work -w /work pixl-mcp"
      ]
    }
  }
}
```

Build the image first with `docker build -t pixl-mcp .` (or pull it once published).

## Develop

```bash
npm install --include=dev   # this machine has npm omit=dev set globally
npm run build               # compile the server to dist/
npm run typecheck
npx vitest run               # linter unit tests (pass/fail fixtures)
node scripts/smoke.mjs        # workspace + preview API end-to-end
node scripts/mcp-smoke.mjs    # drives the server as a real MCP client
node scripts/phase2-smoke.mjs # design system + screen plan
node scripts/phase3-smoke.mjs # write/lint screen: reject bad, accept fixed
node scripts/phase4-smoke.mjs # flow graph + drag-persist round-trip
```

## Register a local build (from source)

Claude Code:

```bash
npm install --include=dev && npm run build
claude mcp add pixl -- node /absolute/path/to/pixl-mcp/dist/index.js
```

The preview auto-starts and opens `localhost:4321` — then ask your assistant to set a design system and generate screens.

## Tools

| Tool | Purpose |
|---|---|
| `pixl_init` | Re-open the preview / fetch its URL (auto-runs on startup — you don't call it) |
| `pixl_status` | Report workspace state |
| `pixl_list_presets` / `pixl_set_design_system` / `pixl_plan_screens` | Design system + screen plan |
| `pixl_write_screen` / `pixl_lint_screen` | Generate + lint screens |
| `pixl_set_flow` | User-journey flow graph |

MIT.