figma-proxy-mcp 0.0.0-stage → 1.1.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/.env.example ADDED
@@ -0,0 +1,9 @@
1
+ # Copy to .env and fill in. .env is git-ignored: never commit your real token.
2
+ # Prefer passing FIGMA_API_KEY through your MCP client's "env" block instead.
3
+ FIGMA_API_KEY=figd_your_token_here
4
+
5
+ # Optional (see README "Environment variables" and SECURITY.md)
6
+ # FIGMA_PROXY_CACHE_DIR=/path/for/registry-and-diff-images
7
+ # FIGMA_PROXY_SVG_DIR=./exported-svgs
8
+ # FIGMA_PROXY_CHROME_PATH=/path/to/chrome
9
+ # FIGMA_PROXY_PORT=4444
package/CHANGELOG.md ADDED
@@ -0,0 +1,43 @@
1
+ # Changelog
2
+
3
+ ## 1.1.1
4
+
5
+ - Add `mcpName` and `server.json` for the official MCP Registry (io.github.Semmargl/figma-proxy-mcp).
6
+
7
+ ## 1.1.0
8
+
9
+ ### Added
10
+ - Run without cloning: `npx -y figma-proxy-mcp --stdio`.
11
+ - MCP `instructions` in the `initialize` response (stdio and HTTP): the summary → flat/lean
12
+ sections → build → render → verify loop, and the "links must contain node-id" rule.
13
+ - Setup doctor: `npx figma-proxy-mcp --check` (also the `figma-proxy-mcp-doctor` bin). It checks
14
+ Node, the token (value never printed), `GET /v1/me` status and Chromium. Exit codes 0/1.
15
+ - `--help` and `--version` flags; `ping` method.
16
+ - `SECURITY.md`: hosts contacted, files written, token scope.
17
+ - Env vars: `FIGMA_PROXY_CACHE_DIR`, `FIGMA_PROXY_DATA_DIR`, `FIGMA_PROXY_VERIFY_DIR`,
18
+ `FIGMA_PROXY_SVG_DIR`, `FIGMA_PROXY_CHROME_PATH`, `FIGMA_PROXY_PORT`, `FIGMA_PROXY_HOST`,
19
+ `FIGMA_PROXY_NO_DOTENV`.
20
+ - Offline smoke tests (`npm test`).
21
+ - Support for Figma branch URLs and instance node ids (`I1-2;3-4`).
22
+
23
+ ### Changed
24
+ - `.env` lookup: environment variable → `.env` in the working directory → `.env` next to the package.
25
+ An empty env var no longer hides a `.env` value.
26
+ - Component registry and `verify_render` diff images now go to the OS temp dir by default
27
+ (previously inside the package folder, which is the npm cache under npx).
28
+ - The HTTP mode binds to `127.0.0.1` by default (previously all interfaces).
29
+ - Clearer errors for 403/404/429 and for a missing Chromium.
30
+ - Node.js 20+ required.
31
+
32
+ ### Security
33
+ - Token is redacted from every error message; logs contain error messages only, not full error objects.
34
+ - File keys are validated before they are used in API paths; image URLs must be `https://`.
35
+ - Removed the `postinstall` script and unused dependencies (`axios`, `eventsource`, `node-fetch`).
36
+ - npm package ships only the runtime files (`files` whitelist).
37
+
38
+ ### Fixed
39
+ - Stdio: messages split across chunks are buffered correctly.
40
+ - JSON-RPC notifications no longer receive error responses.
41
+
42
+ ## 1.0.0
43
+ - Initial release.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vladyslav (Semmargl)
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,3 +1,150 @@
1
- # Temporary Holding Version
1
+ # figma-proxy-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ MCP server for **Figma → code** pipelines. It reads Figma through the REST API and returns
4
+ data an agent can use directly, instead of the raw Figma tree:
5
+
6
+ | Tool | What it gives the agent |
7
+ |---|---|
8
+ | `get_figma_component` | Normalised IR of a node: `summary:true` (sections + boxes + tokens), `format:"flat", lean:true` (flat node list with coordinates relative to the root), CSS variables and a ready **Tailwind theme** |
9
+ | `render_node_png` | Reference render of a node (PNG, base64 + image URL) |
10
+ | `verify_render` | Renders your HTML in headless Chromium and diffs it against the Figma render → SSIM, pixel-diff %, clustered diff regions |
11
+ | `export_svg`, `migrate_all_svgs`, `list_svg_cache` | Icon / vector export |
12
+ | `get_figma_file`, `get_cached_components`, `get_component_by_name` | File tree and component cache |
13
+
14
+ **Read-only**: it never writes to your Figma files. Every host it contacts and every file
15
+ it writes is listed in [SECURITY.md](SECURITY.md).
16
+
17
+ ---
18
+
19
+ ## 1. Requirements
20
+ - **Node.js 20+** (https://nodejs.org, LTS). Check with `node -v`.
21
+ - A **Figma personal access token** (next section).
22
+ - Optional, only for `verify_render`: Chromium for Playwright (step 4).
23
+
24
+ ## 2. Get your Figma token (2 minutes)
25
+ 1. Open Figma (web or desktop) → click your **avatar** → **Settings**.
26
+ 2. Tab **Security** → **Personal access tokens** → **Generate new token**.
27
+ 3. Name: `figma-proxy-mcp`. Expiration: your choice (90 days is fine).
28
+ 4. Scopes: **File content → Read-only** (enough for everything here). Optionally *Dev resources → Read-only*.
29
+ 5. Click **Generate token** and **copy it now**. It starts with `figd_` and is shown only once.
30
+
31
+ The token can read every file *your account* can open. To work with someone else's file,
32
+ ask them to share it with your Figma account (view access is enough).
33
+
34
+ ## 3. Connect to your AI tool (npx, recommended)
35
+ No clone needed. `npx` downloads and runs the published package.
36
+
37
+ **Claude Code** (run in your project folder):
38
+ ```bash
39
+ claude mcp add figma-proxy -e FIGMA_API_KEY=figd_your_token -- npx -y figma-proxy-mcp --stdio
40
+ ```
41
+ Add `--scope project` to share the server with your team via `.mcp.json`, but then
42
+ **do not** put the token in that file: export `FIGMA_API_KEY` in your shell instead.
43
+
44
+ **Cursor** (`.cursor/mcp.json` or `~/.cursor/mcp.json`) / **Claude Desktop** (`claude_desktop_config.json`):
45
+ ```json
46
+ {
47
+ "mcpServers": {
48
+ "figma-proxy": {
49
+ "command": "npx",
50
+ "args": ["-y", "figma-proxy-mcp", "--stdio"],
51
+ "env": { "FIGMA_API_KEY": "figd_your_token" }
52
+ }
53
+ }
54
+ }
55
+ ```
56
+ Restart the app after editing the config.
57
+
58
+ Token lookup order: environment variable (the `env` block above) → `.env` in the working
59
+ directory → `.env` next to the package. Never commit a real token.
60
+
61
+ ## 4. Check your setup
62
+ ```bash
63
+ FIGMA_API_KEY=figd_your_token npx -y figma-proxy-mcp --check
64
+ ```
65
+ It checks the Node version, that the token is set (the value is never printed), that Figma
66
+ accepts it (`GET /v1/me`, only the HTTP status is shown), and whether Chromium is available.
67
+ Exit code `0` = ready, `1` = something required is missing.
68
+
69
+ For `verify_render`, install Chromium once:
70
+ ```bash
71
+ npx playwright install chromium
72
+ ```
73
+ Already have Chrome/Chromium and cannot download? Set `FIGMA_PROXY_CHROME_PATH` to its binary.
74
+
75
+ ## 5. Alternative: run from a git clone
76
+ ```bash
77
+ git clone https://github.com/Semmargl/figma-proxy-mcp.git
78
+ cd figma-proxy-mcp
79
+ npm install
80
+ npx playwright install chromium # only for verify_render
81
+ cp .env.example .env # then put your token in .env
82
+ npm run check
83
+ ```
84
+ Connect with the **absolute** path to `proxy-mcp.js`:
85
+ ```bash
86
+ claude mcp add figma-proxy -- node /ABS/PATH/figma-proxy-mcp/proxy-mcp.js --stdio
87
+ ```
88
+ ```json
89
+ { "mcpServers": { "figma-proxy": { "command": "node", "args": ["/ABS/PATH/figma-proxy-mcp/proxy-mcp.js", "--stdio"] } } }
90
+ ```
91
+ The `.env` next to `proxy-mcp.js` is found whatever the working directory is.
92
+
93
+ ## 6. HTTP mode (scripts / agents that start it on demand)
94
+ ```bash
95
+ npx -y figma-proxy-mcp # → http://127.0.0.1:4444/mcp (JSON-RPC: initialize, tools/list, tools/call)
96
+ ```
97
+ ```bash
98
+ curl -s 127.0.0.1:4444/mcp -H 'content-type: application/json' \
99
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_figma_component","arguments":{"figmaUrl":"<link with node-id>","summary":true}}}'
100
+ ```
101
+ It binds to loopback only. Change with `FIGMA_PROXY_PORT` / `FIGMA_PROXY_HOST`.
102
+
103
+ ## 7. Recommended workflow
104
+ The server also sends this to MCP clients as `instructions` on initialize.
105
+ 1. Links must contain `node-id`: in Figma right-click a frame → **Copy link to selection**.
106
+ 2. `get_figma_component {figmaUrl, summary:true}`: tokens, Tailwind theme, registry, root box, sections with `relativeBox`.
107
+ 3. Per section: `get_figma_component {figmaUrl, format:"flat", lean:true}`.
108
+ 4. Build the markup with the `$--var` tokens and `relativeBox` coordinates.
109
+ 5. `render_node_png {figmaUrl, scale:2}` for the reference image.
110
+ 6. `verify_render {htmlPath, frameWidth, figmaUrl, scale:2}`, fix only the reported regions, repeat until SSIM ≥ threshold (default 0.95).
111
+
112
+ `verify_render` needs `htmlPath` (absolute path to a self-contained HTML file) and `frameWidth`
113
+ (the Figma frame width = root `w` from the summary).
114
+
115
+ ## 8. Environment variables
116
+ | Variable | Default | Purpose |
117
+ |---|---|---|
118
+ | `FIGMA_API_KEY` | (required) | Figma personal access token |
119
+ | `FIGMA_FILE_DEPTH` / `FIGMA_NODE_DEPTH` | 4 / 12 | Fetch depth for helper scripts |
120
+ | `FIGMA_PROXY_CACHE_DIR` | `<os temp>/figma-proxy-mcp` | Base dir for everything the server writes |
121
+ | `FIGMA_PROXY_DATA_DIR` | `<cache>/data` | Component registry |
122
+ | `FIGMA_PROXY_VERIFY_DIR` | `<cache>/verify-out` | `verify_render` diff images |
123
+ | `FIGMA_PROXY_SVG_DIR` | `./exported-svgs` | Default SVG output dir |
124
+ | `FIGMA_PROXY_CHROME_PATH` | (Playwright's Chromium) | Use an existing Chrome/Chromium binary |
125
+ | `FIGMA_PROXY_PORT` / `FIGMA_PROXY_HOST` | 4444 / 127.0.0.1 | HTTP mode |
126
+ | `FIGMA_PROXY_NO_DOTENV` | unset | `1` = ignore `.env` files |
127
+
128
+ ## Troubleshooting
129
+ | Symptom | Fix |
130
+ |---|---|
131
+ | `FIGMA_API_KEY is not set` | Add it to the client's `env` block, or to `.env` (section 3 / 5). Run `--check`. |
132
+ | `403` / token invalid | Token expired, revoked or wrong: generate a new one. |
133
+ | `404` on a node | No access to the file, or wrong `node-id`. |
134
+ | `Invalid Figma file key` | Use the key from the file URL: `figma.com/design/<fileKey>/...` |
135
+ | `verify_render`: Chromium not installed | `npx playwright install chromium`, or set `FIGMA_PROXY_CHROME_PATH`. |
136
+ | `--check`: cannot reach api.figma.com | Network/firewall. Behind an HTTP proxy, Node 22.21+/24 needs `NODE_USE_ENV_PROXY=1` with `HTTPS_PROXY` set. |
137
+ | `EADDRINUSE :4444` | HTTP mode already running, or set `FIGMA_PROXY_PORT`. |
138
+
139
+ ## Development
140
+ ```bash
141
+ npm test # offline smoke tests: stdio + HTTP JSON-RPC, doctor, image diff
142
+ ```
143
+ `scripts/capture.js` and `scripts/inspect-ir.js` are dev-only helpers (not in the npm package):
144
+ they save a raw Figma response to `./fixtures/` and print IR statistics for it.
145
+
146
+ ## Security
147
+ See [SECURITY.md](SECURITY.md). Changes: [CHANGELOG.md](CHANGELOG.md).
148
+
149
+ ## License
150
+ MIT
package/SECURITY.md ADDED
@@ -0,0 +1,70 @@
1
+ # Security and privacy
2
+
3
+ figma-proxy-mcp is a local MCP server. It runs on your machine, uses your Figma
4
+ personal access token, and only **reads** from Figma. It has no telemetry and no
5
+ analytics, and sends nothing anywhere except the requests listed below.
6
+
7
+ ## Read-only
8
+
9
+ The server only calls `GET` endpoints of the Figma REST API. It never creates,
10
+ edits, comments on or deletes anything in Figma.
11
+
12
+ ## Token handling
13
+
14
+ - The token is read only from the `FIGMA_API_KEY` environment variable or a `.env` file.
15
+ Resolution order: real environment variable → `.env` in the current working directory
16
+ → `.env` next to the installed package. Set `FIGMA_PROXY_NO_DOTENV=1` to use env vars only.
17
+ - The token is sent only to `api.figma.com` in the `X-Figma-Token` header.
18
+ - It is never logged, never written to disk, and never included in tool output.
19
+ Error messages pass through a redaction step as an extra safeguard.
20
+ - `--check` / `figma-proxy-mcp-doctor` reports only whether the token is set (and its
21
+ length) plus the HTTP status of `GET /v1/me`. The response body (your account
22
+ details) is thrown away, not printed.
23
+
24
+ **Recommended token scope:** *File content: Read-only*. Nothing else is needed.
25
+ (*Dev resources: Read-only* is optional.) Use an expiry date and revoke the token
26
+ when you stop using the server. The token can read every file your Figma account can
27
+ open, so treat it like a password.
28
+
29
+ ## Network: every host contacted
30
+
31
+ | Host | When | What |
32
+ |---|---|---|
33
+ | `api.figma.com` | every Figma tool call, and `--check` | `GET /v1/files/:key`, `GET /v1/files/:key/nodes`, `GET /v1/images/:key`, `GET /v1/me` (doctor only). Token sent. |
34
+ | Figma image storage, currently `*.s3.*.amazonaws.com` (for example `figma-alpha-api.s3.us-west-2.amazonaws.com`) | `render_node_png`, `export_svg`, `migrate_all_svgs`, `verify_render` with `figmaUrl` | Downloads the PNG/SVG at the short-lived signed URL that `GET /v1/images` returned. **No token is sent.** Only `https://` URLs are accepted. The host is chosen by Figma and may change. |
35
+ | Whatever your HTML page loads | `verify_render` | Headless Chromium opens your local HTML file (`file://`). If that page references remote fonts, scripts or images, Chromium fetches them, exactly as a browser would. Use a self-contained HTML file to avoid this. |
36
+ | Playwright's browser CDN | only when **you** run `npx playwright install chromium` | One-time Chromium download. The server never triggers this itself, and there is no `postinstall` script. |
37
+
38
+ The HTTP mode (`figma-proxy-mcp` without `--stdio`) listens on **`127.0.0.1:4444`**
39
+ only. Change it with `FIGMA_PROXY_PORT` / `FIGMA_PROXY_HOST`. Do not bind it to a
40
+ public interface: anyone who can reach it can use your token through it.
41
+
42
+ ## Files written
43
+
44
+ | What | Default location | Override |
45
+ |---|---|---|
46
+ | Component registry (component names, variant axes, text styles and node ids from the designs you fetched, plus the file key; no token) | `<os temp dir>/figma-proxy-mcp/data/component-registry.json` | `FIGMA_PROXY_DATA_DIR` or `FIGMA_PROXY_CACHE_DIR` |
47
+ | `verify_render` diff image (`<html-name>-diff.png`) | `<os temp dir>/figma-proxy-mcp/verify-out/` | per call `outDir`, or `FIGMA_PROXY_VERIFY_DIR` / `FIGMA_PROXY_CACHE_DIR` |
48
+ | SVG files, only when `export_svg` is called with `save:true`, or `migrate_all_svgs` runs | `./exported-svgs` relative to the server's working directory | per call `outputDir`, or `FIGMA_PROXY_SVG_DIR` |
49
+
50
+ `<os temp dir>` is `os.tmpdir()`, for example `/tmp` on Linux or `/var/folders/...` on macOS.
51
+ SVG and PNG data fetched from Figma is otherwise kept **in memory only** (the SVG
52
+ cache shown by `list_svg_cache` is lost when the process exits). The server writes nothing else.
53
+
54
+ ## Files read
55
+
56
+ - `.env` (see *Token handling*).
57
+ - `verify_render` reads the `htmlPath` you pass and, if given, `figmaPngPath`.
58
+ The server reads these local paths on behalf of the MCP client, so only connect it
59
+ to clients and agents you trust.
60
+
61
+ ## Dependencies
62
+
63
+ Runtime: `express` (HTTP mode only), `playwright` (only for `verify_render`; Chromium
64
+ is not downloaded automatically), `pixelmatch`, `pngjs`. No install scripts.
65
+
66
+ ## Reporting a vulnerability
67
+
68
+ Please open a private security advisory on GitHub:
69
+ https://github.com/Semmargl/figma-proxy-mcp/security/advisories/new
70
+ (or an issue without exploit details if advisories are unavailable).
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "figma-proxy-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.1",
4
+ "mcpName": "io.github.Semmargl/figma-proxy-mcp",
5
+ "description": "Read-only MCP server for Figma to code: normalised IR, Tailwind theme, PNG renders and visual diff (verify_render).",
6
+ "keywords": [
7
+ "mcp",
8
+ "mcp-server",
9
+ "figma",
10
+ "model-context-protocol",
11
+ "figma-to-code",
12
+ "tailwind",
13
+ "visual-regression",
14
+ "claude",
15
+ "cursor"
16
+ ],
17
+ "homepage": "https://github.com/Semmargl/figma-proxy-mcp#readme",
18
+ "bugs": {
19
+ "url": "https://github.com/Semmargl/figma-proxy-mcp/issues"
20
+ },
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/Semmargl/figma-proxy-mcp.git"
24
+ },
25
+ "license": "MIT",
26
+ "main": "proxy-mcp.js",
27
+ "bin": {
28
+ "figma-proxy-mcp": "proxy-mcp.js",
29
+ "figma-proxy-mcp-doctor": "scripts/check-setup.js"
30
+ },
31
+ "files": [
32
+ "proxy-mcp.js",
33
+ "src/",
34
+ "scripts/check-setup.js",
35
+ "README.md",
36
+ "SECURITY.md",
37
+ "CHANGELOG.md",
38
+ "LICENSE",
39
+ ".env.example"
40
+ ],
41
+ "scripts": {
42
+ "start": "node proxy-mcp.js --stdio",
43
+ "http": "node proxy-mcp.js",
44
+ "check": "node proxy-mcp.js --check",
45
+ "test": "node test/smoke.js"
46
+ },
47
+ "engines": {
48
+ "node": ">=20"
49
+ },
50
+ "dependencies": {
51
+ "express": "^5.1.0",
52
+ "pixelmatch": "^5.3.0",
53
+ "playwright": "^1.44.0",
54
+ "pngjs": "^7.0.0"
55
+ }
56
+ }