tellfigma 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +103 -70
  2. package/dist/index.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,28 +1,36 @@
1
- # tellfigma
1
+ # tellfigma 🎨
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/tellfigma.svg)](https://www.npmjs.com/package/tellfigma)
4
4
  [![npm downloads](https://img.shields.io/npm/dm/tellfigma.svg)](https://www.npmjs.com/package/tellfigma)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
6
  [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
7
7
 
8
- <!-- 🎬 Add a demo GIF here — this is the #1 thing that makes repos go viral on GitHub/Twitter/Reddit -->
8
+ <!-- 🎬 demo GIF coming soon — this is where the magic happens -->
9
9
  <!-- ![tellfigma demo](https://tellfigma.com/demo.gif) -->
10
10
 
11
- **MCP server that gives AI full control over Figma. Create and edit designs from natural language.**
11
+ **Your AI just learned how to use Figma. You're welcome.**
12
12
 
13
- > Figma's MCP reads designs. **tellfigma writes them.**
13
+ Every other Figma AI tool out there? Read-only. They can *look* at your designs. Wow, incredible, so can I. 👀
14
14
 
15
- One command. No Figma API key. No plugin. Works with Claude Desktop, Claude Code, VS Code Copilot, Cursor, Windsurf — any MCP client.
15
+ tellfigma actually **writes** to Figma. Creates frames. Sets colors. Builds full pages. Takes screenshots. The whole damn thing.
16
16
 
17
17
  ```bash
18
18
  npx tellfigma
19
19
  ```
20
20
 
21
+ That's it. That's the setup. I've seen longer Starbucks orders. ☕
22
+
21
23
  ---
22
24
 
23
- ## Why tellfigma?
25
+ ## 🤔 Why does this exist?
26
+
27
+ Because I got tired of copying hex codes between Figma and my code editor like some kind of unpaid intern.
28
+
29
+ Every Figma MCP tool I found was either:
30
+ - **Read-only** — cool, thanks, very helpful, love that for me 🙃
31
+ - **Plugin sandbox** — great, now I need a plugin + WebSocket + MCP server + a prayer
24
32
 
25
- Every other Figma AI tool is **read-only** or **sandboxed**. tellfigma is the only MCP server that uses **Chrome DevTools Protocol** to give AI full read/write access to Figma's Plugin API — the same API that Figma plugins use, but without the sandbox.
33
+ tellfigma skips all that nonsense. It uses **Chrome DevTools Protocol** to talk directly to Figma's Plugin API. Same API the plugins use, minus the sandbox, minus the setup headaches.
26
34
 
27
35
  ```
28
36
  ┌─────────────────┐ MCP (stdio) ┌──────────┐ Chrome DevTools ┌──────────┐
@@ -33,29 +41,41 @@ Every other Figma AI tool is **read-only** or **sandboxed**. tellfigma is the on
33
41
  └─────────────────┘
34
42
  ```
35
43
 
36
- ### The AI + Figma Loop
44
+ ### The full AI + Figma loop 🔄
37
45
 
38
46
  ```
39
- ① tellfigma AI ──────► Figma "Design a dashboard"
40
- ② Figma MCP Server Figma ──────► Code "Build this design"
41
- ③ Claude Code to Figma Code ──────► Figma "Capture this UI"
47
+ Your Code Figma
48
+ │ ▲
49
+ │ reads tailwind, │ creates & edits
50
+ │ components, tokens │ designs live
51
+ ▼ │
52
+ AI Agent ─────────────────────┘
53
+ ▲ │
54
+ │ screenshots, │
55
+ │ inspect, variables │
56
+ └───────────────────────────┘
57
+ reads back
42
58
  ```
43
59
 
44
- tellfigma is **step ①** — the missing piece that lets AI create and modify Figma designs from scratch.
60
+ tellfigma goes **both ways**. It writes designs, reads them back, takes screenshots, inspects nodes — and if you're in VS Code/Cursor/Claude Code, it reads your codebase first so designs match your actual tokens.
61
+
62
+ Other tools in the ecosystem:
63
+ - **Figma MCP Server** — reads designs for code generation (read-only)
64
+ - **Claude Code to Figma** — captures running UI as Figma layers (one-time import)
45
65
 
46
66
  ---
47
67
 
48
- ## Quick Start
68
+ ## 🚀 Quick Start
49
69
 
50
- ### 1. Run tellfigma
70
+ ### 1. Run it
51
71
 
52
72
  ```bash
53
73
  npx tellfigma
54
74
  ```
55
75
 
56
- A Chrome window opens. Sign into Figma and open a design file.
76
+ Chrome opens. Sign into Figma. Open a design file. Done.
57
77
 
58
- ### 2. Add to your AI app
78
+ ### 2. Hook it up to your AI
59
79
 
60
80
  <details>
61
81
  <summary><strong>Claude Desktop</strong></summary>
@@ -82,6 +102,8 @@ Restart Claude Desktop.
82
102
  ```bash
83
103
  claude mcp add tellfigma -- npx -y tellfigma
84
104
  ```
105
+
106
+ That's literally it.
85
107
  </details>
86
108
 
87
109
  <details>
@@ -136,59 +158,66 @@ Add to `~/.windsurf/mcp.json`:
136
158
  ```
137
159
  </details>
138
160
 
139
- ### 3. Start designing
161
+ ### 3. Tell it what to make
140
162
 
141
- Tell your AI what to create:
163
+ Just talk to your AI like a normal human:
142
164
 
143
165
  > "Design a modern login page with email and password fields, a sign-in button, and a 'Forgot password?' link"
144
166
 
145
- > "Take a screenshot and give me feedback on the spacing and hierarchy"
167
+ > "Take a screenshot and roast the spacing"
146
168
 
147
- > "Find all text nodes on this page and make them use Inter Semi Bold"
169
+ > "Find all text nodes on this page and make them Inter Semi Bold"
148
170
 
149
- > "Create a card component with a subtle shadow, 16px padding, and 12px border radius"
171
+ > "Create a card component with a subtle shadow, 16px padding, and 12px corners"
172
+
173
+ It just... does it. In Figma. Live. 🤯
150
174
 
151
175
  ---
152
176
 
153
- ## Features
177
+ ## 🛠️ What's under the hood
154
178
 
155
179
  ### 16 MCP Tools
156
180
 
157
181
  | Tool | What it does |
158
182
  |------|-------------|
159
- | `execute_figma_code` | Run any JavaScript with full `figma` Plugin API access |
160
- | `take_screenshot` | Capture what's on screen — the AI sees your canvas |
183
+ | `execute_figma_code` | Run any JS with full `figma` Plugin API access — the big one 🔥 |
184
+ | `take_screenshot` | Captures what's on screen — the AI actually *sees* your canvas |
161
185
  | `read_selection` | Deep inspect fills, strokes, effects, layout, fonts, children |
162
186
  | `get_page_context` | Page name, selection, top-level frames |
163
- | `select_nodes` | Find and select by name or type (FRAME, TEXT, COMPONENT, etc.) |
164
- | `list_components` | List all components and component sets |
165
- | `get_styles` | List local paint, text, and effect styles |
166
- | `get_variables` | List design tokens — colors, numbers, strings |
187
+ | `select_nodes` | Find and select by name or type |
188
+ | `list_components` | All components and component sets |
189
+ | `get_styles` | Local paint, text, and effect styles |
190
+ | `get_variables` | Design tokens — colors, numbers, strings |
167
191
  | `export_node` | Export as PNG, SVG, JPG, or PDF |
168
- | `duplicate_node` | Clone with offset and count for grids |
169
- | `undo` / `redo` | Roll back or redo with configurable steps |
170
- | `zoom_to` | Zoom to selection, all nodes, or a specific node |
171
- | `navigate` | Open a URL (e.g., a specific Figma file) |
172
- | `click` | Click at coordinates on the page |
192
+ | `duplicate_node` | Clone with offset — great for grids |
193
+ | `undo` / `redo` | Oops button, but for AI |
194
+ | `zoom_to` | Zoom to selection, all nodes, or a specific one |
195
+ | `navigate` | Open a URL (specific Figma files, etc.) |
196
+ | `click` | Click coordinates on the page |
173
197
  | `get_snapshot` | Accessibility tree for understanding UI structure |
174
198
 
175
- ### Built-in Design Intelligence
199
+ ### Built-in design smarts 🧠
200
+
201
+ tellfigma doesn't just blindly execute code. The AI gets a massive system prompt with:
176
202
 
177
- The AI receives a comprehensive system prompt with:
203
+ - **Full Figma Plugin API reference** — every method, property, and gotcha
204
+ - **Design recipes** — buttons, cards, inputs, navbars ready to compose
205
+ - **Design system defaults** — 8px spacing scale, color ramps, type scale, shadow presets
206
+ - **Error recovery** — "hey you forgot to load the font" hints that save you 10 minutes of debugging
207
+ - **Auto-reconnect** — connection drops? No drama. Picks right back up.
178
208
 
179
- - **Figma Plugin API reference** — every method, property, and pattern
180
- - **Design recipes** — buttons, cards, inputs, navbars the AI can compose
181
- - **Design system defaults** — 8px spacing scale, color palette, type scale, shadows
182
- - **Smart error recovery** — hints for common Figma API mistakes (fonts, layout ordering, null nodes)
183
- - **Auto-reconnect** — drops CDP? Picks back up on the next tool call
209
+ ### 🎯 Design from your actual codebase
184
210
 
185
- ### Design From Your Codebase
211
+ This one's nuts. If you're in VS Code, Cursor, or Claude Code, the AI already has your project files. So you can say:
186
212
 
187
- Using VS Code, Cursor, or Claude Code? The AI already has your project files. Ask it to design screens that match your actual codebase:
213
+ > "Design a settings page that matches my app"
188
214
 
189
- > "Design a settings page that matches my app's design system"
215
+ And it will:
216
+ 1. Read your `tailwind.config.ts`, `globals.css`, component files
217
+ 2. Pull your **exact** colors, fonts, spacing, radius, shadows
218
+ 3. Design in Figma using YOUR tokens — not some generic blue from 2019
190
219
 
191
- It reads your `tailwind.config.ts`, `globals.css`, component files — then creates Figma designs using your exact colors, fonts, spacing, and patterns. Works with **Tailwind**, **shadcn/ui**, **MUI**, **Chakra**, and any component library.
220
+ Works with **Tailwind**, **shadcn/ui**, **MUI**, **Chakra**, whatever you're running. No config. No flags. Your editor already knows your project.
192
221
 
193
222
  ```
194
223
  ┌──────────┐ reads ┌───────────┐ designs ┌────────┐
@@ -200,30 +229,34 @@ It reads your `tailwind.config.ts`, `globals.css`, component files — then crea
200
229
 
201
230
  ---
202
231
 
203
- ## How It Works
232
+ ## ⚙️ How it actually works
204
233
 
205
- 1. `npx tellfigma` launches Chrome with `--remote-debugging-port=9222` and a dedicated profile (`~/.tellfigma-chrome-profile`)
206
- 2. The MCP server starts on stdio
207
- 3. When an AI calls `execute_figma_code`, tellfigma connects via CDP, finds the Figma tab, and runs JavaScript through `Runtime.evaluate`
208
- 4. Screenshots use `Page.captureScreenshot` — real browser screenshots, not API renders
209
- 5. The AI receives a system prompt with the full Figma Plugin API reference
234
+ Not magic — just clever plumbing:
210
235
 
211
- Chrome runs with its own profile so it doesn't interfere with your normal browsing.
236
+ 1. `npx tellfigma` launches Chrome with `--remote-debugging-port=9222` and its own profile (`~/.tellfigma-chrome-profile`) so it doesn't mess with your regular browser
237
+ 2. MCP server starts on stdio
238
+ 3. AI calls `execute_figma_code` → tellfigma connects via CDP → finds the Figma tab → runs JS through `Runtime.evaluate`
239
+ 4. Screenshots use `Page.captureScreenshot` — real browser screenshots, not some janky API render
240
+ 5. AI gets a loaded system prompt with the full Plugin API reference
241
+
242
+ Your normal Chrome stays untouched. Pinky promise. 🤙
212
243
 
213
244
  ---
214
245
 
215
- ## Compared to Alternatives
246
+ ## 📊 tellfigma vs. everything else
216
247
 
217
248
  | | tellfigma | Figma MCP (Dev Mode) | Claude Code to Figma | Plugin + WebSocket |
218
249
  |---|---|---|---|---|
219
- | **Creates designs** | ✅ | ❌ Read-only | ❌ Captures existing UI | ✅ |
220
- | **Edits designs** | ✅ | ❌ | ❌ One-time import | ✅ |
250
+ | **Creates designs** | ✅ yep | ❌ read-only | ❌ captures existing UI | ✅ |
251
+ | **Edits designs** | ✅ | ❌ | ❌ one-time import | ✅ |
221
252
  | **Real screenshots** | ✅ | ✅ | N/A | ❌ |
222
- | **Any MCP client** | ✅ | ✅ | ❌ Claude only | ❌ |
223
- | **No API key** | ✅ | ❌ Token required | ❌ OAuth required | ✅ |
253
+ | **Any MCP client** | ✅ all of them | ✅ | ❌ Claude only | ❌ |
254
+ | **No API key** | ✅ zero keys | ❌ token required | ❌ OAuth required | ✅ |
224
255
  | **No plugin install** | ✅ | ❌ | ❌ | ❌ |
225
- | **Full Plugin API** | ✅ | ❌ | ❌ | Partial |
226
- | **Setup** | `npx tellfigma` | Config + token | Server + OAuth | Plugin + WS + MCP |
256
+ | **Full Plugin API** | ✅ | ❌ | ❌ | partial |
257
+ | **Setup** | `npx tellfigma` | config + token | server + OAuth | plugin + WS + MCP |
258
+
259
+ Yeah. It's like that. 😎
227
260
 
228
261
  ---
229
262
 
@@ -238,31 +271,31 @@ npx tellfigma [options]
238
271
 
239
272
  ## Requirements
240
273
 
241
- - **Node.js 18+**
242
- - **Google Chrome** (or Chromium)
243
- - Any MCP-compatible AI app
274
+ - **Node.js 18+** — you probably already have this
275
+ - **Google Chrome** (or Chromium) — you definitely already have this
276
+ - Any MCP-compatible AI app — Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, etc.
244
277
 
245
- ## Troubleshooting
278
+ ## 🔧 Troubleshooting
246
279
 
247
- **"No Figma tab found"** — Open a Figma design file in the Chrome window that tellfigma launched. Make sure the URL contains `figma.com/design` or `figma.com/file`.
280
+ **"No Figma tab found"** — Open a Figma design file in the Chrome window that tellfigma launched. Needs `figma.com/design` or `figma.com/file` in the URL.
248
281
 
249
- **"Chrome debug port didn't become available"** — Another process may be using port 9222. Try `npx tellfigma --port 9333` or close other Chrome debug instances.
282
+ **"Chrome debug port didn't become available"** — Something else is hogging port 9222. Try `npx tellfigma --port 9333` or kill the squatter.
250
283
 
251
- **"Connection lost, reconnecting..."** — This is normal. tellfigma auto-reconnects on the next tool call. If it persists, reload the Figma tab.
284
+ **"Connection lost, reconnecting..."** — Totally normal. Auto-reconnects on the next tool call. If it keeps happening, reload the Figma tab.
252
285
 
253
- **Font errors** — Always call `await figma.loadFontAsync({ family, style })` before setting `.characters` on a text node. Inter "Semi Bold" has a space (not "SemiBold").
286
+ **Font errors** — Always `await figma.loadFontAsync({ family, style })` before setting text. And it's `"Semi Bold"` with a space, not `"SemiBold"`. Yeah, that one gets everyone. 🫠
254
287
 
255
- **Code executed but nothing appeared** — Make sure you're calling `figma.currentPage.appendChild(node)` after creating frames/shapes. New nodes aren't visible until appended.
288
+ **Code ran but nothing showed up** — You probably forgot `figma.currentPage.appendChild(node)`. New nodes are invisible until you append them. Classic.
256
289
 
257
290
  ---
258
291
 
259
- ## Contributing
292
+ ## 🤝 Contributing
260
293
 
261
- PRs welcome. Please open an issue first for major changes.
294
+ PRs welcome. Open an issue first for big changes so we don't step on each other.
262
295
 
263
296
  ## License
264
297
 
265
- MIT — [Directive Labs](https://directivelabs.com)
298
+ MIT — built by [Directive Labs](https://directivelabs.com) ⚡
266
299
 
267
300
  ---
268
301
 
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import { registerTools } from './tools.js';
11
11
  // ---- MCP Server Setup ----
12
12
  const server = new McpServer({
13
13
  name: 'tellfigma',
14
- version: '0.2.0',
14
+ version: '0.2.2',
15
15
  });
16
16
  // Register all prompts/resources and tools
17
17
  registerPrompts(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tellfigma",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "MCP server that gives AI apps (Claude, Cursor, VS Code Copilot, Windsurf) full control over Figma via Chrome DevTools Protocol. Create and edit designs from natural language. No plugin, no API key — just npx tellfigma.",
5
5
  "type": "module",
6
6
  "bin": {