@ttsalpha/mirra 1.1.0 → 1.2.0

package/README.md

@@ -1,4 +1,8 @@
-# Mirra
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ttsalpha/mirra/refs/heads/main/assets/icon.png" width="96" height="96" alt="" />
+</p>
+
+<h1 align="center">Mirra</h1>
 
 Two-way MCP server for Figma: an agent reads a design and renders one back through the
 Figma Plugin API, so it needs no REST token and has no per-month call limit.
@@ -104,7 +108,7 @@ the tool when `MIRRA_ALLOW_EXEC` is set, and the plugin only runs it while **All
 execution** is ticked in its panel. The tick resets every time the plugin runs.
 
 ```sh
-claude mcp add -s user mirra-exec -e MIRRA_ALLOW_EXEC=1 -- npx -y @ttsalpha/mirra serve
+claude mcp add -s user Mirra-exec -e MIRRA_ALLOW_EXEC=1 -- npx -y @ttsalpha/mirra serve
 ```
 
 The socket listens on loopback and refuses any browser origin other than Figma's, so a page

package/dist/index.js

@@ -32495,15 +32495,19 @@ var PatchResult = external_exports.object({
   keys: external_exports.record(external_exports.string(), external_exports.string())
 });
 var ScreenshotParams = external_exports.object({
-  /** Defaults to the current selection, or the page if nothing is selected. */
+  /** Defaults to the current selection. */
   target: Target.optional(),
-  scale: external_exports.number().min(0.1).max(4).optional()
+  scale: external_exports.number().min(0.1).max(4).optional(),
+  /** Longest edge in pixels; the scale is lowered to fit, not refused. */
+  maxEdge: external_exports.number().int().min(64).max(4096).optional()
 });
 var ScreenshotResult = external_exports.object({
   id: external_exports.string(),
   name: external_exports.string(),
   width: external_exports.number(),
   height: external_exports.number(),
+  /** What the export used, once maxEdge had its say. */
+  scale: external_exports.number(),
   /** base64 PNG. */
   png: external_exports.string()
 });
@@ -32620,7 +32624,9 @@ var ReadParams = external_exports.object({
   /** Defaults to the current selection. */
   nodeId: external_exports.string().optional(),
   /** How many levels of children to walk. */
-  depth: external_exports.number().int().min(0).max(20).optional()
+  depth: external_exports.number().int().min(0).max(20).optional(),
+  /** Most nodes to return, so one call cannot fill the context. */
+  limit: external_exports.number().int().min(1).max(2e3).optional()
 });
 var ReadResult = external_exports.object({
   nodes: external_exports.array(external_exports.object({ id: external_exports.string(), tree: UINode })),
@@ -32631,7 +32637,8 @@ var PingResult = external_exports.object({
   fileName: external_exports.string(),
   fileKey: external_exports.string().nullable(),
   currentPage: external_exports.string(),
-  selectionCount: external_exports.number()
+  selectionCount: external_exports.number(),
+  pluginVersion: external_exports.string()
 });
 
 // src/clients.ts
@@ -32640,7 +32647,8 @@ import { access, copyFile, readFile, rename, writeFile } from "node:fs/promises"
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { realpath } from "node:fs/promises";
-var SERVER_NAME = "mirra";
+var SERVER_NAME = "Mirra";
+var LEGACY_NAME = "mirra";
 async function stableNodePath() {
   try {
     return await realpath(process.execPath);
@@ -32684,6 +32692,7 @@ async function writeEntry(target, node2, entryPoint) {
     const raw = await readFile(target.file, "utf8");
     const config2 = JSON.parse(raw);
     const servers = config2[target.key] ?? {};
+    delete servers[LEGACY_NAME];
     servers[SERVER_NAME] = {
       ...target.typed ? { type: "stdio" } : {},
       command: node2,
@@ -32708,6 +32717,7 @@ function claudeCode(node2, entryPoint) {
   const probe = spawnSync("claude", ["--version"], { stdio: "ignore" });
   if (probe.error)
     return { client: "Claude Code", status: "skipped", detail: "claude not on PATH" };
+  spawnSync("claude", ["mcp", "remove", "-s", "user", LEGACY_NAME], { stdio: "ignore" });
   const result = spawnSync(
     "claude",
     ["mcp", "add", "-s", "user", SERVER_NAME, "--", node2, entryPoint, "serve"],
@@ -32724,7 +32734,7 @@ function claudeCode(node2, entryPoint) {
 
 // src/install.ts
 import { spawn } from "node:child_process";
-import { access as access2, cp, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { access as access2, cp, mkdir, readFile as readFile2, rm } from "node:fs/promises";
 import { homedir as homedir2, platform } from "node:os";
 import { join as join2, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -32733,9 +32743,9 @@ var PLUGIN_HOME = join2(MIRRA_HOME, "plugin");
 var SERVER_HOME = join2(MIRRA_HOME, "server");
 var DIST = fileURLToPath(new URL(".", import.meta.url));
 var BUNDLED_PLUGIN = resolve(DIST, "plugin");
-async function installPlugin() {
+async function installPlugin(from = BUNDLED_PLUGIN) {
   await mkdir(PLUGIN_HOME, { recursive: true });
-  await cp(BUNDLED_PLUGIN, PLUGIN_HOME, { recursive: true });
+  await cp(from, PLUGIN_HOME, { recursive: true });
   const manifest = join2(PLUGIN_HOME, "manifest.json");
   return { manifest, version: await installedVersion() };
 }
@@ -32755,11 +32765,18 @@ async function isInstalled() {
     return false;
   }
 }
-async function installServer() {
-  const running = resolve(DIST, "index.js");
-  if (!DIST.includes(`${sep}_npx${sep}`)) return running;
+function isTransientInstall(directory) {
+  return directory.includes(`${sep}_npx${sep}`);
+}
+async function installServer(from = DIST) {
+  if (!isTransientInstall(from)) return resolve(from, "index.js");
+  const plugin = resolve(from, "plugin");
+  await rm(SERVER_HOME, { recursive: true, force: true });
   await mkdir(SERVER_HOME, { recursive: true });
-  await cp(DIST, SERVER_HOME, { recursive: true });
+  await cp(from, SERVER_HOME, {
+    recursive: true,
+    filter: (source) => source !== plugin && !source.startsWith(plugin + sep)
+  });
   return join2(SERVER_HOME, "index.js");
 }
 function reveal(path) {
@@ -40803,6 +40820,9 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// src/version.ts
+var SERVER_VERSION = "1.2.0";
+
 // src/errors.ts
 var MirraError = class extends Error {
   constructor(message, code, hint) {
@@ -41048,11 +41068,18 @@ function registerPing(server, bridge) {
     async () => {
       try {
         const result = PingResult.parse(await bridge.request("ping"));
+        const drifted = result.pluginVersion !== SERVER_VERSION;
         return text([
           `file: ${result.fileName}${result.fileKey ? ` (${result.fileKey})` : ""}`,
           `page: ${result.currentPage}`,
           `selection: ${result.selectionCount} node(s)`,
-          `port: ${bridge.status.port}`
+          `port: ${bridge.status.port}`,
+          `server ${SERVER_VERSION}, plugin ${result.pluginVersion}`,
+          ...drifted ? [
+            "",
+            "The two halves are different versions. Run `npx @ttsalpha/mirra init`, then run",
+            "the plugin again in Figma so both come from the same release."
+          ] : []
         ]);
       } catch (error62) {
         return text([describeError(error62)], true);
@@ -41064,7 +41091,8 @@ function registerPing(server, bridge) {
 // src/tools/read.ts
 var DESCRIPTION5 = `Read layers out of the open Figma file as the same tree mirra_render takes,
 so a design can be edited or turned into code without learning a second format.
-Reads the current selection unless a nodeId is given.`;
+Reads the current selection unless a nodeId is given, and at most 200 nodes unless limit
+says otherwise, so a large design cannot fill the context in one call.`;
 function registerRead(server, bridge) {
   server.registerTool(
     "mirra_read",
@@ -41076,7 +41104,9 @@ function registerRead(server, bridge) {
     async (params) => {
       try {
         const result = ReadResult.parse(await bridge.request("read", params));
-        const note = result.skipped ? [`${result.skipped} node(s) left out: unsupported type, or past the depth limit`] : [];
+        const note = result.skipped ? [
+          `${result.skipped} node(s) left out: unsupported type, or past the depth or node limit`
+        ] : [];
         return text([...note, JSON.stringify(result.nodes, null, 2)]);
       } catch (error62) {
         return text([describeError(error62)], true);
@@ -41119,7 +41149,8 @@ function registerRender(server, bridge) {
 
 // src/tools/screenshot.ts
 var DESCRIPTION7 = `Export a layer as a PNG and return the image, so the rendered result can be
-checked by eye and corrected with mirra_patch. Defaults to the current selection.`;
+checked by eye and corrected with mirra_patch. Defaults to the current selection. The scale
+is lowered when it has to be, so the longest edge stays within maxEdge, 1200px by default.`;
 function registerScreenshot(server, bridge) {
   server.registerTool(
     "mirra_screenshot",
@@ -41167,9 +41198,8 @@ function registerTokens(server, bridge) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "1.1.0";
 function createMcpServer(bridge) {
-  const server = new McpServer({ name: "mirra", version: SERVER_VERSION });
+  const server = new McpServer({ name: "Mirra", version: SERVER_VERSION });
   registerPing(server, bridge);
   registerRender(server, bridge);
   registerRead(server, bridge);
@@ -41203,6 +41233,15 @@ var import_websocket_server = __toESM(require_websocket_server(), 1);
 // src/transport.ts
 var HOSTS = ["127.0.0.1", "::1"];
 var DEFAULT_TIMEOUT_MS = 3e4;
+var TIMEOUT_MS = {
+  ping: 5e3,
+  pages: 1e4,
+  render: 12e4,
+  patch: 12e4,
+  export: 12e4,
+  define: 6e4,
+  exec: 12e4
+};
 function originAllowed(origin) {
   if (!origin || origin === "null") return true;
   if (process.env["MIRRA_ALLOW_ORIGIN"] === origin) return true;
@@ -41213,16 +41252,22 @@ function originAllowed(origin) {
     return false;
   }
 }
+var UPDATE_HINT = "Run `npx @ttsalpha/mirra init` to install both halves from the same version, then run the plugin again in Figma.";
 var OPEN_PLUGIN_HINT = "Open the file in Figma Desktop, then Plugins -> Development -> Mirra, and keep the panel open.";
 var PluginBridge = class {
   #servers = [];
   #socket = null;
   #hello = null;
+  #protocolMismatch = null;
   #port = null;
   #pending = /* @__PURE__ */ new Map();
   get status() {
     return { port: this.#port, connected: this.#socket !== null, hello: this.#hello };
   }
+  /** Set while a connected plugin speaks a protocol this server does not. */
+  get protocolMismatch() {
+    return this.#protocolMismatch;
+  }
   async listen(preferredPort2) {
     const first = preferredPort2 ?? DEFAULT_PORT;
     const last = preferredPort2 ?? PORT_RANGE_END;
@@ -41265,11 +41310,14 @@ var PluginBridge = class {
     this.#servers = [];
     this.#port = null;
   }
-  async request(op, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  async request(op, params, timeoutMs = TIMEOUT_MS[op] ?? DEFAULT_TIMEOUT_MS) {
     const socket = this.#socket;
     if (!socket) {
       throw new MirraError("No Figma plugin is connected", "plugin_offline", OPEN_PLUGIN_HINT);
     }
+    if (this.#protocolMismatch && op !== "ping") {
+      throw new MirraError(this.#protocolMismatch, "protocol_mismatch", UPDATE_HINT);
+    }
     const id = randomUUID();
     const envelope = { id, op, params };
     return new Promise((resolve4, reject) => {
@@ -41313,11 +41361,8 @@ var PluginBridge = class {
     if ("type" in data) {
       if (data.type === "log") return log(`[plugin:${data.level}] ${data.message}`);
       this.#hello = data;
-      if (data.protocolVersion !== PROTOCOL_VERSION) {
-        log(
-          `protocol mismatch: plugin speaks v${data.protocolVersion}, server speaks v${PROTOCOL_VERSION}. Rebuild and re-import the plugin.`
-        );
-      }
+      this.#protocolMismatch = data.protocolVersion === PROTOCOL_VERSION ? null : `The plugin speaks protocol v${data.protocolVersion}, this server speaks v${PROTOCOL_VERSION}`;
+      if (this.#protocolMismatch) log(this.#protocolMismatch);
       return log(`plugin connected: ${data.fileName} (plugin v${data.pluginVersion})`);
     }
     const pending = this.#pending.get(data.id);

package/dist/plugin/main.js

@@ -949,30 +949,39 @@
     return node;
   }
 
+  // src/version.ts
+  var PLUGIN_VERSION = "1.2.0";
+
   // src/ops/ping.ts
   function ping() {
     return {
       fileName: figma.root.name,
       fileKey: readFileKey(),
       currentPage: figma.currentPage.name,
-      selectionCount: figma.currentPage.selection.length
+      selectionCount: figma.currentPage.selection.length,
+      pluginVersion: PLUGIN_VERSION
     };
   }
 
   // src/figma/read.ts
-  function readNode(node, depth, names = EMPTY_NAMES) {
-    const skipped = { count: 0 };
-    const tree = toSpec(node, depth, skipped, names);
-    return { tree, skipped: skipped.count };
-  }
-  function toSpec(node, depth, skipped, names) {
+  function readNode(node, depth, names = EMPTY_NAMES, limit = Number.MAX_SAFE_INTEGER) {
+    const budget = { count: 0, left: limit };
+    const tree = toSpec(node, depth, budget, names);
+    return { tree, skipped: budget.count };
+  }
+  function toSpec(node, depth, budget, names) {
+    if (budget.left <= 0) {
+      budget.count += 1;
+      return null;
+    }
+    budget.left -= 1;
     const svg = node.getPluginData(SVG_FIELD);
     if (svg) return { type: "svg", ...common(node), src: svg };
     const src = node.getPluginData(SRC_FIELD);
     if (src) return { type: "image", ...common(node), ...painted(node, names), src };
     switch (node.type) {
       case "FRAME":
-        return frameSpec(node, depth, skipped, names);
+        return frameSpec(node, depth, budget, names);
       case "TEXT":
         return textSpec(node, names);
       case "RECTANGLE":
@@ -982,19 +991,19 @@
       case "INSTANCE":
         return instanceSpec(node);
       default:
-        skipped.count += 1;
+        budget.count += 1;
         return null;
     }
   }
-  function frameSpec(node, depth, skipped, names) {
+  function frameSpec(node, depth, budget, names) {
     const children = [];
     if (depth > 0) {
       for (const child of node.children) {
-        const spec = toSpec(child, depth - 1, skipped, names);
+        const spec = toSpec(child, depth - 1, budget, names);
         if (spec) children.push(spec);
       }
     } else if (node.children.length) {
-      skipped.count += node.children.length;
+      budget.count += node.children.length;
     }
     return {
       type: "frame",
@@ -1151,6 +1160,7 @@
 
   // src/ops/read.ts
   var DEFAULT_DEPTH = 6;
+  var DEFAULT_LIMIT2 = 200;
   async function read(params) {
     const targets = params.nodeId ? [await resolve(params.nodeId)] : [...figma.currentPage.selection];
     if (!targets.length) {
@@ -1160,10 +1170,14 @@
     const nodes = [];
     let skipped = 0;
     for (const target of targets) {
-      const outcome = readNode(target, params.depth ?? DEFAULT_DEPTH, names);
+      const outcome = readNode(
+        target,
+        params.depth ?? DEFAULT_DEPTH,
+        names,
+        params.limit ?? DEFAULT_LIMIT2
+      );
       skipped += outcome.skipped;
       if (outcome.tree) nodes.push({ id: target.id, tree: outcome.tree });
-      else skipped += 1;
     }
     return { nodes, skipped };
   }
@@ -1211,21 +1225,29 @@
   }
 
   // src/ops/screenshot.ts
+  var DEFAULT_MAX_EDGE = 1200;
+  function fittingScale(wanted, box, maxEdge) {
+    const longest = Math.max(box.width, box.height) * wanted;
+    if (longest <= maxEdge) return wanted;
+    return Math.max(0.01, wanted * maxEdge / longest);
+  }
   async function screenshot(params) {
     const node = params.target ? await new NodeIndex().resolve(params.target) : figma.currentPage.selection[0];
     if (!node) {
       throw new Error("Nothing is selected: select a layer in Figma, or pass a target");
     }
+    const box = node;
+    const scale = fittingScale(params.scale ?? 1, box, params.maxEdge ?? DEFAULT_MAX_EDGE);
     const bytes = await node.exportAsync({
       format: "PNG",
-      constraint: { type: "SCALE", value: params.scale ?? 1 }
+      constraint: { type: "SCALE", value: scale }
     });
-    const box = node;
     return {
       id: node.id,
       name: node.name,
-      width: Math.round(box.width),
-      height: Math.round(box.height),
+      width: Math.round(box.width * scale),
+      height: Math.round(box.height * scale),
+      scale,
       png: figma.base64Encode(bytes)
     };
   }
@@ -1269,7 +1291,6 @@
   }
 
   // src/main.ts
-  var PLUGIN_VERSION = "1.1.0";
   figma.showUI(__html__, { width: 300, height: 300, themeColors: true });
   var queue = Promise.resolve();
   figma.ui.onmessage = (message2) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsalpha/mirra",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Two-way MCP server for Figma: read a design and render one back through the Figma Plugin API",
   "keywords": [
     "figma",