@atezer/figma-mcp-bridge 1.2.0 → 1.2.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.
Files changed (28) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +97 -9
  3. package/dist/cloudflare/core/config.js +1 -1
  4. package/dist/cloudflare/core/figma-url.js +48 -0
  5. package/dist/cloudflare/core/plugin-bridge-connector.js +52 -43
  6. package/dist/cloudflare/core/plugin-bridge-server.js +211 -87
  7. package/dist/core/config.js +1 -1
  8. package/dist/core/config.js.map +1 -1
  9. package/dist/core/figma-url.d.ts +10 -0
  10. package/dist/core/figma-url.d.ts.map +1 -0
  11. package/dist/core/figma-url.js +49 -0
  12. package/dist/core/figma-url.js.map +1 -0
  13. package/dist/core/plugin-bridge-connector.d.ts +6 -1
  14. package/dist/core/plugin-bridge-connector.d.ts.map +1 -1
  15. package/dist/core/plugin-bridge-connector.js +52 -43
  16. package/dist/core/plugin-bridge-connector.js.map +1 -1
  17. package/dist/core/plugin-bridge-server.d.ts +47 -14
  18. package/dist/core/plugin-bridge-server.d.ts.map +1 -1
  19. package/dist/core/plugin-bridge-server.js +211 -87
  20. package/dist/core/plugin-bridge-server.js.map +1 -1
  21. package/dist/local-plugin-only.d.ts.map +1 -1
  22. package/dist/local-plugin-only.js +163 -43
  23. package/dist/local-plugin-only.js.map +1 -1
  24. package/f-mcp-plugin/README.md +5 -5
  25. package/f-mcp-plugin/code.js +216 -2
  26. package/f-mcp-plugin/manifest.json +2 -0
  27. package/f-mcp-plugin/ui.html +260 -36
  28. package/package.json +6 -6
package/CHANGELOG.md ADDED
@@ -0,0 +1,82 @@
1
+ # Changelog
2
+
3
+ Bu dosya [Keep a Changelog](https://keepachangelog.com/tr/1.1.0/) bicimine uygundur. Surum numaralari [`package.json`](package.json) ile uyumludur.
4
+
5
+ **Surum takibi (kullanicilar icin):**
6
+
7
+ | Kanal | Aciklama |
8
+ |-------|----------|
9
+ | [GitHub Releases](https://github.com/atezer/FMCP/releases) | Surum etiketleri ve (yayimlandiginda) derlenmis notlar |
10
+ | [npm - @atezer/figma-mcp-bridge](https://www.npmjs.com/package/@atezer/figma-mcp-bridge) | Yayinlanan paket surumu; `npm view @atezer/figma-mcp-bridge version` ile kontrol |
11
+ | Bu dosya | Repoda her surum icin ozet degisiklik listesi |
12
+
13
+ Bu changelog'a ekleme oncesi surumlerin tam ayrintilari icin `git log` kullanilabilir.
14
+
15
+ ## [Unreleased]
16
+
17
+ ### Bridge (port yonetimi)
18
+
19
+ - **Sabit port stratejisi:** Otomatik port taramasi (5454-5470 sirali deneme) kaldirildi. Bridge artik yapilandirilan porta dogrudan baglanir; port mesgulse HTTP health-check ile canli F-MCP / olu surec / farkli servis ayirt edilir; olu port icin kisa gecikmeli tek retry.
20
+ - **Graceful shutdown:** `local-plugin-only.ts`'e SIGINT/SIGTERM handler eklendi -- IDE veya Claude kapandiginda `bridge.stop()` cagrilarak port aninda serbest birakilir (olu port sorununun ana duzeltmesi).
21
+ - **probePort edge case:** `FIGMA_BRIDGE_HOST=0.0.0.0` durumunda port probe'u `127.0.0.1` uzerinden yapilir.
22
+
23
+ ### Dokumantasyon
24
+
25
+ - [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md): "Tek MCP = tum pencereler ayni oturum" bolumu, **"Paralel gorevler (Claude + Cursor + ikinci hat)"** bolumu (mimari, port tablosu, plugin Advanced uyarisi, Cursor paylasimli MCP notu, audit log cakisma notu).
26
+ - [docs/CLAUDE_DESKTOP_CONFIG.md](docs/CLAUDE_DESKTOP_CONFIG.md): coklu `mcpServers` ornegi (5455 + 5470 farkli sunucu adlariyla).
27
+ - [KURULUM.md](KURULUM.md): Claude config "sik gorulen hatalar" ozeti.
28
+ - [README.md](README.md): Port catismasi uyarisi guncellemesi.
29
+
30
+ ### Araclar
31
+
32
+ - `npm run check-ports` -- [`scripts/check-ports.sh`](scripts/check-ports.sh): 5454-5470 arasinda LISTEN durumundaki surecleri listeler (paralel gorev dogrulamasi ve sorun giderme icin).
33
+
34
+ ### Cursor skills (F-MCP)
35
+
36
+ - Yeni skill'ler: `audit-figma-design-system`, `fix-figma-design-system-finding`, `apply-figma-design-system` (tuval ici design system audit/fix/apply; F-MCP Bridge arac eslemesi).
37
+ - Mevcut F-MCP skill'lerine karsilikli **F-MCP skill koordinasyonu** bolumleri eklendi.
38
+ - Tuval skill'lerinde `figma_get_metadata` kaldirildi; Bridge ile uyum icin `figma_get_file_data` / `figma_get_component` / `figma_get_design_context` eslemesi; **design-drift-detector** koordinasyonunda tipik sira (implement - drift) netlestirildi; **audit** icinde zincir performans notlari.
39
+ - [.cursor/skills/f-mcp/SKILL_INDEX.md](.cursor/skills/f-mcp/SKILL_INDEX.md): tum skill'lerin dizini, workspace koku (FCM) notu, ozet akis.
40
+ - `npm run validate:fmcp-skills` -- [`scripts/validate-fmcp-skills-tools.mjs`](scripts/validate-fmcp-skills-tools.mjs): skill `.md` icindeki `figma_*` adlarini `src/local.ts`, `src/local-plugin-only.ts`, `src/core/figma-tools.ts` icindeki `registerTool` birlesimne gore dogrular.
41
+ - GitHub Actions: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) -- `master` / `main` icin PR ve push'ta `npm run validate:fmcp-skills` zorunlu.
42
+
43
+ ### Plugin (F-MCP Bridge)
44
+
45
+ - Gelismis panel: **Otomatik tara** dugmesi -- port alaniyla tek porta kilitlenmeyi kaldirip 5454-5470 taramasini yeniden baslatir.
46
+ - Advanced panel kapatildiginda ayni kilit kalkar (ilk yuklemede cift baglanti tetiklenmez).
47
+
48
+ ### Surec (bakimcilar)
49
+
50
+ - Sonraki surum: `CHANGELOG.md` guncelle - `docs/releases/vX.Y.Z-body.md` olustur - [RELEASE_NOTES_TEMPLATE.md](docs/RELEASE_NOTES_TEMPLATE.md) icindeki `gh release create` / `gh release edit` ile GitHub Release ac veya guncelle.
51
+
52
+ ## [1.2.1] - 2026-04-01
53
+
54
+ GitHub Release: [v1.2.1](https://github.com/atezer/FMCP/releases/tag/v1.2.1); govde: [docs/releases/v1.2.1-body.md](docs/releases/v1.2.1-body.md).
55
+
56
+ ### Bridge
57
+
58
+ - **`figma_search_components`:** Cikti ozetine bileşen **`key`** alani eklendi; `figma_instantiate_component(componentKey)` akisi ile uyum.
59
+ - **`prepublishOnly`:** `npm publish` oncesi `build:local` + `validate:fmcp-skills` (Worker `build:cloudflare` ayri; npm paketi bin'leri `dist/local*.js`).
60
+
61
+ ### Dokumantasyon
62
+
63
+ - **`docs/TOOLS.md`**, **`docs/TOOLS_FULL_LIST.md`:** `dist/local-plugin-only.js` ile parite; `figma_search_assets` / `figma_get_code_connect` / `figma_use` bu build'de kayitli degildir notu; `figma_search_components` + `key` aciklamasi.
64
+ - **`docs/FMCP_AGENT_CANVAS_COMPAT.md`:** Bolum 3 guncel envanter / planlanan ayrimi.
65
+ - **`docs/FIGMA_USE_STRUCTURED_INTENT.md`:** `figma_use` taslak; canli araç `figma_execute` notu.
66
+
67
+ ## [1.2.0] - 2026-03-27
68
+
69
+ ### Dokumantasyon
70
+
71
+ - Surum takibi ve guncelleme adimlari: [README.md](README.md#surum-ve-guncellemeler), [KURULUM.md](KURULUM.md#surum-takibi-ve-guncelleme-notlari).
72
+ - Bu changelog dosyasi eklendi; GitHub Releases ve npm ile birlikte tek referans olarak kullanilmalidir.
73
+ - GitHub [Release v1.2.0](https://github.com/atezer/FMCP/releases/tag/v1.2.0); govde: [docs/releases/v1.2.0-body.md](docs/releases/v1.2.0-body.md). Bakimci akisi: [docs/RELEASE_NOTES_TEMPLATE.md](docs/RELEASE_NOTES_TEMPLATE.md).
74
+
75
+ ### Bakim ve dogrulama (2026-03)
76
+
77
+ - [FUTURE.md](FUTURE.md) kod taramasi: npm `@atezer/figma-mcp-bridge@1.2.0` dogrulandi; `dist/` ile `docs/TOOLS.md` Agent Canvas uclusu uyumsuzlugu not edildi (dokuman duzeltmesi S7'de acik).
78
+ - Figma Organization private plugin yayini tamamlandi (FUTURE S5).
79
+
80
+ ### Not
81
+
82
+ Bu surum, npm paketi `@atezer/figma-mcp-bridge@1.2.0` ve depo kokundeki `package.json` ile hizalidir. Onceki surumlerin ayrintili kaydi bu dosyada baslamaktadir.
package/README.md CHANGED
@@ -1,11 +1,17 @@
1
1
  <p align="center">
2
- <img src="../lmcp.png" alt="F-MCP Bridge Logo" width="280" />
2
+ <img src="assets/logo.png" alt="F-MCP Bridge Logo" width="280" />
3
3
  </p>
4
4
 
5
5
  # F-MCP (Figma MCP Bridge)
6
6
 
7
7
  Figma tasarım verilerini ve işlemlerini Model Context Protocol (MCP) ile AI asistanlarına (Claude, Cursor vb.) açan MCP sunucusu ve Figma plugin'i. Bu repo MCP sunucusu ve **F-MCP Bridge** Figma plugin kaynağını içerir.
8
8
 
9
+ **Proje düzeni:** `src/`, `dist/` ve `f-mcp-plugin` bu depo **kökündedir.** Yerel MCP config ve dokümanlardaki yollar `…/<clone>/dist/...` ve `…/<clone>/f-mcp-plugin/...` şeklinde olmalıdır.
10
+
11
+ **Eski kurulum:** MCP `args` içinde `…/f-mcp-bridge/dist/...` varsa `…/<clone-kökü>/dist/...` yapın. Launch Agent, `.app` ve ayrıntılı adımlar için [KURULUM.md](KURULUM.md) içindeki **«Eski f-mcp-bridge alt yolundan geçiş»** bölümüne bakın.
12
+
13
+ **Claude Desktop config:** `env.FIGMA_PLUGIN_BRIDGE_PORT` kullanıyorsanız Figma plugin’deki port ile aynı olmalı; tam örnekler [docs/CLAUDE_DESKTOP_CONFIG.md](docs/CLAUDE_DESKTOP_CONFIG.md).
14
+
9
15
  ### Figma API token tüketmiyor
10
16
 
11
17
  figma-mcp-bridge, Figma'nın **REST API'sini kullanmıyor**. Akış:
@@ -45,7 +51,7 @@ REST API çağrısı ve Figma'ya tasarım verisi aktarımı yoktur. Bu sayede ku
45
51
  | Tasarım envanteri ve analiz | `figma_get_design_system_summary`, `figma_get_file_data` | Özet, bileşen sayıları, token koleksiyonları; büyük dosyada varsayılan **currentPageOnly** (timeout önlemi) |
46
52
  | Kabul kriterleri ve dokümantasyon | `figma_get_component_for_development`, `figma_capture_screenshot` | Bileşen spec + görsel; test ve kabul için referans |
47
53
  | Design–code uyumu (gap analizi) | `figma_check_design_parity` | Figma token'ları ile kod token'larını karşılaştırır; kurumsal raporlama ve test kriterleri |
48
- | Keşif ve durum | `figma_search_components`, `figma_get_status` | Bileşen arama (varsayılan currentPageOnly), bağlantı kontrolü |
54
+ | Keşif ve durum | `figma_search_components`, `figma_get_status`, `figma_list_connected_files` | Bileşen arama, bağlantı kontrolü, bağlı dosya listesi (multi-client) |
49
55
 
50
56
 
51
57
  ### Geliştiriciler
@@ -71,6 +77,31 @@ REST API çağrısı ve Figma'ya tasarım verisi aktarımı yoktur. Bu sayede ku
71
77
 
72
78
  Kurulum: **En basit (repo indirmeden):** aşağıdaki [En basit kurulum](#en-basit-kurulum-npx--repo-indirmeden) adımları. **Detaylı:** [Kurulum rehberi (Onboarding)](docs/ONBOARDING.md). **Windows:** [WINDOWS-INSTALLATION.md](docs/WINDOWS-INSTALLATION.md) (Node veya Python bridge).
73
79
 
80
+ ### Çalışma modları (hangi binary?)
81
+
82
+ | Mod | NPM / `node` girişi | Ne zaman |
83
+ | --- | --- | --- |
84
+ | **Plugin-only (önerilen)** | `figma-mcp-bridge-plugin` veya `dist/local-plugin-only.js` | Figma’da **F-MCP ATezer Bridge** plugin’i ile çalışmak; REST token gerekmez; debug portu gerekmez. |
85
+ | **Tam (CDP + REST)** | `figma-mcp-bridge` veya `dist/local.js` | Console log, ekran görüntüsü CDP üzerinden, `FIGMA_ACCESS_TOKEN`, Figma `--remote-debugging-port=9222` vb. |
86
+
87
+ Varsayılan NPM `main` ve `figma-mcp-bridge` komutu **tam mod**dur; plugin ile yetiniyorsanız config’te **`figma-mcp-bridge-plugin`** kullanın (NPX örnekleri aşağıda).
88
+
89
+ ## Sürüm ve güncellemeler
90
+
91
+ | Ne | Nerede |
92
+ | --- | --- |
93
+ | **Sürüm numarası** | [`package.json`](package.json) içindeki `version` (ör. **1.2.1**) |
94
+ | **Değişiklik özeti** | [CHANGELOG.md](CHANGELOG.md) |
95
+ | **Yayın bildirimi** | GitHub’da [Releases](https://github.com/atezer/FMCP/releases) — *Watch* → *Custom* → *Releases* ile e-posta bildirimi |
96
+ | **npm paketi** | [@atezer/figma-mcp-bridge](https://www.npmjs.com/package/@atezer/figma-mcp-bridge) — sürüm geçmişi npm sayfasında |
97
+
98
+ **Zaten kurulu yapıyı güncellemek (özet):**
99
+
100
+ - **Repo clone + `node …/dist/local-plugin-only.js`:** `git pull` → gerekirse `npm install` → `npm run build:local` → Cursor/Claude’u yeniden başlatın. Figma plugin kaynağı (`f-mcp-plugin/`) değiştiyse Development’tan manifest’i yeniden import edin veya plugin’i yeniden çalıştırın.
101
+ - **NPX:** Config’te `@latest` kullanıyorsanız yeni npm sürümü yayınlandıktan sonra bir sonraki MCP başlatmada indirilir; takılmada yukarıdaki önbellek notuna bakın. Sabit sürüm kullanıyorsanız `package.json`/CHANGELOG ile uyumlu sürüm numarasını elle güncelleyin.
102
+
103
+ Ayrıntılı adımlar: [KURULUM.md — Sürüm takibi ve güncelleme notları](KURULUM.md#sürüm-takibi-ve-güncelleme-notları).
104
+
74
105
  ## Hızlı başlangıç
75
106
 
76
107
  Plugin'in **"ready (:5454)"** olması için **önce** MCP bridge sunucusu çalışıyor olmalı; **sonra** Figma'da plugin'i açarsınız.
@@ -79,14 +110,14 @@ Plugin'in **"ready (:5454)"** olması için **önce** MCP bridge sunucusu çalı
79
110
 
80
111
  ### En basit kurulum (NPX — repo indirmeden)
81
112
 
82
- Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek için paket otomatik güncellenir (`@latest`).
113
+ Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. **NPX güncelleme:** `@latest` bir sonraki çalıştırmada genelde yeni sürümü indirir; `npx` önbelleği eski paketi tutuyorsa `npx clear-npx-cache` (veya belirli sürüm: `@atezer/figma-mcp-bridge@1.2.0`) kullanın. Ayrıntı: [Sürüm ve güncellemeler](#sürüm-ve-güncellemeler).
83
114
 
84
115
 
85
116
  | Adım | Yapılacak |
86
117
  | ---- | ------------------------------------------------------------------------------------------------------------ |
87
118
  | 1 | **Node.js kur** — [nodejs.org](https://nodejs.org) LTS. Terminalde `node -v` ile kontrol edin. |
88
119
  | 2 | **MCP config ekle** — Aşağıdaki JSON bloğunu Cursor veya Claude config dosyasına ekleyin. |
89
- | 3 | **Cursor veya Claude'u yeniden başlatın** — MCP sunucusu port 5454'te otomatik başlar. |
120
+ | 3 | **Cursor veya Claude'u yeniden başlatın** — köprü varsayılan olarak **5454**’te dinler (meşgulse **5454–5470** arasında sabit port; port mesgulse acik hata mesaji verir). Farkli porta gecmek icin `FIGMA_PLUGIN_BRIDGE_PORT` env var kullanin. |
90
121
  | 4 | **Figma'da plugini açın** — Plugins → **F-MCP ATezer Bridge** → **"ready (:5454)"** görünene kadar bekleyin. |
91
122
 
92
123
 
@@ -97,7 +128,7 @@ Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek iç
97
128
  "mcpServers": {
98
129
  "figma-mcp-bridge": {
99
130
  "command": "npx",
100
- "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
131
+ "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"]
101
132
  }
102
133
  }
103
134
  }
@@ -110,12 +141,29 @@ Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek iç
110
141
  "mcpServers": {
111
142
  "figma-mcp-bridge": {
112
143
  "command": "npx",
113
- "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
144
+ "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"]
114
145
  }
115
146
  }
116
147
  }
117
148
  ```
118
149
 
150
+ **Cursor ve Claude aynı makinede:** İkisi de varsayılan 5454’ü kullandığı için “Port 5454 is already used” / “Server disconnected” alırsınız. Claude tarafında **ayrı port** kullanın; Figma plugin’de de aynı portu seçin.
151
+
152
+ - **Cursor:** Config’e dokunmayın (5454 kalır).
153
+ - **Claude:** Config’te `figma-mcp-bridge` için `env` ekleyin; plugin’de Port’u **5455** yapın.
154
+
155
+ ```json
156
+ "figma-mcp-bridge": {
157
+ "command": "npx",
158
+ "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"],
159
+ "env": {
160
+ "FIGMA_PLUGIN_BRIDGE_PORT": "5455"
161
+ }
162
+ }
163
+ ```
164
+
165
+ Repo ile (clone + build) kullanıyorsanız: `"command": "node"`, `"args": ["<PROJE-YOLU>/dist/local-plugin-only.js"]` ile aynı `"env": { "FIGMA_PLUGIN_BRIDGE_PORT": "5455" }` ekleyin. Claude’u yeniden başlatın; Figma’da plugini açıp Port alanına **5455** yazın → **"ready (:5455)"** görünmeli.
166
+
119
167
  İlk çalıştırmada `npx` paketi indirir; sonraki açılışlarda cache'den çalışır. **Plugin'i Figma'da ilk kez kullanıyorsanız** [Plugin'i Figma'ya yükleyin](#plugini-figmaya-yükleyin-ilk-seferde) adımına bakın.
120
168
 
121
169
  ### A) Clone + build ile (Cursor / Claude)
@@ -175,16 +223,20 @@ npm run dev:local
175
223
 
176
224
  ## Claude / Cursor ile bağlama (detay)
177
225
 
178
- **NPX:** Paket npm'de **@atezer/figma-mcp-bridge** adıyla yayınlı. `npx @atezer/figma-mcp-bridge@latest` ile clone yapmadan kullanılabilir. Bkz. [NPX-INSTALLATION.md](docs/NPX-INSTALLATION.md).
226
+ **NPX:** Paket npm'de **@atezer/figma-mcp-bridge** adıyla yayınlı. Plugin-only için: `npx -y @atezer/figma-mcp-bridge@latest figma-mcp-bridge-plugin` (tam mod için son argümanı atlayıp varsayılan `figma-mcp-bridge` binary’si kullanılır). Bkz. [NPX-INSTALLATION.md](docs/NPX-INSTALLATION.md).
179
227
 
180
228
  **Tam mod (console/screenshot):** Config'te `dist/local-plugin-only.js` yerine `dist/local.js` kullanın; Figma'yı `--remote-debugging-port=9222` ile açın.
181
229
 
182
- **Çoklu kullanıcı (multi-instance):** Aynı anda birden fazla kişi kullanacaksa her kullanıcı farklı port (5454, 5455, … 5470) seçer; MCP config'e `"env": { "FIGMA_PLUGIN_BRIDGE_PORT": "5455" }` ekleyin, plugin'de aynı portu girin. Detay: [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md).
230
+ **Paralel görevler / çoklu kullanıcı:** Aynı anda farklı Figma dosyalarında (Figma Desktop + FigJam + Figma Browser gibi) paralel AI görevleri çalıştırabilirsiniz. Her hat için ayrı port (5454, 5455, 5456, …) ve ayrı bridge process başlatın. MCP config'e `"env": { "FIGMA_PLUGIN_BRIDGE_PORT": "5455" }` ekleyin, plugin'de aynı portu girin. Port durumunu kontrol: `npm run check-ports`. Detay: [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md).
183
231
 
184
232
  **Enterprise:** Audit log (`FIGMA_MCP_AUDIT_LOG_PATH`), air-gap kurulum ve Organization plugin: [ENTERPRISE.md](docs/ENTERPRISE.md).
185
233
 
186
234
  **"Server disconnected" / "wrong server"?** (1) Port 5454'te başka bir process var mı kontrol edin: `lsof -i :5454`. (2) Cursor/Claude Desktop kullanıyorsanız `npm run dev:local` çalışmıyor olmalı. (3) Build güncel mi: `npm run build:local`.
187
235
 
236
+ **Claude'da "connectedClients: 0" / "Plugin Figma Desktop'ta çalışmıyor"?** Claude, Cursor ile aynı anda kullanılıyorsa 5455 portunda çalışır. Plugin ise varsayılan 5454'e bağlanır (Cursor’un bridge’i). Bu yüzden Claude tarafında 0 bağlantı görünür. **Çözüm:** Figma’da plugini açın → **Port** alanına **5455** yazın → Bağlan’a tıklayın. "ready (:5455)" görününce Claude’daki araçlar çalışır. Sadece Claude kullanıyorsanız ve port 5454 ise, pluginde Port’un **5454** olduğundan emin olun.
237
+
238
+ **Birden fazla dosya/board açık, hepsi "ready" ama link verince hep aynı dosya dönüyor?** Plugin'in `fileKey` gönderebilmesi için manifest'te `enablePrivatePluginApi: true` gerekir (bu repoda ekli). Plugin'i **Development → Import plugin from manifest** ile yeniden seçin; sonra her iki sekmede de plugini tekrar çalıştırıp "ready" yapın. Böylece board ve design dosyası ayrı fileKey ile kaydedilir, URL ile doğru dosyaya yönlenir.
239
+
188
240
  ### Browser Figma desteği
189
241
 
190
242
  Plugin, Figma'nın **tarayıcı sürümünde** de (figma.com) çalışır. Desktop uygulaması zorunlu değildir.
@@ -215,6 +267,37 @@ Plugin, Figma'nın **tarayıcı sürümünde** de (figma.com) çalışır. Deskt
215
267
 
216
268
  Detay: [ONBOARDING.md](docs/ONBOARDING.md) (Dev Mode bölümü).
217
269
 
270
+ ### Multi-client: Aynı anda birden fazla dosya
271
+
272
+ F-MCP Bridge **aynı anda birden fazla Figma/FigJam plugin bağlantısını** destekler. Üç ortam birlikte kullanılabilir:
273
+
274
+ - **Figma Desktop** — bir veya daha fazla design dosyasında plugin açık
275
+ - **FigJam browser** — tarayıcıda FigJam board'unda plugin açık
276
+ - **Figma browser** — tarayıcıda figma.com design dosyasında plugin açık
277
+
278
+ Hangi **linki** verirseniz, istek o linkteki dosyaya yönlendirilir; diğer pencereler etkilenmez. **Çoklu ajan:** Farklı dosya linkleri kullanarak birden fazla ajan veya oturum aynı anda farklı dosyalarda çalışabilir.
279
+
280
+ **Link ile kullanım:** Verdiğiniz Figma veya FigJam linki, ilgili tool çağrılarında `figmaUrl` parametresi olarak verilebilir; bridge linkten dosyayı tespit edip o dosyadaki plugin'e yönlendirir. Örneğin: "Bu FigJam linkine bak: https://figma.com/board/XYZ/..." → AI `figma_get_design_context({ figmaUrl: "https://..." })` ile çağırır.
281
+
282
+ **Manuel fileKey:** Her plugin bağlantısı kendini `fileKey` ile tanıtır. `figma_list_connected_files` ile bağlı dosyaları listeleyip, diğer tool'larda `fileKey` parametresi ile hedef dosyayı belirtebilirsiniz. `fileKey` ve `figmaUrl` belirtilmezse en son bağlanan dosyaya gider (geriye uyumlu).
283
+
284
+ **Kullanım:**
285
+
286
+ 1. Birden fazla Figma/FigJam dosyasında (Desktop veya tarayıcı) plugin'i açın → her biri **"ready (:5454)"** gösterir.
287
+ 2. İstediğiniz dosyanın linkini Claude/Cursor'a verin veya `figma_list_connected_files` ile bağlı dosyaları listeleyin.
288
+ 3. Tool çağrılarında `figmaUrl` (link) veya `fileKey` ile hedef dosyayı belirtin.
289
+
290
+ ```
291
+ // Bağlı dosyaları listele
292
+ figma_list_connected_files
293
+
294
+ // Link ile: belirli dosyadaki design context
295
+ figma_get_design_context { "figmaUrl": "https://www.figma.com/board/XYZ/...", "depth": 2 }
296
+
297
+ // veya fileKey ile
298
+ figma_get_design_context { "fileKey": "abc123...", "depth": 2 }
299
+ ```
300
+
218
301
  **Plugin–MCP bağlantı özeti:** İki mod var; debug portu zorunlu değil. **Plugin-only (önerilen):** Config'te `dist/local-plugin-only.js`, Figma normal açılır, token yok. **Tam mod:** Config'te `dist/local.js`, Figma `--remote-debugging-port=9222` ile açılır (console/screenshot için). Ayrıntı: [PLUGIN-MCP-BAGLANTI.md](docs/PLUGIN-MCP-BAGLANTI.md).
219
302
 
220
303
  ## Detaylı Rehber
@@ -248,6 +331,8 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
248
331
  | [DEVELOPER_FIGMA_CAPABILITIES.md](docs/DEVELOPER_FIGMA_CAPABILITIES.md) | **Cursor + F-MCP:** Neyi alır/almaz, birebir çıkartma, code-ready/SUI/token referansı, ileride |
249
332
  | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Sorun giderme |
250
333
  | [NPX-INSTALLATION.md](docs/NPX-INSTALLATION.md) | NPX ile kurulum |
334
+ | [CHANGELOG.md](CHANGELOG.md) | **Sürüm geçmişi** — npm/GitHub Releases ile birlikte referans |
335
+ | [RELEASE_NOTES_TEMPLATE.md](docs/RELEASE_NOTES_TEMPLATE.md) | **Yeni sürüm yayını** — GitHub Release gövdesi şablonu ve `gh release create` ipuçları |
251
336
  | [OAUTH_SETUP.md](docs/OAUTH_SETUP.md) | OAuth (remote sunucu) |
252
337
  | [SELF_HOSTING.md](docs/SELF_HOSTING.md) | Kendi sunucunda host |
253
338
  | [DEPLOYMENT_COMPARISON.md](docs/DEPLOYMENT_COMPARISON.md) | Dağıtım karşılaştırma |
@@ -256,8 +341,11 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
256
341
  | [RECONSTRUCTION_FORMAT.md](docs/RECONSTRUCTION_FORMAT.md) | Reconstruction format |
257
342
  | [BITBUCKET-README.md](docs/BITBUCKET-README.md) | Bitbucket README şablonu |
258
343
  | [PORT-5454-KAPALI.md](docs/PORT-5454-KAPALI.md) | Port 5454 kapalı sorun giderme |
259
- | [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | **Çoklu kullanıcı** — Aynı anda birden fazla kişi (port 5454–5470) |
344
+ | [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | **Paralel görevler & çoklu kullanıcı** — sabit port, paralel hatlar, Claude çoklu MCP |
345
+ | [CLAUDE_DESKTOP_CONFIG.md](docs/CLAUDE_DESKTOP_CONFIG.md) | Claude Desktop config örnekleri (tek ve çoklu MCP sunucusu) |
346
+ | [DEPENDENCY_LAYERS.md](docs/DEPENDENCY_LAYERS.md) | Bağımlılık katmanları (plugin-only / tam / Cloudflare) ve olası paket ayrımı taslağı |
260
347
  | [ENTERPRISE.md](docs/ENTERPRISE.md) | **Enterprise** — Audit log, air-gap, Organization plugin |
348
+ | [SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) | **Güvenlik denetimi** — bulgular checklist ([FUTURE.md](FUTURE.md) §10) |
261
349
  | [PUBLISH-PLUGIN.md](docs/PUBLISH-PLUGIN.md) | **Publish plugin** — Figma'da yayınlama: Data security cevapları, final details, Plugin ID |
262
350
  | | |
263
351
 
package/dist/cloudflare/core/config.js CHANGED
@@ -51,7 +51,7 @@ const DEFAULT_CONFIG = {
51
51
  local: {
52
52
  debugHost: process.env.FIGMA_DEBUG_HOST || 'localhost',
53
53
  debugPort: parseInt(process.env.FIGMA_DEBUG_PORT || '9222', 10),
54
- pluginBridgePort: parseInt(process.env.FIGMA_PLUGIN_BRIDGE_PORT || '5454', 10),
54
+ pluginBridgePort: parseInt(process.env.FIGMA_MCP_BRIDGE_PORT || process.env.FIGMA_PLUGIN_BRIDGE_PORT || '5454', 10),
55
55
  auditLogPath: process.env.FIGMA_MCP_AUDIT_LOG_PATH || undefined,
56
56
  },
57
57
  };
package/dist/cloudflare/core/figma-url.js ADDED
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Parse Figma and FigJam URLs to extract fileKey and optional nodeId.
3
+ * Used for link-based routing in multi-client scenarios.
4
+ */
5
+ /**
6
+ * Supported URL patterns:
7
+ * - https://www.figma.com/design/<fileKey>/...
8
+ * - https://www.figma.com/board/<fileKey>/... (FigJam)
9
+ * - https://www.figma.com/jam/<fileKey>/...
10
+ * - https://www.figma.com/proto/<fileKey>/...
11
+ * - https://figma.com/... (no www)
12
+ * Query: ?node-id=0-1 or ?node-id=0:1 → nodeId "0:1"
13
+ */
14
+ const FIGMA_PATH_REGEX = /^https?:\/\/(www\.)?figma\.com\/(design|board|jam|proto|file)\/([a-zA-Z0-9_-]{10,128})(?:\/|$)/i;
15
+ export function parseFigmaUrl(url) {
16
+ if (!url || typeof url !== "string")
17
+ return null;
18
+ const trimmed = url.trim();
19
+ if (!trimmed)
20
+ return null;
21
+ let fileKey = null;
22
+ // Try path-based match: /design/KEY, /board/KEY, /jam/KEY, /proto/KEY, /file/KEY
23
+ const pathMatch = trimmed.match(FIGMA_PATH_REGEX);
24
+ if (pathMatch) {
25
+ fileKey = pathMatch[3];
26
+ }
27
+ // Fallback: some Figma links use /file/KEY or just KEY in path
28
+ if (!fileKey) {
29
+ const fileKeyFromPath = trimmed.match(/figma\.com\/(?:design|board|jam|proto|file)\/([a-zA-Z0-9_-]{10,128})/i);
30
+ if (fileKeyFromPath)
31
+ fileKey = fileKeyFromPath[1];
32
+ }
33
+ if (!fileKey)
34
+ return null;
35
+ let nodeId;
36
+ try {
37
+ const parsed = new URL(trimmed);
38
+ const nodeIdParam = parsed.searchParams.get("node-id");
39
+ if (nodeIdParam) {
40
+ // Figma uses 0-1 or 0:1 format; plugin API expects "0:1"
41
+ nodeId = nodeIdParam.replace(/-/g, ":");
42
+ }
43
+ }
44
+ catch {
45
+ // URL constructor failed, ignore query parsing
46
+ }
47
+ return { fileKey, nodeId };
48
+ }
package/dist/cloudflare/core/plugin-bridge-connector.js CHANGED
@@ -3,56 +3,61 @@
3
3
  *
4
4
  * Implements the same interface as FigmaDesktopConnector but talks to the
5
5
  * Figma plugin over WebSocket (PluginBridgeServer). No CDP / debug port needed.
6
+ * Supports optional fileKey routing for multi-client scenarios.
6
7
  */
7
8
  import { logger } from "./logger.js";
8
9
  export class PluginBridgeConnector {
9
- constructor(bridge) {
10
+ constructor(bridge, fileKey) {
10
11
  this.bridge = bridge;
12
+ this.fileKey = fileKey;
13
+ }
14
+ setFileKey(fileKey) {
15
+ this.fileKey = fileKey;
11
16
  }
12
17
  async initialize() {
13
18
  logger.info("Plugin bridge connector initialized (no CDP)");
14
19
  }
15
20
  async getVariablesFromPluginUI(fileKey) {
16
- return this.bridge.request("getVariablesFromPluginUI", { fileKey });
21
+ return this.bridge.request("getVariablesFromPluginUI", { fileKey }, this.fileKey ?? fileKey);
17
22
  }
18
23
  async getComponentFromPluginUI(nodeId) {
19
- return this.bridge.request("getComponentFromPluginUI", { nodeId });
24
+ return this.bridge.request("getComponentFromPluginUI", { nodeId }, this.fileKey);
20
25
  }
21
26
  async getVariables(fileKey) {
22
- return this.bridge.request("getVariables", { fileKey });
27
+ return this.bridge.request("getVariables", { fileKey }, this.fileKey ?? fileKey);
23
28
  }
24
29
  async getComponentByNodeId(nodeId) {
25
- return this.bridge.request("getComponentByNodeId", { nodeId });
30
+ return this.bridge.request("getComponentByNodeId", { nodeId }, this.fileKey);
26
31
  }
27
32
  async executeCodeViaUI(code, timeout = 5000) {
28
- return this.bridge.request("executeCodeViaUI", { code, timeout });
33
+ return this.bridge.request("executeCodeViaUI", { code, timeout }, this.fileKey);
29
34
  }
30
35
  async updateVariable(variableId, modeId, value) {
31
- return this.bridge.request("updateVariable", { variableId, modeId, value });
36
+ return this.bridge.request("updateVariable", { variableId, modeId, value }, this.fileKey);
32
37
  }
33
38
  async createVariable(name, collectionId, resolvedType, options) {
34
- return this.bridge.request("createVariable", { name, collectionId, resolvedType, options });
39
+ return this.bridge.request("createVariable", { name, collectionId, resolvedType, options }, this.fileKey);
35
40
  }
36
41
  async createVariableCollection(name, options) {
37
- return this.bridge.request("createVariableCollection", { name, options });
42
+ return this.bridge.request("createVariableCollection", { name, options }, this.fileKey);
38
43
  }
39
44
  async deleteVariable(variableId) {
40
- return this.bridge.request("deleteVariable", { variableId });
45
+ return this.bridge.request("deleteVariable", { variableId }, this.fileKey);
41
46
  }
42
47
  async deleteVariableCollection(collectionId) {
43
- return this.bridge.request("deleteVariableCollection", { collectionId });
48
+ return this.bridge.request("deleteVariableCollection", { collectionId }, this.fileKey);
44
49
  }
45
50
  async renameVariable(variableId, newName) {
46
- return this.bridge.request("renameVariable", { variableId, newName });
51
+ return this.bridge.request("renameVariable", { variableId, newName }, this.fileKey);
47
52
  }
48
53
  async addMode(collectionId, modeName) {
49
- return this.bridge.request("addMode", { collectionId, modeName });
54
+ return this.bridge.request("addMode", { collectionId, modeName }, this.fileKey);
50
55
  }
51
56
  async renameMode(collectionId, modeId, newName) {
52
- return this.bridge.request("renameMode", { collectionId, modeId, newName });
57
+ return this.bridge.request("renameMode", { collectionId, modeId, newName }, this.fileKey);
53
58
  }
54
59
  async refreshVariables() {
55
- return this.bridge.request("refreshVariables", {});
60
+ return this.bridge.request("refreshVariables", {}, this.fileKey);
56
61
  }
57
62
  async getLocalComponents(opts) {
58
63
  const params = {};
@@ -60,64 +65,66 @@ export class PluginBridgeConnector {
60
65
  params.currentPageOnly = opts.currentPageOnly;
61
66
  if (opts?.limit != null && opts.limit > 0)
62
67
  params.limit = opts.limit;
63
- return this.bridge.request("getLocalComponents", params);
68
+ return this.bridge.request("getLocalComponents", params, this.fileKey);
64
69
  }
65
70
  async instantiateComponent(componentKey, options) {
66
- return this.bridge.request("instantiateComponent", { componentKey, options });
71
+ return this.bridge.request("instantiateComponent", { componentKey, options }, this.fileKey);
67
72
  }
68
73
  async setNodeDescription(nodeId, description, descriptionMarkdown) {
69
- return this.bridge.request("setNodeDescription", { nodeId, description, descriptionMarkdown });
74
+ return this.bridge.request("setNodeDescription", { nodeId, description, descriptionMarkdown }, this.fileKey);
70
75
  }
71
76
  async addComponentProperty(nodeId, propertyName, type, defaultValue, options) {
72
- return this.bridge.request("addComponentProperty", { nodeId, propertyName, type, defaultValue, options });
77
+ return this.bridge.request("addComponentProperty", { nodeId, propertyName, type, defaultValue, options }, this.fileKey);
73
78
  }
74
79
  async editComponentProperty(nodeId, propertyName, newValue) {
75
- return this.bridge.request("editComponentProperty", { nodeId, propertyName, newValue });
80
+ return this.bridge.request("editComponentProperty", { nodeId, propertyName, newValue }, this.fileKey);
76
81
  }
77
82
  async deleteComponentProperty(nodeId, propertyName) {
78
- return this.bridge.request("deleteComponentProperty", { nodeId, propertyName });
83
+ return this.bridge.request("deleteComponentProperty", { nodeId, propertyName }, this.fileKey);
79
84
  }
80
85
  async resizeNode(nodeId, width, height, withConstraints = true) {
81
- return this.bridge.request("resizeNode", { nodeId, width, height, withConstraints });
86
+ return this.bridge.request("resizeNode", { nodeId, width, height, withConstraints }, this.fileKey);
82
87
  }
83
88
  async moveNode(nodeId, x, y) {
84
- return this.bridge.request("moveNode", { nodeId, x, y });
89
+ return this.bridge.request("moveNode", { nodeId, x, y }, this.fileKey);
85
90
  }
86
91
  async setNodeFills(nodeId, fills) {
87
- return this.bridge.request("setNodeFills", { nodeId, fills });
92
+ return this.bridge.request("setNodeFills", { nodeId, fills }, this.fileKey);
88
93
  }
89
94
  async setNodeStrokes(nodeId, strokes, strokeWeight) {
90
- return this.bridge.request("setNodeStrokes", { nodeId, strokes, strokeWeight });
95
+ return this.bridge.request("setNodeStrokes", { nodeId, strokes, strokeWeight }, this.fileKey);
91
96
  }
92
97
  async setNodeOpacity(nodeId, opacity) {
93
- return this.bridge.request("setNodeOpacity", { nodeId, opacity });
98
+ return this.bridge.request("setNodeOpacity", { nodeId, opacity }, this.fileKey);
94
99
  }
95
100
  async setNodeCornerRadius(nodeId, radius) {
96
- return this.bridge.request("setNodeCornerRadius", { nodeId, radius });
101
+ return this.bridge.request("setNodeCornerRadius", { nodeId, radius }, this.fileKey);
97
102
  }
98
103
  async cloneNode(nodeId) {
99
- return this.bridge.request("cloneNode", { nodeId });
104
+ return this.bridge.request("cloneNode", { nodeId }, this.fileKey);
100
105
  }
101
106
  async deleteNode(nodeId) {
102
- return this.bridge.request("deleteNode", { nodeId });
107
+ return this.bridge.request("deleteNode", { nodeId }, this.fileKey);
103
108
  }
104
109
  async renameNode(nodeId, newName) {
105
- return this.bridge.request("renameNode", { nodeId, newName });
110
+ return this.bridge.request("renameNode", { nodeId, newName }, this.fileKey);
106
111
  }
107
112
  async setTextContent(nodeId, text, options) {
108
- return this.bridge.request("setTextContent", { nodeId, text, options });
113
+ return this.bridge.request("setTextContent", { nodeId, text, options }, this.fileKey);
109
114
  }
110
115
  async createChildNode(parentId, nodeType, properties) {
111
- return this.bridge.request("createChildNode", { parentId, nodeType, properties });
116
+ return this.bridge.request("createChildNode", { parentId, nodeType, properties }, this.fileKey);
112
117
  }
113
118
  async captureScreenshot(nodeId, options) {
114
- return this.bridge.request("captureScreenshot", { nodeId, options });
119
+ return this.bridge.request("captureScreenshot", { nodeId, options }, this.fileKey);
115
120
  }
116
121
  async setInstanceProperties(nodeId, properties) {
117
- return this.bridge.request("setInstanceProperties", { nodeId, properties });
122
+ return this.bridge.request("setInstanceProperties", { nodeId, properties }, this.fileKey);
118
123
  }
119
124
  async getDocumentStructure(depth, verbosity, opts) {
120
125
  const params = { depth: depth ?? 1, verbosity: verbosity ?? "summary" };
126
+ if (opts?.excludeScreenshot !== undefined)
127
+ params.excludeScreenshot = opts.excludeScreenshot;
121
128
  if (opts?.includeLayout !== undefined)
122
129
  params.includeLayout = opts.includeLayout;
123
130
  if (opts?.includeVisual !== undefined)
@@ -128,7 +135,7 @@ export class PluginBridgeConnector {
128
135
  params.includeCodeReady = opts.includeCodeReady;
129
136
  if (opts?.outputHint !== undefined)
130
137
  params.outputHint = opts.outputHint;
131
- return this.bridge.request("getDocumentStructure", params);
138
+ return this.bridge.request("getDocumentStructure", params, this.fileKey);
132
139
  }
133
140
  async getNodeContext(nodeId, depth, verbosity, opts) {
134
141
  const params = {
@@ -136,6 +143,8 @@ export class PluginBridgeConnector {
136
143
  depth: depth ?? 2,
137
144
  verbosity: verbosity ?? "standard",
138
145
  };
146
+ if (opts?.excludeScreenshot !== undefined)
147
+ params.excludeScreenshot = opts.excludeScreenshot;
139
148
  if (opts?.includeLayout !== undefined)
140
149
  params.includeLayout = opts.includeLayout;
141
150
  if (opts?.includeVisual !== undefined)
@@ -146,24 +155,24 @@ export class PluginBridgeConnector {
146
155
  params.includeCodeReady = opts.includeCodeReady;
147
156
  if (opts?.outputHint !== undefined)
148
157
  params.outputHint = opts.outputHint;
149
- return this.bridge.request("getNodeContext", params);
158
+ return this.bridge.request("getNodeContext", params, this.fileKey);
150
159
  }
151
160
  async getLocalStyles(verbosity) {
152
- return this.bridge.request("getLocalStyles", { verbosity: verbosity ?? "summary" });
161
+ return this.bridge.request("getLocalStyles", { verbosity: verbosity ?? "summary" }, this.fileKey);
153
162
  }
154
163
  async getConsoleLogs(limit = 50) {
155
- const res = await this.bridge.request("getConsoleLogs", { limit });
164
+ const res = await this.bridge.request("getConsoleLogs", { limit }, this.fileKey);
156
165
  return res?.data ?? { logs: [], total: 0 };
157
166
  }
158
167
  async clearConsole() {
159
- await this.bridge.request("clearConsole", {});
168
+ await this.bridge.request("clearConsole", {}, this.fileKey);
160
169
  }
161
170
  async batchCreateVariables(items) {
162
- const res = await this.bridge.request("batchCreateVariables", { items });
171
+ const res = await this.bridge.request("batchCreateVariables", { items }, this.fileKey);
163
172
  return res ?? { created: [], failed: [] };
164
173
  }
165
174
  async batchUpdateVariables(items) {
166
- const res = await this.bridge.request("batchUpdateVariables", { items });
175
+ const res = await this.bridge.request("batchUpdateVariables", { items }, this.fileKey);
167
176
  return res ?? { updated: [], failed: [] };
168
177
  }
169
178
  async setupDesignTokens(payload) {
@@ -176,10 +185,10 @@ export class PluginBridgeConnector {
176
185
  collectionName: payload.collectionName,
177
186
  modes: payload.modes,
178
187
  tokens,
179
- });
188
+ }, this.fileKey);
180
189
  }
181
190
  async arrangeComponentSet(nodeIds) {
182
- const res = (await this.bridge.request("arrangeComponentSet", { nodeIds }));
191
+ const res = (await this.bridge.request("arrangeComponentSet", { nodeIds }, this.fileKey));
183
192
  return res?.data ?? res ?? { nodeId: "", name: "" };
184
193
  }
185
194
  async dispose() {