@obra-studio/figma-console-mcp 1.32.0 → 1.32.1
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.
package/README.md
CHANGED
|
@@ -7,6 +7,60 @@
|
|
|
7
7
|
|
|
8
8
|
> **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, **debugging**, and **bidirectional token sync**.
|
|
9
9
|
|
|
10
|
+
## ✨ What this fork adds: Obra Autodocs
|
|
11
|
+
|
|
12
|
+
Two tools that run the [Obra Autodocs](https://www.figma.com/community/plugin/1603778616137404487) generator **from inside the Desktop Bridge** — so your AI can document component-variant sets in one call, without you switching to the Autodocs plugin (which would drop the MCP connection):
|
|
13
|
+
|
|
14
|
+
- **`figma_generate_autodocs`** — draws the labeled variant grid (brackets + property labels) around a selected component set. Params: `nodeId`, `showGrid`, `color`, `showBooleanVisibility`, `showNestedInstances`, `fontFamily`.
|
|
15
|
+
- **`figma_remove_autodocs`** — removes it again.
|
|
16
|
+
|
|
17
|
+
Everything else is the full upstream [`figma-console-mcp`](https://github.com/southleft/figma-console-mcp) toolset.
|
|
18
|
+
|
|
19
|
+
### Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
claude mcp add figma-console -s user \
|
|
23
|
+
-e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true \
|
|
24
|
+
-- npx -y @obra-studio/figma-console-mcp@latest
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Or in your MCP client config (`~/.claude.json`, `claude_desktop_config.json`, `.cursor/mcp.json`, …):
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"mcpServers": {
|
|
32
|
+
"figma-console": {
|
|
33
|
+
"command": "npx",
|
|
34
|
+
"args": ["-y", "@obra-studio/figma-console-mcp@latest"],
|
|
35
|
+
"env": { "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE", "ENABLE_MCP_APPS": "true" }
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Already using `figma-console-mcp`? Switch in one line
|
|
42
|
+
|
|
43
|
+
This is a drop-in superset — same tools, same Desktop Bridge plugin, plus the autodocs tools. In your config, change the package name only:
|
|
44
|
+
|
|
45
|
+
```diff
|
|
46
|
+
- "args": ["-y", "figma-console-mcp@latest"],
|
|
47
|
+
+ "args": ["-y", "@obra-studio/figma-console-mcp@latest"],
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Keep your `env` (token, flags) as-is. **No plugin re-import needed** — the Desktop Bridge plugin is unchanged from upstream. Restart your MCP client and you'll have `figma_generate_autodocs` / `figma_remove_autodocs` alongside everything you already use.
|
|
51
|
+
|
|
52
|
+
### Example prompt
|
|
53
|
+
|
|
54
|
+
With the Desktop Bridge connected, just ask your agent in plain language. To document something that already exists:
|
|
55
|
+
|
|
56
|
+
> **"Document the Button component set with autodocs."**
|
|
57
|
+
|
|
58
|
+
Or build and document in one flow:
|
|
59
|
+
|
|
60
|
+
> **"Make a blue triangle, a red square and a purple hexagon. Give them logical properties (Shape / Color), generate all the variants, put them in a grid, then apply autodocs."**
|
|
61
|
+
|
|
62
|
+
The agent selects (or builds) the component set and calls `figma_generate_autodocs` — the labeled variant grid appears in Figma, brackets and property labels included, while the Desktop Bridge stays connected the whole time. To take it back off, ask it to **"remove the autodocs from that component set."**
|
|
63
|
+
|
|
10
64
|
> **🆕 The "not connected until restart" bug is fixed (v1.31.0):** The Desktop Bridge dropping its connection — and only recovering when you closed the plugin, restarted your MCP client, or killed ports by hand — was caused by **zombie MCP processes** squatting the WebSocket port range after a bad shutdown. v1.31.0 force-kills them (`SIGTERM` → `SIGKILL`), sweeps the range every 5 minutes, and adds a shutdown backstop so a server can't zombify in the first place. The plugin now reconnects itself (auto-reconnect watchdog + one-click **Reconnect** button) instead of needing a restart. **Update and re-import the plugin once** to get the fix. [See what's new →](CHANGELOG.md#1310---2026-06-05)
|
|
11
65
|
|
|
12
66
|
## What is this?
|
|
@@ -84,7 +138,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
|
|
|
84
138
|
|
|
85
139
|
**Claude Code (CLI):**
|
|
86
140
|
```bash
|
|
87
|
-
claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
|
|
141
|
+
claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y @obra-studio/figma-console-mcp@latest
|
|
88
142
|
```
|
|
89
143
|
|
|
90
144
|
**Cursor / Windsurf / Claude Desktop:**
|
|
@@ -96,7 +150,7 @@ Add to your MCP config file (see [Where to find your config file](#-where-to-fin
|
|
|
96
150
|
"mcpServers": {
|
|
97
151
|
"figma-console": {
|
|
98
152
|
"command": "npx",
|
|
99
|
-
"args": ["-y", "figma-console-mcp@latest"],
|
|
153
|
+
"args": ["-y", "@obra-studio/figma-console-mcp@latest"],
|
|
100
154
|
"env": {
|
|
101
155
|
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
|
|
102
156
|
"ENABLE_MCP_APPS": "true"
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"autodocs-tools.d.ts","sourceRoot":"","sources":["../../src/core/autodocs-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;
|
|
1
|
+
{"version":3,"file":"autodocs-tools.d.ts","sourceRoot":"","sources":["../../src/core/autodocs-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmFpE;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,QA2IvC"}
|
|
@@ -42,15 +42,22 @@ if (__pg && figma.currentPage !== __pg) await figma.setCurrentPageAsync(__pg);
|
|
|
42
42
|
figma.currentPage.selection = [__target];
|
|
43
43
|
`;
|
|
44
44
|
}
|
|
45
|
-
function buildGenerateScript(opts, nodeId) {
|
|
45
|
+
function buildGenerateScript(opts, nodeId, arrange = true) {
|
|
46
46
|
const entry = `${FONT_PRELUDE}${selectSnippet(nodeId)}
|
|
47
47
|
const __cs = getComponentSet();
|
|
48
48
|
const __standalone = __cs ? null : getStandaloneComponent();
|
|
49
49
|
const __node = __cs || __standalone;
|
|
50
50
|
if (!__node) return { error: 'No component set or component selected. Pass nodeId or select one in Figma.' };
|
|
51
|
+
// Auto-tidy: re-space variants uniformly (40px) and hug the set frame before documenting.
|
|
52
|
+
// Uses the plugin's "quick align" (groupifyQuickAlign); only meaningful for component sets.
|
|
53
|
+
let __arranged = false;
|
|
54
|
+
if (__cs && ${arrange ? "true" : "false"}) {
|
|
55
|
+
try { await groupifyQuickAlign({ spacing: 40 }); __arranged = true; }
|
|
56
|
+
catch (e) { /* tidy is best-effort — still document if it fails */ }
|
|
57
|
+
}
|
|
51
58
|
const __opts = Object.assign({ showGrid: __standalone ? false : true }, ${JSON.stringify(opts)});
|
|
52
59
|
await generate(__opts);
|
|
53
|
-
return { generated: true, target: __node.name, type: __node.type, nodeId: __node.id };
|
|
60
|
+
return { generated: true, arranged: __arranged, target: __node.name, type: __node.type, nodeId: __node.id };
|
|
54
61
|
`;
|
|
55
62
|
return `${AUTODOCS_BODY}\n${entry}`;
|
|
56
63
|
}
|
|
@@ -74,11 +81,18 @@ return { removed: true, target: __node.name, nodeId: __node.id };
|
|
|
74
81
|
export function registerAutodocsTools(server, getDesktopConnector) {
|
|
75
82
|
server.tool("figma_generate_autodocs", `Generate Obra Autodocs documentation (labeled variant grid with brackets/labels) around a component set or component — the same output as the Obra Autodocs plugin's "Generate docs" command, but run inside the Desktop Bridge so the connection stays alive (running the plugin itself would disconnect the Bridge).
|
|
76
83
|
|
|
77
|
-
Select the target component set first, or pass its nodeId. Re-running regenerates (replaces) existing docs. Use figma_remove_autodocs to remove them. After generating, screenshot with figma_capture_screenshot to verify
|
|
84
|
+
Select the target component set first, or pass its nodeId. Re-running regenerates (replaces) existing docs. Use figma_remove_autodocs to remove them. After generating, screenshot with figma_capture_screenshot to verify.
|
|
85
|
+
|
|
86
|
+
By default it first tidies the component set — re-spacing every variant uniformly (40px) and hugging the set frame — via the plugin's "quick align", so the docs are generated on a clean grid. Set arrange:false to skip the tidy and document the set exactly as-is.`, {
|
|
78
87
|
nodeId: z
|
|
79
88
|
.string()
|
|
80
89
|
.optional()
|
|
81
90
|
.describe("Component set / component node id to document. If omitted, uses the current selection."),
|
|
91
|
+
arrange: z
|
|
92
|
+
.boolean()
|
|
93
|
+
.optional()
|
|
94
|
+
.default(true)
|
|
95
|
+
.describe("Tidy the component set before documenting: uniform 40px variant spacing + hug the set frame (plugin 'quick align'). Default true. Set false to document as-is. Ignored for standalone components."),
|
|
82
96
|
showGrid: z
|
|
83
97
|
.boolean()
|
|
84
98
|
.optional()
|
|
@@ -107,14 +121,14 @@ Select the target component set first, or pass its nodeId. Re-running regenerate
|
|
|
107
121
|
.optional()
|
|
108
122
|
.default(60000)
|
|
109
123
|
.describe("Execution timeout in ms (default 60000). Large variant sets take longer."),
|
|
110
|
-
}, async ({ nodeId, showGrid, color, showBooleanVisibility, showNestedInstances, fontFamily, timeout }) => {
|
|
124
|
+
}, async ({ nodeId, arrange, showGrid, color, showBooleanVisibility, showNestedInstances, fontFamily, timeout }) => {
|
|
111
125
|
try {
|
|
112
126
|
const opts = { showGrid, showBooleanVisibility, showNestedInstances };
|
|
113
127
|
if (color)
|
|
114
128
|
opts.color = color;
|
|
115
129
|
if (fontFamily)
|
|
116
130
|
opts.fontFamily = fontFamily;
|
|
117
|
-
const code = buildGenerateScript(opts, nodeId);
|
|
131
|
+
const code = buildGenerateScript(opts, nodeId, arrange);
|
|
118
132
|
const connector = await getDesktopConnector();
|
|
119
133
|
const result = await connector.executeCodeViaUI(code, Math.min(timeout, 120000));
|
|
120
134
|
return {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"autodocs-tools.js","sourceRoot":"","sources":["../../src/core/autodocs-tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAC;AAEnF,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAElE;;;;;;;;;;;;GAYG;AAEH,wEAAwE;AACxE,gFAAgF;AAChF,+EAA+E;AAC/E,MAAM,YAAY,GAAG;;;;;;;;;;CAUpB,CAAC;AAEF,8EAA8E;AAC9E,oEAAoE;AACpE,SAAS,aAAa,CAAC,MAAe;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO;gDACwC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;sDAChB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;;;;CAI3E,CAAC;AACF,CAAC;AAED,SAAS,mBAAmB,CAAC,IAA6B,EAAE,MAAe;
|
|
1
|
+
{"version":3,"file":"autodocs-tools.js","sourceRoot":"","sources":["../../src/core/autodocs-tools.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@obra-studio/figma-console-mcp",
|
|
3
|
-
"version": "1.32.
|
|
3
|
+
"version": "1.32.1",
|
|
4
4
|
"description": "Obra Studio fork of figma-console-mcp (by Southleft) adding Obra Autodocs: generate labeled component-variant documentation from inside the Desktop Bridge. The most comprehensive MCP server for Figma — design tokens, variables, components, write tools, version history diff, accessibility audits, FigJam, Slides, and more.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/local.js",
|