figma-coder-mcp 0.2.2 → 0.4.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.
Files changed (4) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +164 -152
  3. package/dist/bin.js +4299 -154
  4. package/package.json +5 -1
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,152 +1,164 @@
1
- # figma-coder-mcp
2
-
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.
15
-
16
- ```bash
17
- npm i -g figma-coder-mcp # or run on demand with: npx figma-coder-mcp
18
- ```
19
-
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).
25
-
26
- ### Local mode — personal access token
27
-
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
- ```
44
-
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.
48
-
49
- ### Remote mode — sign in with Figma (OAuth)
50
-
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.
54
-
55
- ```json
56
- {
57
- "mcpServers": {
58
- "figma": {
59
- "command": "npx",
60
- "args": ["-y", "figma-coder-mcp"]
61
- }
62
- }
63
- }
64
- ```
65
-
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."**
74
-
75
- ## Tools
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
-
81
- | Tool | What it does |
82
- |------|--------------|
83
- | `get_figma_data` | Returns the deterministic **Style IR** (the exact CSS for each node) so the agent can reason about the design and generate code itself. Small trees come back inline; large trees are written to a JSON file and summarised. |
84
- | `convert_figma_to_html` | Produces finished, self-contained **HTML + Tailwind** (assets inlined, optional LLM restructure). The HTML is written to a file, and a compact summary plus path is returned to keep the agent's context small. Args: `mode`, `assets`, `assetScale`, `llm`, `outFile`. |
85
-
86
- ## Configuration
87
-
88
- A setting can come from three places. When the same setting appears in more than
89
- one, the higher one wins: **command flags > environment variables > stored
90
- `settings.json`**.
91
-
92
- Settings live in two places:
93
-
94
- - **`.mcp.json`** (project scope): how your agent launches the server, plus an
95
- optional inline `env` (such as `FIGMA_PAT`). Only applies to this project.
96
- - **`~/.figma-mcp/settings.json`** (global scope): your stored Figma token or
97
- OAuth login, written by `set-token` / `login`. Shared by every project. You
98
- only have this file if you run `set-token` or `login`.
99
-
100
- The global file mirrors the `env` block of a `.mcp.json` — user-facing values sit
101
- under `env`, keyed by the same names as the environment variables, so you can
102
- edit it by hand:
103
-
104
- ```json
105
- {
106
- "env": {
107
- "FIGMA_PAT": "figd_xxx",
108
- "FIGMA_MCP_API": "https://figmacoder-api.sitenow.cloud",
109
- "FIGMA_MCP_TOKEN": "<oauth access token>"
110
- },
111
- "refreshToken": "<oauth refresh token>",
112
- "apiTokenExpiresAt": 1735689600000
113
- }
114
- ```
115
-
116
- Environment variables:
117
-
118
- | Var | Meaning |
119
- |-----|---------|
120
- | `FIGMA_PAT` / `FIGMA_TOKEN` | Figma personal access token (local mode). |
121
- | `FIGMA_MCP_API` | Backend converter base URL. Defaults to `https://figmacoder-api.sitenow.cloud`. |
122
- | `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. |
123
- | `FIGMA_MCP_MODE` | `auto` (default) · `local` · `remote`. Auto prefers local. |
124
- | `FIGMA_MCP_OUT_DIR` | Where HTML/JSON outputs are written. Default `<cwd>/figma-output`. |
125
- | `FIGMA_MCP_NO_BROWSER` | If set, `login` prints the URL instead of opening a browser (headless/SSH). |
126
- | `OLLAMA_CLOUD_URL` / `OLLAMA_API_KEY` / `OLLAMA_CLOUD_MODELS` | Optional, advanced. Only needed for the `--llm` restructure pass. |
127
-
128
- ## CLI
129
-
130
- The same program also works on its own, without an agent. Flags for
131
- convert/data: `--node <id>`, `--mode tailwind|inline`, `--no-assets`, `--llm`,
132
- `--out <file>`.
133
-
134
- | Command | What it does |
135
- |---------|--------------|
136
- | `figma-coder-mcp` | Start the MCP server over stdio (the default command). |
137
- | `convert <url\|key>` | One-off convert to a self-contained HTML file. |
138
- | `data <url\|key>` | Print or save the deterministic Style IR. |
139
- | `set-token <PAT>` | Store a Figma personal access token globally (local mode). |
140
- | `login` | Sign in with Figma via OAuth, stored globally (remote mode). |
141
- | `status` | Show how requests will be served. No secrets printed. |
142
- | `logout` | Remove the global stored credentials. |
143
-
144
- ```bash
145
- figma-coder-mcp convert "https://www.figma.com/design/<key>/Title?node-id=1-23"
146
- figma-coder-mcp convert <fileKey> --node 1:23 --no-assets --out page.html
147
- figma-coder-mcp data <fileKey> --node 1:23
148
- ```
149
-
150
- ## License
151
-
152
- MIT
1
+ # figma-coder-mcp
2
+
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.
15
+
16
+ ```bash
17
+ npm i -g figma-coder-mcp # or run on demand with: npx figma-coder-mcp
18
+ ```
19
+
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).
25
+
26
+ ### Local mode — personal access token
27
+
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
+ ```
44
+
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.
48
+
49
+ ### Remote mode — sign in with Figma (OAuth)
50
+
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.
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "figma": {
59
+ "command": "npx",
60
+ "args": ["-y", "figma-coder-mcp"]
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
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."**
74
+
75
+ ## Tools
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
+
81
+ | Tool | What it does |
82
+ |------|--------------|
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. Returned as **minified JSON** (most token-efficient); pass `format:"yaml"` for a more readable (but larger) form. Small results come back inline; large ones are written to a 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`. |
85
+
86
+ ### Conversion fidelity
87
+
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`, and exact palette colors → `bg-blue-500`); off-grid values and non-palette colors stay exact, so it never silently changes real sizes or colors. Pass `round:false` (or `--no-round` on the CLI) for exact arbitrary values everywhere.
95
+
96
+ ## Configuration
97
+
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`**.
101
+
102
+ Settings live in two places:
103
+
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`.
109
+
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:
113
+
114
+ ```json
115
+ {
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
123
+ }
124
+ ```
125
+
126
+ Environment variables:
127
+
128
+ | Var | Meaning |
129
+ |-----|---------|
130
+ | `FIGMA_PAT` / `FIGMA_TOKEN` | Figma personal access token (local mode). |
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. |
133
+ | `FIGMA_MCP_MODE` | `auto` (default) · `local` · `remote`. Auto prefers local. |
134
+ | `FIGMA_MCP_OUT_DIR` | Where HTML/JSON outputs are written. Default `<cwd>/figma-output`. |
135
+ | `FIGMA_MCP_NO_BROWSER` | If set, `login` prints the URL instead of opening a browser (headless/SSH). |
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). `--format json` (default) or `yaml`. |
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
163
+
164
+ MIT