# Pi Paper Design

Pi package that bridges [Pi](https://pi.dev) to the [Paper](https://paper.design) MCP server, letting AI agents read, create, edit, and export Paper design files.

## Prerequisites

- [Paper Desktop](https://paper.design/downloads) installed and running with a design file open.
- Pi installed (`npm install -g @earendil-works/pi-coding-agent`).

## Install

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

Or install locally in a project:

```bash
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:

```bash
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