mcp-server-penpot 1.0.2 → 1.1.0

package/dist/data/prompts.yml

@@ -210,9 +210,54 @@ initial_instructions: |
         });
         Always validate against the root container that is supposed to contain the shapes.
 
-  # Visual Inspection of Designs
-
-  For many tasks, it can be critical to visually inspect the design. Remember to use the `export_shape` tool for this purpose! 
+  # Visual Inspection of Designs (Screenshots)
+
+  For many tasks, it is CRITICAL to visually inspect the design. The `export_shape` tool is your primary tool for
+  taking screenshots and visually verifying designs. ALWAYS use it after making design changes to confirm correctness.
+
+  ## When to Take Screenshots
+
+  * After creating or modifying shapes, boards, or components -- verify the result looks correct
+  * When analyzing an existing design -- screenshot key elements to understand their appearance
+  * When debugging layout issues -- screenshot the parent board to see actual rendered layout
+  * Before and after making changes -- to compare and verify the change had the desired effect
+  * When the user asks you to review, check, or verify any visual aspect of the design
+
+  ## Screenshot Workflows
+
+  **Screenshot the current selection:**
+  Use `export_shape` with shapeId="selection" to screenshot whatever the user has selected.
+
+  **Screenshot a board by name:**
+  First find the board, then screenshot it:
+  ```
+  // Step 1: Find the board using execute_code
+  const board = penpotUtils.findShape(s => s.type === 'board' && s.name === 'Login Screen');
+  return { id: board.id, name: board.name };
+  ```
+  Then call `export_shape` with the returned shape ID.
+
+  **Screenshot after creating a component:**
+  After using `execute_code` to create shapes, always capture the parent board or the created shape
+  to verify it rendered correctly:
+  ```
+  // After creating shapes, return the parent board ID for visual verification
+  return { boardId: parentBoard.id };
+  ```
+  Then call `export_shape` with that board ID.
+
+  **High-resolution screenshot for detailed inspection:**
+  Use `export_shape` with scale=2 for higher resolution when checking fine details like text,
+  alignment, or small UI elements.
+
+  ## Visual Verification Checklist
+
+  When visually inspecting a screenshot, check for:
+  * Layout alignment -- are elements properly aligned and spaced?
+  * Text readability -- are fonts, sizes, and colors correct?
+  * Overflow/clipping -- are any elements cut off or overflowing their containers?
+  * Color correctness -- do fills, strokes, and text colors match the intended design?
+  * Completeness -- are all required elements present and visible?
 
   # Revising Designs
 

package/dist/index.js

@@ -14519,6 +14519,9 @@ var ExportShapeArgs = class {
     mode: external_exports.enum(["shape", "fill"]).default("shape").describe(
       "The export mode: either 'shape' (full shape as it appears in the design, including descendants; the default) or 'fill' (export the raw image that is used as a fill for the shape; PNG format only)"
     ),
+    scale: external_exports.number().min(0.01).max(10).default(1).optional().describe(
+      "Scale factor for the export. Use values > 1 (e.g. 2) for higher resolution screenshots. Only applies to bitmap formats (png). Default: 1."
+    ),
     filePath: external_exports.string().optional().describe(
       "Optional file path to save the exported image to. If not provided, the image data is returned directly for you to see."
     )
@@ -14526,6 +14529,7 @@ var ExportShapeArgs = class {
   shapeId;
   format = "png";
   mode = "shape";
+  scale;
   filePath;
 };
 var ExportShapeTool = class extends Tool {
@@ -14550,6 +14554,7 @@ var ExportShapeTool = class extends Tool {
     if (this.mcpServer.isFileSystemAccessEnabled()) {
       description += "\nAlternatively, you can save it to a file.";
     }
+    description += "\n\n**This is the primary tool for taking screenshots and visually inspecting designs.** Use it to:\n- Take a screenshot of a shape, board, or component to verify its appearance\n- Visually inspect a design after making changes to confirm correctness\n- Check layout, alignment, colors, and typography by looking at the actual rendered output\n\nTo screenshot a specific element, find its shape ID first (via `execute_code` with `penpotUtils.shapeStructure` or `penpotUtils.findShape`), then call this tool with that ID. Use 'selection' as the shapeId to screenshot whatever the user has selected.\n\nFor high-resolution screenshots, use the `scale` parameter (e.g. scale=2 for 2x resolution).";
     return description;
   }
   async executeCore(args) {
@@ -14563,7 +14568,8 @@ var ExportShapeTool = class extends Tool {
       shapeCode = `penpotUtils.findShapeById("${args.shapeId}")`;
     }
     const asSvg = args.format === "svg";
-    const code = `return penpotUtils.exportImage(${shapeCode}, "${args.mode}", ${asSvg});`;
+    const scale = args.scale ?? 1;
+    const code = `return penpotUtils.exportImage(${shapeCode}, "${args.mode}", ${asSvg}, ${scale});`;
     const task = new ExecuteCodePluginTask({ code });
     const result = await this.mcpServer.pluginBridge.executePluginTask(task);
     const imageData = result.data.result;
@@ -14681,6 +14687,102 @@ var ImportImageTool = class _ImportImageTool extends Tool {
   }
 };
 
+// src/prompts/VerifyDesignPrompt.ts
+var VERIFY_DESIGN_PROMPT = {
+  name: "verify-design",
+  config: {
+    title: "Verify Design",
+    description: "Takes a screenshot of a design element and performs a visual review. Use after making design changes to verify correctness, or to check the current state of a shape, board, or component.",
+    argsSchema: {
+      shapeName: external_exports.string().optional().describe(
+        "Name of the shape or board to verify. If omitted, verifies the user's current selection."
+      )
+    }
+  },
+  callback: async (args) => {
+    const target = args.shapeName ? `the shape named "${args.shapeName}"` : "the user's current selection";
+    const findStep = args.shapeName ? `1. **Find the target shape** using \`execute_code\`:
+   \`\`\`javascript
+   const shape = penpotUtils.findShape(s => s.name === '${args.shapeName}');
+   if (!shape) throw new Error('Shape "${args.shapeName}" not found');
+   return { id: shape.id, name: shape.name, type: shape.type };
+   \`\`\`
+` : `1. **The target is the current selection.** Use shapeId="selection" in the next step.
+`;
+    const exportStep = args.shapeName ? `2. **Take a screenshot** using \`export_shape\` with the shape ID from step 1.` : `2. **Take a screenshot** using \`export_shape\` with shapeId="selection".`;
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please visually verify ${target} in the Penpot design. Follow these steps:
+
+${findStep}
+${exportStep}
+
+3. **Analyze the screenshot** and check for:
+   - Layout alignment and spacing
+   - Text readability (fonts, sizes, colors)
+   - Element overflow or clipping
+   - Color correctness
+   - Completeness (all expected elements visible)
+
+4. **Report findings** with specific observations about what looks correct and any issues found.`
+          }
+        }
+      ]
+    };
+  }
+};
+
+// src/prompts/ExploreDesignPrompt.ts
+var EXPLORE_DESIGN_PROMPT = {
+  name: "explore-design",
+  config: {
+    title: "Explore Design",
+    description: "Explores a Penpot design page by analyzing its structure and taking screenshots of key elements. Use to understand what a page contains and how it looks.",
+    argsSchema: {
+      pageName: external_exports.string().optional().describe(
+        "Name of the page to explore. If omitted, explores the current page."
+      )
+    }
+  },
+  callback: async (args) => {
+    const pageRef = args.pageName ? `the page named "${args.pageName}"` : "the current page";
+    const getPageCode = args.pageName ? `const page = penpotUtils.getPageByName('${args.pageName}');
+   if (!page) throw new Error('Page "${args.pageName}" not found');
+   const root = page.root;` : `const root = penpot.root;`;
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please explore and summarize ${pageRef} in the Penpot design. Follow these steps:
+
+1. **Get the page structure** using \`execute_code\`:
+   \`\`\`javascript
+   ${getPageCode}
+   return penpotUtils.shapeStructure(root, 3);
+   \`\`\`
+
+2. **Identify key elements**: From the structure, identify the main boards, groups, and notable shapes.
+
+3. **Take screenshots of the main boards** using \`export_shape\` for each top-level board to see how they look.
+
+4. **Summarize the design**: Provide a structured overview including:
+   - Page name and overall structure
+   - List of boards with their purpose (inferred from names and visual content)
+   - Notable design patterns (layout systems, component usage)
+   - Any potential issues spotted in the screenshots`
+          }
+        }
+      ]
+    };
+  }
+};
+
 // src/ReplServer.ts
 import express from "express";
 import path3 from "path";
@@ -14908,6 +15010,7 @@ var PenpotMcpServer = class {
     this.pluginBridge = new PluginBridge(this, this.webSocketPort);
     this.replServer = new ReplServer(this.pluginBridge, this.replPort);
     this.registerTools();
+    this.registerPrompts();
   }
   logger = createLogger("PenpotMcpServer");
   server;
@@ -15003,6 +15106,17 @@ var PenpotMcpServer = class {
       );
     }
   }
+  registerPrompts() {
+    const prompts = [VERIFY_DESIGN_PROMPT, EXPLORE_DESIGN_PROMPT];
+    for (const prompt of prompts) {
+      this.logger.info(`Registering prompt: ${prompt.name}`);
+      this.server.registerPrompt(
+        prompt.name,
+        prompt.config,
+        prompt.callback
+      );
+    }
+  }
   setupHttpEndpoints() {
     this.app.all("/mcp", async (req, res) => {
       const userToken = req.query.userToken;
@@ -15075,6 +15189,12 @@ var PenpotMcpServer = class {
     const pluginDistPath = path5.join(__dirname2, "plugin");
     const fs4 = await import("fs");
     if (fs4.existsSync(pluginDistPath)) {
+      pluginApp.use((_req, res, next) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "*");
+        next();
+      });
       pluginApp.use(express2.static(pluginDistPath));
       return new Promise((resolve2) => {
         pluginApp.listen(this.pluginPort, this.listenAddress, () => {
@@ -15095,7 +15215,12 @@ var PenpotMcpServer = class {
     const pluginDistPath = path5.join(__dirname2, "plugin");
     const fs4 = await import("fs");
     if (fs4.existsSync(pluginDistPath)) {
-      this.app.use("/plugin", express2.static(pluginDistPath));
+      this.app.use("/plugin", (_req, res, next) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "*");
+        next();
+      }, express2.static(pluginDistPath));
       this.logger.info(`Plugin files will be served at: http://${this.serverAddress}:${this.port}/plugin/`);
     }
     return new Promise((resolve2) => {

package/dist/plugin/plugin.js

@@ -1,2 +1,2 @@
-class y{constructor(e,t,o){this.requestId=e,this.taskType=t,this.params=o}isResponseSent=!1;sendResponse(e,t=void 0,o=void 0){if(this.isResponseSent){console.error("Response already sent for task:",this.requestId);return}const n={type:"task-response",response:{id:this.requestId,success:e,data:t,error:o}};penpot.ui.sendMessage(n),console.log("Sent task response:",n),this.isResponseSent=!0}sendSuccess(e=void 0){this.sendResponse(!0,e)}sendError(e){this.sendResponse(!1,void 0,e)}}class w{isApplicableTo(e){return this.taskType===e.taskType}}class f{static shapeStructure(e,t=void 0){let o;(t===void 0||t>0)&&"children"in e&&e.children&&(o=e.children.map(r=>this.shapeStructure(r,t===void 0?void 0:t-1)));const n={id:e.id,name:e.name,type:e.type,children:o};if("flex"in e&&e.flex){const r=e.flex;n.layout={type:"flex",dir:r.dir,rowGap:r.rowGap,columnGap:r.columnGap}}else if("grid"in e&&e.grid){const r=e.grid;n.layout={type:"grid",rows:r.rows,columns:r.columns,rowGap:r.rowGap,columnGap:r.columnGap}}return n}static findShapes(e,t=penpot.root){let o=new Array,n=function(r){if(r&&(e(r)&&o.push(r),"children"in r&&r.children))for(let s of r.children)n(s)};return n(t),o}static findShape(e,t=null){let o=function(n){if(!n)return null;if(e(n))return n;if("children"in n&&n.children)for(let r of n.children){let s=o(r);if(s)return s}return null};if(t===null){const n=penpot.currentFile?.pages;if(n)for(let r of n){let s=o(r.root);if(s)return s}return null}else return o(t)}static findShapeById(e){return this.findShape(t=>t.id===e)}static findPage(e){return penpot.currentFile.pages.find(e)||null}static getPages(){return penpot.currentFile.pages.map(e=>({id:e.id,name:e.name}))}static getPageById(e){return this.findPage(t=>t.id===e)}static getPageByName(e){return this.findPage(t=>t.name.toLowerCase()===e.toLowerCase())}static getPageForShape(e){for(const t of penpot.currentFile.pages)if(t.getShapeById(e.id))return t;return null}static generateCss(e){const t=this.getPageForShape(e);if(!t)throw new Error("Shape is not part of any page");return penpot.openPage(t),penpot.generateStyle([e],{type:"css",includeChildren:!0})}static isContainedIn(e,t){return e.x>=t.x&&e.y>=t.y&&e.x+e.width<=t.x+t.width&&e.y+e.height<=t.y+t.height}static setParentXY(e,t,o){if(!e.parent)throw new Error("Shape has no parent - cannot set parent-relative position");e.x=e.parent.x+t,e.y=e.parent.y+o}static addFlexLayout(e,t){const n=("children"in e&&e.children?[...e.children]:[]).sort((s,i)=>t==="row"?s.x-i.x:s.y-i.y),r=e.addFlexLayout();r.dir=t;for(const s of n)s.setParentIndex(0);return r}static analyzeDescendants(e,t,o=void 0){const n=[],r=(s,i)=>{const p=t(e,s);if(p!=null&&n.push({shape:s,result:p}),(o===void 0||i<o)&&"children"in s&&s.children)for(const a of s.children)r(a,i+1)};if("children"in e&&e.children)for(const s of e.children)r(s,1);return n}static atob(e){const t="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",o=new Uint8Array(256);for(let i=0;i<t.length;i++)o[t.charCodeAt(i)]=i;let n=e.length*.75;e[e.length-1]==="="&&(n--,e[e.length-2]==="="&&n--);const r=new Uint8Array(n);let s=0;for(let i=0;i<e.length;i+=4){const p=o[e.charCodeAt(i)],a=o[e.charCodeAt(i+1)],c=o[e.charCodeAt(i+2)],d=o[e.charCodeAt(i+3)];r[s++]=p<<2|a>>4,r[s++]=(a&15)<<4|c>>2,r[s++]=(c&3)<<6|d&63}return r}static async importImage(e,t,o,n,r,s,i){const p=f.atob(e),a=await penpot.uploadMediaData(o,p,t),c=penpot.createRectangle();c.name=o;let d,u;const g=s!==void 0,h=i!==void 0;return g&&h?(d=s,u=i):g?(d=s,u=d*(a.height/a.width)):h?(u=i,d=u*(a.width/a.height)):(d=a.width,u=a.height),c.resize(d,u),n!==void 0&&(c.x=n),r!==void 0&&(c.y=r),c.fills=[{fillOpacity:1,fillImage:a}],c}static async exportImage(e,t,o){switch(t){case"shape":return e.export({type:o?"svg":"png"});case"fill":if(o)throw new Error("Image fills cannot be exported as SVG");if(!("fills"in e))throw new Error("Shape with `fills` member is required for fill export mode");const n=e.fills;for(const r of n)if(r.fillImage)return r.fillImage.data();throw new Error("No fill with image data found in the shape");default:throw new Error(`Unsupported export mode: ${t}`)}}}class m{logOutput="";resetLog(){this.logOutput=""}getLog(){return this.logOutput}appendToLog(e,...t){const o=t.map(n=>typeof n=="object"?JSON.stringify(n,null,2):String(n)).join(" ");this.logOutput+=`[${e}] ${o}
+class y{constructor(e,t,o){this.requestId=e,this.taskType=t,this.params=o}isResponseSent=!1;sendResponse(e,t=void 0,o=void 0){if(this.isResponseSent){console.error("Response already sent for task:",this.requestId);return}const n={type:"task-response",response:{id:this.requestId,success:e,data:t,error:o}};penpot.ui.sendMessage(n),console.log("Sent task response:",n),this.isResponseSent=!0}sendSuccess(e=void 0){this.sendResponse(!0,e)}sendError(e){this.sendResponse(!1,void 0,e)}}class w{isApplicableTo(e){return this.taskType===e.taskType}}class f{static shapeStructure(e,t=void 0){let o;(t===void 0||t>0)&&"children"in e&&e.children&&(o=e.children.map(r=>this.shapeStructure(r,t===void 0?void 0:t-1)));const n={id:e.id,name:e.name,type:e.type,children:o};if("flex"in e&&e.flex){const r=e.flex;n.layout={type:"flex",dir:r.dir,rowGap:r.rowGap,columnGap:r.columnGap}}else if("grid"in e&&e.grid){const r=e.grid;n.layout={type:"grid",rows:r.rows,columns:r.columns,rowGap:r.rowGap,columnGap:r.columnGap}}return n}static findShapes(e,t=penpot.root){let o=new Array,n=function(r){if(r&&(e(r)&&o.push(r),"children"in r&&r.children))for(let s of r.children)n(s)};return n(t),o}static findShape(e,t=null){let o=function(n){if(!n)return null;if(e(n))return n;if("children"in n&&n.children)for(let r of n.children){let s=o(r);if(s)return s}return null};if(t===null){const n=penpot.currentFile?.pages;if(n)for(let r of n){let s=o(r.root);if(s)return s}return null}else return o(t)}static findShapeById(e){return this.findShape(t=>t.id===e)}static findPage(e){return penpot.currentFile.pages.find(e)||null}static getPages(){return penpot.currentFile.pages.map(e=>({id:e.id,name:e.name}))}static getPageById(e){return this.findPage(t=>t.id===e)}static getPageByName(e){return this.findPage(t=>t.name.toLowerCase()===e.toLowerCase())}static getPageForShape(e){for(const t of penpot.currentFile.pages)if(t.getShapeById(e.id))return t;return null}static generateCss(e){const t=this.getPageForShape(e);if(!t)throw new Error("Shape is not part of any page");return penpot.openPage(t),penpot.generateStyle([e],{type:"css",includeChildren:!0})}static isContainedIn(e,t){return e.x>=t.x&&e.y>=t.y&&e.x+e.width<=t.x+t.width&&e.y+e.height<=t.y+t.height}static setParentXY(e,t,o){if(!e.parent)throw new Error("Shape has no parent - cannot set parent-relative position");e.x=e.parent.x+t,e.y=e.parent.y+o}static addFlexLayout(e,t){const n=("children"in e&&e.children?[...e.children]:[]).sort((s,i)=>t==="row"?s.x-i.x:s.y-i.y),r=e.addFlexLayout();r.dir=t;for(const s of n)s.setParentIndex(0);return r}static analyzeDescendants(e,t,o=void 0){const n=[],r=(s,i)=>{const p=t(e,s);if(p!=null&&n.push({shape:s,result:p}),(o===void 0||i<o)&&"children"in s&&s.children)for(const a of s.children)r(a,i+1)};if("children"in e&&e.children)for(const s of e.children)r(s,1);return n}static atob(e){const t="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",o=new Uint8Array(256);for(let i=0;i<t.length;i++)o[t.charCodeAt(i)]=i;let n=e.length*.75;e[e.length-1]==="="&&(n--,e[e.length-2]==="="&&n--);const r=new Uint8Array(n);let s=0;for(let i=0;i<e.length;i+=4){const p=o[e.charCodeAt(i)],a=o[e.charCodeAt(i+1)],c=o[e.charCodeAt(i+2)],d=o[e.charCodeAt(i+3)];r[s++]=p<<2|a>>4,r[s++]=(a&15)<<4|c>>2,r[s++]=(c&3)<<6|d&63}return r}static async importImage(e,t,o,n,r,s,i){const p=f.atob(e),a=await penpot.uploadMediaData(o,p,t),c=penpot.createRectangle();c.name=o;let d,u;const g=s!==void 0,h=i!==void 0;return g&&h?(d=s,u=i):g?(d=s,u=d*(a.height/a.width)):h?(u=i,d=u*(a.width/a.height)):(d=a.width,u=a.height),c.resize(d,u),n!==void 0&&(c.x=n),r!==void 0&&(c.y=r),c.fills=[{fillOpacity:1,fillImage:a}],c}static async exportImage(e,t,o,n=1){switch(t){case"shape":return e.export({type:o?"svg":"png",scale:n});case"fill":if(o)throw new Error("Image fills cannot be exported as SVG");if(!("fills"in e))throw new Error("Shape with `fills` member is required for fill export mode");const r=e.fills;for(const s of r)if(s.fillImage)return s.fillImage.data();throw new Error("No fill with image data found in the shape");default:throw new Error(`Unsupported export mode: ${t}`)}}}class m{logOutput="";resetLog(){this.logOutput=""}getLog(){return this.logOutput}appendToLog(e,...t){const o=t.map(n=>typeof n=="object"?JSON.stringify(n,null,2):String(n)).join(" ");this.logOutput+=`[${e}] ${o}
 `}log(...e){this.appendToLog("LOG",...e)}warn(...e){this.appendToLog("WARN",...e)}error(...e){this.appendToLog("ERROR",...e)}info(...e){this.appendToLog("INFO",...e)}debug(...e){this.appendToLog("DEBUG",...e)}trace(...e){this.appendToLog("TRACE",...e)}table(e){this.appendToLog("TABLE",e)}time(e){this.appendToLog("TIME",`Timer started: ${e||"default"}`)}timeEnd(e){this.appendToLog("TIME_END",`Timer ended: ${e||"default"}`)}group(e){this.appendToLog("GROUP",e||"")}groupCollapsed(e){this.appendToLog("GROUP_COLLAPSED",e||"")}groupEnd(){this.appendToLog("GROUP_END","")}clear(){}count(e){this.appendToLog("COUNT",e||"default")}countReset(e){this.appendToLog("COUNT_RESET",e||"default")}assert(e,...t){e||this.appendToLog("ASSERT",...t)}}class T extends w{taskType="executeCode";context;constructor(){super(),this.context={penpot,storage:{},console:new m,penpotUtils:f}}async handle(e){if(!e.params.code){e.sendError("executeCode task requires 'code' parameter");return}this.context.console.resetLog();const t=this.context,o=e.params.code;let n=await(async s=>new Function(...Object.keys(s),`return (async () => { ${o} })();`)(...Object.values(s)))(t);console.log("Code execution result:",n);let r={result:n,log:this.context.console.getLog()};e.sendSuccess(r)}}const k=[new T],E=!1;penpot.ui.open("Penpot MCP Plugin",`?theme=${penpot.theme}&multiUser=${E}`,{width:158,height:200});penpot.ui.onMessage(l=>{typeof l=="object"&&l.task&&l.id&&x(l).catch(e=>{console.error("Error in handlePluginTaskRequest:",e)})});async function x(l){console.log("Executing plugin task:",l.task,l.params);const e=new y(l.id,l.task,l.params),t=k.find(o=>o.isApplicableTo(e));if(t)try{console.log("Processing task with handler:",t),await t.handle(e),e.isResponseSent||(console.warn("Handler did not send a response, sending generic success."),e.sendSuccess("Task completed without a specific response.")),console.log("Task handled successfully:",e)}catch(o){console.error("Error handling task:",o);const n=o instanceof Error?o.message:"Unknown error";e.sendError(`Error handling task: ${n}`)}else console.error("Unknown plugin task:",l.task),e.sendError(`Unknown task type: ${l.task}`)}penpot.on("themechange",l=>{penpot.ui.sendMessage({source:"penpot",type:"themechange",theme:l})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-penpot",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "MCP server for Penpot design tool integration",
   "type": "module",
   "main": "dist/index.js",