Wiri

Wiri is a headless wireframing MCP server designed for an LLM operator. It stores each screen as a small semantic scene graph, lays elements out without absolute coordinates, and closes the editing loop with deterministic renders and lint findings.

The v1 contract is in SPEC.md. The persisted document shape is also available as schemas/wire-document.schema.json.

Requirements

• Node.js 20.9 or newer
• A local directory for documents and exports

Wiri runs entirely on the local machine. It makes no network requests and sends no telemetry. Documents, checkpoint history, rendered exports, form values, and annotations are stored as plaintext; do not use production secrets as wireframe content.

Install and run

npm install
npm run build
node dist/index.js --workspace ./wireframes

The process speaks MCP over standard input/output. It writes protocol messages only to stdout and exits when its client disconnects. WIRI_WORKSPACE can set the workspace when --workspace is omitted; the current directory is the final default.

An MCP client configuration can launch the built server like this (use absolute paths in a real configuration):

{
  "mcpServers": {
    "wiri": {
      "command": "node",
      "args": [
        "/absolute/path/to/wiri/dist/index.js",
        "--workspace",
        "/absolute/path/to/wireframes"
      ]
    }
  }
}

For development, npm run dev -- --workspace ./wireframes runs the TypeScript entry point directly.

Canonical workflow

1. Call create_document, then add one or more screens with create_screen.
2. Call get_tree before editing a screen that has not been read in the current context.
3. Prefer one or two atomic batch calls to build a screen. A later operation can refer to a node created by an earlier add with $0, $1, and so on.
4. Use render for visual feedback and lint for deterministic findings.
5. Use checkpoint before a larger revision; diff, undo, and redo make changes inspectable and reversible.
6. Use links or render_flow to verify navigation, then export to produce PNG, SVG, or static HTML.

A compact signup flow can be built in one document with this shape:

welcome --start_btn--> email --continue_btn--> password
password --continue_btn--> verify --verify_btn--> done

Each arrow is simply a to prop on its source button. HTML export turns those links into fragment navigation between screen sections.

Layered application surfaces use constrained anchors rather than freeform coordinates. For example, a full-screen image or map placeholder can use anchor="stretch", while any number of variant="fab" buttons live in stacks anchored to screen corners. Semantic left, right, and bottom drawers are direct children of the same layer.

Storage

The server owns one active document at a time and writes successful mutations before returning:

<workspace>/
  checkout_redesign.wire.json
  checkout_redesign.history.json
  exports/
    ...

Writes use a temporary file plus atomic rename. Opening another document clears session-only undo/redo stacks; named checkpoints persist in the history file. Export files are safe to regenerate and overwrite deterministically.

Commands

npm test          # unit and integration tests
npm run typecheck # strict TypeScript check
npm run build     # emit dist/
npm start -- --workspace ./wireframes

The server intentionally exposes tools only in v1—no MCP resources or prompts. Run node dist/index.js --help for command-line options.

Limits and troubleshooting

• Names and ids must match [a-z][a-z0-9_]{0,31}.
• A document supports 50 screens; a screen supports 300 nodes; a batch supports 100 operations.
• Rendered height is capped at 4000 px.
• If a call returns NO_ACTIVE_DOCUMENT, call create_document or open_document first.
• If a parent is rejected, call get_tree and choose root, overlay, or an existing container id.
• A failed call and a failed batch never change the active graph or its document file.

Wiri reads schema version 1 only. Malformed files, unknown node types, invalid props, or unsupported schema versions are rejected rather than repaired silently.

License notices

Rendered output embeds Inter from @fontsource/inter, distributed under the SIL Open Font License 1.1. See THIRD_PARTY_NOTICES.md.