figma-coder-mcp 0.2.1 → 0.3.0
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/LICENSE +21 -21
- package/README.md +124 -72
- package/dist/bin.js +920 -142
- package/package.json +5 -5
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 GoldynLabs
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 GoldynLabs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,112 +1,164 @@
|
|
|
1
1
|
# figma-coder-mcp
|
|
2
2
|
|
|
3
|
-
MCP server
|
|
4
|
-
|
|
3
|
+
> **Figma Coder** is an MCP server and CLI that turns any Figma frame into
|
|
4
|
+
> pixel-faithful, self-contained HTML, right inside your AI coding agent. No
|
|
5
|
+
> screenshots, no rebuilding by hand. Works with any Figma account: no paid
|
|
6
|
+
> plan, completely free.
|
|
7
|
+
|
|
8
|
+
Homepage: **https://figmacoder.sitenow.cloud**
|
|
9
|
+
|
|
10
|
+
`figma-coder-mcp` is one program that is two things at once: an MCP server your
|
|
11
|
+
AI agent talks to, and a command-line tool you can run in a terminal. It runs in
|
|
12
|
+
two modes and picks one automatically: with a Figma token it converts locally on
|
|
13
|
+
your machine; without one it uses the hosted backend. Both modes produce
|
|
14
|
+
identical output.
|
|
5
15
|
|
|
6
16
|
```bash
|
|
7
|
-
npm i -g figma-coder-mcp # or: npx figma-coder-mcp
|
|
8
|
-
figma-coder-mcp set-token figd_xxx
|
|
17
|
+
npm i -g figma-coder-mcp # or run on demand with: npx figma-coder-mcp
|
|
9
18
|
```
|
|
10
19
|
|
|
11
|
-
|
|
20
|
+
## Setup
|
|
21
|
+
|
|
22
|
+
Setup is two steps. Step 1 (required): add the server to your project's
|
|
23
|
+
`.mcp.json`. Step 2: give it access to Figma using either a personal access token
|
|
24
|
+
(local mode) or by signing in with Figma (remote mode).
|
|
12
25
|
|
|
13
|
-
|
|
14
|
-
[`@figma-to-code/core`](../packages/figma-core) directly. **No backend needed** —
|
|
15
|
-
works even if the API server is down. Just provide a Figma PAT.
|
|
16
|
-
- **remote**: delegates to a running `figma-to-html-api` over HTTP (`FIGMA_MCP_API`).
|
|
17
|
-
Authenticate with **OAuth** (`figma-coder-mcp login`) so no personal access
|
|
18
|
-
token lives in your config — the backend holds the OAuth secret.
|
|
26
|
+
### Local mode — personal access token
|
|
19
27
|
|
|
20
|
-
|
|
21
|
-
|
|
28
|
+
Create a personal access token (`figd_…`) in your Figma account settings
|
|
29
|
+
(Settings → Security → Personal access tokens:
|
|
30
|
+
https://www.figma.com/settings). Add the server to `.mcp.json` with the token in
|
|
31
|
+
the inline `env`:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"mcpServers": {
|
|
36
|
+
"figma": {
|
|
37
|
+
"command": "npx",
|
|
38
|
+
"args": ["-y", "figma-coder-mcp"],
|
|
39
|
+
"env": { "FIGMA_PAT": "figd_xxx" }
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
```
|
|
22
44
|
|
|
23
|
-
|
|
45
|
+
Prefer not to keep the token in the project file? Run
|
|
46
|
+
`npx figma-coder-mcp set-token figd_xxx` to store it once in the global settings
|
|
47
|
+
file instead, and leave the `env` out.
|
|
24
48
|
|
|
25
|
-
|
|
26
|
-
|---|---|---|
|
|
27
|
-
| Setup | `set-api <url>` then `login` (browser) | `set-token figd_xxx` (or `FIGMA_PAT`) |
|
|
28
|
-
| Needs the backend? | Yes | No — fully local |
|
|
29
|
-
| Survives backend outage? | No | **Yes** |
|
|
30
|
-
| Token in your config? | No | Yes (PAT) |
|
|
49
|
+
### Remote mode — sign in with Figma (OAuth)
|
|
31
50
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
figma-coder-mcp login # opens the browser; token is stored for you
|
|
51
|
+
Add the server to `.mcp.json` with no token, then run
|
|
52
|
+
`npx figma-coder-mcp login` once to authorize via the hosted backend. The login
|
|
53
|
+
is stored globally; no token lives in your project.
|
|
36
54
|
|
|
37
|
-
|
|
38
|
-
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"figma": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["-y", "figma-coder-mcp"]
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
39
64
|
```
|
|
40
65
|
|
|
41
|
-
`login` opens
|
|
42
|
-
hands back over a one-shot
|
|
43
|
-
`~/.figma-mcp/
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
66
|
+
`login` opens the authorize page in your browser, captures the token the backend
|
|
67
|
+
hands back over a one-shot loopback server, and stores it in
|
|
68
|
+
`~/.figma-mcp/settings.json`. The access token is refreshed silently when it
|
|
69
|
+
expires; re-run `login` only if the refresh token itself is revoked. Set
|
|
70
|
+
`FIGMA_MCP_NO_BROWSER=1` on headless/SSH hosts to print the URL instead of
|
|
71
|
+
launching a browser.
|
|
72
|
+
|
|
73
|
+
Then ask your agent: **"Convert this Figma frame to HTML."**
|
|
47
74
|
|
|
48
75
|
## Tools
|
|
49
76
|
|
|
77
|
+
Once the server is registered, your agent can call these two tools. There is
|
|
78
|
+
nothing to configure: just ask in plain language and the agent picks the right
|
|
79
|
+
one.
|
|
80
|
+
|
|
50
81
|
| Tool | What it does |
|
|
51
82
|
|------|--------------|
|
|
52
|
-
| `get_figma_data` | Returns
|
|
53
|
-
| `convert_figma_to_html` | Produces finished, self-contained **HTML + Tailwind** (assets
|
|
83
|
+
| `get_figma_data` | Returns a **compact, token-efficient design tree** for the agent to reason about and generate code from. Repeated styles are deduped into `globalVars.styles` (each node carries a short `style` ref), per-node position/size stays inline as `box`, and repeated subtrees are hoisted into `elements` (occurrences become `{ref}`) — typically 30–45% smaller than the raw per-node CSS. Small results come back inline; large ones are written to a JSON file and summarised. |
|
|
84
|
+
| `convert_figma_to_html` | Produces finished, self-contained **HTML + Tailwind**. Asset inlining is **off by default** (placeholders shown for images/vectors); pass `assets:true` to render & inline them. The HTML is written to a file and a compact summary + path is returned to keep the agent's context small. Args: `mode` (`tailwind`/`inline`), `document`, `assets`, `assetScale`, `round`, `llm`, `outFile`. |
|
|
54
85
|
|
|
55
|
-
|
|
86
|
+
### Conversion fidelity
|
|
56
87
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
88
|
+
The deterministic converter preserves a lot of Figma intent automatically:
|
|
89
|
+
|
|
90
|
+
- **Auto-layout → responsive flex**: consumes `layoutSizing` (FILL → `flex-1`/`self-stretch`, HUG → content-sized, FIXED → px) plus gap, padding, alignment and min/max — auto-layout frames come out responsive, not pixel-frozen. Non-auto-layout frames stay exact-positioned.
|
|
91
|
+
- **Images**: image fills honor `scaleMode` (FILL/FIT/TILE/STRETCH) and crop transforms. Icon/illustration groups collapse into a single SVG (fewer renders); image-filled ellipses become CSS circles.
|
|
92
|
+
- **Styles**: per-corner radius, stroke alignment (OUTSIDE/CENTER via `outline`), per-side borders, all gradient types (linear/radial/conic), blend modes, shadows, backdrop blur, opacity.
|
|
93
|
+
- **Text**: font, line-height, letter-spacing, alignment (incl. vertical), decoration/case, gradient text, and **mixed-style runs** (a bold/colored word becomes its own `<span>`).
|
|
94
|
+
- **`round`** (on by default): snaps on-grid values to idiomatic Tailwind tokens (`p-4`, `gap-6`, `rounded-lg`, `text-2xl`, `font-bold`); off-grid values stay exact, so it never silently changes real sizes. Pass `round:false` (or `--no-round` on the CLI) for exact arbitrary values everywhere.
|
|
61
95
|
|
|
62
|
-
|
|
63
|
-
node figma-mcp/dist/bin.js set-token figd_xxx
|
|
64
|
-
# …or set it per-process: FIGMA_PAT=figd_xxx
|
|
96
|
+
## Configuration
|
|
65
97
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
98
|
+
A setting can come from three places. When the same setting appears in more than
|
|
99
|
+
one, the higher one wins: **command flags > environment variables > stored
|
|
100
|
+
`settings.json`**.
|
|
69
101
|
|
|
70
|
-
|
|
71
|
-
node figma-mcp/dist/bin.js status
|
|
72
|
-
```
|
|
102
|
+
Settings live in two places:
|
|
73
103
|
|
|
74
|
-
|
|
104
|
+
- **`.mcp.json`** (project scope): how your agent launches the server, plus an
|
|
105
|
+
optional inline `env` (such as `FIGMA_PAT`). Only applies to this project.
|
|
106
|
+
- **`~/.figma-mcp/settings.json`** (global scope): your stored Figma token or
|
|
107
|
+
OAuth login, written by `set-token` / `login`. Shared by every project. You
|
|
108
|
+
only have this file if you run `set-token` or `login`.
|
|
75
109
|
|
|
76
|
-
|
|
110
|
+
The global file mirrors the `env` block of a `.mcp.json` — user-facing values sit
|
|
111
|
+
under `env`, keyed by the same names as the environment variables, so you can
|
|
112
|
+
edit it by hand:
|
|
77
113
|
|
|
78
114
|
```json
|
|
79
115
|
{
|
|
80
|
-
"
|
|
81
|
-
"
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
116
|
+
"env": {
|
|
117
|
+
"FIGMA_PAT": "figd_xxx",
|
|
118
|
+
"FIGMA_MCP_API": "https://figmacoder-api.sitenow.cloud",
|
|
119
|
+
"FIGMA_MCP_TOKEN": "<oauth access token>"
|
|
120
|
+
},
|
|
121
|
+
"refreshToken": "<oauth refresh token>",
|
|
122
|
+
"apiTokenExpiresAt": 1735689600000
|
|
87
123
|
}
|
|
88
124
|
```
|
|
89
125
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
## One-off CLI (no agent)
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
figma-coder-mcp convert "https://www.figma.com/design/<key>/Title?node-id=1-23"
|
|
96
|
-
figma-coder-mcp convert <fileKey> --node 1:23 --no-assets --out page.html
|
|
97
|
-
figma-coder-mcp data <fileKey> --node 1:23
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
## Configuration
|
|
126
|
+
Environment variables:
|
|
101
127
|
|
|
102
128
|
| Var | Meaning |
|
|
103
129
|
|-----|---------|
|
|
104
130
|
| `FIGMA_PAT` / `FIGMA_TOKEN` | Figma personal access token (local mode). |
|
|
105
|
-
| `FIGMA_MCP_API` | Backend converter base URL
|
|
106
|
-
| `FIGMA_MCP_TOKEN` | OAuth/bearer token for the backend
|
|
131
|
+
| `FIGMA_MCP_API` | Backend converter base URL. Defaults to `https://figmacoder-api.sitenow.cloud`. |
|
|
132
|
+
| `FIGMA_MCP_TOKEN` | OAuth/bearer token for the backend. Usually set for you by `login`; an explicit value is used verbatim and never auto-refreshed. |
|
|
107
133
|
| `FIGMA_MCP_MODE` | `auto` (default) · `local` · `remote`. Auto prefers local. |
|
|
108
134
|
| `FIGMA_MCP_OUT_DIR` | Where HTML/JSON outputs are written. Default `<cwd>/figma-output`. |
|
|
109
135
|
| `FIGMA_MCP_NO_BROWSER` | If set, `login` prints the URL instead of opening a browser (headless/SSH). |
|
|
110
|
-
| `OLLAMA_CLOUD_URL` / `OLLAMA_API_KEY` / `OLLAMA_CLOUD_MODELS` |
|
|
136
|
+
| `OLLAMA_CLOUD_URL` / `OLLAMA_API_KEY` / `OLLAMA_CLOUD_MODELS` | Optional, advanced. Only needed for the `--llm` restructure pass. |
|
|
137
|
+
|
|
138
|
+
## CLI
|
|
139
|
+
|
|
140
|
+
The same program also works on its own, without an agent. Flags for
|
|
141
|
+
convert/data: `--node <id>`, `--mode tailwind|inline`, `--assets` (off by
|
|
142
|
+
default), `--no-round` (idiomatic Tailwind snapping is on by default), `--llm`,
|
|
143
|
+
`--out <file>`.
|
|
144
|
+
|
|
145
|
+
| Command | What it does |
|
|
146
|
+
|---------|--------------|
|
|
147
|
+
| `figma-coder-mcp` | Start the MCP server over stdio (the default command). |
|
|
148
|
+
| `convert <url\|key>` | One-off convert to a self-contained HTML file. |
|
|
149
|
+
| `data <url\|key>` | Print or save the compact design tree (deduped styles + repeated-subtree templates). |
|
|
150
|
+
| `set-token <PAT>` | Store a Figma personal access token globally (local mode). |
|
|
151
|
+
| `login` | Sign in with Figma via OAuth, stored globally (remote mode). |
|
|
152
|
+
| `status` | Show how requests will be served. No secrets printed. |
|
|
153
|
+
| `logout` | Remove the global stored credentials. |
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
figma-coder-mcp convert "https://www.figma.com/design/<key>/Title?node-id=1-23"
|
|
157
|
+
figma-coder-mcp convert <fileKey> --node 1:23 --assets --out page.html
|
|
158
|
+
figma-coder-mcp convert <fileKey> --node 1:23 --no-round # exact arbitrary values
|
|
159
|
+
figma-coder-mcp data <fileKey> --node 1:23
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## License
|
|
111
163
|
|
|
112
|
-
|
|
164
|
+
MIT
|