@ttsalpha/mirra 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,1186 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../schema/dist/protocol.js
+import { z as z2 } from "zod";
+
+// ../schema/dist/constants.js
+var PROTOCOL_VERSION = 1;
+var DEFAULT_PORT = 51730;
+var PORT_RANGE_END = 51739;
+
+// ../schema/dist/tree.js
+import { z } from "zod";
+var Hex = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
+var SolidFill = z.object({
+  type: z.literal("solid"),
+  color: Hex,
+  opacity: z.number().min(0).max(1).optional()
+});
+var GradientStop = z.object({ at: z.number().min(0).max(1), color: Hex });
+var GradientFill = z.object({
+  type: z.literal("gradient"),
+  kind: z.enum(["linear", "radial"]).optional(),
+  /** Degrees clockwise from left-to-right. 90 points downwards. */
+  angle: z.number().optional(),
+  stops: z.array(GradientStop).min(2)
+});
+var TokenRef = z.string().regex(/^\$[\w][\w .\/-]*$/);
+var Fill = z.union([Hex, TokenRef, SolidFill, GradientFill]);
+var Stroke = z.object({
+  color: Hex,
+  width: z.number().positive().optional(),
+  align: z.enum(["inside", "outside", "center"]).optional()
+});
+var ShadowEffect = z.object({
+  type: z.enum(["shadow", "inner-shadow"]),
+  x: z.number().optional(),
+  y: z.number().optional(),
+  blur: z.number().optional(),
+  spread: z.number().optional(),
+  color: Hex.optional()
+});
+var BlurEffect = z.object({
+  type: z.enum(["layer-blur", "background-blur"]),
+  radius: z.number().nonnegative()
+});
+var Effect = z.union([ShadowEffect, BlurEffect]);
+var Sizing = z.union([z.number().nonnegative(), z.literal("fill"), z.literal("hug")]);
+var Padding = z.union([
+  z.number(),
+  z.tuple([z.number(), z.number()]),
+  z.tuple([z.number(), z.number(), z.number(), z.number()])
+]);
+var Layout = z.object({
+  dir: z.enum(["horizontal", "vertical"]),
+  gap: z.number().optional(),
+  pad: Padding.optional(),
+  /** Along the layout direction. */
+  justify: z.enum(["start", "center", "end", "space-between", "space-around", "space-evenly"]).optional(),
+  /** Across the layout direction. */
+  align: z.enum(["start", "center", "end", "baseline"]).optional(),
+  wrap: z.boolean().optional()
+});
+var Radius = z.union([
+  z.number().nonnegative(),
+  z.tuple([z.number(), z.number(), z.number(), z.number()])
+]);
+var ConstraintSide = z.enum(["min", "center", "max", "stretch", "scale"]);
+var base = {
+  /** Caller-chosen, stable across renders: `patch` and `read` address nodes by it. */
+  key: z.string().optional(),
+  name: z.string().optional(),
+  w: Sizing.optional(),
+  h: Sizing.optional(),
+  opacity: z.number().min(0).max(1).optional(),
+  visible: z.boolean().optional(),
+  /** Bounds for a node that fills or hugs. */
+  minW: z.number().nonnegative().optional(),
+  maxW: z.number().nonnegative().optional(),
+  minH: z.number().nonnegative().optional(),
+  maxH: z.number().nonnegative().optional(),
+  /** Position inside the parent. Inside an auto layout it lifts the node out of the flow. */
+  at: z.object({ x: z.number(), y: z.number() }).optional(),
+  /** How the node reacts when its parent resizes. */
+  constraints: z.object({ h: ConstraintSide, v: ConstraintSide }).optional()
+};
+var painted = {
+  fill: Fill.optional(),
+  stroke: Stroke.optional(),
+  radius: Radius.optional(),
+  effects: z.array(Effect).optional()
+};
+var typography = {
+  font: z.object({ family: z.string(), style: z.string().optional() }).optional(),
+  size: z.number().positive().optional(),
+  /** A number is px; "auto" leaves Figma's automatic line height. */
+  lineHeight: z.union([z.number().positive(), z.literal("auto")]).optional(),
+  letterSpacing: z.number().optional(),
+  align: z.enum(["left", "center", "right", "justify"]).optional(),
+  color: Fill.optional(),
+  /** A text style by name, e.g. "$text/heading". Overridden by the fields above. */
+  style: TokenRef.optional()
+};
+var container = {
+  layout: Layout.optional(),
+  clip: z.boolean().optional()
+};
+var TextNode = z.object({
+  ...base,
+  ...typography,
+  type: z.literal("text"),
+  text: z.string()
+});
+var RectNode = z.object({ ...base, ...painted, type: z.literal("rect") });
+var asset = {
+  /** Inline content: SVG markup, or a data URI for an image. */
+  src: z.string(),
+  /** The path the server inlined `src` from, kept so `read` can name it again. */
+  srcRef: z.string().optional()
+};
+var SvgNode = z.object({ ...base, ...asset, type: z.literal("svg") });
+var ImageNode = z.object({
+  ...base,
+  ...asset,
+  ...painted,
+  type: z.literal("image"),
+  fit: z.enum(["fill", "fit", "crop", "tile"]).optional()
+});
+var instance = {
+  /** Component name, e.g. "Button" or "Button/Primary" for a variant. */
+  component: z.string(),
+  /** Component properties, by the name Figma shows (without its id suffix). */
+  properties: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+};
+var InstanceNode = z.object({ ...base, ...instance, type: z.literal("instance") });
+var EllipseNode = z.object({ ...base, ...painted, type: z.literal("ellipse") });
+var NodeProps = z.object({
+  ...base,
+  ...painted,
+  ...container,
+  ...typography,
+  text: z.string().optional(),
+  src: z.string().optional(),
+  srcRef: z.string().optional(),
+  fit: ImageNode.shape.fit,
+  component: z.string().optional(),
+  properties: instance.properties
+});
+var FrameBase = z.object({
+  ...base,
+  ...painted,
+  ...container,
+  type: z.literal("frame")
+});
+var FrameNode = FrameBase.extend({
+  get children() {
+    return z.array(UINode).optional();
+  }
+});
+var UINode = z.discriminatedUnion("type", [
+  FrameNode,
+  TextNode,
+  RectNode,
+  EllipseNode,
+  InstanceNode,
+  SvgNode,
+  ImageNode
+]);
+
+// ../schema/dist/protocol.js
+var OpName = z2.enum([
+  "ping",
+  "render",
+  "read",
+  "patch",
+  "screenshot",
+  "tokens",
+  "export",
+  "find",
+  "pages",
+  "exec",
+  "define"
+]);
+var RequestEnvelope = z2.object({
+  id: z2.string(),
+  op: OpName,
+  params: z2.unknown().optional()
+});
+var ErrorBody = z2.object({
+  code: z2.string(),
+  message: z2.string(),
+  hint: z2.string().optional()
+});
+var ResponseEnvelope = z2.discriminatedUnion("ok", [
+  z2.object({ id: z2.string(), ok: z2.literal(true), result: z2.unknown() }),
+  z2.object({ id: z2.string(), ok: z2.literal(false), error: ErrorBody })
+]);
+var HelloMessage = z2.object({
+  type: z2.literal("hello"),
+  protocolVersion: z2.number(),
+  pluginVersion: z2.string(),
+  fileKey: z2.string().nullable(),
+  fileName: z2.string()
+});
+var LogMessage = z2.object({
+  type: z2.literal("log"),
+  level: z2.enum(["debug", "info", "warn", "error"]),
+  message: z2.string()
+});
+var PluginMessage = z2.union([ResponseEnvelope, HelloMessage, LogMessage]);
+var RenderParams = z2.object({
+  tree: UINode,
+  /** Where to put the root. Defaults to the current page. */
+  parentId: z2.string().optional(),
+  /** Absolute position for the root; defaults to the middle of the viewport. */
+  at: z2.object({ x: z2.number(), y: z2.number() }).optional(),
+  /** Select the new root and scroll it into view. */
+  reveal: z2.boolean().optional()
+});
+var RenderResult = z2.object({
+  rootId: z2.string(),
+  nodeCount: z2.number(),
+  /** Every node that carried a `key`, so later patches can address it. */
+  keys: z2.record(z2.string(), z2.string())
+});
+var Target = z2.union([z2.object({ key: z2.string() }), z2.object({ id: z2.string() })]);
+var PatchOp = z2.discriminatedUnion("op", [
+  z2.object({ op: z2.literal("set"), target: Target, props: NodeProps }),
+  z2.object({
+    op: z2.literal("append"),
+    target: Target,
+    tree: UINode,
+    /** Position among the existing children; appended last by default. */
+    index: z2.number().int().nonnegative().optional()
+  }),
+  z2.object({ op: z2.literal("replace"), target: Target, tree: UINode }),
+  z2.object({ op: z2.literal("remove"), target: Target }),
+  z2.object({
+    op: z2.literal("move"),
+    target: Target,
+    /** Defaults to the node's current parent. */
+    parent: Target.optional(),
+    index: z2.number().int().nonnegative().optional()
+  })
+]);
+var PatchParams = z2.object({
+  ops: z2.array(PatchOp).min(1),
+  reveal: z2.boolean().optional()
+});
+var PatchResult = z2.object({
+  applied: z2.number(),
+  /** Keys of any nodes the patch created. */
+  keys: z2.record(z2.string(), z2.string())
+});
+var ScreenshotParams = z2.object({
+  /** Defaults to the current selection, or the page if nothing is selected. */
+  target: Target.optional(),
+  scale: z2.number().min(0.1).max(4).optional()
+});
+var ScreenshotResult = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  width: z2.number(),
+  height: z2.number(),
+  /** base64 PNG. */
+  png: z2.string()
+});
+var NodeKind = z2.enum([
+  "frame",
+  "text",
+  "rect",
+  "ellipse",
+  "instance",
+  "component",
+  "group",
+  "vector",
+  "any"
+]);
+var FindParams = z2.object({
+  /** Case-insensitive substring of the layer name. */
+  name: z2.string().optional(),
+  kind: NodeKind.optional(),
+  /** A key written by render or patch. */
+  key: z2.string().optional(),
+  /** "document" loads every page first, which can be slow in a large file. */
+  scope: z2.enum(["page", "document"]).optional(),
+  /** Select the matches in Figma and scroll them into view. */
+  select: z2.boolean().optional(),
+  limit: z2.number().int().min(1).max(200).optional()
+});
+var FindResult = z2.object({
+  nodes: z2.array(z2.object({
+    id: z2.string(),
+    name: z2.string(),
+    kind: z2.string(),
+    page: z2.string(),
+    key: z2.string().optional()
+  })),
+  truncated: z2.boolean()
+});
+var PagesParams = z2.object({
+  /** Page id or exact name to switch to. */
+  select: z2.string().optional()
+});
+var PagesResult = z2.object({
+  pages: z2.array(z2.object({ id: z2.string(), name: z2.string(), current: z2.boolean() }))
+});
+var ExecParams = z2.object({ code: z2.string() });
+var ExecResult = z2.object({ result: z2.string() });
+var TokenValue = z2.union([z2.string(), z2.number(), z2.boolean()]);
+var StyleDefs = z2.object({
+  paint: z2.array(z2.object({ name: z2.string(), fill: Fill })).optional(),
+  text: z2.array(z2.object({
+    name: z2.string(),
+    font: z2.object({ family: z2.string(), style: z2.string().optional() }),
+    size: z2.number().positive(),
+    lineHeight: z2.union([z2.number().positive(), z2.literal("auto")]).optional(),
+    letterSpacing: z2.number().optional()
+  })).optional(),
+  effect: z2.array(z2.object({ name: z2.string(), effects: z2.array(Effect) })).optional()
+});
+var DefineParams = z2.object({
+  collection: z2.string().optional(),
+  styles: StyleDefs.optional(),
+  /** Modes to create or reuse, in order. Defaults to the collection's first mode. */
+  modes: z2.array(z2.string()).optional(),
+  variables: z2.array(z2.object({
+    /** Without the "$", e.g. "color/primary". */
+    name: z2.string(),
+    type: z2.enum(["color", "number", "string", "boolean"]),
+    /** One value, or one per mode name. A "$ref" value becomes an alias. */
+    value: z2.union([TokenValue, z2.record(z2.string(), TokenValue)])
+  })).optional()
+});
+var DefineResult = z2.object({
+  collection: z2.string().optional(),
+  /** The modes the collection ended up with; a plan may cap how many it allows. */
+  modes: z2.array(z2.string()),
+  styles: z2.array(z2.string()),
+  created: z2.array(z2.string()),
+  updated: z2.array(z2.string()),
+  /** What the file would not let us do, rather than failing the whole call. */
+  notes: z2.array(z2.string())
+});
+var TokensParams = z2.object({});
+var VariableValue = z2.union([z2.string(), z2.number(), z2.boolean()]);
+var TokensResult = z2.object({
+  collections: z2.array(z2.object({
+    name: z2.string(),
+    modes: z2.array(z2.string()),
+    variables: z2.array(z2.object({
+      /** The name a tree refers to, e.g. "$color/primary". */
+      ref: z2.string(),
+      type: z2.string(),
+      /** Value per mode name; an alias reads as another "$ref". */
+      values: z2.record(z2.string(), VariableValue)
+    }))
+  })),
+  styles: z2.object({
+    paint: z2.array(z2.object({ ref: z2.string(), fill: z2.string().optional() })),
+    text: z2.array(z2.object({ ref: z2.string(), font: z2.string(), size: z2.number().optional() })),
+    effect: z2.array(z2.object({ ref: z2.string() }))
+  })
+});
+var ExportParams = z2.object({
+  targets: z2.array(Target).min(1),
+  format: z2.enum(["png", "svg"]).optional(),
+  scale: z2.number().min(0.1).max(4).optional(),
+  /** Directory the server writes into, relative to MIRRA_ROOT or its own. */
+  outDir: z2.string()
+});
+var ExportResult = z2.object({
+  assets: z2.array(z2.object({ id: z2.string(), name: z2.string(), extension: z2.string(), data: z2.string() }))
+});
+var ReadParams = z2.object({
+  /** Defaults to the current selection. */
+  nodeId: z2.string().optional(),
+  /** How many levels of children to walk. */
+  depth: z2.number().int().min(0).max(20).optional()
+});
+var ReadResult = z2.object({
+  nodes: z2.array(z2.object({ id: z2.string(), tree: UINode })),
+  /** Nodes left out because the DSL has no shape for them yet, or depth ran out. */
+  skipped: z2.number()
+});
+var PingResult = z2.object({
+  fileName: z2.string(),
+  fileKey: z2.string().nullable(),
+  currentPage: z2.string(),
+  selectionCount: z2.number()
+});
+
+// src/clients.ts
+import { spawnSync } from "node:child_process";
+import { access, copyFile, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+var SERVER_NAME = "mirra";
+async function stableNodePath() {
+  try {
+    return await realpath(process.execPath);
+  } catch {
+    return process.execPath;
+  }
+}
+function targets() {
+  const home = homedir();
+  return [
+    {
+      client: "Claude Desktop",
+      file: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
+      key: "mcpServers"
+    },
+    { client: "Cursor", file: join(home, ".cursor/mcp.json"), key: "mcpServers" },
+    {
+      client: "VS Code",
+      file: join(home, "Library/Application Support/Code/User/mcp.json"),
+      key: "servers",
+      typed: true
+    }
+  ];
+}
+async function registerWithClients(entryPoint) {
+  const node = await stableNodePath();
+  const reports = [];
+  for (const target of targets()) {
+    reports.push(await writeEntry(target, node, entryPoint));
+  }
+  reports.push(claudeCode(node, entryPoint));
+  return reports;
+}
+async function writeEntry(target, node, entryPoint) {
+  try {
+    await access(target.file);
+  } catch {
+    return { client: target.client, status: "skipped", detail: "not installed" };
+  }
+  try {
+    const raw = await readFile(target.file, "utf8");
+    const config = JSON.parse(raw);
+    const servers = config[target.key] ?? {};
+    servers[SERVER_NAME] = {
+      ...target.typed ? { type: "stdio" } : {},
+      command: node,
+      args: [entryPoint, "serve"]
+    };
+    config[target.key] = servers;
+    await copyFile(target.file, `${target.file}.mirra-backup`);
+    const temporary = join(dirname(target.file), `.${SERVER_NAME}-${process.pid}.json`);
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}
+`);
+    await rename(temporary, target.file);
+    return { client: target.client, status: "written", detail: target.file };
+  } catch (error) {
+    return {
+      client: target.client,
+      status: "failed",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function claudeCode(node, entryPoint) {
+  const probe = spawnSync("claude", ["--version"], { stdio: "ignore" });
+  if (probe.error)
+    return { client: "Claude Code", status: "skipped", detail: "claude not on PATH" };
+  const result = spawnSync(
+    "claude",
+    ["mcp", "add", "-s", "user", SERVER_NAME, "--", node, entryPoint, "serve"],
+    { stdio: "pipe", encoding: "utf8" }
+  );
+  if (result.status === 0)
+    return { client: "Claude Code", status: "written", detail: "user scope" };
+  return {
+    client: "Claude Code",
+    status: "failed",
+    detail: (result.stderr || result.stdout || "claude mcp add failed").trim().split("\n")[0] ?? ""
+  };
+}
+function serverEntryPoint() {
+  return resolve(fileDirectory(), "index.js");
+}
+function fileDirectory() {
+  return dirname(new URL(import.meta.url).pathname);
+}
+
+// src/install.ts
+import { spawn } from "node:child_process";
+import { access as access2, cp, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { homedir as homedir2, platform } from "node:os";
+import { join as join2, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PLUGIN_HOME = join2(homedir2(), ".mirra", "plugin");
+var BUNDLED_PLUGIN = resolve2(fileURLToPath(new URL(".", import.meta.url)), "plugin");
+async function installPlugin() {
+  await mkdir(PLUGIN_HOME, { recursive: true });
+  await cp(BUNDLED_PLUGIN, PLUGIN_HOME, { recursive: true });
+  const manifest = join2(PLUGIN_HOME, "manifest.json");
+  return { manifest, version: await installedVersion() };
+}
+async function installedVersion() {
+  try {
+    const manifest = JSON.parse(await readFile2(join2(PLUGIN_HOME, "manifest.json"), "utf8"));
+    return typeof manifest.name === "string" ? manifest.name : "unknown";
+  } catch {
+    return "not installed";
+  }
+}
+async function isInstalled() {
+  try {
+    await access2(join2(PLUGIN_HOME, "manifest.json"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function reveal(path) {
+  if (platform() !== "darwin") return;
+  spawn("open", ["-R", path], { stdio: "ignore", detached: true }).unref();
+}
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/errors.ts
+var MirraError = class extends Error {
+  constructor(message, code, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.name = "MirraError";
+  }
+};
+
+// src/tools/text.ts
+function text(lines, isError = false) {
+  return { content: [{ type: "text", text: lines.join("\n") }], isError };
+}
+function describeError(error) {
+  if (error instanceof MirraError) {
+    return error.hint ? `${error.message}
+
+${error.hint}` : error.message;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/tools/define.ts
+var DESCRIPTION = `Create or update the design system itself: variables in a collection, and
+paint, text or effect styles. A value of "$other/name" becomes an alias to that variable, and a
+value keyed by mode name sets one value per mode. Both halves are optional.`;
+function registerDefine(server, bridge) {
+  server.registerTool(
+    "mirra_define_tokens",
+    { title: "Define Figma variables", description: DESCRIPTION, inputSchema: DefineParams.shape },
+    async (params) => {
+      try {
+        const result = DefineResult.parse(await bridge.request("define", params));
+        return text([
+          ...result.collection ? [
+            `collection ${result.collection} (modes: ${result.modes.join(", ")})`,
+            `created: ${result.created.join(", ") || "none"}`,
+            `updated: ${result.updated.join(", ") || "none"}`
+          ] : [],
+          ...result.styles.length ? [`styles: ${result.styles.join(", ")}`] : [],
+          ...result.notes
+        ]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/exec.ts
+var DESCRIPTION2 = `Run Plugin API code in the open file and return what it evaluates to.
+The body is an async function receiving \`figma\`; use it only for what the typed tools cannot do.`;
+function registerExec(server, bridge) {
+  server.registerTool(
+    "mirra_exec",
+    { title: "Run Plugin API code", description: DESCRIPTION2, inputSchema: ExecParams.shape },
+    async (params) => {
+      try {
+        const result = ExecResult.parse(await bridge.request("exec", params));
+        return text([result.result]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/export.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { resolve as resolve4 } from "node:path";
+
+// src/tools/paths.ts
+import { resolve as resolve3, sep } from "node:path";
+function rootDirectory() {
+  const configured = process.env["MIRRA_ROOT"];
+  return configured ? resolve3(configured) : process.cwd();
+}
+function resolveInRoot(path) {
+  const root = rootDirectory();
+  const full = resolve3(root, path);
+  if (!process.env["MIRRA_ROOT"]) return full;
+  if (full !== root && !full.startsWith(root + sep)) {
+    throw new MirraError(
+      `${path} is outside MIRRA_ROOT`,
+      "outside_root",
+      `This server may only touch files under ${root}.`
+    );
+  }
+  return full;
+}
+
+// src/tools/export.ts
+var DESCRIPTION3 = `Export layers as PNG or SVG files on disk, for icons and images a tree cannot
+describe. Targets are keys or Figma node ids; outDir is relative to where the server runs.`;
+function registerExport(server, bridge) {
+  server.registerTool(
+    "mirra_export_assets",
+    {
+      title: "Export Figma layers to files",
+      description: DESCRIPTION3,
+      inputSchema: ExportParams.shape
+    },
+    async (params) => {
+      try {
+        const result = ExportResult.parse(await bridge.request("export", params));
+        const directory = resolveInRoot(params.outDir);
+        await mkdir2(directory, { recursive: true });
+        const written = [];
+        for (const asset2 of result.assets) {
+          const file = resolve4(directory, `${slug(asset2.name)}.${asset2.extension}`);
+          await writeFile2(file, Buffer.from(asset2.data, "base64"));
+          written.push(file);
+        }
+        return text([`wrote ${written.length} file(s):`, ...written]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+function slug(name) {
+  const cleaned = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned || "asset";
+}
+
+// src/tools/find.ts
+var FIND = `Locate layers by name, kind or mirra key, so an existing design can be targeted
+without clicking in Figma first. Searches the current page unless scope is "document".`;
+var PAGES = `List the pages of the file, and switch to one by name or id. Every other tool works
+on the current page, so start here when the layer you want is elsewhere.`;
+function registerFind(server, bridge) {
+  server.registerTool(
+    "mirra_find",
+    { title: "Find Figma layers", description: FIND, inputSchema: FindParams.shape },
+    async (params) => {
+      try {
+        const result = FindResult.parse(await bridge.request("find", params));
+        if (!result.nodes.length) return text(["no matches"]);
+        return text([
+          ...result.nodes.map(
+            (node) => `${node.id}  ${node.kind.toLowerCase().padEnd(12)} ${node.name}${node.key ? `  [key: ${node.key}]` : ""}  (${node.page})`
+          ),
+          ...result.truncated ? ["", "more matches exist: raise limit or narrow the query"] : []
+        ]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+  server.registerTool(
+    "mirra_pages",
+    { title: "List or switch Figma pages", description: PAGES, inputSchema: PagesParams.shape },
+    async (params) => {
+      try {
+        const result = PagesResult.parse(await bridge.request("pages", params));
+        return text(
+          result.pages.map((page) => `${page.current ? "*" : " "} ${page.id}  ${page.name}`)
+        );
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/assets.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { extname } from "node:path";
+var MIME = /* @__PURE__ */ new Map([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"]
+]);
+async function inlineAssets(tree) {
+  if (Array.isArray(tree)) {
+    return await Promise.all(tree.map((item) => inlineAssets(item)));
+  }
+  if (!tree || typeof tree !== "object") return tree;
+  const node = { ...tree };
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== "src") node[key] = await inlineAssets(value);
+  }
+  const src = node["src"];
+  if (typeof src === "string" && isPath(src)) {
+    node["srcRef"] = src;
+    node["src"] = node["type"] === "svg" ? await readSvg(src) : await readImage(src);
+  }
+  return node;
+}
+function isPath(src) {
+  if (src.startsWith("data:") || src.trimStart().startsWith("<")) return false;
+  return true;
+}
+async function readSvg(path) {
+  return readFile3(resolveInRoot(path), "utf8");
+}
+async function readImage(path) {
+  const file = resolveInRoot(path);
+  const type = MIME.get(extname(file).toLowerCase());
+  if (!type) throw new Error(`Unsupported image type: ${extname(file) || file}`);
+  return `data:${type};base64,${(await readFile3(file)).toString("base64")}`;
+}
+
+// src/tools/patch.ts
+var DESCRIPTION4 = `Change layers that already exist, addressed by the "key" they were rendered with
+(or by Figma node id). Ops are "set" to change properties, "append" to add a child tree,
+"replace" to swap a node for a new tree, and "remove". The whole patch is one undo step.`;
+function registerPatch(server, bridge) {
+  server.registerTool(
+    "mirra_patch",
+    {
+      title: "Patch existing Figma layers",
+      description: DESCRIPTION4,
+      inputSchema: PatchParams.shape
+    },
+    async (params) => {
+      try {
+        const result = PatchResult.parse(await bridge.request("patch", await inlineAssets(params)));
+        const created = Object.entries(result.keys);
+        return text([
+          `applied ${result.applied} op(s)`,
+          ...created.length ? ["new keys:", ...created.map(([key, id]) => `  ${key} -> ${id}`)] : []
+        ]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/ping.ts
+function registerPing(server, bridge) {
+  server.registerTool(
+    "mirra_ping",
+    {
+      title: "Ping the Figma plugin",
+      description: "Check that the Mirra plugin is connected, and report the open file, current page and selection size."
+    },
+    async () => {
+      try {
+        const result = PingResult.parse(await bridge.request("ping"));
+        return text([
+          `file: ${result.fileName}${result.fileKey ? ` (${result.fileKey})` : ""}`,
+          `page: ${result.currentPage}`,
+          `selection: ${result.selectionCount} node(s)`,
+          `port: ${bridge.status.port}`
+        ]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// 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.`;
+function registerRead(server, bridge) {
+  server.registerTool(
+    "mirra_read",
+    {
+      title: "Read Figma layers as a UI tree",
+      description: DESCRIPTION5,
+      inputSchema: ReadParams.shape
+    },
+    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`] : [];
+        return text([...note, JSON.stringify(result.nodes, null, 2)]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/render.ts
+var DESCRIPTION6 = `Build a whole screen in the open Figma file from one declarative tree.
+
+The tree mirrors flexbox: a frame carries layout {dir, gap, pad, justify, align}, and a
+child sizes itself with w/h set to a number, "fill" or "hug". Node types are frame, text,
+rect and ellipse. Colours are hex strings; fill also takes {type:"gradient", stops}.
+Give each node you may want to change later a stable "key" and address it from there.`;
+function registerRender(server, bridge) {
+  server.registerTool(
+    "mirra_render",
+    {
+      title: "Render a UI tree into Figma",
+      description: DESCRIPTION6,
+      inputSchema: RenderParams.shape
+    },
+    async (params) => {
+      try {
+        const result = RenderResult.parse(
+          await bridge.request("render", await inlineAssets(params))
+        );
+        const keys = Object.entries(result.keys);
+        return text([
+          `rendered ${result.nodeCount} node(s), root ${result.rootId}`,
+          ...keys.length ? ["keys:", ...keys.map(([key, id]) => `  ${key} -> ${id}`)] : []
+        ]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// 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.`;
+function registerScreenshot(server, bridge) {
+  server.registerTool(
+    "mirra_screenshot",
+    {
+      title: "Screenshot a Figma layer",
+      description: DESCRIPTION7,
+      inputSchema: ScreenshotParams.shape
+    },
+    async (params) => {
+      try {
+        const shot = ScreenshotResult.parse(await bridge.request("screenshot", params));
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${shot.name} (${shot.width}x${shot.height}, ${shot.id})`
+            },
+            { type: "image", data: shot.png, mimeType: "image/png" }
+          ]
+        };
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/tools/tokens.ts
+var DESCRIPTION8 = `List the variables and styles of the open file, with the "$name" each one
+answers to. Pass those names as fill, color or style in a tree and the rendered node stays
+bound to the design system instead of to a hardcoded value.`;
+function registerTokens(server, bridge) {
+  server.registerTool(
+    "mirra_tokens",
+    { title: "List design tokens", description: DESCRIPTION8 },
+    async () => {
+      try {
+        const result = TokensResult.parse(await bridge.request("tokens"));
+        return text([JSON.stringify(result, null, 2)]);
+      } catch (error) {
+        return text([describeError(error)], true);
+      }
+    }
+  );
+}
+
+// src/mcp.ts
+var SERVER_VERSION = "1.0.0";
+function createMcpServer(bridge) {
+  const server = new McpServer({ name: "mirra", version: SERVER_VERSION });
+  registerPing(server, bridge);
+  registerRender(server, bridge);
+  registerRead(server, bridge);
+  registerPatch(server, bridge);
+  registerScreenshot(server, bridge);
+  registerTokens(server, bridge);
+  registerExport(server, bridge);
+  registerFind(server, bridge);
+  registerDefine(server, bridge);
+  if (isOn(process.env["MIRRA_ALLOW_EXEC"])) registerExec(server, bridge);
+  return server;
+}
+function isOn(value) {
+  return value !== void 0 && value !== "" && value !== "false" && value !== "0";
+}
+
+// src/transport.ts
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+var HOSTS = ["127.0.0.1", "::1"];
+var DEFAULT_TIMEOUT_MS = 3e4;
+function originAllowed(origin) {
+  if (!origin || origin === "null") return true;
+  if (process.env["MIRRA_ALLOW_ORIGIN"] === origin) return true;
+  try {
+    const { hostname } = new URL(origin);
+    return hostname === "figma.com" || hostname.endsWith(".figma.com");
+  } catch {
+    return false;
+  }
+}
+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;
+  #port = null;
+  #pending = /* @__PURE__ */ new Map();
+  get status() {
+    return { port: this.#port, connected: this.#socket !== null, hello: this.#hello };
+  }
+  async listen(preferredPort2) {
+    const first = preferredPort2 ?? DEFAULT_PORT;
+    const last = preferredPort2 ?? PORT_RANGE_END;
+    let lastError;
+    for (let port = first; port <= last; port++) {
+      try {
+        const primary = await openServer(HOSTS[0], port);
+        this.#servers = [primary];
+        this.#port = actualPort(primary, port);
+        try {
+          this.#servers.push(await openServer(HOSTS[1], this.#port));
+        } catch {
+          log("no IPv6 loopback; listening on 127.0.0.1 only");
+        }
+        for (const server of this.#servers) {
+          server.on("connection", (socket) => this.#attach(socket));
+        }
+        return this.#port;
+      } catch (error) {
+        lastError = error;
+        if (error.code !== "EADDRINUSE") throw error;
+      }
+    }
+    throw new MirraError(
+      `No free port in ${first}-${last} (last error: ${String(lastError)})`,
+      "no_free_port",
+      "Another Mirra session is probably running. Close the other Claude Code window, or set MIRRA_PORT to a free port."
+    );
+  }
+  async close() {
+    for (const [id, pending] of this.#pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new MirraError("Server shutting down", "shutdown"));
+      this.#pending.delete(id);
+    }
+    this.#socket?.close(1001, "server shutting down");
+    await Promise.all(
+      this.#servers.map((server) => new Promise((resolve5) => server.close(() => resolve5())))
+    );
+    this.#servers = [];
+    this.#port = null;
+  }
+  async request(op, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const socket = this.#socket;
+    if (!socket) {
+      throw new MirraError("No Figma plugin is connected", "plugin_offline", OPEN_PLUGIN_HINT);
+    }
+    const id = randomUUID();
+    const envelope = { id, op, params };
+    return new Promise((resolve5, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new MirraError(
+            `Plugin did not answer "${op}" within ${timeoutMs}ms`,
+            "timeout",
+            "Check the Mirra panel in Figma: it may have disconnected or hit an error."
+          )
+        );
+      }, timeoutMs);
+      this.#pending.set(id, { resolve: resolve5, reject, timer });
+      socket.send(JSON.stringify(envelope));
+    });
+  }
+  #attach(socket) {
+    if (this.#socket) this.#socket.close(4e3, "replaced by a newer plugin connection");
+    this.#socket = socket;
+    this.#hello = null;
+    socket.on("message", (raw) => this.#onMessage(String(raw)));
+    socket.on("close", () => {
+      if (this.#socket === socket) {
+        this.#socket = null;
+        this.#hello = null;
+      }
+    });
+    socket.on("error", (error) => log("plugin socket error:", error.message));
+  }
+  #onMessage(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return log("dropped non-JSON message from plugin");
+    }
+    const message = PluginMessage.safeParse(parsed);
+    if (!message.success) return log("dropped unknown message from plugin");
+    const data = message.data;
+    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.`
+        );
+      }
+      return log(`plugin connected: ${data.fileName} (plugin v${data.pluginVersion})`);
+    }
+    const pending = this.#pending.get(data.id);
+    if (!pending) return;
+    this.#pending.delete(data.id);
+    clearTimeout(pending.timer);
+    if (data.ok) pending.resolve(data.result);
+    else pending.reject(new MirraError(data.error.message, data.error.code, data.error.hint));
+  }
+};
+function actualPort(wss, requested) {
+  const address = wss.options.server?.address() ?? null;
+  return typeof address === "object" && address ? address.port : requested;
+}
+function openServer(host, port) {
+  return new Promise((resolve5, reject) => {
+    const http = createServer((request, response) => {
+      const origin = request.headers.origin;
+      log(`http ${request.method} ${request.url} from ${request.socket.remoteAddress}`);
+      response.writeHead(200, {
+        "content-type": "text/plain",
+        // Only the plugin may read the body; another page can at most see a 200.
+        ...originAllowed(origin) ? { "access-control-allow-origin": origin ?? "*" } : {}
+      });
+      response.end("mirra");
+    });
+    const wss = new WebSocketServer({
+      server: http,
+      verifyClient: ({ origin }, done) => {
+        if (originAllowed(origin)) return done(true);
+        log(`refused a connection from origin ${origin}`);
+        done(false, 403, "origin not allowed");
+      }
+    });
+    wss.on("error", (error) => log(`websocket server error: ${error.message}`));
+    http.listen(port, host);
+    const onError = (error) => {
+      http.close();
+      reject(error);
+    };
+    http.once("error", onError);
+    http.once("listening", () => {
+      http.off("error", onError);
+      resolve5(wss);
+    });
+  });
+}
+function log(...parts) {
+  console.error("[mirra]", ...parts);
+}
+
+// src/index.ts
+var USAGE = `mirra <command>
+
+  serve    Run the MCP server over stdio (default; this is what Claude Code spawns)
+  init     Install the Figma plugin into ~/.mirra/plugin and print the next steps
+  doctor   Bind the plugin port and wait for the Figma plugin to connect
+
+Flags:
+  --no-reveal   init: do not open the folder in Finder
+  --no-config   init: do not touch any client's configuration
+
+Environment:
+  MIRRA_PORT   Bind this exact port instead of scanning ${DEFAULT_PORT}-${PORT_RANGE_END}
+`;
+var preferredPort = process.env["MIRRA_PORT"] ? Number(process.env["MIRRA_PORT"]) : void 0;
+switch (process.argv[2] ?? "serve") {
+  case "serve":
+    await serve();
+    break;
+  case "init":
+    await init();
+    break;
+  case "doctor":
+    await doctor();
+    break;
+  case "--help":
+  case "-h":
+  case "help":
+    process.stdout.write(USAGE);
+    break;
+  default:
+    process.stderr.write(USAGE);
+    process.exit(1);
+}
+async function serve() {
+  const bridge = new PluginBridge();
+  try {
+    const port = await bridge.listen(preferredPort);
+    console.error(`[mirra] listening on ws://127.0.0.1:${port}`);
+  } catch (error) {
+    console.error(`[mirra] ${describeError(error)}`);
+    process.exit(1);
+  }
+  const server = createMcpServer(bridge);
+  await server.connect(new StdioServerTransport());
+  const shutdown = () => {
+    void bridge.close().then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+async function init() {
+  const { manifest } = await installPlugin();
+  const lines = [`Plugin installed at ${PLUGIN_HOME}`, ""];
+  if (process.argv.includes("--no-config")) {
+    lines.push("Left every client configuration alone.", "");
+  } else {
+    const reports = await registerWithClients(serverEntryPoint());
+    lines.push("Clients:");
+    for (const report of reports) {
+      lines.push(`  ${report.status.padEnd(8)} ${report.client.padEnd(15)} ${report.detail}`);
+    }
+    lines.push("", "A client that was already running has to be restarted to see the tools.", "");
+  }
+  lines.push(
+    "Then, in Figma Desktop:",
+    "  1. Plugins -> Development -> Import plugin from manifest...",
+    `     and choose ${manifest}`,
+    "  2. Open a file, run Mirra, and leave the panel open",
+    "  3. Ask the agent for mirra_ping; the panel badge should turn green"
+  );
+  if (!process.argv.includes("--no-reveal")) reveal(manifest);
+  console.log(lines.join("\n"));
+}
+async function doctor() {
+  const bridge = new PluginBridge();
+  try {
+    const port = await bridge.listen(preferredPort);
+    console.log(`port      ok    ws://127.0.0.1:${port}`);
+  } catch (error) {
+    console.log(`port      FAIL  ${describeError(error)}`);
+    process.exit(1);
+  }
+  console.log(
+    await isInstalled() ? `plugin    ok    installed at ${PLUGIN_HOME}` : "plugin    warn  not installed; run `mirra init`"
+  );
+  const connected = await waitFor(() => bridge.status.connected, 5e3);
+  if (!connected) {
+    console.log(
+      "socket    FAIL  no connection after 5s\n                Open the file in Figma Desktop, then Plugins -> Development -> Mirra."
+    );
+    await bridge.close();
+    process.exit(1);
+  }
+  const hello = bridge.status.hello;
+  console.log(`socket    ok    plugin v${hello?.pluginVersion} on "${hello?.fileName}"`);
+  await bridge.close();
+}
+async function waitFor(predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return true;
+    await new Promise((resolve5) => setTimeout(resolve5, 100));
+  }
+  return predicate();
+}