Penpot MCP Operator 是一个用于通过 MCP 操作 Penpot 的技能，目标是在不猜测 API 的前提下操作 Penpot。
用途
该技能用于通过 MCP 操作 Penpot，包括远程或本地 Penpot MCP 环境搭建、读取或修改当前聚焦的 Penpot 设计文件、创建页面、画板等。它强调 Penpot MCP 作用于当前聚焦的 Penpot 文件和页面，写入前必须先检查。
主要能力与操作规则
- 确认可用的服务器是远程还是本地。
- 每个会话中，如果尚未阅读 Penpot 高层概览，则阅读一次。
- 在写入操作前，对计划依赖的每个对象类型和成员使用 penpot_api_info。
- 使用 execute_code 运行只读探测。
- 执行最小的请求变更。
- 通过结构化回读验证，并在可能时使用 export_shape。
- 报告确切的证明级别和限制。
远程与本地
远程 MCP 对 Penpot Cloud 最简单，通常暴露 execute_code、high_level_overview、penpot_api_info、export_shape。远程 MCP 不提供完整本地文件系统访问，不要假设本地路径图像导入或本地导出写入可用。对于远程 MCP 图像上传、本地资源导入、文件选择器、插件 UI 或拖放式工作流，需使用 Chrome 或 computer-use 进行浏览器控制。远程 MCP 本身不应被视为本地资源桥。
对于 PDF/图像密集型工作流，在手动重建资源前先检查 Penpot 插件路径。Penpot 插件中心包含 Import PDF、位图矢量化、设计令牌管理、颜色导出和 HTML-to-design 等插件。当 MCP 远程无法执行浏览器交互时，使用 Chrome 或 computer-use 进行插件安装/UI 步骤。
对于品牌排版，在近似使用系统字体前，先使用 Penpot 自定义字体。自定义字体在团队/仪表板级别上传，然后在该团队的文件夹内可用。支持的格式包括 TTF、OTF、WOFF 和 WOFF2。当 MCP 无法操作该 UI 时，使用 Chrome 或 computer-use 进行仪表板上传流程。
本地 MCP 需要运行本地服务器和 Penpot 插件连接。根据配置，它可以暴露本地资源工作流，如本地图像导入和更强的导出路径。
切勿粘贴、记录、提交或截图远程 MCP 的 userToken。
Illustrator 源重建
当 Penpot 任务是 1:1 重建 Illustrator 文件、品牌手册、logo 表或分层 .ai 源时，将此技能与 adobe-illustrator-operator 一起使用。Penpot MCP 是执行表面。Illustrator 仍是画板、视觉堆叠、图层顺序、对象名称、文本和导出参考的规范来源。
在写入 Penpot 对象前：通过 Illustrator 工作流读取 Illustrator 树；创建或选择匹配的 Penpot 文件；按 Illustrator 画板顺序重建画板；按 Illustrator 树顺序导入或重建子对象；在技术上可能的情况下，将 Illustrator TextFrames 重建为 Penpot 文本；用与 Illustrator 树相关的语义名称替换通用导入名称；在进入下一个画板前，对每个画板进行视觉和结构验证。不要使用扁平化的页面 SVG 作为 1:1 重建的最终证明。
必需读取探测
从以下代码开始： return { page: penpot.currentPage ? { id: penpot.currentPage.id, name: penpot.currentPage.name, keys: Object.keys(penpot.currentPage) } : null, root: penpot.root ? { id: penpot.root.id, name: penpot.root.name, type: penpot.root.type, keys: Object.keys(penpot.root) } : null };
如果任务需要子级遍历，先查询特定容器类型和成员。不要假设 children、remove 或 findShapes 全局存在。
API 优先写入工作流
在写入画板、文本、令牌、图像或组件前：向 penpot_api_info 询问创建方法，例如 Penpot.createBoard；向 penpot_api_info 询问将使用的具体形状类型方法，例如 Board.resize、Rectangle.resize、Text.growType、Group.appendChild；仅使用已确认的成员；通过清晰命名生成的节点保持代码幂等；如果需要删除或替换，在使用前确认删除/移除 API 存在。
安全创建模式
当删除 API 未确认时，使用仅追加创建。示例代码： const board = penpot.createBoard(); board.name = "REVIEW__Example"; board.x = 0; board.y = 0; board.resize(1440, 900); board.fills = [{ fillColor: "#050505", fillOpacity: 1 }]; penpot.root.appendChild(board);
const text = penpot.createText("Example Brand"); text.name = "TITLE__Example_Brand"; text.x = 80; text.y = 80; text.resize(600, 90); text.growType = "fixed"; text.fontSize = "72"; text.fills = [{ fillColor: "#FFDF00", fillOpacity: 1 }]; board.appendChild(text);
penpot.viewport.zoomIntoView([board]); return { ok: true, boardId: board.id, boardName: board.name };
验证
变更后，运行结构化回读，返回：活动页面名称；生成的画板或节点 ID；生成的节点名称；当 API 支持时直接元素的数量；任何已知限制，例如远程导出或本地导入不可用。当可用时，使用 export_shape 进行视觉证明。如果远程模式下导出失败，说明视觉证明在 Penpot 画布中待定，不要声称有截图证明。
参考
使用 references/penpot-mcp-api-map.md 获取命令映射、已知限制、设置模式和安全片段。当任务需要更完整的 Penpot 代理工作流时，例如令牌、组件、屏幕构建、审计、迁移、路由、审批检查点或提示模板，使用 references/upstream-penpot-ai-kit.md。