@atezer/figma-mcp-bridge 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+Bu dosya [Keep a Changelog](https://keepachangelog.com/tr/1.1.0/) bicimine uygundur. Surum numaralari [`package.json`](package.json) ile uyumludur.
+
+**Surum takibi (kullanicilar icin):**
+
+| Kanal | Aciklama |
+|-------|----------|
+| [GitHub Releases](https://github.com/atezer/FMCP/releases) | Surum etiketleri ve (yayimlandiginda) derlenmis notlar |
+| [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 |
+| Bu dosya | Repoda her surum icin ozet degisiklik listesi |
+
+Bu changelog'a ekleme oncesi surumlerin tam ayrintilari icin `git log` kullanilabilir.
+
+## [Unreleased]
+
+(Yaklasan degisiklikler buraya.)
+
+## [1.2.2] - 2026-04-01
+
+GitHub Release: [v1.2.2](https://github.com/atezer/FMCP/releases/tag/v1.2.2); govde: [docs/releases/v1.2.2-body.md](docs/releases/v1.2.2-body.md).
+
+### Plugin (F-MCP Bridge)
+
+- **Multi-client `fileKey`:** UI WebSocket `onopen` bazen plugin ana iş parçacığından gelen `FILE_IDENTITY` mesajından önce çalışıyordu; ilk `ready` `fileKey`/`fileName` olmadan gidince köprü (`PluginBridgeServer`) o client’ı `null` anahtarla listeliyordu. `pushBridgeFileIdentity()` eklendi: kimlik geldikten sonra açık soket varsa `ready` yeniden gönderiliyor; `figma_list_connected_files` ve `fileKey` ile yönlendirme tüm pencerelerde (FigJam + birden fazla Figma tarayıcı sekmesi) tutarlı çalışır.
+
+### Dokumantasyon
+
+- [README.md](README.md): Multi-client bölümünde kimlik zamanlaması notu (1.2.2+).
+- [FUTURE.md](FUTURE.md): Sürüm satırı ve tamamlanan madde özeti.
+
+## [1.2.1] - 2026-04-01
+
+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).
+
+### Bridge
+
+- **`figma_search_components`:** Cikti ozetine bileşen **`key`** alani eklendi; `figma_instantiate_component(componentKey)` akisi ile uyum.
+- **`prepublishOnly`:** `npm publish` oncesi `build:local` + `validate:fmcp-skills` (Worker `build:cloudflare` ayri; npm paketi bin'leri `dist/local*.js`).
+
+### Dokumantasyon
+
+- **`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.
+- **`docs/FMCP_AGENT_CANVAS_COMPAT.md`:** Bolum 3 guncel envanter / planlanan ayrimi.
+- **`docs/FIGMA_USE_STRUCTURED_INTENT.md`:** `figma_use` taslak; canli araç `figma_execute` notu.
+
+## [1.2.0] - 2026-03-27
+
+### Dokumantasyon
+
+- Surum takibi ve guncelleme adimlari: [README.md](README.md#surum-ve-guncellemeler), [KURULUM.md](KURULUM.md#surum-takibi-ve-guncelleme-notlari).
+- Bu changelog dosyasi eklendi; GitHub Releases ve npm ile birlikte tek referans olarak kullanilmalidir.
+- 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).
+
+### Bakim ve dogrulama (2026-03)
+
+- [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).
+- Figma Organization private plugin yayini tamamlandi (FUTURE S5).
+
+### Not
+
+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

@@ -1,11 +1,17 @@
 <p align="center">
-  <img src="../lmcp.png" alt="F-MCP Bridge Logo" width="280" />
+  <img src="assets/logo.png" alt="F-MCP Bridge Logo" width="280" />
 </p>
 
 # F-MCP (Figma MCP Bridge)
 
 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.
 
+**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.
+
+**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.
+
+**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).
+
 ### Figma API token tüketmiyor
 
 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
 | 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) |
 | Kabul kriterleri ve dokümantasyon | `figma_get_component_for_development`, `figma_capture_screenshot` | Bileşen spec + görsel; test ve kabul için referans                                                          |
 | 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                  |
-| Keşif ve durum                    | `figma_search_components`, `figma_get_status`                     | Bileşen arama (varsayılan currentPageOnly), bağlantı kontrolü                                               |
+| 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)                                       |
 
 
 ### Geliştiriciler
@@ -71,6 +77,31 @@ REST API çağrısı ve Figma'ya tasarım verisi aktarımı yoktur. Bu sayede ku
 
 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).
 
+### Çalışma modları (hangi binary?)
+
+| Mod | NPM / `node` girişi | Ne zaman |
+| --- | --- | --- |
+| **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. |
+| **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. |
+
+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).
+
+## Sürüm ve güncellemeler
+
+| Ne | Nerede |
+| --- | --- |
+| **Sürüm numarası** | [`package.json`](package.json) içindeki `version` (ör. **1.2.2**) |
+| **Değişiklik özeti** | [CHANGELOG.md](CHANGELOG.md) |
+| **Yayın bildirimi** | GitHub’da [Releases](https://github.com/atezer/FMCP/releases) — *Watch* → *Custom* → *Releases* ile e-posta bildirimi |
+| **npm paketi** | [@atezer/figma-mcp-bridge](https://www.npmjs.com/package/@atezer/figma-mcp-bridge) — sürüm geçmişi npm sayfasında |
+
+**Zaten kurulu yapıyı güncellemek (özet):**
+
+- **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.
+- **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.
+
+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ı).
+
 ## Hızlı başlangıç
 
 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ı
 
 ### En basit kurulum (NPX — repo indirmeden)
 
-Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek için paket otomatik güncellenir (`@latest`).
+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.2`) kullanın. Ayrıntı: [Sürüm ve güncellemeler](#sürüm-ve-güncellemeler).
 
 
 | Adım | Yapılacak                                                                                                    |
 | ---- | ------------------------------------------------------------------------------------------------------------ |
 | 1    | **Node.js kur** — [nodejs.org](https://nodejs.org) LTS. Terminalde `node -v` ile kontrol edin.               |
 | 2    | **MCP config ekle** — Aşağıdaki JSON bloğunu Cursor veya Claude config dosyasına ekleyin.                    |
-| 3    | **Cursor veya Claude'u yeniden başlatın** — MCP sunucusu port 5454'te otomatik başlar.                       |
+| 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. |
 | 4    | **Figma'da plugini açın** — Plugins → **F-MCP ATezer Bridge** → **"ready (:5454)"** görünene kadar bekleyin. |
 
 
@@ -97,7 +128,7 @@ Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek iç
   "mcpServers": {
     "figma-mcp-bridge": {
       "command": "npx",
-      "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
+      "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"]
     }
   }
 }
@@ -110,12 +141,29 @@ Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek iç
   "mcpServers": {
     "figma-mcp-bridge": {
       "command": "npx",
-      "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
+      "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"]
     }
   }
 }
 ```
 
+**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.
+
+- **Cursor:** Config’e dokunmayın (5454 kalır).
+- **Claude:** Config’te `figma-mcp-bridge` için `env` ekleyin; plugin’de Port’u **5455** yapın.
+
+```json
+"figma-mcp-bridge": {
+  "command": "npx",
+  "args": ["-y", "@atezer/figma-mcp-bridge@latest", "figma-mcp-bridge-plugin"],
+  "env": {
+    "FIGMA_PLUGIN_BRIDGE_PORT": "5455"
+  }
+}
+```
+
+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.
+
 İ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.
 
 ### A) Clone + build ile (Cursor / Claude)
@@ -175,16 +223,20 @@ npm run dev:local
 
 ## Claude / Cursor ile bağlama (detay)
 
-**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).
+**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).
 
 **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.
 
-**Ç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).
+**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).
 
 **Enterprise:** Audit log (`FIGMA_MCP_AUDIT_LOG_PATH`), air-gap kurulum ve Organization plugin: [ENTERPRISE.md](docs/ENTERPRISE.md).
 
 **"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`.
 
+**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.
+
+**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.
+
 ### Browser Figma desteği
 
 Plugin, Figma'nın **tarayıcı sürümünde** de (figma.com) çalışır. Desktop uygulaması zorunlu değildir.
@@ -215,6 +267,39 @@ Plugin, Figma'nın **tarayıcı sürümünde** de (figma.com) çalışır. Deskt
 
 Detay: [ONBOARDING.md](docs/ONBOARDING.md) (Dev Mode bölümü).
 
+### Multi-client: Aynı anda birden fazla dosya
+
+F-MCP Bridge **aynı anda birden fazla Figma/FigJam plugin bağlantısını** destekler. Üç ortam birlikte kullanılabilir:
+
+- **Figma Desktop** — bir veya daha fazla design dosyasında plugin açık
+- **FigJam browser** — tarayıcıda FigJam board'unda plugin açık
+- **Figma browser** — tarayıcıda figma.com design dosyasında plugin açık
+
+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.
+
+**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.
+
+**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).
+
+**Kimlik zamanlaması (1.2.2+):** WebSocket bazen ana iş parçacığından gelen dosya kimliğinden önce açılabiliyordu; köprüde bir bağlantı `fileKey: null` görünebiliyordu. Plugin artık `FILE_IDENTITY` geldikten sonra `ready` mesajını yeniden göndererek sunucu kaydını güncelliyor. Çoklu sekme kullanıyorsanız bu sürümdeki `f-mcp-plugin` kaynağını yeniden import edin veya npm paketindeki `f-mcp-plugin` ile hizalayın ([CHANGELOG.md](CHANGELOG.md) **\[1.2.2\]**).
+
+**Kullanım:**
+
+1. Birden fazla Figma/FigJam dosyasında (Desktop veya tarayıcı) plugin'i açın → her biri **"ready (:5454)"** gösterir.
+2. İstediğiniz dosyanın linkini Claude/Cursor'a verin veya `figma_list_connected_files` ile bağlı dosyaları listeleyin.
+3. Tool çağrılarında `figmaUrl` (link) veya `fileKey` ile hedef dosyayı belirtin.
+
+```
+// Bağlı dosyaları listele
+figma_list_connected_files
+
+// Link ile: belirli dosyadaki design context
+figma_get_design_context { "figmaUrl": "https://www.figma.com/board/XYZ/...", "depth": 2 }
+
+// veya fileKey ile
+figma_get_design_context { "fileKey": "abc123...", "depth": 2 }
+```
+
 **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).
 
 ## Detaylı Rehber
@@ -248,6 +333,8 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
 | [DEVELOPER_FIGMA_CAPABILITIES.md](docs/DEVELOPER_FIGMA_CAPABILITIES.md) | **Cursor + F-MCP:** Neyi alır/almaz, birebir çıkartma, code-ready/SUI/token referansı, ileride   |
 | [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)                           | Sorun giderme                                                                                    |
 | [NPX-INSTALLATION.md](docs/NPX-INSTALLATION.md)                         | NPX ile kurulum                                                                                  |
+| [CHANGELOG.md](CHANGELOG.md)                                           | **Sürüm geçmişi** — npm/GitHub Releases ile birlikte referans                                    |
+| [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ı          |
 | [OAUTH_SETUP.md](docs/OAUTH_SETUP.md)                                   | OAuth (remote sunucu)                                                                            |
 | [SELF_HOSTING.md](docs/SELF_HOSTING.md)                                 | Kendi sunucunda host                                                                             |
 | [DEPLOYMENT_COMPARISON.md](docs/DEPLOYMENT_COMPARISON.md)               | Dağıtım karşılaştırma                                                                            |
@@ -256,8 +343,11 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
 | [RECONSTRUCTION_FORMAT.md](docs/RECONSTRUCTION_FORMAT.md)               | Reconstruction format                                                                            |
 | [BITBUCKET-README.md](docs/BITBUCKET-README.md)                         | Bitbucket README şablonu                                                                         |
 | [PORT-5454-KAPALI.md](docs/PORT-5454-KAPALI.md)                         | Port 5454 kapalı sorun giderme                                                                   |
-| [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)                             | **Çoklu kullanıcı** — Aynı anda birden fazla kişi (port 5454–5470)                               |
+| [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)                             | **Paralel görevler & çoklu kullanıcı** — sabit port, paralel hatlar, Claude çoklu MCP           |
+| [CLAUDE_DESKTOP_CONFIG.md](docs/CLAUDE_DESKTOP_CONFIG.md)               | Claude Desktop config örnekleri (tek ve çoklu MCP sunucusu)                                      |
+| [DEPENDENCY_LAYERS.md](docs/DEPENDENCY_LAYERS.md)                       | Bağımlılık katmanları (plugin-only / tam / Cloudflare) ve olası paket ayrımı taslağı            |
 | [ENTERPRISE.md](docs/ENTERPRISE.md)                                     | **Enterprise** — Audit log, air-gap, Organization plugin                                         |
+| [SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md)                           | **Güvenlik denetimi** — bulgular checklist ([FUTURE.md](FUTURE.md) §10)                            |
 | [PUBLISH-PLUGIN.md](docs/PUBLISH-PLUGIN.md)                             | **Publish plugin** — Figma'da yayınlama: Data security cevapları, final details, Plugin ID       |
 |                                                                         |                                                                                                  |
 

package/dist/cloudflare/cloud-cors.js

@@ -0,0 +1,40 @@
+/**
+ * CORS allowlist for Cloud Mode + remote MCP (claude.ai, v0, Lovable, etc.).
+ */
+const DEFAULT_ALLOWED_ORIGINS = [
+    "https://claude.ai",
+    "https://www.claude.ai",
+    "https://v0.dev",
+    "https://www.v0.dev",
+    "https://lovable.dev",
+    "https://www.lovable.dev",
+];
+export function getAllowedCorsOrigin(request, extra) {
+    const origin = request.headers.get("Origin");
+    if (!origin)
+        return null;
+    const set = new Set([...DEFAULT_ALLOWED_ORIGINS, ...(extra ?? [])]);
+    return set.has(origin) ? origin : null;
+}
+export function corsHeaders(request, extraOrigins) {
+    const o = getAllowedCorsOrigin(request, extraOrigins);
+    const base = {
+        "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Accept, Authorization, mcp-session-id, Mcp-Protocol-Version, mcp-protocol-version",
+        "Access-Control-Expose-Headers": "mcp-session-id",
+        "Access-Control-Max-Age": "86400",
+    };
+    if (o)
+        base["Access-Control-Allow-Origin"] = o;
+    else
+        base["Access-Control-Allow-Origin"] = "*";
+    return base;
+}
+export function withCors(request, response, extraOrigins) {
+    const h = new Headers(response.headers);
+    const ch = corsHeaders(request, extraOrigins);
+    for (const [k, v] of Object.entries(ch)) {
+        h.set(k, v);
+    }
+    return new Response(response.body, { status: response.status, headers: h });
+}

package/dist/cloudflare/cloud-mode-kv.js

@@ -0,0 +1,86 @@
+/**
+ * Cloud Mode pairing / bind / rate-limit helpers (KV: reuses OAUTH_STATE binding).
+ * Key prefixes are reserved to avoid collisions with OAuth state tokens (64+ hex).
+ */
+export const FMCP_PAIR_PREFIX = "fmcp_pair:";
+export const FMCP_BIND_PREFIX = "fmcp_bind:";
+export const FMCP_RL_PREFIX = "fmcp_rl:";
+export const PAIRING_TTL_SEC = 300;
+export const BIND_TTL_SEC = 86400;
+export const PAIRING_CODE_LENGTH = 6;
+const CODE_CHARS = "23456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function generatePairingCode() {
+    let out = "";
+    const arr = new Uint8Array(PAIRING_CODE_LENGTH);
+    crypto.getRandomValues(arr);
+    for (let i = 0; i < PAIRING_CODE_LENGTH; i++) {
+        out += CODE_CHARS[arr[i] % CODE_CHARS.length];
+    }
+    return out;
+}
+export function generatePairingSecret() {
+    const a = new Uint8Array(16);
+    crypto.getRandomValues(a);
+    return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+export async function putPairing(kv, code, record) {
+    await kv.put(`${FMCP_PAIR_PREFIX}${code}`, JSON.stringify(record), {
+        expirationTtl: PAIRING_TTL_SEC,
+    });
+}
+export async function getPairing(kv, code) {
+    const raw = await kv.get(`${FMCP_PAIR_PREFIX}${code}`, "text");
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function deletePairing(kv, code) {
+    await kv.delete(`${FMCP_PAIR_PREFIX}${code}`);
+}
+export async function putBind(kv, mcpSessionId, record) {
+    await kv.put(`${FMCP_BIND_PREFIX}${mcpSessionId}`, JSON.stringify(record), {
+        expirationTtl: BIND_TTL_SEC,
+    });
+}
+export async function getBind(kv, mcpSessionId) {
+    const raw = await kv.get(`${FMCP_BIND_PREFIX}${mcpSessionId}`, "text");
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function deleteBind(kv, mcpSessionId) {
+    await kv.delete(`${FMCP_BIND_PREFIX}${mcpSessionId}`);
+}
+export async function rateLimitAllow(kv, key, limit, windowSec) {
+    const now = Date.now();
+    const raw = await kv.get(key, "text");
+    let stamps = [];
+    if (raw) {
+        try {
+            stamps = JSON.parse(raw).t ?? [];
+        }
+        catch {
+            stamps = [];
+        }
+    }
+    const windowMs = windowSec * 1000;
+    stamps = stamps.filter((ts) => now - ts < windowMs);
+    if (stamps.length >= limit)
+        return false;
+    stamps.push(now);
+    await kv.put(key, JSON.stringify({ t: stamps }), { expirationTtl: Math.max(windowSec * 2, 120) });
+    return true;
+}
+export function clientIp(request) {
+    return request.headers.get("CF-Connecting-IP") || request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim() || "unknown";
+}

package/dist/cloudflare/cloud-mode-routes.js

@@ -0,0 +1,97 @@
+/**
+ * HTTP + WebSocket routes for FMCP Cloud Mode (pairing, plugin bridge).
+ */
+import { corsHeaders, getAllowedCorsOrigin, withCors } from "./cloud-cors.js";
+import { clientIp, FMCP_RL_PREFIX, generatePairingCode, generatePairingSecret, PAIRING_TTL_SEC, putPairing, rateLimitAllow, getPairing, } from "./cloud-mode-kv.js";
+const PAIRING_HTTP_LIMIT = 20;
+const PAIRING_HTTP_WINDOW_SEC = 60;
+function json(data, status = 200, request) {
+    const headers = { "Content-Type": "application/json" };
+    if (request)
+        Object.assign(headers, corsHeaders(request));
+    return new Response(JSON.stringify(data), { status, headers });
+}
+function baseUrl(request) {
+    const u = new URL(request.url);
+    return `${u.protocol}//${u.host}`;
+}
+export async function handleCloudModeRoutes(request, env) {
+    const url = new URL(request.url);
+    if (url.pathname === "/fmcp-cloud/plugin") {
+        if (request.method === "OPTIONS") {
+            return new Response(null, { headers: corsHeaders(request) });
+        }
+        if (request.headers.get("Upgrade") !== "websocket") {
+            return json({ error: "expected_websocket_upgrade" }, 426, request);
+        }
+        const code = url.searchParams.get("code")?.trim().toUpperCase();
+        const secret = url.searchParams.get("secret");
+        if (!code || !secret) {
+            return json({ error: "missing_code_or_secret" }, 400, request);
+        }
+        const pair = await getPairing(env.OAUTH_STATE, code);
+        if (!pair || pair.secret !== secret) {
+            return json({ error: "invalid_or_expired_pairing" }, 401, request);
+        }
+        const id = env.FMCP_RELAY.idFromName(`pair:${code}`);
+        const res = await env.FMCP_RELAY.get(id).fetch(request);
+        return withCors(request, res);
+    }
+    if (url.pathname === "/fmcp-cloud/pairing") {
+        if (request.method === "OPTIONS") {
+            return new Response(null, { headers: corsHeaders(request) });
+        }
+        if (request.method !== "POST") {
+            return json({ error: "method_not_allowed" }, 405, request);
+        }
+        const token = env.FMCP_PAIRING_TOKEN;
+        if (token) {
+            const auth = request.headers.get("Authorization");
+            const expected = `Bearer ${token}`;
+            if (auth !== expected) {
+                return json({ error: "unauthorized" }, 401, request);
+            }
+        }
+        const ip = clientIp(request);
+        const rlKey = `${FMCP_RL_PREFIX}pair:${ip}`;
+        const ok = await rateLimitAllow(env.OAUTH_STATE, rlKey, PAIRING_HTTP_LIMIT, PAIRING_HTTP_WINDOW_SEC);
+        if (!ok) {
+            return json({ error: "rate_limited" }, 429, request);
+        }
+        const code = generatePairingCode();
+        const secret = generatePairingSecret();
+        const record = { secret, createdAt: Date.now() };
+        await putPairing(env.OAUTH_STATE, code, record);
+        const origin = baseUrl(request);
+        const wsProto = url.protocol === "https:" ? "wss:" : "ws:";
+        const wsHost = url.host;
+        const pluginWsUrl = `${wsProto}//${wsHost}/fmcp-cloud/plugin?code=${encodeURIComponent(code)}&secret=${encodeURIComponent(secret)}`;
+        return json({
+            ok: true,
+            code,
+            secret,
+            expiresInSeconds: PAIRING_TTL_SEC,
+            pluginWebSocketUrl: pluginWsUrl,
+            hint: "Paste code and secret into F-MCP plugin Cloud Mode, or share code + secret with your AI to call fmcp_cloud_bind.",
+        }, 200, request);
+    }
+    if (url.pathname === "/fmcp-cloud/health") {
+        return json({ ok: true, cloudMode: true }, 200, request);
+    }
+    return null;
+}
+/** Merge restrictive CORS onto MCP / SSE responses when Origin matches allowlist. */
+export function maybeTightenMcpCors(request, response) {
+    const origin = request.headers.get("Origin");
+    if (!origin)
+        return response;
+    const allowed = getAllowedCorsOrigin(request);
+    if (!allowed)
+        return response;
+    const h = new Headers(response.headers);
+    h.set("Access-Control-Allow-Origin", allowed);
+    if (!h.has("Access-Control-Expose-Headers")) {
+        h.set("Access-Control-Expose-Headers", "mcp-session-id");
+    }
+    return new Response(response.body, { status: response.status, headers: h });
+}

package/dist/cloudflare/cloud-relay-session.js

@@ -0,0 +1,141 @@
+/**
+ * FMCP Cloud Mode — per-pairing-code Durable Object.
+ * Holds the Figma plugin WebSocket and forwards PluginBridge RPC to the plugin.
+ */
+const RPC_TIMEOUT_MS = 120_000;
+export class FmcpRelaySession {
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.pending = new Map();
+        this.env = env;
+    }
+    relayNameFromId() {
+        return this.ctx.id.toString();
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === "POST" && url.pathname.endsWith("/disconnect")) {
+            for (const s of this.ctx.getWebSockets()) {
+                try {
+                    s.close(1000, "disconnect");
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return Response.json({ ok: true, closed: true });
+        }
+        if (request.method === "POST" && url.pathname.endsWith("/rpc")) {
+            return this.handleRpc(request);
+        }
+        if (request.method === "GET" && url.pathname.endsWith("/status")) {
+            const sockets = this.ctx.getWebSockets();
+            const connected = sockets.length > 0;
+            return Response.json({
+                ok: true,
+                pluginConnected: connected,
+                relayId: this.relayNameFromId(),
+            });
+        }
+        if (request.headers.get("Upgrade") !== "websocket") {
+            return new Response("Not found", { status: 404 });
+        }
+        const pair = new WebSocketPair();
+        const [client, server] = Object.values(pair);
+        this.ctx.acceptWebSocket(server);
+        return new Response(null, { status: 101, webSocket: client });
+    }
+    async handleRpc(request) {
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+        }
+        const method = body.method;
+        if (!method || typeof method !== "string") {
+            return Response.json({ ok: false, error: "missing_method" }, { status: 400 });
+        }
+        const sockets = this.ctx.getWebSockets();
+        if (!sockets || sockets.length === 0) {
+            return Response.json({ ok: false, error: "plugin_not_connected" }, { status: 503 });
+        }
+        const ws = sockets[0];
+        const id = `req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        const payload = JSON.stringify({
+            id,
+            method,
+            params: body.params ?? {},
+        });
+        try {
+            const result = await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`Plugin bridge request '${method}' timed out after ${RPC_TIMEOUT_MS}ms`));
+                }, RPC_TIMEOUT_MS);
+                this.pending.set(id, { resolve, reject, timeout });
+                ws.send(payload);
+            });
+            return Response.json({ ok: true, result });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return Response.json({ ok: false, error: msg }, { status: 500 });
+        }
+    }
+    async webSocketMessage(ws, message) {
+        const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        const t = msg.type;
+        if (t === "pong" || t === "keepalive")
+            return;
+        if (t === "ready") {
+            try {
+                ws.send(JSON.stringify({
+                    type: "welcome",
+                    bridgeVersion: "cloud-1.0.0",
+                    port: 0,
+                    clientId: `cloud_${Date.now()}`,
+                    multiClient: false,
+                }));
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        const mid = msg.id;
+        if (mid && this.pending.has(mid)) {
+            const p = this.pending.get(mid);
+            this.pending.delete(mid);
+            clearTimeout(p.timeout);
+            if (msg.error) {
+                p.reject(new Error(String(msg.error)));
+            }
+            else {
+                p.resolve(msg.result);
+            }
+        }
+    }
+    async webSocketClose(_ws, _code, _reason, _wasClean) {
+        for (const [rid, p] of this.pending) {
+            clearTimeout(p.timeout);
+            p.reject(new Error("Plugin disconnected"));
+            this.pending.delete(rid);
+        }
+    }
+    async webSocketError(_ws, _error) {
+        for (const [rid, p] of this.pending) {
+            clearTimeout(p.timeout);
+            p.reject(new Error("Plugin WebSocket error"));
+            this.pending.delete(rid);
+        }
+    }
+}

package/dist/cloudflare/core/config.js

@@ -51,7 +51,7 @@ const DEFAULT_CONFIG = {
     local: {
         debugHost: process.env.FIGMA_DEBUG_HOST || 'localhost',
         debugPort: parseInt(process.env.FIGMA_DEBUG_PORT || '9222', 10),
-        pluginBridgePort: parseInt(process.env.FIGMA_PLUGIN_BRIDGE_PORT || '5454', 10),
+        pluginBridgePort: parseInt(process.env.FIGMA_MCP_BRIDGE_PORT || process.env.FIGMA_PLUGIN_BRIDGE_PORT || '5454', 10),
         auditLogPath: process.env.FIGMA_MCP_AUDIT_LOG_PATH || undefined,
     },
 };