@zseven-w/pen-mcp

MCP server for OpenPencil — enables Claude, GPT, Gemini, and other LLMs to read, create, and modify designs through a standard tool protocol.

Note: pen-mcp is shipped as part of the OpenPencil app (desktop + web) and is not a standalone CLI. The published package ships TypeScript source against workspace-only dependencies and has no bin entry, so npx @zseven-w/pen-mcp does not work. Run the server from the OpenPencil monorepo or connect external clients to the HTTP endpoint exposed by a running OpenPencil instance.

Overview

pen-mcp exposes OpenPencil's full editing API as MCP tools. External AI agents can open documents, inspect the canvas, insert/update/delete nodes, and generate complete designs — all through structured tool calls.

Three workflows are supported:

| Workflow | Tools | Best for | | --------------- | ---------------------------------------------------------- | ------------------------------------ | | Single-shot | insert_node, batch_design | Quick edits, single components | | Layered | design_skeleton → design_content × N → design_refine | Full-page designs with high fidelity | | CRUD | batch_get → update_node / delete_node | Reading & modifying existing content |

Running the MCP Server

The server supports both stdio and streamable HTTP transports. The default HTTP endpoint is http://localhost:3100/mcp.

From the monorepo (development)

git clone https://github.com/ZSeven-W/openpencil.git
cd openpencil && bun install
bun run mcp:dev              # starts stdio + HTTP on port 3100
# flags: --http (HTTP only), --stdio (stdio only), --port <n>

Built-in to the OpenPencil app

Launching the desktop or web app automatically starts the MCP server in the background. External MCP clients should connect over HTTP to the running instance — no separate install required.

Connecting an MCP client

Most MCP-aware clients (Claude Desktop, Cursor, Continue, etc.) accept an HTTP URL pointing at a running server. Point them at http://localhost:3100/mcp while the OpenPencil app or bun run mcp:dev is running.

Tools

Document & Read Tools

| Tool | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | open_document | Open an .op file or connect to the live Electron canvas. Always call first. | | batch_get | Search and read nodes by type, name regex, or specific IDs. Controls read depth for nested content. | | get_selection | Get the currently selected nodes on the live canvas. | | snapshot_layout | Get a compact bounding-box layout tree — useful for spatial understanding. | | find_empty_space | Find available canvas space in a given direction for placing new content. | | get_design_prompt | Retrieve segmented design knowledge (schema, layout, roles, text, style, icons, examples). |

Node CRUD Tools

| Tool | Description | | -------------- | ----------------------------------------------------------------------------------- | | insert_node | Insert a new node with full PenNode data. Supports postProcess for auto-defaults. | | update_node | Shallow-merge properties into an existing node. | | delete_node | Delete a node and all its children. | | move_node | Reparent a node to a new container. | | copy_node | Deep-clone a node with new IDs under a target parent. | | replace_node | Replace a node entirely with new data at the same position. | | import_svg | Import a local SVG file as editable PenNodes. |

Batch Design DSL

batch_design accepts a compact DSL — one operation per line:

root=I(null, { "type": "frame", "name": "Page", "width": 1200, ... })
header=I(root, { "type": "frame", "name": "Header", ... })
U(header, { "fill": [{ "type": "solid", "color": "#1A1A2E" }] })
logo=C("existing-logo", header, { "x": 24 })
M("floating-btn", header)
D("old-section")

| Op | Syntax | Description | | ----- | ------------------------------------------ | ----------------- | | I | binding=I(parent, { data }) | Insert node | | U | U(path, { updates }) | Update properties | | C | binding=C(source, parent, { overrides }) | Copy node | | R | binding=R(path, { newData }) | Replace node | | M | M(nodeId, parent, index?) | Move node | | D | D(nodeId) | Delete node |

Layered Generation Workflow

For high-fidelity multi-section designs:

1. design_skeleton  → Create root frame + section placeholders
2. design_content   → Fill each section with content nodes (call per section)
3. design_refine    → Run full-tree validation and auto-fixes

Page Management

| Tool | Description | | ---------------- | ------------------------------------------ | | add_page | Add a new page to the document | | remove_page | Remove a page (cannot remove the last one) | | rename_page | Rename a page | | reorder_page | Move a page to a new index | | duplicate_page | Deep-clone a page with new IDs |

Post-Processing

All creation tools support postProcess=true for automatic:

• Semantic role defaults (button padding, input height, card radius, etc.)
• Icon name → SVG path resolution (Lucide icon set)
• Card row equalization in horizontal layouts
• Text height estimation
• Frame height expansion when content overflows
• clipContent auto-addition for frames with cornerRadius + images

Design Prompt Sections

get_design_prompt(section) returns focused subsets of design knowledge:

| Section | Content | | ------------ | ------------------------------------------------------------------------- | | schema | PenNode type definitions and property reference | | layout | Flexbox layout engine rules (gap, padding, justify, align) | | roles | Semantic roles and their auto-defaults (button, input, card, navbar, ...) | | text | Typography rules, CJK support, copywriting guidelines | | style | Visual style policy (colors, fonts, aesthetic) | | icons | Feather/Lucide icon naming conventions | | examples | Complete design examples with DSL | | guidelines | Design tips (cards, inputs, phone mockups, hero sections) | | planning | Layered workflow guide with section decomposition rules |

Live Canvas Sync

When connected to a running OpenPencil desktop app, changes made via MCP tools appear on the canvas in real-time. The sync is bidirectional — user edits on the canvas are reflected in subsequent batch_get / snapshot_layout calls.

Programmatic Usage

import { configureMcpHooks, MCP_DEFAULT_PORT } from '@zseven-w/pen-mcp';

// Configure custom hooks (optional)
configureMcpHooks({
  onDocumentOpen: (path) => console.log(`Opened: ${path}`),
  onNodeInsert: (node) => console.log(`Inserted: ${node.id}`),
});

License

MIT