figma-coder-mcp 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 GoldynLabs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 GoldynLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,83 +1,112 @@
-# figma-coder-mcp
-
-MCP server **and** CLI that exposes the Figma → HTML/Tailwind converter to AI
-coding agents (Claude Code, Cursor, …).
-
-```bash
-npm i -g figma-coder-mcp      # or: npx figma-coder-mcp
-figma-coder-mcp set-token figd_xxx
-```
-
-It runs in two modes and picks automatically:
-
-- **local** (default when a PAT is present): converts using the bundled
-  [`@figma-to-code/core`](../packages/figma-core) directly. **No backend needed** —
-  works even if the API server is down. Just provide a Figma PAT.
-- **remote**: delegates to a running `figma-to-html-api` over HTTP (`FIGMA_MCP_API`).
-
-Both modes share the **exact same conversion code** (the core package), so output
-is identical.
-
-## Tools
-
-| Tool | What it does |
-|------|--------------|
-| `get_figma_data` | Returns the deterministic **Style IR** (exact CSS per node) so the agent can generate code itself. Large trees are written to a JSON file and summarised. |
-| `convert_figma_to_html` | Produces finished, self-contained **HTML + Tailwind** (assets inlined, optional LLM restructure). The HTML is written to a file; a compact summary + path is returned to keep the agent's context small. |
-
-## Setup
-
-```bash
-# Build the workspace from the repo root
-npm install
-npm run build
-
-# Store a Figma personal access token (local mode, no backend)
-node figma-mcp/dist/bin.js set-token figd_xxx
-# …or set it per-process: FIGMA_PAT=figd_xxx
-
-# (optional) Point at a backend instead / as fallback
-node figma-mcp/dist/bin.js set-api http://localhost:3000
-
-# Check how requests will be served (no secrets printed)
-node figma-mcp/dist/bin.js status
-```
-
-## Register with an agent
-
-`.mcp.json` (Claude Code) / Cursor MCP config — once installed (`npm i -g`) or via npx:
-
-```json
-{
-  "mcpServers": {
-    "figma": {
-      "command": "npx",
-      "args": ["-y", "figma-coder-mcp"],
-      "env": { "FIGMA_PAT": "figd_xxx" }
-    }
-  }
-}
-```
-
-(From a local clone instead, point `command: "node"`, `args: [".../figma-mcp/dist/bin.js"]`.)
-
-## One-off CLI (no agent)
-
-```bash
-figma-coder-mcp convert "https://www.figma.com/design/<key>/Title?node-id=1-23"
-figma-coder-mcp convert <fileKey> --node 1:23 --no-assets --out page.html
-figma-coder-mcp data <fileKey> --node 1:23
-```
-
-## Configuration
-
-| Var | Meaning |
-|-----|---------|
-| `FIGMA_PAT` / `FIGMA_TOKEN` | Figma personal access token (local mode). |
-| `FIGMA_MCP_API` | Backend converter base URL (remote mode). |
-| `FIGMA_MCP_TOKEN` | Bearer token for the backend (remote mode, optional). |
-| `FIGMA_MCP_MODE` | `auto` (default) · `local` · `remote`. Auto prefers local. |
-| `FIGMA_MCP_OUT_DIR` | Where HTML/JSON outputs are written. Default `<cwd>/figma-output`. |
-| `OLLAMA_CLOUD_URL` / `OLLAMA_API_KEY` / `OLLAMA_CLOUD_MODELS` | Enable the `--llm` restructure pass. |
-
-Priority for every setting: **flags > env > stored credentials** (`~/.figma-mcp/credentials.json`).
+# figma-coder-mcp
+
+MCP server **and** CLI that exposes the Figma → HTML/Tailwind converter to AI
+coding agents (Claude Code, Cursor, …).
+
+```bash
+npm i -g figma-coder-mcp      # or: npx figma-coder-mcp
+figma-coder-mcp set-token figd_xxx
+```
+
+It runs in two modes and picks automatically:
+
+- **local** (default when a PAT is present): converts using the bundled
+  [`@figma-to-code/core`](../packages/figma-core) directly. **No backend needed** —
+  works even if the API server is down. Just provide a Figma PAT.
+- **remote**: delegates to a running `figma-to-html-api` over HTTP (`FIGMA_MCP_API`).
+  Authenticate with **OAuth** (`figma-coder-mcp login`) so no personal access
+  token lives in your config — the backend holds the OAuth secret.
+
+Both modes share the **exact same conversion code** (the core package), so output
+is identical.
+
+## Two ways to authenticate
+
+| | Option A — Remote + OAuth | Option B — Local + PAT |
+|---|---|---|
+| Setup | `set-api <url>` then `login` (browser) | `set-token figd_xxx` (or `FIGMA_PAT`) |
+| Needs the backend? | Yes | No — fully local |
+| Survives backend outage? | No | **Yes** |
+| Token in your config? | No | Yes (PAT) |
+
+```bash
+# Option A — OAuth via the backend (no PAT in your config)
+figma-coder-mcp set-api http://localhost:4403
+figma-coder-mcp login          # opens the browser; token is stored for you
+
+# Option B — fully local with a PAT
+figma-coder-mcp set-token figd_xxx
+```
+
+`login` opens `…/auth/figma/login` in your browser, captures the token the backend
+hands back over a one-shot **loopback** server, and stores it in
+`~/.figma-mcp/credentials.json`. The access token is **refreshed silently** (using
+the stored refresh token) when it expires — re-run `login` only if the refresh
+token itself is revoked. Set `FIGMA_MCP_NO_BROWSER=1` on headless/SSH hosts to
+print the URL instead of launching a browser.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `get_figma_data` | Returns the deterministic **Style IR** (exact CSS per node) so the agent can generate code itself. Large trees are written to a JSON file and summarised. |
+| `convert_figma_to_html` | Produces finished, self-contained **HTML + Tailwind** (assets inlined, optional LLM restructure). The HTML is written to a file; a compact summary + path is returned to keep the agent's context small. |
+
+## Setup
+
+```bash
+# Build the workspace from the repo root
+npm install
+npm run build
+
+# Store a Figma personal access token (local mode, no backend)
+node figma-mcp/dist/bin.js set-token figd_xxx
+# …or set it per-process: FIGMA_PAT=figd_xxx
+
+# …or use OAuth via a backend instead (no PAT in your config)
+node figma-mcp/dist/bin.js set-api http://localhost:4403
+node figma-mcp/dist/bin.js login
+
+# Check how requests will be served (no secrets printed)
+node figma-mcp/dist/bin.js status
+```
+
+## Register with an agent
+
+`.mcp.json` (Claude Code) / Cursor MCP config — once installed (`npm i -g`) or via npx:
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "figma-coder-mcp"],
+      "env": { "FIGMA_PAT": "figd_xxx" }
+    }
+  }
+}
+```
+
+(From a local clone instead, point `command: "node"`, `args: [".../figma-mcp/dist/bin.js"]`.)
+
+## One-off CLI (no agent)
+
+```bash
+figma-coder-mcp convert "https://www.figma.com/design/<key>/Title?node-id=1-23"
+figma-coder-mcp convert <fileKey> --node 1:23 --no-assets --out page.html
+figma-coder-mcp data <fileKey> --node 1:23
+```
+
+## Configuration
+
+| Var | Meaning |
+|-----|---------|
+| `FIGMA_PAT` / `FIGMA_TOKEN` | Figma personal access token (local mode). |
+| `FIGMA_MCP_API` | Backend converter base URL (remote mode). |
+| `FIGMA_MCP_TOKEN` | OAuth/bearer token for the backend (remote mode). Usually set for you by `login`; an explicit value here is used verbatim and never auto-refreshed. |
+| `FIGMA_MCP_MODE` | `auto` (default) · `local` · `remote`. Auto prefers local. |
+| `FIGMA_MCP_OUT_DIR` | Where HTML/JSON outputs are written. Default `<cwd>/figma-output`. |
+| `FIGMA_MCP_NO_BROWSER` | If set, `login` prints the URL instead of opening a browser (headless/SSH). |
+| `OLLAMA_CLOUD_URL` / `OLLAMA_API_KEY` / `OLLAMA_CLOUD_MODELS` | Enable the `--llm` restructure pass. |
+
+Priority for every setting: **flags > env > stored credentials** (`~/.figma-mcp/credentials.json`).

package/dist/bin.js

@@ -1836,13 +1836,40 @@ async function clearCredentials() {
   }
 }
 
+// src/refresh.ts
+var SKEW_MS = 6e4;
+async function ensureFreshApiToken(apiUrl, force = false) {
+  const creds = await loadCredentials();
+  if (!creds.apiToken || !creds.refreshToken) return;
+  if (!force) {
+    if (!creds.apiTokenExpiresAt) return;
+    if (Date.now() < creds.apiTokenExpiresAt - SKEW_MS) return;
+  }
+  const base = apiUrl.replace(/\/+$/, "");
+  try {
+    const res = await fetch(`${base}/auth/figma/cli-refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: creds.refreshToken })
+    });
+    if (!res.ok) return;
+    const t = await res.json();
+    await saveCredentials({
+      apiToken: t.access_token,
+      refreshToken: t.refresh_token ?? creds.refreshToken,
+      apiTokenExpiresAt: t.expires_in ? Date.now() + t.expires_in * 1e3 : void 0
+    });
+  } catch {
+  }
+}
+
 // src/config.ts
 async function resolveConfig(overrides = {}) {
-  const creds = await loadCredentials();
+  let creds = await loadCredentials();
   const mode = overrides.mode ?? process.env.FIGMA_MCP_MODE ?? "auto";
   const pat = overrides.pat ?? process.env.FIGMA_PAT ?? process.env.FIGMA_TOKEN ?? creds.pat;
   const apiUrl = overrides.apiUrl ?? process.env.FIGMA_MCP_API ?? creds.apiUrl;
-  const apiToken = overrides.apiToken ?? process.env.FIGMA_MCP_TOKEN ?? creds.apiToken;
+  const apiTokenOverride = overrides.apiToken ?? process.env.FIGMA_MCP_TOKEN;
   const outDir = overrides.outDir ?? process.env.FIGMA_MCP_OUT_DIR ?? `${process.cwd()}/figma-output`;
   let effectiveMode;
   if (mode === "local") {
@@ -1852,6 +1879,11 @@ async function resolveConfig(overrides = {}) {
   } else {
     effectiveMode = pat ? "local" : apiUrl ? "remote" : "local";
   }
+  if (effectiveMode === "remote" && apiUrl && !apiTokenOverride) {
+    await ensureFreshApiToken(apiUrl);
+    creds = await loadCredentials();
+  }
+  const apiToken = apiTokenOverride ?? creds.apiToken;
   return { mode, effectiveMode, pat, apiUrl, apiToken, outDir };
 }
 function describeConfig(cfg) {
@@ -1862,16 +1894,24 @@ function describeConfig(cfg) {
 }
 
 // src/api-client.ts
-function authHeaders(cfg) {
+function authHeaders(cfg, apiToken = cfg.apiToken) {
   const headers = { "Content-Type": "application/json" };
   if (cfg.pat) headers["X-Figma-Token"] = cfg.pat;
-  if (cfg.apiToken) headers["Authorization"] = `Bearer ${cfg.apiToken}`;
+  if (apiToken) headers["Authorization"] = `Bearer ${apiToken}`;
   return headers;
 }
 async function post(cfg, route, body) {
   if (!cfg.apiUrl) throw new Error("Remote mode requires a backend URL (FIGMA_MCP_API).");
   const url = `${cfg.apiUrl.replace(/\/+$/, "")}${route}`;
-  const res = await fetch(url, { method: "POST", headers: authHeaders(cfg), body: JSON.stringify(body) });
+  const payload = JSON.stringify(body);
+  let res = await fetch(url, { method: "POST", headers: authHeaders(cfg), body: payload });
+  if (res.status === 401 && cfg.apiToken) {
+    await ensureFreshApiToken(cfg.apiUrl, true);
+    const refreshed = (await loadCredentials()).apiToken;
+    if (refreshed && refreshed !== cfg.apiToken) {
+      res = await fetch(url, { method: "POST", headers: authHeaders(cfg, refreshed), body: payload });
+    }
+  }
   const text = await res.text();
   if (!res.ok) {
     let msg = `${res.status} ${res.statusText}`;
@@ -2004,7 +2044,7 @@ function safe(handler) {
   };
 }
 function buildServer() {
-  const server = new McpServer({ name: "figma-coder-mcp", version: "0.1.0" });
+  const server = new McpServer({ name: "figma-coder-mcp", version: "0.2.0" });
   server.registerTool(
     "get_figma_data",
     {
@@ -2040,6 +2080,91 @@ async function serveStdio() {
   console.error("[figma-coder-mcp] stdio server ready");
 }
 
+// src/login.ts
+import * as http from "http";
+import { spawn } from "child_process";
+function openBrowser(url) {
+  if (process.env.FIGMA_MCP_NO_BROWSER) return;
+  try {
+    if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+    } else if (process.platform === "darwin") {
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    } else {
+      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    }
+  } catch {
+  }
+}
+var page = (title, body) => `<!doctype html><meta charset="utf-8"><title>figma-coder-mcp</title><body style="font-family:system-ui,sans-serif;text-align:center;padding-top:4rem;color:#0f172a"><h2>${title}</h2><p>${body}</p></body>`;
+async function login(opts = {}) {
+  const cfg = await resolveConfig({ apiUrl: opts.apiUrl });
+  if (!cfg.apiUrl) {
+    throw new Error(
+      "OAuth login needs the backend URL. Set it with `figma-coder-mcp set-api <URL>` or FIGMA_MCP_API."
+    );
+  }
+  const base = cfg.apiUrl.replace(/\/+$/, "");
+  const tokens = await new Promise((resolve2, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const error = url.searchParams.get("error");
+      const accessToken = url.searchParams.get("access_token");
+      if (error || !accessToken) {
+        const msg = error ?? "no token returned";
+        res.writeHead(400, { "Content-Type": "text/html" }).end(page("Login failed", msg));
+        cleanup();
+        reject(new Error(`Figma login failed: ${msg}`));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html" }).end(page("\u2713 Logged in to Figma", "You can close this tab and return to your terminal."));
+      cleanup();
+      resolve2({
+        access_token: accessToken,
+        refresh_token: url.searchParams.get("refresh_token") ?? void 0,
+        expires_in: Number(url.searchParams.get("expires_in")) || void 0
+      });
+    });
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error("Login timed out after 5 minutes."));
+    }, opts.timeoutMs ?? 5 * 60 * 1e3);
+    function cleanup() {
+      clearTimeout(timeout);
+      server.close();
+    }
+    server.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      const loopback = `http://127.0.0.1:${port}/callback`;
+      const authorizeUrl = `${base}/auth/figma/login?cli=${encodeURIComponent(loopback)}`;
+      console.error(
+        `Opening your browser to log in with Figma\u2026
+If it doesn't open automatically, visit:
+  ${authorizeUrl}
+`
+      );
+      openBrowser(authorizeUrl);
+    });
+  });
+  await saveCredentials({
+    apiUrl: base,
+    apiToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    apiTokenExpiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1e3 : void 0
+  });
+  console.error(`\u2713 Saved Figma OAuth session to ${credentialsPath()}`);
+  console.error("Run the MCP in remote mode (set FIGMA_MCP_MODE=remote) to use it.");
+}
+
 // src/bin.ts
 function parseArgs(argv) {
   const positionals = [];
@@ -2075,6 +2200,7 @@ Usage:
   figma-coder-mcp data <url|key> [..]     One-off: print/save the Style IR
   figma-coder-mcp set-token <PAT>         Store a Figma personal access token (local mode)
   figma-coder-mcp set-api <URL>           Store the backend converter URL (remote mode)
+  figma-coder-mcp login [--api <URL>]     Log in with Figma via OAuth (remote mode)
   figma-coder-mcp status                  Show how requests will be served (no secrets)
   figma-coder-mcp logout                  Remove stored credentials
   figma-coder-mcp help                    Show this help
@@ -2087,7 +2213,8 @@ Common flags (convert/data):
   --out <file>    Output file name (convert)
 
 Config (env or stored): FIGMA_PAT, FIGMA_MCP_API, FIGMA_MCP_TOKEN, FIGMA_MCP_MODE,
-FIGMA_MCP_OUT_DIR. Auto mode prefers local (PAT) so it works even if the backend is down.`;
+FIGMA_MCP_OUT_DIR, FIGMA_MCP_NO_BROWSER (skip auto-opening the browser on login).
+Auto mode prefers local (PAT) so it works even if the backend is down.`;
 async function main() {
   const [positionals, flags] = parseArgs(process.argv.slice(2));
   const cmd = positionals[0] ?? "serve";
@@ -2126,6 +2253,10 @@ async function main() {
       console.log(`Stored backend URL (${url}) in ${credentialsPath()}`);
       return;
     }
+    case "login": {
+      await login({ apiUrl: typeof flags.api === "string" ? flags.api : void 0 });
+      return;
+    }
     case "status": {
       const cfg = await resolveConfig();
       console.log(describeConfig(cfg));

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "figma-coder-mcp",
-  "version": "0.1.0",
-  "description": "MCP server + CLI that converts Figma designs into HTML + Tailwind for AI coding agents. Runs locally with a Figma PAT (no backend) or delegates to a figma-to-html-api backend.",
-  "license": "MIT",
-  "author": "GoldynLabs",
-  "type": "module",
-  "bin": {
-    "figma-coder-mcp": "dist/bin.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "figma",
-    "mcp",
-    "model-context-protocol",
-    "tailwind",
-    "html",
-    "figma-to-code",
-    "ai",
-    "claude",
-    "cursor"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/goldynlabs/figma-coder-mcp.git"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run build",
-    "start": "node dist/bin.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "openai": "^4.77.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@figma-to-code/core": "*",
-    "@types/node": "^22.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.1.3"
-  }
-}
+{
+  "name": "figma-coder-mcp",
+  "version": "0.2.0",
+  "description": "MCP server + CLI that converts Figma designs into HTML + Tailwind for AI coding agents. Runs locally with a Figma PAT (no backend) or delegates to a figma-to-html-api backend.",
+  "license": "MIT",
+  "author": "GoldynLabs",
+  "type": "module",
+  "bin": {
+    "figma-coder-mcp": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "model-context-protocol",
+    "tailwind",
+    "html",
+    "figma-to-code",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goldynlabs/figma-coder-mcp.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "start": "node dist/bin.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "openai": "^4.77.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@figma-to-code/core": "*",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.1.3"
+  }
+}