# figma-mcp

MCP server custom untuk Figma REST API. Sudah terdaftar di Claude Code (user scope) sebagai `figma`.

## Setup token (wajib, sekali saja)

1. Buka Figma → **Settings → Security → Personal access tokens** → *Generate new token*.
2. Scope minimal: `File content (read)`. Tambahkan kalau perlu:
   - `Comments (write)` → untuk `figma_post_comment`
   - `File variables (read)` → untuk `figma_get_variables` (Enterprise saja)
3. Simpan tokennya:

```bash
printf '%s' 'figd_XXXXXXXXXXXX' > ~/.figma-token && chmod 600 ~/.figma-token
```

Alternatifnya set env `FIGMA_TOKEN`. Env menang atas file.

4. Verifikasi:

```bash
cd ~/mcp-figma && npm run check
```

Harusnya keluar `OK — token valid, login sebagai <handle>`.

5. Restart Claude Code supaya server ke-load, lalu cek dengan `/mcp`.

## Tools

| Tool | Fungsi |
|---|---|
| `figma_whoami` | Cek token valid + info akun. Panggil duluan kalau ada error auth. |
| `figma_get_file` | Ringkasan struktur file: halaman + pohon layer (default depth 3). Orientasi awal. |
| `figma_find_nodes` | Cari layer berdasarkan nama dan/atau tipe. Balikin id + path. |
| `figma_inspect_node` | **Tool utama.** Properti visual siap-implementasi: ukuran, HEX fill/stroke, radius, shadow, auto-layout, properti teks. |
| `figma_get_node_raw` | JSON Figma mentah. Cuma kalau `inspect_node` kurang. Output besar. |
| `figma_export_images` | Render node ke PNG/JPG/SVG/PDF. `saveDir` untuk sekalian download ke disk. |
| `figma_get_styles` | Style lokal (FILL/TEXT/EFFECT/GRID) + nilainya → design token. |
| `figma_get_components` | Daftar komponen & component set. |
| `figma_get_variables` | Variable lokal. **Enterprise only**, plan lain balas 403. |
| `figma_get_comments` | Baca komentar di file. |
| `figma_post_comment` | Tulis komentar. Satu-satunya tool yang menulis ke Figma dan kelihatan tim. |
| `figma_list_files` | `teamId` → daftar project, `projectId` → daftar file. |

Semua tool yang butuh file menerima **file key mentah atau URL Figma lengkap**. Kalau URL-nya
mengandung `?node-id=12-34`, `figma_inspect_node` dan `figma_export_images` otomatis pakai node itu
tanpa perlu isi `nodeIds`.

## Contoh pemakaian

```
"Inspect https://www.figma.com/design/AbC123/App?node-id=45-678 lalu bikinin komponen React-nya"
"Cari semua layer bertipe COMPONENT di file AbC123"
"Export frame 45:678 dari AbC123 ke PNG 2x, simpan ke ./assets"
"Ambil semua color style dari AbC123 dan jadikan CSS custom properties"
```

## Catatan

- Response dipotong di 40.000 karakter supaya context tidak meledak. Ubah lewat env `FIGMA_MAX_CHARS`.
- URL gambar hasil `figma_export_images` kedaluwarsa ~30 hari. Pakai `saveDir` kalau mau permanen.
- Rate limit Figma cukup ketat untuk endpoint `/images`; render banyak node sekaligus dalam satu panggilan, jangan satu-satu.
- Server ini **read-only** kecuali `figma_post_comment`. Untuk bikin/ubah node langsung di canvas Figma
  butuh arsitektur lain (plugin Figma + WebSocket bridge), tidak tercakup di sini.

## Test

```bash
npm test
```