Paper 设计 — MCP Bridge 技能

Paper 是一款运行在 macOS 本地的专业设计工具（类似 Figma）。本技能通过 HTTP 连接 Paper 的 MCP 服务器，为您提供完整的界面设计能力。

前提条件：必须已打开 Paper 并加载了一个设计文件。若 Paper 尚未运行，请提示用户先启动该应用。

如何使用 Paper

所有 Paper 操作均通过本技能目录下的 paper.sh 脚本执行：

exec {baseDir}/paper.sh  ''

重要提示：JSON 参数必须用单引号包裹，以防止 Shell 展开。

快速上手

# 1. 查看画布当前内容
exec {baseDir}/paper.sh get_basic_info

# 2. 创建一个新的移动设备画板
exec {baseDir}/paper.sh create_artboard '{"name":"Home Screen","styles":{"width":"390px","height":"844px","display":"flex","flexDirection":"column","backgroundColor":"#FAFAFA"}}'

# 3. 添加内容（每次仅添加一个视觉分组）
exec {baseDir}/paper.sh write_html '{"html":"
Home
","targetNodeId":"ARTBOARD_ID","mode":"insert-children"}'

# 4. 截图以供审查
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}'
# → 保存至 /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

# 5. 查看截图
image /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

# 6. 完成操作后，释放工作状态指示器
exec {baseDir}/paper.sh finish_working_on_nodes

工具参考

读取画布信息

视觉审查

# 对画板或节点截图
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}'

# 高分辨率截图（便于阅读小字号文本）
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID","scale":2}'

# 保存至指定路径
exec {baseDir}/paper.sh get_screenshot '{"nodeId":"ARTBOARD_ID"}' --save /tmp/my-review.jpg

# 然后使用 image 工具查看截图
image /tmp/paper-screenshots/screenshot-TIMESTAMP.jpg

创建设计

# 创建移动设备画板
exec {baseDir}/paper.sh create_artboard '{"name":"Screen Name","styles":{"width":"390px","height":"844px","display":"flex","flexDirection":"column","backgroundColor":"#FFFFFF"}}'

# 创建桌面端画板
exec {baseDir}/paper.sh create_artboard '{"name":"Dashboard","styles":{"width":"1440px","height":"900px","display":"flex","flexDirection":"column","backgroundColor":"#F5F5F5"}}'

# 创建关联画板（紧邻已有画板排列）
exec {baseDir}/paper.sh create_artboard '{"name":"Screen V2","relatedNodeId":"EXISTING_ID","styles":{"width":"390px","height":"844px"}}'

向设计中写入 HTML

# 将元素作为子节点添加到目标节点
exec {baseDir}/paper.sh write_html '{"html":"
content
","targetNodeId":"PARENT_ID","mode":"insert-children"}'

# 替换现有节点
exec {baseDir}/paper.sh write_html '{"html":"
new content
","targetNodeId":"OLD_NODE_ID","mode":"replace"}'

HTML 规则（关键）：

• 始终使用内联样式（style="..."）
• 所有布局均使用 display: flex — 不得使用 grid、inline 或 table 布局
• 使用 padding 和 gap 控制间距 — 禁止使用 margin
• 禁止使用 emoji 作为图标 — 应使用 SVG path
• 为关键元素设置 layer-name="Semantic Name"
• 可通过 font-family: "Font Name" 使用 Google Fonts
• 字体大小必须使用 px 单位
• 默认采用 border-box 盒模型计算方式

修改已有设计

# 更新节点样式
exec {baseDir}/paper.sh update_styles '{"updates":[{"nodeIds":["ID1","ID2"],"styles":{"backgroundColor":"#FF0000","padding":"20px"}}]}'

# 修改文本内容
exec {baseDir}/paper.sh set_text_content '{"updates":[{"nodeId":"TEXT_ID","textContent":"New text here"}]}'

# 复制节点（适用于重复元素，效率高）
exec {baseDir}/paper.sh duplicate_nodes '{"nodes":[{"id":"SOURCE_ID"}]}'
# 指定父节点进行复制：
exec {baseDir}/paper.sh duplicate_nodes '{"nodes":[{"id":"SOURCE_ID","parentId":"TARGET_PARENT"}]}'

# 删除节点
exec {baseDir}/paper.sh delete_nodes '{"nodeIds":["ID1","ID2"]}'

# 重命名图层
exec {baseDir}/paper.sh rename_nodes '{"updates":[{"nodeId":"ID","name":"Header"}]}'

收尾操作

# 完成画板操作后务必调用 — 用于释放工作状态指示器
exec {baseDir}/paper.sh finish_working_on_nodes

设计工作流（强制要求）

1. 起始 — 调用 get_basic_info 查看画布当前状态
2. 检查字体 — 在编写任何文字内容前，先调用 get_font_family_info
3. 设计简报 — 编写 HTML 前需明确：配色方案（5–6 种十六进制色值）、字体选择、间距节奏、视觉方向
4. 渐进式构建 — 每次 write_html 调用仅添加一个视觉分组（如页眉、一行内容、按钮组等），而非整屏内容
5. 每 2–3 次修改后审查一次 — 执行 get_screenshot → image → 检查间距、排版、对比度、对齐、裁切等问题
6. 修复问题后再继续
7. 完成 — 完成画板操作后调用 finish_working_on_nodes

审查检查点（每 2–3 次修改后执行）

截图完成后，请评估以下方面：

• 间距 — 间隙是否不均？是否过于拥挤？节奏是否清晰？
• 排版 — 是否易读？层级结构是否明确？
• 对比度 — 文字对比度是否偏低？元素是否相互混淆？
• 对齐 — 垂直/水平对齐线是否一致？
• 裁切 — 内容是否被边缘截断？

默认画板尺寸

故障排查

• “Paper 未运行” — 请先在 macOS 上打开 Paper 应用
• “无法初始化 MCP 会话” — Paper 必须已打开一个设计文件（而不仅仅是启动了应用）
• 返回空响应 — 节点 ID 可能有误；请使用 get_basic_info 查询有效 ID
• 会话过期 — 脚本将自动使用新会话重试；若持续失败，请删除 /tmp/paper-mcp-session