genable-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,24 +1,52 @@
 # genable-mcp
 
-**The write-side complement to Figma's official MCP.** Build, edit, and search Figma nodes from any MCP client (Claude Code, Cursor, etc.) via the Genable plugin.
+[![npm version](https://img.shields.io/npm/v/genable-mcp.svg)](https://www.npmjs.com/package/genable-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/genable-mcp.svg)](https://www.npmjs.com/package/genable-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
+
+**The write-side MCP server for Figma.** Build, edit, restructure, and search Figma designs from Claude Code, Cursor, Cline, or any MCP-compatible client.
+
+> Figma's official MCP is read-only — perfect for code generation. `genable-mcp` is the complement: **41 write-side tools** so an LLM can actually build and edit your designs.
 
 ## What this is
 
 Figma's official MCP is excellent for **reading** designs (`get_design_context`, code generation). But it's mostly read-only — there's no first-class way to write to the canvas, navigate across pages, or run plugin-API code from your MCP client.
 
-`genable-mcp` fills that gap. It exposes 39 tools focused on the **write** side:
+`genable-mcp` fills that gap. It exposes **41 tools** focused on the **write** side:
 
-- **Tree creation** — build complete subtrees with JSX-like markup (`jsx`)
+- **Tree creation** — build complete subtrees with JSX-like markup (`jsx`), vector primitives (`create_vector`)
 - **Property edits** — text, fills, strokes, layout, all auto-layout aware (`set_text`, `set_fill`, `set_layout`, `set_stroke`, `edit`)
 - **Variables / tokens** — collections, modes, bindings (`create_variable`, `bind_variable`, `set_variable_mode`, etc.)
 - **Components** — create, combine, expose props, instance (`create_component`, `add_component_prop`, `create_instance`)
 - **Cross-page navigation** — `switch_page` (officially the painful gap)
-- **Search & inspect** — `find_nodes`, `inspect`, `describe`, `find_references`
-- **Visual verification** — `get_screenshot`
-- **Escape hatch** — `js` for raw plugin API access (with sandbox-limit docs in the tool description)
+- **Search & inspect** — `find_nodes`, `inspect`, `describe`, `find_references`, `discover_props`
+- **Visual verification** — `get_screenshot` returns PNG as MCP image content for vision-capable models
+- **Curated knowledge** — design `skill` / `style` / `guideline` readers built into the plugin
+- **Agent ergonomics** — `session_note` scratchpad, `subtask` delegation, `ask_user` interactive pause
 
 We **recommend pairing** with Figma's official MCP. They cover read-for-codegen; we cover write-and-edit. The two MCPs together give an LLM full read+write access to a Figma file.
 
+## FAQ
+
+**Is this an alternative to Figma's official MCP?**
+No — it's a complement. Use both. Official MCP for "read this design → give me code". `genable-mcp` for "build / edit / restructure this design".
+
+**What MCP clients does it work with?**
+Any client that supports STDIO MCP servers: Claude Code, Claude Desktop, Cursor, Cline, Continue, Zed, and others.
+
+**Does it need a Figma plugin?**
+Yes. The plugin runs inside Figma desktop and is the only way to actually call `figma.*` API. `genable-mcp` is the bridge between your MCP client (outside Figma) and the plugin (inside Figma).
+
+**How is this different from "Figma to code" plugins?**
+Those plugins are one-shot exporters (Figma → React/Vue/HTML). `genable-mcp` is bidirectional and interactive — your AI agent can read, edit, verify visually, and iterate inside Figma.
+
+**Can it build a full design from a prompt?**
+Yes. The `jsx` tool accepts JSX-like markup and creates an entire subtree atomically. Pair with `bind_variable` for token-driven designs.
+
+**Is it free?**
+Yes. MIT license. The MCP server is free; the Genable plugin in Figma Community is free.
+
 ## How it works
 
 ```
@@ -97,6 +125,7 @@ Each tool's full description (parameters, examples, sandbox limits) is exposed v
 
 ### Tree creation
 - `jsx` — Build a complete subtree with JSX-like markup. Single-call atomicity.
+- `create_vector` — Create vector primitives from SVG path data.
 
 ### Read
 - `inspect` — Read a node with selectable property facets (layout, paint, typography, etc.).
@@ -126,7 +155,7 @@ Each tool's full description (parameters, examples, sandbox limits) is exposed v
 - `bind_variable` — Bind a variable to a node property.
 
 ### Knowledge readers
-- `skill`, `style`, `anatomy`, `guideline`, `help` — Curated design knowledge baked into the plugin.
+- `skill`, `style`, `guideline`, `help` — Curated design knowledge baked into the plugin.
 
 ### Page navigation
 - `switch_page` — Switch active page by ID or name. Returns the full page roster.
@@ -137,9 +166,10 @@ Each tool's full description (parameters, examples, sandbox limits) is exposed v
 ### Interaction
 - `ask_user` — Pause and ask the user a question (interactive client only).
 - `subtask` — Delegate a sub-prompt to a focused agent.
+- `session_note` — Scratchpad for the agent to record findings across a session.
 
-### Escape hatch
-- `js` — `[advanced]` Run JS in the plugin runtime. Full `figma.*` API access. Sandbox limits documented in the tool description (cross-page loading, frozen arrays, font requirements, etc.).
+### Plugin data
+- `read_plugin_data`, `write_plugin_data` — Persist key/value metadata on nodes via Figma's plugin-data API.
 
 ## Limitations
 

package/dist/tools-schema.json

@@ -1,7 +1,7 @@
 [
   {
     "name": "jsx",
-    "description": "Create design trees with nested JSX markup. One jsx call builds a complete subtree atomically — nesting is the hierarchy. Keep a single logical unit inside one call; the returned root's children are already built, not stubs to be filled in later.\n\nExamples:\n  jsx({markup: \"<frame name='Card' layout='column' padding={16} fill='#FFFFFF' w='fill' />\"})\n  jsx({markup: \"<frame name='Row' layout='row' gap={8} padding={12} w='fill'><icon name='lucide:settings' size={20} /><text name='Label' w='fill'>Account</text><icon name='lucide:chevron-right' size={16} /></frame>\"})\n\nElements: frame, text, rect, ellipse, line, icon, image, instance, component, group, section, vector\nAttributes (frame): layout, justify, items, wrap, w, h, minW, maxW, p, gap, bg, fill, rounded, stroke, shadow, blur, bgblur, opacity, layoutPositioning\nAttributes (text): size, weight, lineHeight, font, fill, w (w=\"fill\" for wrap), maxLines, textTruncation\nEffects: shadow=\"0,8,32,0,#0006\" or shadow={shadow(0,8,32,0,'#0006')}; blur={10} for layer blur; bgblur={20} for frosted-glass/glassmorphism background blur. Multiple effects merge automatically.\nDecoration in auto-layout: floating orbs/blobs/decorative shapes inside a row/column parent need layoutPositioning=\"absolute\" so they don't get stacked into the main-axis flow.\nFull-frame backgrounds: set the parent frame's bg directly (supports gradients via bg=\"linear-gradient(135deg, #A 0%, #B 100%)\"). Don't add a separate <rect> backdrop.\nText: <text size={24}>content here</text>\nInstance: <instance ref=\"Button\" variant=\"Size=Large\"/>\nSelf-closing: <line w=\"fill\" stroke=\"#E5E7EB\"/> (use line for dividers/separators; rect/ellipse for SMALL pure decoration with no children — page-level backgrounds belong on the parent frame's bg)\nArc/Ring: <ellipse w={120} h={120} arc=\"0 270\" fill=\"#4F46E5\"/> (arc=\"start end innerRadius?\" — innerRadius 0-1 makes a donut/ring)\nGrid layout: call help({ name: \"grid-layout\" }) for tracks, gaps, and when row/column is a better fit\nVariable binding: fill/bg/stroke accept qualified bare-name token strings (e.g. bg=\"$Theme/Bg/Surface\"). Object literals (fill={{variable_id:...}}) drop the binding silently — always use the string form.\n\nSwap an existing subtree: jsx({replaceId: \"<id>\", markup: \"...\"}) replaces the old node at the same parent and sibling index atomically, preserving position in one call. Markup must have a single root. Use jsx for tree creation; edit for property updates on known nodes.",
+    "description": "Create design trees with nested JSX markup. One jsx call builds a complete subtree atomically — nesting is the hierarchy. Keep a single logical unit inside one call; the returned root's children are already built, not stubs to be filled in later.\n\nExamples:\n  jsx({markup: \"<frame name='Card' layout='column' padding={16} fill='#FFFFFF' w='fill' />\"})\n  jsx({markup: \"<frame name='Row' layout='row' gap={8} padding={12} w='fill'><icon name='lucide:settings' size={20} /><text name='Label' w='fill'>Account</text><icon name='lucide:chevron-right' size={16} /></frame>\"})\n\nElements: frame, text, rect, ellipse, line, icon, image, instance, component, group, section, vector\nAttributes (frame): layout, justify, items, wrap, w, h, minW, maxW, p, gap, bg, fill, rounded, stroke, shadow, blur, bgblur, opacity, layoutPositioning\nAttributes (text): size, weight, lineHeight, font, fill, w (w=\"fill\" for wrap), maxLines, textTruncation\nEffects: shadow=\"0,8,32,0,#0006\" or shadow={shadow(0,8,32,0,'#0006')}; blur={10} for layer blur; bgblur={20} for frosted-glass/glassmorphism background blur. Multiple effects merge automatically.\nDecoration in auto-layout: floating orbs/blobs/decorative shapes inside a row/column parent need layoutPositioning=\"absolute\" so they don't get stacked into the main-axis flow.\nFull-frame backgrounds: set the parent frame's bg directly. Don't add a separate <rect> backdrop. Supported gradient strings (CSS-like subset, not full CSS):\n  - linear-gradient(<angle>deg, <#hex> <pos>%, ...)        e.g. \"linear-gradient(135deg, #A 0%, #B 100%)\"\n  - linear-gradient(to <direction>, <stops>)               directions: top/right/bottom/left and corners (e.g. \"to bottom right\")\n  - radial-gradient(<stops>)                               centered, ellipse-fill — no position/shape modifiers\n  - radial-gradient(circle, <stops>)                       centered, circle shape only\n  - conic-gradient(from <angle>deg, <stops>)\n  Unsupported (will be rejected): \"circle at X% Y%\", \"ellipse at ...\", \"X% Y%\" position syntax, named colors (red/blue/...), hsl(), and numeric stops without a percent sign.\nText: <text size={24}>content here</text>\nInstance: <instance ref=\"Button\" variant=\"Size=Large\"/>\nSelf-closing: <line w=\"fill\" stroke=\"#E5E7EB\"/> (use line for dividers/separators; rect/ellipse for SMALL pure decoration with no children — page-level backgrounds belong on the parent frame's bg)\nArc/Ring: <ellipse w={120} h={120} arc=\"0 270\" fill=\"#4F46E5\"/> (arc=\"start end innerRadius?\" — innerRadius 0-1 makes a donut/ring)\nGrid layout: call help({ name: \"grid-layout\" }) for tracks, gaps, and when row/column is a better fit\nVariable binding: fill/bg/stroke accept qualified bare-name token strings (e.g. bg=\"$Theme/Bg/Surface\"). Object literals (fill={{variable_id:...}}) drop the binding silently — always use the string form.\n\nSwap an existing subtree: jsx({replaceId: \"<id>\", markup: \"...\"}) replaces the old node at the same parent and sibling index atomically, preserving position in one call. Markup must have a single root. Use jsx for tree creation; edit for property updates on known nodes.",
     "parameters": {
       "type": "object",
       "properties": {
@@ -335,7 +335,7 @@
   },
   {
     "name": "style",
-    "description": "Load a visual style preset — color tokens, typography, shape, depth. Use when picking a named aesthetic from the menu before generating new design.\n\nExample: style({ name: \"neon-cyber\" })",
+    "description": "Load a visual style preset as INSPIRATION — color tokens, typography, shape, depth. Treat as a reference library, not a cage: pick one wholesale, mix elements, or invent your own. You are not restricted to the menu.\n\nExample: style({ name: \"neon-cyber\" })",
     "parameters": {
       "type": "object",
       "properties": {
@@ -349,22 +349,6 @@
       ]
     }
   },
-  {
-    "name": "anatomy",
-    "description": "Load a component anatomy reference — structural blueprint of a UI component (parts, slots, hierarchy). Use before building complex components.\n\nExample: anatomy({ name: \"data-table\" })",
-    "parameters": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "The anatomy name exactly as it appears in the KNOWLEDGE LIBRARY menu — no \"anatomy:\" prefix, no quotes."
-        }
-      },
-      "required": [
-        "name"
-      ]
-    }
-  },
   {
     "name": "guideline",
     "description": "Load a page-type design guideline — layout patterns for landing pages, dashboards, login flows, forms, etc.\n\nExample: guideline({ name: \"form\" })",
@@ -793,7 +777,7 @@
   },
   {
     "name": "set_fill",
-    "description": "Set fill or background color on a node.\n\n  set_fill({node: \"1:2\", bg: \"#F5F5F5\"})\n  set_fill({node: \"1:2\", fill: \"#333333\"})\n  set_fill({node: \"1:2\", bg: \"linear-gradient(135deg, #8B5CF6 0%, #F97316 100%)\"})\n\n  // Batch — bulk paint update in one call:\n  set_fill({nodes: [{node: \"1:2\", bg: \"#FFF\"}, {node: \"1:3\", bg: \"#F5F5F5\"}]})\n\nfill = text color or shape fill. bg = frame background.\nFor stroke color, use set_stroke.\n\nAccepted color formats (for fill or bg):\n  hex                \"#FFF\", \"#F5F5F5\"\n  gradient string    \"linear-gradient(angle, #color stop%, ...)\" or \"radial-gradient(...)\"\n  variable token     qualified bare name \"$Surface/Card\"\n  transparent        \"transparent\" (bg only)",
+    "description": "Set fill or background color on a node.\n\n  set_fill({node: \"1:2\", bg: \"#F5F5F5\"})\n  set_fill({node: \"1:2\", fill: \"#333333\"})\n  set_fill({node: \"1:2\", bg: \"linear-gradient(135deg, #8B5CF6 0%, #F97316 100%)\"})\n\n  // Batch — bulk paint update in one call:\n  set_fill({nodes: [{node: \"1:2\", bg: \"#FFF\"}, {node: \"1:3\", bg: \"#F5F5F5\"}]})\n\nfill = text color or shape fill. bg = frame background.\nFor stroke color, use set_stroke.\n\nAccepted color formats (for fill or bg):\n  hex                \"#FFF\", \"#F5F5F5\"\n  gradient string    CSS-like subset, not full CSS:\n                       \"linear-gradient(<angle>deg, <#hex> <pos>%, ...)\"\n                       \"linear-gradient(to <direction>, ...)\"   directions: top/right/bottom/left + corners\n                       \"radial-gradient(<stops>)\"               centered, no position/shape modifiers\n                       \"radial-gradient(circle, <stops>)\"       circle shape only\n                       \"conic-gradient(from <angle>deg, ...)\"\n                     Rejected: \"circle at X% Y%\", \"ellipse at ...\", named colors, hsl().\n  variable token     qualified bare name \"$Surface/Card\"\n  transparent        \"transparent\" (bg only)",
     "parameters": {
       "type": "object",
       "properties": {
@@ -823,7 +807,7 @@
   },
   {
     "name": "set_stroke",
-    "description": "Set stroke (border) on a node.\n\n  set_stroke({node: \"1:2\", stroke: \"1 #E0E0E0\"})\n  set_stroke({node: \"1:2\", stroke: \"2 #333 inside\"})\n  set_stroke({node: \"1:2\", color: \"#E0E0E0\", weight: 1, align: \"inside\"})\n  set_stroke({node: \"1:2\", color: \"linear-gradient(90deg, #8B5CF6 0%, #F97316 100%)\", weight: 1.5, align: \"inside\"})\n\n  // Batch — bulk stroke update in one call:\n  set_stroke({nodes: [{node: \"1:2\", color: \"#E0E0E0\", weight: 1}, {node: \"1:3\", color: \"#333\", weight: 2}]})\n\nShorthand: \"weight color align\" (e.g. \"1 #E0E0E0 inside\"). Hex only in shorthand.\n\nAccepted color formats (for the explicit `color` field, not the shorthand):\n  hex                \"#E0E0E0\"\n  gradient string    \"linear-gradient(angle, #color stop%, ...)\" or \"radial-gradient(...)\"\n  variable token     qualified bare name \"$Border/Default\"\n\nTo bind a variable to the stroke color, use the explicit `color` field — the shorthand parser silently drops bare-name tokens.",
+    "description": "Set stroke (border) on a node.\n\n  set_stroke({node: \"1:2\", stroke: \"1 #E0E0E0\"})\n  set_stroke({node: \"1:2\", stroke: \"2 #333 inside\"})\n  set_stroke({node: \"1:2\", color: \"#E0E0E0\", weight: 1, align: \"inside\"})\n  set_stroke({node: \"1:2\", color: \"linear-gradient(90deg, #8B5CF6 0%, #F97316 100%)\", weight: 1.5, align: \"inside\"})\n\n  // Batch — bulk stroke update in one call:\n  set_stroke({nodes: [{node: \"1:2\", color: \"#E0E0E0\", weight: 1}, {node: \"1:3\", color: \"#333\", weight: 2}]})\n\nShorthand: \"weight color align\" (e.g. \"1 #E0E0E0 inside\"). Hex only in shorthand.\n\nAccepted color formats (for the explicit `color` field, not the shorthand):\n  hex                \"#E0E0E0\"\n  gradient string    CSS-like subset (see set_fill description for full grammar — same rules).\n                     Common: \"linear-gradient(<angle>deg, <#hex> <pos>%, ...)\", \"radial-gradient(<stops>)\".\n                     Rejected: \"circle at X% Y%\", named colors, hsl().\n  variable token     qualified bare name \"$Border/Default\"\n\nTo bind a variable to the stroke color, use the explicit `color` field — the shorthand parser silently drops bare-name tokens.",
     "parameters": {
       "type": "object",
       "properties": {
@@ -1216,5 +1200,34 @@
         "prompt"
       ]
     }
+  },
+  {
+    "name": "session_note",
+    "description": "Read / write your own session scratchpad. Persists across turns within one design session (\"New Design\" resets it). Notes are how state carries from this turn into the next — the next session loads them as context.\n\nActions:\n  action: \"read\"   → read({key}) returns the current value (empty string if unset)\n  action: \"write\"  → write({key, value}) replaces or deletes (pass value:\"\" to delete)\n  action: \"list\"   → list({}) returns [{key, chars}] for all existing notes\n\nSlots — FORWARD-LOOKING (what we plan / commit to):\n  - plan       — this turn's intent + step outline (write at turn start)\n  - decisions  — locked choices: style picked + reason, accent token, font scale, hero treatment, etc. (write BEFORE jsx)\n  - brand      — durable brand notes pulled from a project design.md (if user supplied one)\n  - todo       — TRULY unfinished work for the next turn (omit if everything shipped)\n\nSlots — BACKWARD-LOOKING (what happened, write AT TURN END):\n  - failures   — tool calls that failed this turn + how you worked around them.\n                 Example: \"jsx items='stretch' rejected (DSL valid: center|start|end|space-between|baseline); retried with 'center'.\"\n                 If a failure repeats a class you've seen before, name the class.\n  - gotchas    — validator warnings you noticed but chose not to fix + why.\n                 Example: \"4 LOW_CONTRAST on nav links (2.5:1) — deliberate for ambient-grey style; revisit if user complains.\"\n                 Also: magic numbers / hand-tuned positions and what motivated them.\n                 Example: \"Glow ellipses at (-180, 220) / (1060, 70) — placed half outside frame to bleed in.\"\n  - learnings  — surprises about this codebase / DSL / Figma API.\n                 Example: \"radial-gradient(circle at X% Y%) rejected — DSL only takes the simple form. Same trap as CSS-prior bleed elsewhere.\"\n\nREQUIRED behavior:\n  - First turn: write at least `decisions` BEFORE any jsx (commit-before-act).\n  - Every turn end: write at least ONE of `failures / gotchas / learnings` if ANY of these happened this turn:\n      • a tool call returned an error\n      • a tool call returned warnings you chose not to fix\n      • you hand-tuned a coordinate / size / color away from a value the model would have picked\n      • you found a DSL behavior that surprised you\n    \"All clean, no carry-over\" is almost never accurate — at least one backward slot belongs.\n  - jsx that uses a color / font / size should round-trip through `decisions` (token traceability).\n\nExamples:\n  session_note({action: \"write\", key: \"decisions\", value: \"Style: fintech-dark.\\nAccent: #3B82F6 (style.accent — NOT indigo).\\nFont: Space Grotesk display / Inter body.\\nHero treatment: split (overrides anatomy VERTICAL — desktop convention).\\nH1 size: 32 (style.display).\"})\n  session_note({action: \"write\", key: \"failures\", value: \"jsx #6 align='stretch' rejected (DSL valid: center|start|end|space-between|baseline) — retried with 'center'. Same CSS-prior class as gradient: model has CSS values that DSL doesn't accept.\"})\n  session_note({action: \"write\", key: \"gotchas\", value: \"8 LOW_CONTRAST warnings on nav links + secondary CTA (2.5:1 against dark bg). Left as-is — user prompt didn't require WCAG pass; flagging in case next iteration tightens contrast.\"})\n  session_note({action: \"write\", key: \"learnings\", value: \"layoutPositioning='absolute' children render correctly inside auto-layout frame, but parent needs clipsContent=true to suppress overflow on big glow ellipses.\"})\n  session_note({action: \"read\", key: \"decisions\"})\n  session_note({action: \"list\"})",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "read",
+            "write",
+            "list"
+          ],
+          "description": "read | write | list"
+        },
+        "key": {
+          "type": "string",
+          "description": "Note key. Required for read/write. Recommended slots: plan, decisions, brand, todo."
+        },
+        "value": {
+          "type": "string",
+          "description": "Markdown body for write. Pass \"\" to delete. Ignored for read/list."
+        }
+      },
+      "required": [
+        "action"
+      ]
+    }
   }
 ]

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "genable-mcp",
-  "version": "0.1.0",
-  "description": "The write-side complement to Figma's official MCP. Build, edit, and search Figma nodes from any MCP client (Claude Code, Cursor, etc.) via the Genable plugin.",
+  "version": "0.1.1",
+  "mcpName": "io.github.muse40007/genable-mcp",
+  "description": "Write-side MCP server for Figma — build, edit, restructure, and search Figma designs from Claude Code, Cursor, Cline, or any MCP client. Complements Figma's official MCP (which is read-only). 41 tools covering tree creation (JSX), variables/tokens, components, cross-page navigation, and visual verification.",
+  "author": "musec <muse40007@gmail.com>",
+  "bugs": {
+    "url": "https://github.com/muse40007/figma-ai-generator-dogfood/issues"
+  },
   "main": "dist/index.js",
   "bin": {
     "genable-mcp": "dist/index.js"
@@ -20,12 +25,28 @@
   },
   "keywords": [
     "figma",
+    "figma-mcp",
+    "figma-plugin",
+    "figma-api",
+    "figma-write",
     "mcp",
+    "mcp-server",
     "model-context-protocol",
-    "figma-plugin",
     "ai",
+    "ai-agent",
+    "llm",
+    "claude",
     "claude-code",
+    "claude-desktop",
     "cursor",
+    "cline",
+    "design-system",
+    "design-tokens",
+    "design-automation",
+    "ui-generation",
+    "generative-ui",
+    "jsx",
+    "anthropic",
     "genable"
   ],
   "engines": {