# Nib MCP guide for design agents

Nib is a local macOS design canvas controlled through MCP. Agents edit plain `.nibs` documents, inspect rendered results, and export exact PNG or HTML files.

## Connect an agent

The easiest setup is **Nib → Set up agents…**. Select Claude Code, Codex, or Claude Desktop and click Apply. Nib preserves the rest of each config and creates a `.bak` backup before changing an existing file.

The installed MCP command is:

```text
command: /Applications/Nib.app/Contents/MacOS/Nib
args:
  - /Applications/Nib.app/Contents/Resources/mcp-shim/shim.js
  - --agent
  - <agent-name>
env:
  ELECTRON_RUN_AS_NODE: "1"
```

Use `claudeCodeCLI`, `codexCLI`, or `claudeDesktop` for `<agent-name>`. The shim launches Nib automatically when the app is closed and then connects over its local Unix socket.

### Claude Code or Claude Desktop JSON

```json
{
  "mcpServers": {
    "nib": {
      "command": "/Applications/Nib.app/Contents/MacOS/Nib",
      "args": [
        "/Applications/Nib.app/Contents/Resources/mcp-shim/shim.js",
        "--agent",
        "claudeCodeCLI"
      ],
      "env": { "ELECTRON_RUN_AS_NODE": "1" },
      "type": "stdio"
    }
  }
}
```

For Claude Desktop, change the agent value to `claudeDesktop`.

### Codex TOML

```toml
[mcp_servers.nib]
command = "/Applications/Nib.app/Contents/MacOS/Nib"
args = ["/Applications/Nib.app/Contents/Resources/mcp-shim/shim.js", "--agent", "codexCLI"]
startup_timeout_sec = 120
tool_timeout_sec = 300

[mcp_servers.nib.env]
ELECTRON_RUN_AS_NODE = "1"
```

Restart the agent after changing its MCP configuration.

## Recommended design loop

1. Call `get_state` before editing. Read the active file, current selection, variables, tree, and schema summary.
2. Call `get_guidelines()` to list the design guides and styles.
3. Load one task guide and one suitable style with their parameters.
4. Use `get_nodes` when you need full details for specific nodes.
5. Make one coherent atomic change with `batch_edit`.
6. Call `screenshot` and judge the rendered pixels—not only the JSON.
7. Use `snapshot_layout` to catch clipping, overlap, or incorrect sizing.
8. Iterate until the composition is clean, then call `export`.

Do not guess node IDs or edit the `.nibs` file directly while Nib is open.

## Available tools

### `get_state`

Returns the active document path, variables, human selection, and depth-limited tree. The first call from each agent also includes the schema summary.

```json
{ "depth": 3 }
```

### `get_nodes`

Reads nodes by exact ID, case-insensitive name pattern, or both.

```json
{
  "ids": ["hero1", "title"],
  "namePattern": "hero|cta",
  "searchDepth": 2
}
```

### `batch_edit`

Applies all operations atomically and saves the document. If any operation is invalid, none are applied.

```json
{
  "ops": [
    {
      "op": "insert",
      "parentId": null,
      "node": {
        "id": "hero1",
        "type": "frame",
        "name": "Launch Hero",
        "x": 0,
        "y": 0,
        "width": 1440,
        "height": 900,
        "layout": "column",
        "padding": 80,
        "gap": 24,
        "fill": "$surface",
        "children": []
      }
    },
    {
      "op": "insert",
      "parentId": "hero1",
      "node": {
        "id": "title",
        "type": "text",
        "content": "Designed with intent.",
        "font": "Newsreader",
        "size": 88,
        "weight": 600,
        "color": "$text"
      }
    }
  ]
}
```

Supported operations:

- `insert`: `{ op, parentId, index?, node }`. Use `parentId: null` for a top-level node.
- `update`: `{ op, id, props }`. Properties are shallow-merged and revalidated.
- `delete`: `{ op, id }`. Deletes the node and its subtree.
- `move`: `{ op, id, parentId, index? }`. Use `parentId: null` to move to the document root.
- `set_variable`: `{ op, name, value }`.

Important schema rules:

- Every node ID is exactly five characters using letters, digits, `_`, or `-`.
- Top-level nodes require `x` and `y`.
- Nested nodes must not have `x` or `y`; they use their parent frame’s row/column layout.
- Node types are `frame`, `text`, `rect`, `ellipse`, `image`, and `svg`.
- Width and height accept numbers, `fill`, or `hug` where applicable.
- Variables are referenced as `$name` and may contain light/dark values.
- Fills support colors, variables, solid fills, linear/radial gradients, and images.

### `screenshot`

Returns isolated PNG image content for top-level frames.

```json
{ "nodeIds": ["hero1"], "scale": 1 }
```

Use screenshots after every meaningful visual change.

### `export`

Writes every requested frame to a directory. PNG supports exact 1×, 2×, and 3× scales; HTML is self-contained.

```json
{
  "nodeIds": ["hero1", "card1"],
  "dir": "/Users/me/Desktop/nib-exports",
  "format": "png",
  "scales": [1, 2, 3]
}
```

### `get_guidelines`

The guidelines API has three steps:

```json
{}
```

```json
{ "category": "guide", "name": "graphics" }
```

```json
{
  "category": "guide",
  "name": "graphics",
  "params": { "preset": "story-9-16" }
}
```

Task guides: `graphics`, `mobile-app`, and `landing-page`.

Styles: `quiet-linen`, `obsidian-brief`, `broadsheet-noon`, `block-signal`, `cotton-arcade`, `terminal-ledger`, `chamber-ivory`, and `poster-rally`.

### `snapshot_layout`

Returns measured renderer positions and sizes for every node under the requested frames.

```json
{ "frameIds": ["hero1"] }
```

Use it to verify frame bounds, responsive flow, clipping, and spacing after edits.

### `list_projects`

Returns the sidebar tree: projects, loose **Open files**, nested `.nibs` paths, and which file is active.

```json
{}
```

### `open_file`

Opens a `.nibs` path as the active document (same as choosing it in the sidebar).

```json
{ "path": "/Users/you/project/launch.nibs" }
```

### `new_file`

Creates a new document with one starter frame and opens it.

```json
{ "projectFolder": "/Users/you/campaign", "name": "spring-ads" }
```

Or:

```json
{ "path": "/Users/you/Desktop/idea.nibs" }
```

### `duplicate_file` / `rename_file` / `delete_file`

Disk operations on `.nibs` files. Delete moves to Trash and refuses the **active** file until you open another document.

```json
{ "path": "/Users/you/campaign/launch.nibs" }
```

```json
{ "path": "/Users/you/campaign/launch.nibs", "name": "launch-v2.nibs" }
```

## Bundled fonts

These fonts render consistently in the canvas, screenshots, and exports:

- Geist
- Geist Mono
- Inter
- Newsreader
- Playfair Display
- Anton
- IBM Plex Mono

Nib also loads `.ttf` and `.otf` files from an `assets/fonts/` folder beside the active `.nibs` document.

## Prompt templates

### Create a campaign set

```text
Use Nib to create a coordinated launch campaign: one 1080×1350 feed design,
one 1080×1920 story, and one 1200×628 social card. Load the graphics guide
and poster-rally style, build all frames, screenshot each, fix layout issues,
then export all frames at 1× and 2×.
```

### Create an app screen

```text
Use Nib to create a polished iPhone home screen. Load the mobile-app guide
for iPhone 15 Pro and the quiet-linen style. Inspect the rendered screenshot,
check the layout tree, and export the final frame at 1× and 3×.
```

### Redesign selected work

```text
Read Nib's current selection and redesign only those frames using the
broadsheet-noon style. Preserve the content hierarchy, improve typography
and spacing, screenshot every changed frame, and export the final selection.
```

## Troubleshooting

- **Nib is not running:** the installed shim should launch it automatically. Open `/Applications/Nib.app` manually if macOS blocks the first launch.
- **No `nib` tools:** restart the agent after applying MCP configuration.
- **Old path in the config:** rerun **Nib → Set up agents…**. Installed paths must begin with `/Applications/Nib.app`; they must never reference `node_modules`.
- **Invalid batch:** read the returned operation index, JSON path, and validation message; correct the whole batch and retry.
- **Wrong visual output:** call `screenshot`, then `snapshot_layout`; do not infer rendering quality from the document tree alone.