Pi Paper Design

Pi package that bridges Pi to the Paper MCP server, letting AI agents read, create, edit, and export Paper design files.

Prerequisites

• Paper Desktop installed and running with a design file open.
• Pi installed (npm install -g @earendil-works/pi-coding-agent).

Install

pi install npm:@try-works/pi-paper-design

Or install locally in a project:

pi install -l npm:@try-works/pi-paper-design

What It Provides

• Extension (paper-mcp.ts) — Connects to the Paper MCP server at http://127.0.0.1:29979/mcp, discovers tools, registers them as native Pi tools prefixed paper_, forwards text and image results (screenshots), and reconnects on expired sessions (/paper-reconnect).
• System prompt injection (Cursor parity) — When Paper is connected: standing rules every turn; full live paper-mcp-instructions guide for the first 2 agent turns after connect/reconnect. After that, call paper_get_guide as needed. Standing rules always tell the agent to use paper_get_guide for instructions when required.
• Skill (paper-design) — Tool reference + HTML conventions (not a full copy of the design guide).

Usage

1. Open Paper Desktop with a design file.
2. Start Pi and ask design questions:

> List my Paper files
> Open the "role-model runtime design system" file
> What's on the current page?
> Create a new mobile artboard with a hero section

The agent will use paper_* tools against your designs. Standing rules are injected every turn; the full design guide is injected for early turns after connect — afterward (and anytime needed) the agent should call paper_get_guide. The paper-design skill is the tool reference.

Available Tools

Once connected, the extension registers Paper’s tools (names prefixed with paper_). See the skill for the full reference. Groups include:

Files & Navigation: paper_list_files, paper_open_file, paper_create_file, paper_create_page

Reading: paper_get_basic_info, paper_get_selection, paper_get_node_info, paper_get_children, paper_get_tree_summary, paper_get_screenshot, paper_get_jsx, paper_get_computed_styles, paper_get_fill_image, paper_find_nodes, paper_get_font_family_info, paper_get_guide

Comments: paper_list_comment_threads, paper_get_comment_thread, paper_list_comment_thread_authors, paper_set_comment_thread_status

Writing: paper_write_html, paper_create_artboard, paper_set_text_content, paper_rename_nodes, paper_duplicate_nodes, paper_move_nodes, paper_update_styles, paper_delete_nodes, paper_finish_working_on_nodes

Tokens: paper_get_tokens, paper_create_tokens, paper_set_tokens

Export: paper_export, paper_export_combined_pdf

Verify

With Paper Desktop open:

npm test
# or separately:
npm run verify          # bridge smoke (connect, screenshot image, reconnect)
npm run verify:parity   # tool/schema/skill parity vs Cursor Paper plugin catalog
npm run verify:injection # Cursor-parity system prompt standing rules + guide cache

Checks connect, tool list, get_basic_info, screenshot image unwrapping, reconnect, clear errors, parity against the Cursor paper-desktop plugin, and system-prompt injection markers / live guide fetch.

Troubleshooting

• "Paper MCP connection error" — Make sure Paper Desktop is running with a file open.
• "Session not found" — Run /paper-reconnect in Pi, or close/reopen the file in Paper Desktop. The bridge also retries once after re-initialize.
• Tools not appearing — Restart the Pi session, or run /paper-reconnect after opening Paper. Tools register on session_start and again on before_agent_start if needed.
• Screenshots not “seen” — Use a Pi build that supports image tool results; this package forwards MCP image parts as Pi ImageContent.

License

MIT