@atezer/figma-mcp-bridge 1.1.1 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +11 -0
- package/README.md +153 -117
- package/dist/cloudflare/core/figma-desktop-connector.js +28 -16
- package/dist/cloudflare/core/plugin-bridge-connector.js +38 -4
- package/dist/cloudflare/core/plugin-bridge-server.js +42 -13
- package/dist/core/figma-desktop-connector.d.ts +6 -2
- package/dist/core/figma-desktop-connector.d.ts.map +1 -1
- package/dist/core/figma-desktop-connector.js +28 -16
- package/dist/core/figma-desktop-connector.js.map +1 -1
- package/dist/core/plugin-bridge-connector.d.ts +18 -2
- package/dist/core/plugin-bridge-connector.d.ts.map +1 -1
- package/dist/core/plugin-bridge-connector.js +38 -4
- package/dist/core/plugin-bridge-connector.js.map +1 -1
- package/dist/core/plugin-bridge-server.d.ts +2 -1
- package/dist/core/plugin-bridge-server.d.ts.map +1 -1
- package/dist/core/plugin-bridge-server.js +42 -13
- package/dist/core/plugin-bridge-server.js.map +1 -1
- package/dist/local-plugin-only.d.ts.map +1 -1
- package/dist/local-plugin-only.js +69 -7
- package/dist/local-plugin-only.js.map +1 -1
- package/f-mcp-plugin/code.js +314 -53
- package/f-mcp-plugin/manifest.json +21 -2
- package/f-mcp-plugin/ui.html +135 -23
- package/package.json +3 -2
package/LICENSE
CHANGED
|
@@ -19,3 +19,14 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
|
19
19
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
20
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
21
|
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
ADDITIONAL RESTRICTION — PERSONAL USE ONLY
|
|
26
|
+
|
|
27
|
+
Notwithstanding the above permissions, this software is licensed for personal,
|
|
28
|
+
non-commercial use only. You may not use the Software for any commercial
|
|
29
|
+
purpose, including but not limited to: use in a commercial product or service,
|
|
30
|
+
use for profit, or use in the course of a business or professional activity,
|
|
31
|
+
without separate written permission from the copyright holder. Personal use
|
|
32
|
+
means use for private, non-commercial purposes only.
|
package/README.md
CHANGED
|
@@ -1,174 +1,205 @@
|
|
|
1
1
|
# F-MCP (Figma MCP Bridge)
|
|
2
2
|
|
|
3
|
-
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
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
### Figma API token tüketmiyor
|
|
6
6
|
|
|
7
7
|
figma-mcp-bridge, Figma'nın **REST API'sini kullanmıyor**. Akış:
|
|
8
8
|
|
|
9
|
-
**Claude (MCP) → figma-mcp-bridge → Plugin → Figma Desktop
|
|
9
|
+
**Claude (MCP) → figma-mcp-bridge → Plugin → Figma (Desktop veya Tarayıcı)**
|
|
10
10
|
|
|
11
|
-
Sorgular doğrudan Figma
|
|
11
|
+
Sorgular doğrudan Figma içinde çalışan plugin üzerinden gider — hem masaüstü uygulaması hem tarayıcı sürümü (figma.com) desteklenir. Bu sayede:
|
|
12
12
|
|
|
13
13
|
- Figma API token tüketimi **yok** (REST API hiç çağrılmıyor)
|
|
14
14
|
- Rate limit yok
|
|
15
15
|
- Figma tarafında ücretlendirme yok
|
|
16
|
-
-
|
|
16
|
+
- Desktop'ta internet bağlantısı gerekmez; tarayıcı Figma'da yalnızca figma.com erişimi yeterli
|
|
17
17
|
|
|
18
18
|
**Ne tüketiliyor?** Sadece AI tarafı: bu konuşmadaki context token'ları. Her tool call'ın request/response'u context penceresine girer. Büyük dosyalarda çok derin sorgular (örn. `depth: 3`, `verbosity: full`) Claude context'ini hızlı doldurabilir; Figma tarafında ek maliyet oluşmaz.
|
|
19
19
|
|
|
20
20
|
### Zero Trust
|
|
21
21
|
|
|
22
|
-
Veri **yalnızca sizin ortamınızda** kalır. Tasarım içeriği Figma bulutuna MCP üzerinden **gönderilmez**; akış Claude → MCP (yerel) → Plugin (yerel) → Figma Desktop
|
|
22
|
+
Veri **yalnızca sizin ortamınızda** kalır. Tasarım içeriği Figma bulutuna MCP üzerinden **gönderilmez**; akış Claude → MCP (yerel) → Plugin (yerel) → Figma (Desktop veya Tarayıcı).
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
REST API çağrısı ve Figma'ya tasarım verisi aktarımı yoktur. Bu sayede kurumsal güvenlik ve gizlilik politikalarına uyum kolaylaşır (Zero Trust: sunucuya güvenme, yerelde doğrula).
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
### Kurumlar için özet
|
|
27
|
+
|
|
28
|
+
- **Debug modu kapalı.** Figma'yı normal açarsınız; ekstra debug portu veya geliştirici ayarı gerekmez.
|
|
29
|
+
- **Kendi plugin story'nizde yayınlama.** Plugin'i Figma Organization (veya Enterprise) altında kendi plugin story'nize yayınladığınızda tüm kullanıcılar **Plugins** menüsünden tek tıkla erişir; "manifest import" zorunluluğu kalkar, merkezi ve erişilebilir bir mimari olur.
|
|
28
30
|
- **KVKK / GDPR uyumu.** Tasarım verisi yalnızca kullanıcının makinesinde (MCP + Plugin + Figma Desktop) kalır; Figma bulutuna veya üçüncü tarafa MCP üzerinden gönderilmez. Veri minimizasyonu ve yerelde işleme, hassas kurumsal ekipler ve denetim gereksinimleri için uygun bir model sunar.
|
|
29
31
|
|
|
30
32
|
## F-MCP yetenekleri
|
|
31
33
|
|
|
32
|
-
**
|
|
34
|
+
**33 araç** (config'te `dist/local-plugin-only.js` kullanıldığında tamamı aktif). Tam liste: [TOOLS_FULL_LIST.md](docs/TOOLS_FULL_LIST.md). Aşağıda rollerine göre özet.
|
|
33
35
|
|
|
34
36
|
### Ürün yöneticileri (analiz, kabul kriterleri, kurumsal süreçler)
|
|
35
37
|
|
|
36
38
|
|
|
37
|
-
| Kullanım | Araçlar | Açıklama
|
|
38
|
-
| --------------------------------- | ----------------------------------------------------------------- |
|
|
39
|
-
| Tasarım envanteri ve analiz | `figma_get_design_system_summary`, `figma_get_file_data` |
|
|
40
|
-
| Kabul kriterleri ve dokümantasyon | `figma_get_component_for_development`, `figma_capture_screenshot` | Bileşen spec + görsel; test ve kabul için referans
|
|
41
|
-
| 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
|
|
42
|
-
| Keşif ve durum | `figma_search_components`, `figma_get_status` | Bileşen arama, bağlantı kontrolü
|
|
39
|
+
| Kullanım | Araçlar | Açıklama |
|
|
40
|
+
| --------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| 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) |
|
|
42
|
+
| Kabul kriterleri ve dokümantasyon | `figma_get_component_for_development`, `figma_capture_screenshot` | Bileşen spec + görsel; test ve kabul için referans |
|
|
43
|
+
| 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 |
|
|
44
|
+
| Keşif ve durum | `figma_search_components`, `figma_get_status` | Bileşen arama (varsayılan currentPageOnly), bağlantı kontrolü |
|
|
43
45
|
|
|
44
46
|
|
|
45
47
|
### Geliştiriciler
|
|
46
48
|
|
|
47
49
|
|
|
48
|
-
| Kullanım
|
|
49
|
-
|
|
|
50
|
-
| Bileşen ve implementasyon
|
|
51
|
-
| Token ve stil kodu
|
|
52
|
-
| Dosya yapısı
|
|
53
|
-
| Çalıştırma ve doğrulama
|
|
50
|
+
| Kullanım | Araçlar | Açıklama |
|
|
51
|
+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
52
|
+
| Bileşen ve implementasyon | `figma_get_component`, `figma_get_component_for_development`, `figma_get_component_image`, `figma_instantiate_component`, `figma_set_instance_properties` | Metadata, screenshot, instance oluşturma ve property güncelleme |
|
|
53
|
+
| Token ve stil kodu | `figma_get_variables`, `figma_get_styles` | Değişkenler ve stiller (CSS/Tailwind/TS export) |
|
|
54
|
+
| Dosya yapısı / design context | `figma_get_file_data`, `figma_get_design_context` | Yapı, metin, layout, renk, font; SUI bileşen/token adı, layoutSummary, colorHex, fillVariableNames; outputHint: react/tailwind |
|
|
55
|
+
| Çalıştırma ve doğrulama | `figma_execute`, `figma_capture_screenshot`, `figma_get_console_logs`, `figma_watch_console`, `figma_clear_console` | Plugin API'de JS, screenshot, console log okuma/izleme/temizleme |
|
|
54
56
|
|
|
55
57
|
|
|
56
58
|
### DesignOps ve tasarımcılar
|
|
57
59
|
|
|
58
60
|
|
|
59
|
-
| Kullanım | Araçlar | Açıklama
|
|
60
|
-
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
61
|
-
| DesignOps (kritik) | `figma_check_design_parity`, `figma_setup_design_tokens`, `figma_batch_create_variables`, `figma_batch_update_variables` | Design–code gap, koleksiyon+modlar+variable (rollback), toplu token yönetimi
|
|
62
|
-
| Değişken ve stil yönetimi | `figma_get_variables`, `figma_get_styles`, `figma_create_variable_collection`, `figma_create_variable`, `figma_update_variable`, `figma_delete_variable`, `figma_rename_variable`, `figma_add_mode`, `figma_rename_mode`, `figma_refresh_variables`, `figma_get_token_browser` | Tüm variable/stil CRUD ve Token Browser
|
|
63
|
-
| Bileşen kütüphanesi | `figma_get_design_system_summary`, `figma_search_components`, `figma_arrange_component_set`, `figma_set_description` | Özet
|
|
61
|
+
| Kullanım | Araçlar | Açıklama |
|
|
62
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
|
63
|
+
| DesignOps (kritik) | `figma_check_design_parity`, `figma_setup_design_tokens`, `figma_batch_create_variables`, `figma_batch_update_variables` | Design–code gap, koleksiyon+modlar+variable (rollback), toplu token yönetimi |
|
|
64
|
+
| Değişken ve stil yönetimi | `figma_get_variables`, `figma_get_styles`, `figma_create_variable_collection`, `figma_create_variable`, `figma_update_variable`, `figma_delete_variable`, `figma_rename_variable`, `figma_add_mode`, `figma_rename_mode`, `figma_refresh_variables`, `figma_get_token_browser` | Tüm variable/stil CRUD ve Token Browser |
|
|
65
|
+
| Bileşen kütüphanesi | `figma_get_design_system_summary`, `figma_search_components`, `figma_arrange_component_set`, `figma_set_description` | Özet/arama (currentPageOnly varsayılan; SUI/büyük dosyada timeout önlemi), variant set, dokümantasyon |
|
|
64
66
|
|
|
65
67
|
|
|
66
|
-
Kurulum: **[Kurulum rehberi (Onboarding)](docs/ONBOARDING.md)
|
|
68
|
+
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).
|
|
67
69
|
|
|
68
70
|
## Hızlı başlangıç
|
|
69
71
|
|
|
70
|
-
Plugin'in "ready" olması için **önce** MCP bridge sunucusu
|
|
72
|
+
Plugin'in **"ready (:5454)"** olması için **önce** MCP bridge sunucusu çalışıyor olmalı; **sonra** Figma'da plugin'i açarsınız.
|
|
71
73
|
|
|
72
|
-
|
|
74
|
+
> **⚠️ Önemli:** Cursor veya Claude Desktop kullanıyorsanız `npm run dev:local` **çalıştırMAYIN**. MCP sunucusu bu uygulamalar tarafından otomatik başlatılır. İki sunucu aynı anda çalışırsa port çatışması oluşur ve plugin yanlış sunucuya bağlanabilir.
|
|
73
75
|
|
|
74
|
-
|
|
76
|
+
### En basit kurulum (NPX — repo indirmeden)
|
|
75
77
|
|
|
76
|
-
|
|
77
|
-
cd <proje-yolu> # clone ettiğiniz proje klasörü (örn. f-mcp-bridge)
|
|
78
|
-
npm install
|
|
79
|
-
npm run dev:local
|
|
80
|
-
```
|
|
78
|
+
Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek için paket otomatik güncellenir (`@latest`).
|
|
81
79
|
|
|
82
|
-
Çıktıda `Plugin bridge server listening` veya `5454` geçen bir satır görünene kadar bekleyin. Bu, plugin'in bağlanacağı sunucudur.
|
|
83
80
|
|
|
84
|
-
|
|
81
|
+
| Adım | Yapılacak |
|
|
82
|
+
| ---- | ------------------------------------------------------------------------------------------------------------ |
|
|
83
|
+
| 1 | **Node.js kur** — [nodejs.org](https://nodejs.org) LTS. Terminalde `node -v` ile kontrol edin. |
|
|
84
|
+
| 2 | **MCP config ekle** — Aşağıdaki JSON bloğunu Cursor veya Claude config dosyasına ekleyin. |
|
|
85
|
+
| 3 | **Cursor veya Claude'u yeniden başlatın** — MCP sunucusu port 5454'te otomatik başlar. |
|
|
86
|
+
| 4 | **Figma'da plugini açın** — Plugins → **F-MCP ATezer Bridge** → **"ready (:5454)"** görünene kadar bekleyin. |
|
|
85
87
|
|
|
86
|
-
1. Figma'yı açın.
|
|
87
|
-
2. **Plugins** → **Development** → **Import plugin from manifest…**
|
|
88
|
-
3. Bu repodaki `f-mcp-plugin/manifest.json` dosyasını seçin
|
|
89
|
-
4. Plugin listede "F-MCP ATezer Bridge" olarak görünür.
|
|
90
88
|
|
|
91
|
-
|
|
89
|
+
**Cursor** — Proje kökünde veya kullanıcı dizininde `.cursor/mcp.json`:
|
|
92
90
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"figma-mcp-bridge": {
|
|
95
|
+
"command": "npx",
|
|
96
|
+
"args": ["-y", "@atezer/figma-mcp-bridge@latest"]
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
97
101
|
|
|
102
|
+
**Claude Desktop** — macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` | Windows: `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
98
103
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"mcpServers": {
|
|
107
|
+
"figma-mcp-bridge": {
|
|
108
|
+
"command": "npx",
|
|
109
|
+
"args": ["-y", "@atezer/figma-mcp-bridge@latest"]
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
104
114
|
|
|
115
|
+
İ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.
|
|
105
116
|
|
|
106
|
-
|
|
117
|
+
### A) Clone + build ile (Cursor / Claude)
|
|
107
118
|
|
|
108
|
-
|
|
119
|
+
Repo'yu indirip kendi makinenizde build etmek isterseniz (ör. ağ erişimi kısıtlı ortam):
|
|
109
120
|
|
|
110
|
-
|
|
121
|
+
**1. Build (bir kez):**
|
|
111
122
|
|
|
112
123
|
```bash
|
|
124
|
+
cd <proje-yolu>
|
|
125
|
+
npm install
|
|
113
126
|
npm run build:local
|
|
114
127
|
```
|
|
115
128
|
|
|
116
|
-
|
|
129
|
+
**2. MCP config** — `command`: `"node"`, `args`: `["<PROJE-YOLU>/dist/local-plugin-only.js"]` (tam yolu yazın).
|
|
117
130
|
|
|
118
|
-
|
|
131
|
+
**Cursor** — `.cursor/mcp.json` | **Claude** — `claude_desktop_config.json` (yolu yukarıdaki gibi).
|
|
119
132
|
|
|
120
|
-
**
|
|
133
|
+
**3. Cursor/Claude'u yeniden başlatın.**
|
|
134
|
+
**4. Figma'da plugini çalıştırın** → **"ready (:5454)"** bekleyin.
|
|
121
135
|
|
|
122
|
-
|
|
123
|
-
{
|
|
124
|
-
"mcpServers": {
|
|
125
|
-
"figma-mcp-bridge": {
|
|
126
|
-
"command": "node",
|
|
127
|
-
"args": ["<BU-REPONUN-TAM-YOLU>/dist/local-plugin-only.js"]
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
```
|
|
136
|
+
> **Permission denied?** `"command": "bash"`, `"args": ["-c", "cd <PROJE-YOLU> && exec node dist/local-plugin-only.js"]` kullanın.
|
|
132
137
|
|
|
133
|
-
|
|
138
|
+
### B) Manuel geliştirme / debug
|
|
134
139
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
+
> **Bu yöntem sadece bridge/plugin geliştirmesi veya debug içindir.** Cursor/Claude Desktop ile aynı anda **kullanmayın**.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
cd <proje-yolu>
|
|
144
|
+
npm install
|
|
145
|
+
npm run dev:local
|
|
140
146
|
```
|
|
141
147
|
|
|
142
|
-
|
|
148
|
+
Çıktıda `Plugin bridge server listening` geçen satırı görünce Figma'da plugin'i açın.
|
|
143
149
|
|
|
144
|
-
|
|
145
|
-
"figma-mcp-bridge": {
|
|
146
|
-
"command": "node",
|
|
147
|
-
"args": ["<BU-REPONUN-TAM-YOLU>/dist/local.js"]
|
|
148
|
-
}
|
|
149
|
-
```
|
|
150
|
+
> **Port çatışması:** Aynı porta iki F-MCP bridge bağlanamaz. Port meşgulse sunucu açık hata mesajı verir ve durur (sessiz port değiştirme yoktur). `lsof -i :5454` (macOS/Linux) veya `netstat -ano | findstr :5454` (Windows) ile mevcut process'i bulun ve kapatın.
|
|
150
151
|
|
|
151
|
-
|
|
152
|
+
### Plugin'i Figma'ya yükleyin (ilk seferde)
|
|
152
153
|
|
|
153
|
-
|
|
154
|
+
1. Figma'yı açın.
|
|
155
|
+
2. **Plugins** → **Development** → **Import plugin from manifest…**
|
|
156
|
+
3. Bu repodaki `f-mcp-plugin/manifest.json` dosyasını seçin.
|
|
157
|
+
4. Plugin listede "F-MCP ATezer Bridge" olarak görünür.
|
|
154
158
|
|
|
155
|
-
###
|
|
159
|
+
### Plugin durum göstergeleri
|
|
156
160
|
|
|
157
161
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
162
|
+
| Durum | Anlam |
|
|
163
|
+
| --------------- | ----------------------------------------------------------------------- |
|
|
164
|
+
| `connecting...` | WebSocket açıldı, sunucudan handshake bekleniyor |
|
|
165
|
+
| `ready (:5454)` | F-MCP bridge'e başarıyla bağlandı (port numarası gösterilir) |
|
|
166
|
+
| `wrong server` | Bağlantı kuruldu ama karşıdaki F-MCP bridge değil (eski/yanlış process) |
|
|
167
|
+
| `no server` | Sunucu kapalı veya erişilemiyor |
|
|
164
168
|
|
|
165
169
|
|
|
166
|
-
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Claude / Cursor ile bağlama (detay)
|
|
167
173
|
|
|
168
|
-
|
|
174
|
+
**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).
|
|
175
|
+
|
|
176
|
+
**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.
|
|
177
|
+
|
|
178
|
+
**Ç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).
|
|
169
179
|
|
|
170
180
|
**Enterprise:** Audit log (`FIGMA_MCP_AUDIT_LOG_PATH`), air-gap kurulum ve Organization plugin: [ENTERPRISE.md](docs/ENTERPRISE.md).
|
|
171
181
|
|
|
182
|
+
**"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`.
|
|
183
|
+
|
|
184
|
+
### Browser Figma desteği
|
|
185
|
+
|
|
186
|
+
Plugin, Figma'nın **tarayıcı sürümünde** de (figma.com) çalışır. Desktop uygulaması zorunlu değildir.
|
|
187
|
+
|
|
188
|
+
**Aynı makinede (tarayıcı + MCP bridge aynı bilgisayarda):**
|
|
189
|
+
|
|
190
|
+
1. MCP bridge sunucusunu başlatın (Cursor/Claude Desktop açın veya `npm run dev:local`).
|
|
191
|
+
2. Figma'yı tarayıcıda açın → Plugin'i çalıştırın.
|
|
192
|
+
3. Plugin UI'da Host: `localhost`, Port: `5454` → **"ready (:5454)"** göründüğünde hazır.
|
|
193
|
+
|
|
194
|
+
**Uzak makinede (tarayıcı bir bilgisayarda, MCP bridge başka bir makinede):**
|
|
195
|
+
|
|
196
|
+
1. MCP bridge makinesinde `FIGMA_BRIDGE_HOST=0.0.0.0` env var ile sunucuyu başlatın (tüm ağ arayüzlerinden erişim açılır).
|
|
197
|
+
2. Plugin UI'da Host alanına MCP bridge makinesinin IP adresini girin (örn. `192.168.1.50`), Port: `5454`.
|
|
198
|
+
3. **Manifest güncellemesi gerekir:** Uzak IP'yi `manifest.json` dosyasındaki `networkAccess.allowedDomains` dizisine ekleyin (örn. `"ws://192.168.1.50:5454"`). Organization plugin olarak dağıtıldığında admin bunu yapılandırır.
|
|
199
|
+
4. Firewall'da port 5454'ün açık olduğundan emin olun.
|
|
200
|
+
|
|
201
|
+
> **Güvenlik:** Default olarak sunucu yalnızca `127.0.0.1`'de dinler (Zero Trust). Uzak erişim için `FIGMA_BRIDGE_HOST=0.0.0.0` **bilinçli olarak** ayarlanmalı ve firewall ile korunmalıdır.
|
|
202
|
+
|
|
172
203
|
---
|
|
173
204
|
|
|
174
205
|
## Design / Dev Mode
|
|
@@ -181,6 +212,7 @@ Config (macOS): `**~/Library/Application Support/Claude/claude_desktop_config.js
|
|
|
181
212
|
|
|
182
213
|
Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun giderme için:
|
|
183
214
|
|
|
215
|
+
- **[Windows kurulum rehberi](docs/WINDOWS-INSTALLATION.md)** — Windows 10/11, Node veya Python bridge, Claude config, port, sorun giderme
|
|
184
216
|
- **[Plugin–MCP Bağlantı Rehberi](docs/PLUGIN-MCP-BAGLANTI.md)** (mimari, kurulum, sözleşmeler)
|
|
185
217
|
- **[Plugin Nasıl Çalışır?](docs/PLUGIN-NASIL-CALISIR.md)** (Worker/UI akışı, WebSocket vs CDP)
|
|
186
218
|
|
|
@@ -189,32 +221,36 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
|
|
|
189
221
|
- `f-mcp-plugin/` – F-MCP ATezer Bridge plugin kaynağı (manifest, code.js, ui.html)
|
|
190
222
|
- `docs/` – Kurulum, mod karşılaştırma, [Plugin nasıl çalışır](docs/PLUGIN-NASIL-CALISIR.md), sorun giderme
|
|
191
223
|
- `src/` – MCP sunucusu (local, plugin-only, Cloudflare Worker)
|
|
224
|
+
- `python-bridge/` – **Python MCP bridge** (Node.js kurulumu olmayan ortamlar için); aynı WebSocket protokolü, port 5454
|
|
192
225
|
|
|
193
226
|
### Tüm dokümanlar (docs/)
|
|
194
227
|
|
|
195
228
|
|
|
196
|
-
| Dosya
|
|
197
|
-
|
|
|
198
|
-
| [ONBOARDING.md](docs/ONBOARDING.md)
|
|
199
|
-
| [
|
|
200
|
-
| [
|
|
201
|
-
| [PLUGIN-
|
|
202
|
-
| [
|
|
203
|
-
| [
|
|
204
|
-
| [
|
|
205
|
-
| [
|
|
206
|
-
| [
|
|
207
|
-
| [
|
|
208
|
-
| [
|
|
209
|
-
| [
|
|
210
|
-
| [
|
|
211
|
-
| [
|
|
212
|
-
| [
|
|
213
|
-
| [
|
|
214
|
-
| [
|
|
215
|
-
| [
|
|
216
|
-
| [
|
|
217
|
-
|
|
|
229
|
+
| Dosya | Açıklama |
|
|
230
|
+
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
231
|
+
| [ONBOARDING.md](docs/ONBOARDING.md) | **Kurulum rehberi (Onboarding)** — Plugin yükle, Node.js, MCP başlat, Claude config |
|
|
232
|
+
| [WINDOWS-INSTALLATION.md](docs/WINDOWS-INSTALLATION.md) | **Windows kurulum** — Node veya Python bridge, Claude config (Windows yolu), port, sorun giderme |
|
|
233
|
+
| [SETUP.md](docs/SETUP.md) | Kurulum (Remote / Local) |
|
|
234
|
+
| [PLUGIN-MCP-BAGLANTI.md](docs/PLUGIN-MCP-BAGLANTI.md) | Plugin–MCP mimari ve kurulum |
|
|
235
|
+
| [PLUGIN-NASIL-CALISIR.md](docs/PLUGIN-NASIL-CALISIR.md) | Plugin Worker/UI akışı |
|
|
236
|
+
| [MODE_COMPARISON.md](docs/MODE_COMPARISON.md) | Mod karşılaştırma |
|
|
237
|
+
| [TOOLS.md](docs/TOOLS.md) | MCP araçları referansı |
|
|
238
|
+
| [TOOLS_FULL_LIST.md](docs/TOOLS_FULL_LIST.md) | **33 araç tam liste** (referans, Claude ile doğrulanmış) |
|
|
239
|
+
| [DEVELOPER_FIGMA_CAPABILITIES.md](docs/DEVELOPER_FIGMA_CAPABILITIES.md) | **Cursor + F-MCP:** Neyi alır/almaz, birebir çıkartma, code-ready/SUI/token referansı, ileride |
|
|
240
|
+
| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Sorun giderme |
|
|
241
|
+
| [NPX-INSTALLATION.md](docs/NPX-INSTALLATION.md) | NPX ile kurulum |
|
|
242
|
+
| [OAUTH_SETUP.md](docs/OAUTH_SETUP.md) | OAuth (remote sunucu) |
|
|
243
|
+
| [SELF_HOSTING.md](docs/SELF_HOSTING.md) | Kendi sunucunda host |
|
|
244
|
+
| [DEPLOYMENT_COMPARISON.md](docs/DEPLOYMENT_COMPARISON.md) | Dağıtım karşılaştırma |
|
|
245
|
+
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Teknik mimari |
|
|
246
|
+
| [USE_CASES.md](docs/USE_CASES.md) | Örnek kullanım senaryoları |
|
|
247
|
+
| [RECONSTRUCTION_FORMAT.md](docs/RECONSTRUCTION_FORMAT.md) | Reconstruction format |
|
|
248
|
+
| [BITBUCKET-README.md](docs/BITBUCKET-README.md) | Bitbucket README şablonu |
|
|
249
|
+
| [PORT-5454-KAPALI.md](docs/PORT-5454-KAPALI.md) | Port 5454 kapalı sorun giderme |
|
|
250
|
+
| [MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | **Çoklu kullanıcı** — Aynı anda birden fazla kişi (port 5454–5470) |
|
|
251
|
+
| [ENTERPRISE.md](docs/ENTERPRISE.md) | **Enterprise** — Audit log, air-gap, Organization plugin |
|
|
252
|
+
| [PUBLISH-PLUGIN.md](docs/PUBLISH-PLUGIN.md) | **Publish plugin** — Figma'da yayınlama: Data security cevapları, final details, Plugin ID |
|
|
253
|
+
| | |
|
|
218
254
|
|
|
219
255
|
|
|
220
256
|
## Yaygınlaştırma: Organization (private) plugin
|
|
@@ -224,18 +260,18 @@ Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun gi
|
|
|
224
260
|
**Avantajlar:**
|
|
225
261
|
|
|
226
262
|
- Herkesin "Import plugin from manifest" yapması gerekmez; plugin organizasyonun plugin listesinde görünür.
|
|
227
|
-
- Sadece **Plugins** menüsünden (veya Resources → Plugins) ekleyip çalıştırırlar; MCP bridge
|
|
263
|
+
- Sadece **Plugins** menüsünden (veya Resources → Plugins) ekleyip çalıştırırlar; MCP bridge'i (Claude config) kendi makinede kurmaları yeterli.
|
|
228
264
|
- Review süreci yok (private plugin); yayınladıktan kısa süre sonra kullanılabilir.
|
|
229
265
|
|
|
230
266
|
**Gereksinimler:**
|
|
231
267
|
|
|
232
268
|
- Figma **Organization** veya **Enterprise** planı ([Figma: Create private organization plugins](https://help.figma.com/hc/en-us/articles/4404228629655-Create-private-organization-plugins)).
|
|
233
|
-
- Yayınlama: [Publish plugins](https://help.figma.com/hc/en-us/articles/360042293394) adımlarını izleyin; **Publish to** kısmında **organization
|
|
269
|
+
- Yayınlama: [Publish plugins](https://help.figma.com/hc/en-us/articles/360042293394) adımlarını izleyin; **Publish to** kısmında **organization**'ı seçin (Community değil).
|
|
234
270
|
|
|
235
|
-
**Özet:** Önce organization private plugin yapmak, "plugin
|
|
271
|
+
**Özet:** Önce organization private plugin yapmak, "plugin'i herkese tek tıkla ulaştırma" adımını çözer; MCP tarafında (Claude config, build, port) kurulum aynı kalır. Sonrasında isteğe bağlı olarak Community'e açmak veya self-host MCP ile tam entegrasyon düşünülebilir.
|
|
236
272
|
|
|
237
273
|
## Lisans ve Destek
|
|
238
274
|
|
|
239
|
-
- **Lisans:** MIT (bkz. [LICENSE](LICENSE))
|
|
275
|
+
- **Lisans:** MIT tabanlı, ek kısıt: ticari amaçlı kullanılmaz; sadece kişisel kullanım içindir (bkz. [LICENSE](LICENSE))
|
|
240
276
|
- **Sorun bildirimi:** [GitHub Issues](https://github.com/atezer/FMCP/issues)
|
|
241
277
|
|
|
@@ -105,18 +105,27 @@ export class FigmaDesktopConnector {
|
|
|
105
105
|
await this.page.evaluate((url) => {
|
|
106
106
|
console.log(`[DESKTOP_CONNECTOR] Checking frame: ${url}`);
|
|
107
107
|
}, frameUrl);
|
|
108
|
-
// Check if this frame
|
|
108
|
+
// Check if this frame is our plugin UI (cached data or refreshVariables for dynamic-page)
|
|
109
109
|
const hasData = await frame.evaluate('typeof window.__figmaVariablesData !== "undefined" && window.__figmaVariablesReady === true');
|
|
110
|
-
await
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
110
|
+
const hasRefresh = await frame.evaluate('typeof window.refreshVariables === "function"');
|
|
111
|
+
await this.page.evaluate((url, has, hasRef) => {
|
|
112
|
+
console.log(`[DESKTOP_CONNECTOR] Frame ${url} has variables data: ${has}, refreshVariables: ${hasRef}`);
|
|
113
|
+
}, frameUrl, hasData, hasRefresh);
|
|
114
|
+
if (hasData || hasRefresh) {
|
|
114
115
|
logger.info({ frameUrl }, 'Found frame with variables data');
|
|
115
116
|
await this.page.evaluate((url) => {
|
|
116
117
|
console.log(`[DESKTOP_CONNECTOR] ✅ SUCCESS! Found plugin UI with variables data: ${url}`);
|
|
117
118
|
}, frameUrl);
|
|
118
|
-
//
|
|
119
|
-
const result = await frame.evaluate(
|
|
119
|
+
// Refresh first (async API in plugin) so variables work in dynamic-page context, then get data
|
|
120
|
+
const result = (await frame.evaluate(() => new Promise((resolve, reject) => {
|
|
121
|
+
const win = globalThis;
|
|
122
|
+
if (typeof win.refreshVariables === 'function') {
|
|
123
|
+
win.refreshVariables().then(() => resolve(win.__figmaVariablesData)).catch(reject);
|
|
124
|
+
}
|
|
125
|
+
else {
|
|
126
|
+
resolve(win.__figmaVariablesData);
|
|
127
|
+
}
|
|
128
|
+
})));
|
|
120
129
|
logger.info({
|
|
121
130
|
variableCount: result.variables?.length,
|
|
122
131
|
collectionCount: result.variableCollections?.length
|
|
@@ -135,8 +144,7 @@ export class FigmaDesktopConnector {
|
|
|
135
144
|
continue;
|
|
136
145
|
}
|
|
137
146
|
}
|
|
138
|
-
|
|
139
|
-
throw new Error('No plugin UI found with variables data. Make sure the Variables Exporter (Persistent) plugin is running.');
|
|
147
|
+
throw new Error('No plugin UI found with variables data. Make sure the F-MCP ATezer Bridge plugin is running.');
|
|
140
148
|
}
|
|
141
149
|
catch (error) {
|
|
142
150
|
logger.error({ error }, 'Failed to get variables from plugin UI');
|
|
@@ -702,16 +710,20 @@ export class FigmaDesktopConnector {
|
|
|
702
710
|
}
|
|
703
711
|
}
|
|
704
712
|
/**
|
|
705
|
-
* Get all local components for design system manifest generation
|
|
713
|
+
* Get all local components for design system manifest generation.
|
|
714
|
+
* Defaults to currentPageOnly: true to avoid timeout on large files (dynamic-page).
|
|
706
715
|
*/
|
|
707
|
-
async getLocalComponents() {
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
716
|
+
async getLocalComponents(opts) {
|
|
717
|
+
const currentPageOnly = opts?.currentPageOnly !== false;
|
|
718
|
+
const limit = opts?.limit ?? 0;
|
|
719
|
+
await this.page.evaluate((cp, lim) => {
|
|
720
|
+
console.log('[DESKTOP_CONNECTOR] getLocalComponents() called, currentPageOnly:', cp, 'limit:', lim);
|
|
721
|
+
}, currentPageOnly, limit);
|
|
722
|
+
logger.info({ currentPageOnly, limit }, 'Getting local components via plugin UI');
|
|
712
723
|
const frame = await this.findPluginUIFrame();
|
|
713
724
|
try {
|
|
714
|
-
|
|
725
|
+
// Runs in browser iframe; globalThis is the window there
|
|
726
|
+
const result = await frame.evaluate((cp, lim) => globalThis.getLocalComponents(cp, lim), currentPageOnly, limit);
|
|
715
727
|
logger.info({
|
|
716
728
|
success: result.success,
|
|
717
729
|
componentCount: result.data?.totalComponents,
|
|
@@ -54,8 +54,13 @@ export class PluginBridgeConnector {
|
|
|
54
54
|
async refreshVariables() {
|
|
55
55
|
return this.bridge.request("refreshVariables", {});
|
|
56
56
|
}
|
|
57
|
-
async getLocalComponents() {
|
|
58
|
-
|
|
57
|
+
async getLocalComponents(opts) {
|
|
58
|
+
const params = {};
|
|
59
|
+
if (opts?.currentPageOnly !== undefined)
|
|
60
|
+
params.currentPageOnly = opts.currentPageOnly;
|
|
61
|
+
if (opts?.limit != null && opts.limit > 0)
|
|
62
|
+
params.limit = opts.limit;
|
|
63
|
+
return this.bridge.request("getLocalComponents", params);
|
|
59
64
|
}
|
|
60
65
|
async instantiateComponent(componentKey, options) {
|
|
61
66
|
return this.bridge.request("instantiateComponent", { componentKey, options });
|
|
@@ -111,8 +116,37 @@ export class PluginBridgeConnector {
|
|
|
111
116
|
async setInstanceProperties(nodeId, properties) {
|
|
112
117
|
return this.bridge.request("setInstanceProperties", { nodeId, properties });
|
|
113
118
|
}
|
|
114
|
-
async getDocumentStructure(depth, verbosity) {
|
|
115
|
-
|
|
119
|
+
async getDocumentStructure(depth, verbosity, opts) {
|
|
120
|
+
const params = { depth: depth ?? 1, verbosity: verbosity ?? "summary" };
|
|
121
|
+
if (opts?.includeLayout !== undefined)
|
|
122
|
+
params.includeLayout = opts.includeLayout;
|
|
123
|
+
if (opts?.includeVisual !== undefined)
|
|
124
|
+
params.includeVisual = opts.includeVisual;
|
|
125
|
+
if (opts?.includeTypography !== undefined)
|
|
126
|
+
params.includeTypography = opts.includeTypography;
|
|
127
|
+
if (opts?.includeCodeReady !== undefined)
|
|
128
|
+
params.includeCodeReady = opts.includeCodeReady;
|
|
129
|
+
if (opts?.outputHint !== undefined)
|
|
130
|
+
params.outputHint = opts.outputHint;
|
|
131
|
+
return this.bridge.request("getDocumentStructure", params);
|
|
132
|
+
}
|
|
133
|
+
async getNodeContext(nodeId, depth, verbosity, opts) {
|
|
134
|
+
const params = {
|
|
135
|
+
nodeId,
|
|
136
|
+
depth: depth ?? 2,
|
|
137
|
+
verbosity: verbosity ?? "standard",
|
|
138
|
+
};
|
|
139
|
+
if (opts?.includeLayout !== undefined)
|
|
140
|
+
params.includeLayout = opts.includeLayout;
|
|
141
|
+
if (opts?.includeVisual !== undefined)
|
|
142
|
+
params.includeVisual = opts.includeVisual;
|
|
143
|
+
if (opts?.includeTypography !== undefined)
|
|
144
|
+
params.includeTypography = opts.includeTypography;
|
|
145
|
+
if (opts?.includeCodeReady !== undefined)
|
|
146
|
+
params.includeCodeReady = opts.includeCodeReady;
|
|
147
|
+
if (opts?.outputHint !== undefined)
|
|
148
|
+
params.outputHint = opts.outputHint;
|
|
149
|
+
return this.bridge.request("getNodeContext", params);
|
|
116
150
|
}
|
|
117
151
|
async getLocalStyles(verbosity) {
|
|
118
152
|
return this.bridge.request("getLocalStyles", { verbosity: verbosity ?? "summary" });
|