Your loyal Magpie.
Lands every visual in the nest.

00Three actors

You're the reader they all serve.

trainer

Master

Teaches your AI Magpie's rules.

A portable skill bundled in the npm tarball. Decides which project a visual belongs to, when to iterate vs add, when to ask before filing. No code, no storage — pure judgment.

trained bird

Magpie

Tends the nest, version after version.

Your AI with the Master loaded. Brings visuals to the Nest, arranges them by project, keeps versions in order, asks before adding when uncertain.

dumb infra

Nest

Local. Quiet. Yours.

One SQLite file. One blobs folder. Lives at ~/.magpie/ on your disk. Holds what your Magpie brings. No LLM. No telemetry.

Master trains·Magpie tends·Nest keeps.

01Install & wire to your host

Two listeners boot from one command: stdio (for your AI host) and HTTP (for your browser).

1. Boot the server. Run npx magpie-mcp in a terminal. It prints a dashboard URL like http://127.0.0.1:3737. Open that in your browser. If 3737 is taken, it auto-bumps.
2. Install the Master skill. Run npx magpie-mcp --install-skill. Drops the skill into your host's skill directory (auto-detected for Claude Code · Claude Desktop). Your AI now knows the protocol.
3. Get the MCP config snippet. In another terminal: npx magpie-mcp --print-config. It prints both Claude Code and Claude Desktop forms.
4. Paste into your host. Use the tab below that matches your client. Restart the host to load the server.
5. Ask your AI to mock something. Try "Mock a settings page" or "Sketch the auth flow as a diagram." The visual lands in the dashboard within a second.

MCP config snippet

{
  "mcpServers": {
    "magpie": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "magpie-mcp"]
    }
  }
}

{
  "mcpServers": {
    "magpie": {
      "command": "npx",
      "args": ["-y", "magpie-mcp"]
    }
  }
}

02How it works

One process, two surfaces. Your AI commands via stdio. You watch via the browser. No LLM lives in the server.

03Seven supported formats

Your AI picks a format that fits the request. Magpie renders + thumbnails each one. All offline. All side-by-side comparable.

HTML html

.html · sandboxed iframe

UI mockups, dashboards, landing pages. Rendered in a sandboxed iframe (no allow-same-origin).

Mermaid mermaid

.mmd · bundled v11

Flowcharts, sequence, state, ER, gantt. Rendered offline — no CDN.

SVG svg

.svg · direct

Icons, logos, single vector elements. Served as image/svg+xml.

Markdown md

.md · marked + DOMPurify

Prose, READMEs, design notes. Code blocks syntax-highlighted (highlight.js).

Graphviz / DOT dot

.dot · graphviz-wasm

Directed and undirected graphs. digraph / graph source.

Vega-Lite vega-lite

.vl.json · vega SSR

Charts, data viz. JSON spec with inline data (no remote fetches).

D2 d2

.d2 · @terrastruct/d2 (wasm)

Modern diagram-as-code. Clean syntax, good for system maps.

DEFERRED

plantuml · excalidraw

offline + pure-JS rule

JVM dep / canvas-heavy — break the offline rule. Not on the roadmap.

04The dashboard

Three regions: sidebar (filters), grid (your visuals), drawer (the selected one). View-only — entity creation goes through MCP.

Search

Top bar search (or / to focus, ⌘K to reset) matches title, project, and tag. Filters from the sidebar still apply on top.

Empty state · seed scaffold

Brand-new install? The empty-state CTA loads a 7-visual seed bundle (one per format — a fictional bakery called Linden Loaf) so you have something to browse while you wire up your AI host. Dismissible · idempotent · doesn't run twice.

Dark mode

05Compare versions

When your AI iterates a visual, every version sticks. Pick any two and view them side-by-side.

Shell states

The unified shell decides what to render based on the picker selection:

URL-driven: /v/<id> for single, /compare/<id>?a=N&b=M&mode=sxs for compare. Bookmark a specific compare; reload preserves picker + mode.

06Iterate & revert

Each refinement creates a new version. Old versions never disappear.

1. Ask your AI to tweak a visual ("make it dark", "remove the sidebar"). It calls iterate(visual_id, content, message?, description?).
2. The new version becomes current. v(N-1) stays accessible.
3. From the drawer, click any version to preview it. Click Revert to v{n} to make an older version current.
4. Reverting doesn't delete history — it changes which version the thumbnail and default preview point at.

07Talk with agent

Three ways to hand a visual back to your AI — push it to the outbox, design a reusable template, or fire a slash command in your host. Same goal: get the bird flying with context already loaded.

08The Outbox

A two-lane Kanban for queued prompts: Pending on top, Consumed below. Your AI reads from Pending and moves entries to Consumed when picked up.

Lifecycle

1. Pending — entry just added. WS event inbox.added notifies the dashboard.
2. Consumed — your AI marked it consumed. WS event inbox.consumed. Stays visible for audit.
3. Deleted — you removed it. 5-second undo banner; WS event inbox.deleted.

09Templates

Reusable prompts with typed variables and visual references. 10 built-ins ship with Magpie; build your own with the same shape. Templates also surface as slash commands in MCP-aware hosts.

The 10 built-ins

Built-ins are global — they apply to every project and visual. Cannot be edited or deleted; clone first to customize.

Variables

Every template body is a Mustache-style string with named vars. Magpie resolves them against the selected visual:

Scope

User templates can be scoped:

• Global — appears everywhere. Default for new user templates.
• Project — only shows when the selected visual lives in that project. Use for project-specific verbs.
• Visual — only shows for one specific visual. Use for a recurring iteration loop on one artifact.

Built-ins are always global — the store rejects scope on builtin rows.

Visual references

Each template can carry up to 3 visual references — pinned visual ids (optionally version-pinned) that get resolved into the prompt as additional magpie://visual/<id> chips. Use them when an iteration always needs context from the same companion piece — e.g., "compare against the locked design spec".

MCP Prompts — same templates, host-fired

Magpie exposes its templates as MCP Prompts. In your AI coding agent, type /magpie: and the slash menu surfaces them: /magpie:iterate, /magpie:variants, /magpie:explain, /magpie:a11y_audit, /magpie:responsive_check, /magpie:dark_mode_port, /magpie:simplify, /magpie:add_data.

The host resolves the slash, asks for any required vars, and fires the prompt to your AI as the next turn. No clipboard, no Outbox roundtrip — direct invocation. Built-ins ship today; user templates surface in MCP Prompts in v1.1.

10Keyboard shortcuts

Press ? from any dashboard view to see them all.

11MCP tool surface

Your AI has 14 tools and 3 resources. You don't call them directly — you ask in plain English, and the Master skill picks the right tool.

MCP resources

12Export

Take any visual offline. Three single-file forms plus a project zip.

Find these on the drawer ("Download") or via dashboard project menu ("Export project").

13Backup & restore

Two ways to back up. Both produce a single artifact you can store wherever you store everything else.

The folder copy

Everything Magpie holds is at ~/.magpie/ (or wherever MAGPIE_HOME points). Quit Magpie, copy the folder, you're done.

The CLI

$ npx magpie-mcp --backup
→ wrote magpie-backup-2026-05-19.tar.gz (12.4 MB)

Writes a USTAR + gzip archive. Zero new dependencies. Internally runs a WAL checkpoint first so the snapshot is consistent.

Restore

Extract the archive into ~/.magpie/ (or your MAGPIE_HOME), reboot Magpie. Migrations are forward-only — restoring an older snapshot replays missing migrations on next boot. There is no rollback path by design; downgrade = restore from an older backup.

14FAQ & not-goals