Working with the Pencil MCP Server

Non-negotiable rules

• .pen files are JSON-based, human-readable, and Git-diffable. You can read them with standard filesystem tools, but always use Pencil MCP tools (batch_get, batch_design, etc.) for design operations — they handle IDs correctly, apply layout calculations, and prevent format-breaking manual edits.
• Avoid hand-editing a .pen file directly. Manual edits can break internal references, component linkages, or variable bindings — even though the format is plain JSON.
• When in doubt about a node's ID or structure, look it up — never guess node IDs.

Starting every task

Begin with get_editor_state() unless the user has given you an explicit file path. This tells you:

• Which .pen file is currently open and active
• The current user selection (selected node IDs)
• Other essential context (canvas state, viewport)

If no document is open, call open_document("new") to create a blank canvas, or open_document("<path>") to open a specific file.