figmatk 0.0.6

package/mcp-server.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * FigmaTK MCP Server — exposes deck manipulation as tools for Claude Cowork / Claude Code.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { FigDeck } from './lib/fig-deck.mjs';
+import { nid, ov, nestedOv, removeNode, parseId, positionChar } from './lib/node-helpers.mjs';
+import { imageOv, hexToHash, hashToHex } from './lib/image-helpers.mjs';
+import { deepClone } from './lib/deep-clone.mjs';
+
+const server = new McpServer({
+  name: 'figmatk',
+  version: '0.0.3',
+});
+
+// ── inspect ─────────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_inspect',
+  'Show the node hierarchy tree of a Figma .deck or .fig file',
+  { path: z.string().describe('Path to .deck or .fig file') },
+  async ({ path }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const lines = [];
+    const doc = deck.message.nodeChanges.find(n => n.type === 'DOCUMENT');
+    if (!doc) return { content: [{ type: 'text', text: 'No DOCUMENT node found' }] };
+
+    function walk(nodeId, indent) {
+      const node = deck.getNode(nodeId);
+      if (!node || node.phase === 'REMOVED') return;
+      const id = nid(node);
+      const name = node.name || '';
+      const type = node.type || '?';
+      lines.push(`${' '.repeat(indent)}${type} ${id} "${name}"`);
+      const children = deck.childrenMap.get(nodeId) || [];
+      for (const child of children) walk(nid(child), indent + 2);
+    }
+    walk(nid(doc), 0);
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  }
+);
+
+// ── list-text ───────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_list_text',
+  'List all text and image content per slide in a .deck file',
+  { path: z.string().describe('Path to .deck or .fig file') },
+  async ({ path }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const lines = [];
+    const slides = deck.getSlides();
+    for (const slide of slides) {
+      if (slide.phase === 'REMOVED') continue;
+      const id = nid(slide);
+      lines.push(`\n── Slide ${id} "${slide.name || ''}" ──`);
+      const inst = deck.getSlideInstance(id);
+      if (!inst?.symbolData?.symbolOverrides) continue;
+      for (const ov of inst.symbolData.symbolOverrides) {
+        const key = ov.guidPath?.guids?.[0];
+        const keyStr = key ? `${key.sessionID}:${key.localID}` : '?';
+        if (ov.textData?.characters) {
+          lines.push(`  [text] ${keyStr}: ${ov.textData.characters.substring(0, 120)}`);
+        }
+        if (ov.fillPaints?.length) {
+          for (const p of ov.fillPaints) {
+            if (p.image?.hash) {
+              lines.push(`  [image] ${keyStr}: ${hashToHex(p.image.hash)}`);
+            }
+          }
+        }
+      }
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') || 'No slides found' }] };
+  }
+);
+
+// ── list-overrides ──────────────────────────────────────────────────────
+server.tool(
+  'figmatk_list_overrides',
+  'List editable override keys for each symbol in the deck',
+  { path: z.string().describe('Path to .deck or .fig file') },
+  async ({ path }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const lines = [];
+    const symbols = deck.getSymbols();
+    for (const sym of symbols) {
+      const id = nid(sym);
+      lines.push(`\nSymbol ${id} "${sym.name || ''}"`);
+      const children = deck.childrenMap.get(id) || [];
+      function walkChildren(nodeId, depth) {
+        const node = deck.getNode(nodeId);
+        if (!node || node.phase === 'REMOVED') return;
+        const cid = nid(node);
+        const type = node.type || '?';
+        const name = node.name || '';
+        if (type === 'TEXT' || (node.fillPaints?.some(p => p.type === 'IMAGE'))) {
+          lines.push(`  ${'  '.repeat(depth)}${type} ${cid} "${name}"`);
+        }
+        const kids = deck.childrenMap.get(cid) || [];
+        for (const kid of kids) walkChildren(nid(kid), depth + 1);
+      }
+      for (const child of children) walkChildren(nid(child), 0);
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') || 'No symbols found' }] };
+  }
+);
+
+// ── update-text ─────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_update_text',
+  'Apply text overrides to a slide instance. Pass key=value pairs.',
+  {
+    path: z.string().describe('Path to .deck file'),
+    output: z.string().describe('Output .deck path'),
+    instanceId: z.string().describe('Instance node ID (e.g. "1:1631")'),
+    overrides: z.record(z.string()).describe('Object of overrideKey: text pairs, e.g. {"75:127": "Hello"}'),
+  },
+  async ({ path, output, instanceId, overrides }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const inst = deck.getNode(instanceId);
+    if (!inst) return { content: [{ type: 'text', text: `Instance ${instanceId} not found` }] };
+    if (!inst.symbolData) inst.symbolData = { symbolOverrides: [] };
+    if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+
+    for (const [key, text] of Object.entries(overrides)) {
+      const [s, l] = key.split(':').map(Number);
+      inst.symbolData.symbolOverrides.push(ov({ sessionID: s, localID: l }, text));
+    }
+
+    const bytes = await deck.saveDeck(output);
+    return { content: [{ type: 'text', text: `Saved ${output} (${bytes} bytes), ${Object.keys(overrides).length} text overrides applied` }] };
+  }
+);
+
+// ── insert-image ────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_insert_image',
+  'Apply an image fill override to a slide instance',
+  {
+    path: z.string().describe('Path to .deck file'),
+    output: z.string().describe('Output .deck path'),
+    instanceId: z.string().describe('Instance node ID'),
+    targetKey: z.string().describe('Override key for the image rectangle (e.g. "75:126")'),
+    imageHash: z.string().describe('40-char hex SHA-1 hash of the full image'),
+    thumbHash: z.string().describe('40-char hex SHA-1 hash of the thumbnail'),
+    width: z.number().describe('Image width in pixels'),
+    height: z.number().describe('Image height in pixels'),
+    imagesDir: z.string().optional().describe('Path to images directory to include in deck'),
+  },
+  async ({ path, output, instanceId, targetKey, imageHash, thumbHash, width, height, imagesDir }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const inst = deck.getNode(instanceId);
+    if (!inst) return { content: [{ type: 'text', text: `Instance ${instanceId} not found` }] };
+    if (!inst.symbolData) inst.symbolData = { symbolOverrides: [] };
+    if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+
+    const [s, l] = targetKey.split(':').map(Number);
+    inst.symbolData.symbolOverrides.push(
+      imageOv({ sessionID: s, localID: l }, imageHash, thumbHash, width, height)
+    );
+
+    const opts = imagesDir ? { imagesDir } : {};
+    const bytes = await deck.saveDeck(output, opts);
+    return { content: [{ type: 'text', text: `Saved ${output} (${bytes} bytes), image override applied` }] };
+  }
+);
+
+// ── clone-slide ─────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_clone_slide',
+  'Duplicate a slide from the deck',
+  {
+    path: z.string().describe('Path to .deck file'),
+    output: z.string().describe('Output .deck path'),
+    slideId: z.string().describe('Source slide node ID to clone'),
+  },
+  async ({ path, output, slideId }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const slide = deck.getNode(slideId);
+    if (!slide) return { content: [{ type: 'text', text: `Slide ${slideId} not found` }] };
+
+    let nextId = deck.maxLocalID() + 1;
+    const newSlide = deepClone(slide);
+    const newSlideId = nextId++;
+    newSlide.guid = { sessionID: 1, localID: newSlideId };
+    newSlide.phase = 'CREATED';
+    delete newSlide.prototypeInteractions;
+    delete newSlide.slideThumbnailHash;
+    delete newSlide.editInfo;
+
+    const inst = deck.getSlideInstance(slideId);
+    if (inst) {
+      const newInst = deepClone(inst);
+      newInst.guid = { sessionID: 1, localID: nextId++ };
+      newInst.phase = 'CREATED';
+      newInst.parentIndex = { guid: { sessionID: 1, localID: newSlideId }, position: '!' };
+      delete newInst.derivedSymbolData;
+      delete newInst.derivedSymbolDataLayoutVersion;
+      delete newInst.editInfo;
+      deck.message.nodeChanges.push(newInst);
+    }
+
+    deck.message.nodeChanges.push(newSlide);
+    deck.rebuildMaps();
+
+    const bytes = await deck.saveDeck(output);
+    return { content: [{ type: 'text', text: `Cloned slide ${slideId} → 1:${newSlideId}. Saved ${output} (${bytes} bytes)` }] };
+  }
+);
+
+// ── remove-slide ────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_remove_slide',
+  'Mark a slide as REMOVED',
+  {
+    path: z.string().describe('Path to .deck file'),
+    output: z.string().describe('Output .deck path'),
+    slideId: z.string().describe('Slide node ID to remove'),
+  },
+  async ({ path, output, slideId }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const slide = deck.getNode(slideId);
+    if (!slide) return { content: [{ type: 'text', text: `Slide ${slideId} not found` }] };
+    removeNode(slide);
+    const inst = deck.getSlideInstance(slideId);
+    if (inst) removeNode(inst);
+
+    const bytes = await deck.saveDeck(output);
+    return { content: [{ type: 'text', text: `Removed slide ${slideId}. Saved ${output} (${bytes} bytes)` }] };
+  }
+);
+
+// ── roundtrip ───────────────────────────────────────────────────────────
+server.tool(
+  'figmatk_roundtrip',
+  'Decode and re-encode a .deck file to validate the pipeline',
+  {
+    path: z.string().describe('Path to input .deck file'),
+    output: z.string().describe('Path to output .deck file'),
+  },
+  async ({ path, output }) => {
+    const deck = await FigDeck.fromDeckFile(path);
+    const bytes = await deck.saveDeck(output);
+    return { content: [{ type: 'text', text: `Roundtrip complete: ${output} (${bytes} bytes)` }] };
+  }
+);
+
+// ── Start server ────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "figmatk",
+  "version": "0.0.6",
+  "description": "Figma Toolkit — Swiss-army knife CLI for Figma .deck and .fig files",
+  "type": "module",
+  "bin": {
+    "figmatk": "cli.mjs",
+    "figmatk-mcp": "mcp-server.mjs"
+  },
+  "exports": {
+    ".": "./lib/api.mjs",
+    "./deck": "./lib/fig-deck.mjs",
+    "./node-helpers": "./lib/node-helpers.mjs",
+    "./image-helpers": "./lib/image-helpers.mjs",
+    "./deep-clone": "./lib/deep-clone.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "mcp-server.mjs",
+    "lib/",
+    "commands/",
+    "skills/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node cli.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rcoenen/figmatk.git"
+  },
+  "homepage": "https://github.com/rcoenen/figmatk",
+  "bugs": {
+    "url": "https://github.com/rcoenen/figmatk/issues"
+  },
+  "author": "rcoenen",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "archiver": "^7.0.1",
+    "fzstd": "^0.1.1",
+    "kiwi-schema": "^0.5.0",
+    "pako": "^2.1.0",
+    "sharp": "^0.34.5",
+    "zstd-codec": "^0.1.5"
+  },
+  "keywords": [
+    "figma",
+    "deck",
+    "fig",
+    "slides",
+    "presentation",
+    "kiwi",
+    "binary",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/skills/figmatk/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: figmatk
+description: >
+  Inspect and modify Figma Slides .deck files. Use when the user asks to
+  "edit a deck", "modify a presentation", "inspect slides", "update slide text",
+  "insert an image into a slide", "clone a slide", "remove a slide",
+  "list slide content", or works with .deck or .fig files.
+metadata:
+  version: "0.0.3"
+---
+
+Use the FigmaTK MCP tools to manipulate Figma .deck files. The tools are prefixed with `figmatk_`.
+
+## Available tools
+
+- `figmatk_inspect` — Show the node hierarchy tree
+- `figmatk_list_text` — List all text and image content per slide
+- `figmatk_list_overrides` — List editable override keys per symbol
+- `figmatk_update_text` — Apply text overrides to a slide instance
+- `figmatk_insert_image` — Apply image fill override with hash + thumbnail
+- `figmatk_clone_slide` — Duplicate a slide
+- `figmatk_remove_slide` — Mark a slide as REMOVED
+- `figmatk_roundtrip` — Decode and re-encode for validation
+
+## Workflow
+
+1. Start with `figmatk_inspect` to understand the deck structure
+2. Use `figmatk_list_text` to see current content
+3. Use `figmatk_list_overrides` to find editable keys
+4. Apply changes with `figmatk_update_text` or `figmatk_insert_image`
+5. Always write to a new output path — never overwrite the source
+
+## Critical rules
+
+- Text overrides use `overrideKey: text` pairs where keys are `"sessionID:localID"` format
+- Blank text fields must be a single space `" "`, never empty string (crashes Figma)
+- Image overrides require both a full image hash and a thumbnail hash (40-char hex SHA-1)
+- Removed nodes use `phase: 'REMOVED'` — never delete from nodeChanges
+- Always roundtrip-test after modifications to validate the pipeline