try-works-pi-paper-design

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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

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

Open Paper Desktop with a design file.
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