<p align="center">
  <img src="assets/logo.png" alt="F-MCP Bridge Logo" width="280" />
</p>

# F-MCP (Figma MCP Bridge)

<p align="center">
  <a href="https://www.npmjs.com/package/@atezer/figma-mcp-bridge"><img src="https://img.shields.io/npm/v/@atezer/figma-mcp-bridge?label=npm&color=0A7CFF" alt="npm"></a>
  <a href="https://github.com/atezer/FMCP/releases/tag/v1.9.14"><img src="https://img.shields.io/badge/sürüm-v1.9.14-success" alt="version"></a>
  <img src="https://img.shields.io/badge/araç-63-blue" alt="63 tools">
  <img src="https://img.shields.io/badge/skill-28-blue" alt="28 skills">
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-güncel-brightgreen" alt="changelog"></a>
</p>

> **Yeni — v1.9.14 Contract Extractor:** Bir Component Set'i seçin, `figma_extract_contract` deyin — props, anatomy token binding'leri, variant override diff'leri, mode bazlı resolved token'lar, WCAG kontrast denetimi ve base spec'ler tek design contract JSON'unda. Design-to-code handoff'un tek doğruluk kaynağı. Detay: [Release notes](https://github.com/atezer/FMCP/releases/tag/v1.9.14) · [extract-contract SKILL](skills/extract-contract/SKILL.md).
>
> **Son sürüm — v1.9.14 (31 Temmuz 2026):** Contract Extractor — Component Set → design contract JSON spec (63 tool, 132/132 test). Önceki öne çıkanlar: v1.9.13 sıfır-kurulum DS oto-uyumlanma, v1.9.11 Prototype Connections + Animations ([figma-prototype-flow](skills/figma-prototype-flow/SKILL.md)). Detay: [CHANGELOG](CHANGELOG.md) · [Release notes](https://github.com/atezer/FMCP/releases/tag/v1.9.14)

Figma tasarımlarınızı AI'a bağlar. AI'a *"Bu ekrandaki renkleri çıkar"* veya *"Yeni bir login sayfası oluştur"* dersiniz — AI Figma'daki tasarımınızla doğrudan çalışır.

Her şey **bilgisayarınızda** kalır. Tasarım verileriniz internete gönderilmez.

---

## Neye ihtiyacım var?

| Gerekli | Açıklama |
|---------|----------|
| **Figma** | Zaten kullanıyorsanız hazırsınız |
| **Claude Code** | Kurulumu yapacak uygulama — [claude.ai/download](https://claude.ai/download) adresinden indirin |

> **Claude Code nedir?** Bilgisayarınızda çalışan Claude versiyonu. Dosya oluşturabilir, komut çalıştırabilir, kurulum yapabilir. İndirdikten sonra kurulum için sadece bir kez kullanacaksınız.

---

## Kurulum (5 dakika)

**1.** [Claude Code'u indirin](https://claude.ai/download) (henüz yoksa)

**2.** Claude Code'u açın ve şunu yazın:

> *"https://github.com/atezer/FMCP bu repoyu kur"*

Claude gerekli her şeyi (Node.js, build, ayarlar) otomatik yapar. Sizden sadece gerekirse **bilgisayar şifreniz** istenir.

**3.** Claude "kurulum tamamlandı" deyince **Claude Code'u kapatıp tekrar açın**

**4.** Figma'da **Plugins → F-MCP ATezer Bridge** açın → yeşil **"Ready"** görün

**5.** Hazırsınız! Claude'a Figma ile ilgili sorularınızı sorun.

> **Plugin'i ilk kez mi yüklüyorsunuz?** Figma → Plugins → Development → Import plugin from manifest → `f-mcp-plugin/manifest.json`
>
> **Kurumsal kullanım:** Plugin organizasyonda yayınlandıysa import gerekmez — Plugins menüsünden doğrudan çalıştırın.

---

## Kurulumdan sonra hangi Claude'u kullanmalıyım?

Kurulum tek seferlik. Sonrasında **Claude Desktop'ı** açın — tıpkı Claude Chat gibi yazışın, Figma bağlantısı otomatik çalışır.

| Araç | F-MCP çalışır mı? | Not |
|------|-------------------|-----|
| **Claude Desktop** (masaüstü uygulaması) | ✅ | Sohbet arayüzü — günlük kullanım için önerilen |
| **Claude Code** (Mac/PC'de terminal uygulaması) | ✅ | Kod yazma ve geliştirme için |
| **Cursor** | ✅ | Kod editörü — geliştiriciler için |
| **Claude Code** (claude.ai/code web veya mobil) | ❌ | Oturum Anthropic bulutunda çalışır; bilgisayarınızdaki plugin'e erişemez |
| **Claude Chat** (claude.ai web) | ❌ | Web tarayıcısı Figma plugin'ine erişemez |

> **Temel kural:** F-MCP, Claude ile Figma'nın **aynı bilgisayarda** çalışmasını gerektirir. Bridge yalnızca `localhost` (5454–5470) üzerinde dinler ve plugin yalnızca `localhost`'a bağlanır. Bulutta veya başka bir makinede çalışan bir Claude oturumu bu köprüye ulaşamaz; plugin bu durumda sarı **"auto-connect"** durumunda kalır.

### Claude Desktop sınırlamaları

Claude Desktop **Claude Code'dan farklı** çalışır. Şu mekanizmalar **Desktop'ta yoktur**:

- Hook'lar (PreToolUse, SessionStart) — çalışmaz
- Sub-agent spawn — Task tool mevcut değil
- Slash command'lar (`/ds-sync` vb.) — desteklenmez
- `plugin.json` auto-discovery — yüklenmez
- `.claude/CLAUDE.md` auto-inject yok

Desktop'ta enforcement **beş katmandan** gelir:
1. Plugin response BLOCKING signal'i (`_DESIGN_SYSTEM_VIOLATIONS_BLOCKING`)
2. Runtime audit tool'u `figma_scan_ds_compliance`
3. Screenshot method selection — file/summary/regions/base64 (context koruma)
4. Discovery budget — keşif çağrıları sayılır, 12'den sonra BLOCKING
5. Project Knowledge'a yüklenmiş skill dosyaları

Detaylı rehber ve ilk-prompt örneği: **[install/claude-desktop/HOW-TO-ENFORCE.md](install/claude-desktop/HOW-TO-ENFORCE.md)**.

### Yeni chat öncesi öneri

Plugin bağlantı sorunları veya zombie process temizliği için:

```bash
bash scripts/cleanup-ports.sh
```

5454-5470 aralığındaki eski FMCP process'lerini güvenle öldürür (sadece FMCP adıyla eşleşenler).

---

## Kendi Tasarım Sisteminizi Ekleyin (Bring Your Own DS)

F-MCP **DS-agnostic** çalışır — herhangi bir Figma team library'yi (Material, Apple HIG, Tailwind UI, kurumsal kendi DS'iniz vb.) kullanabilirsiniz.

**🪄 Sıfır kurulum (v3.5+ — önerilen):** Hiçbir şey eklemenize gerek yok. Tasarım sisteminizle ilgili herhangi bir şey isteyin (*"tasarım sistemimle bir login ekranı yap"*, *"DS'ime uygun mu denetle"*) — agent Figma ortamınızdan DS'inizi **otomatik keşfeder**: hedef dosyanın subscribe olduğu library'ler + açık library dosyaları + mevcut instance'ların kaynakları taranır, bulgular `.claude/design-systems/registry.local.md`'ye (gitignore'lu, size özel) kaydedilir ve bir daha sorulmaz. Ancak hiçbir sinyal yoksa agent **bir kez** kütüphane linkinizi sorar ve kalıcılaştırır.

**Elle kontrol isteyenler için komutlar:**

| Komut | Ne zaman? |
|---|---|
| `/add-library` | Yeni bir DS kurarken (ana + mobil + ikon + asset Figma dosyalarını tek seferde ekler, cache oluşturur) |
| `/ds-add <Figma-URL>` | Hızlı ekleme — file-key otomatik parse edilir, varolan DS ile çakışma/fuzzy isim eşleşmesi kontrol edilir |
| `/ds-sync <ds-name>` | Mevcut DS cache'ini Figma'dan güncelle (resume destekli, kısmi sync) |

**Claude Desktop'ta:** Slash command'lar tetiklenmez ([Desktop sınırlamaları](#claude-desktop-sınırlamaları)). Bu komutların içeriğini prompt'a yapıştırın; Claude skill instruction'larını adım adım uygular. Veya doğal dil kullanın: *"Kütüphane ekle"*, *"Ana-DS'yi güncelle"*.

**Gizlilik:** Eklediğiniz DS'in gerçek `file-key`, `variableKey`, `componentKey` değerleri **repo'ya yazılmaz** — hepsi size özel, gitignore'lu yerel dosyalardadır: `.claude/design-systems/registry.local.md` (DS kaydı) ve `.claude/design-systems/<ds-name>/` altındaki yerel dokümanlar. v3.3+ live-first mimaride veriler her istekte Figma'dan canlı okunur; eski `~/.claude/data/fcm-ds/` cache dizini opsiyoneldir ve hiçbir zaman repoya girmez.

**Multi-library DS:** Ana-DS gibi birden fazla Figma dosyasından oluşan DS'ler desteklenir. `/add-library` ile ana + mobil + ikon + asset URL'lerini ayrı ayrı verebilirsiniz; `active-ds.md` Secondary Libraries tablosunda yönetilir.

**Doğrulama:** `/ds-validate <ds-name>` ile cache tutarlılığını denetleyin (v1.9.8+).

---

## Neler yapabilirsiniz?

AI ile Figma arasında **çift yönlü** çalışırsınız:

**Figma'dan AI'a** — tasarımı oku, analiz et:
- *"Bu dosyadaki tüm bileşenleri listele"*
- *"Button bileşeninin özelliklerini göster"*
- *"Bu ekranın screenshot'ını al"*
- *"Design token'larını çıkar"*

**AI'dan Figma'ya** — tasarım oluştur, değiştir:
- *"Yeni bir frame oluştur, 375x812, mobile layout"*
- *"Bu tasarımdan React kodu üret"*
- *"Color token'larını toplu güncelle"*
- *"Tüm ikonları SVG olarak export et"*

**Design-to-code köprüsü (v1.9.8):**
- *"Seçili bileşen için tasarım bağlamını topla — component + token + Code Connect"* → `figma_use intent=design_context`
- *"Bu sayfadaki tüm Code Connect eşlemelerini getir"* → `figma_get_code_connect scanCurrentPage=true`

**Kalite kontrolü:**
- *"Kontrast kontrolü yap (erişilebilirlik)"*
- *"Koddaki token'larla Figma'daki token'ları karşılaştır"*
- *"Responsive: Mobile, Tablet, Web versiyonlarını üret"*

**Prototip otomasyonu (v1.9.9+):**
- *"Figma'daki ekranların prototip bağlantılarını yap"*
- *"Login → Home → Register akışını SLIDE_IN animasyonla kur"*
- *"Button hover state'i SMART_ANIMATE ile ayarla"*
- *"Long content için vertical scroll + sticky header"*

Otomatik navigasyon haritası (TR+EN button text heuristic), 9 trigger / 8 action / 9 transition tipi × 4 yön, ON_KEY_DOWN (keyCodes + device), overlay config, scroll behavior, flow starting point — Figma Prototype panel'inin tüm yetenekleri.

63 aracın tam listesi: [TOOLS_FULL_LIST.md](docs/TOOLS_FULL_LIST.md)

---

## Figma API Token (opsiyonel — ek özellikler)

F-MCP temel özellikleri token olmadan çalışır. Figma API token eklerseniz **ek özellikler** açılır:

| Token olmadan | Token ile (ek) |
|---------------|---------------|
| Tasarım okuma, bileşen arama | + Yorum okuma/yazma |
| Frame/text oluşturma | + Versiyon geçmişi |
| Variable/token yönetimi | + REST API görsel export |
| SVG/PNG/PDF export | + Dosya bilgisi detayları |

**Nasıl eklenir:**
1. [figma.com/developers](https://www.figma.com/developers) → **Personal Access Tokens** → yeni token oluşturun
2. Figma'da plugin'i açın → **Advanced** → **API Token** alanına yapıştırın
3. Süre seçin (30/60/90 gün) → token otomatik kaydedilir

> Token bilgisayarınızda kalır, internete gönderilmez.

---

## Güncelleme

Claude Code'a şunu söyleyin:

> *"F-MCP'yi güncelle"*

Claude gerisini halleder. Sonra Claude'u yeniden başlatın.

Detay: [UPDATE.md](docs/UPDATE.md)

---

## Sorun mu yaşıyorsunuz?

| Sorun | Çözüm |
|-------|-------|
| Plugin "no server" diyor | Önce AI aracını (Claude Desktop / Cursor / Claude Code) açın, sonra Figma'da plugin'i çalıştırın |
| Plugin sarı "auto-connect :54xx" durumunda kalıyor, yeşil olmuyor | Bilgisayarınızda dinleyen bir bridge yok. Claude'u **claude.ai/code (web/mobil)** üzerinden açtıysanız oturum bulutta çalışır ve plugin'e ulaşamaz — Claude Desktop'ı veya terminalden Claude Code'u kullanın. Doğrulamak için: `lsof -iTCP:5454-5470 -sTCP:LISTEN` boş dönüyorsa bridge çalışmıyor demektir. Hızlı test: Terminal'de `cd <clone-kökü> && node dist/local-plugin-only.js` çalıştırın; plugin birkaç saniyede yeşile dönmeli (bu yalnızca teşhis içindir — günlük kullanımda bridge'i Claude Desktop / Claude Code kendisi başlatır; testten sonra Ctrl+C ile kapatın) |
| Bulut oturumunda / başka makinede `figma-mcp-bridge` "Connection closed" | `.mcp.json` içindeki `args` yolu (`/Users/<kullanıcı>/FCM/dist/local-plugin-only.js`) o makinede yok. Yerel kurulumda yolu kendi clone kökünüze göre düzenleyin; bulut oturumunda ise bu sunucu tasarım gereği çalışmaz (yukarıdaki "Temel kural") |
| Plugin "connecting..." diyor | Bekleyin, otomatik bağlanır |
| Yeni araçlar görünmüyor | AI aracını tamamen kapatıp tekrar açın |
| DevTools console'da WebSocket hataları | v1.9.1+ ile server-side probe ile giderildi. Plugin hâlâ eski kodu cache'liyorsa: Figma → Plugins → Development → Manage plugins in development → Remove → Import plugin from manifest |

Daha fazla: [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

---

## Teknik detaylar

- **Ne yapar** — Claude veya Cursor'dan Figma'ya ekran tasarlar, tasarım sistemini denetler, renk/yazı/boşluk token'larını yönetir, ekranlar arası **prototip bağlantıları ve animasyonlar** kurar (v1.9.9+), tasarımı koda hazırlar
- **Nerelerde çalışır** — Claude Code, Cursor, Claude Desktop, Claude Web ([kurulum rehberleri](install/))
- **Nasıl çalışır** — Her görev için kendi **skill**'i var (kural seti + örnek). Claude Code'da **agent + sub-agent** yapısı var: ana ajan görevi alır, alt-ajanlar izole çalışır — ana sohbet bağlamı yorulmaz. Cursor ve Claude Desktop'ta aynı skill'ler doğrudan yüklenir (sub-agent yok, tek kaynak 4 platformda)
- **3 orkestratör** — DS denetimi, token senkronizasyonu, ekran üretimi için hazır uçtan uca akışlar ([skill dizini](skills/SKILL_INDEX.md))
- **Figma** — Masaüstü ve tarayıcı, birden fazla AI aynı dosyaya aynı anda bağlanabilir
- **Gizlilik** — Veriler bilgisayarınızdan çıkmaz, internet bağlantısı olmadan da kullanılabilir
- **Detay** — [63 araç](docs/TOOLS_FULL_LIST.md) · [28 skill](skills/SKILL_INDEX.md) · [Mimari](docs/ARCHITECTURE.md) · [Kurumsal kullanım](docs/ENTERPRISE.md) · [Katkı rehberi](CONTRIBUTING.md)

---

| | |
|---|---|
| Güncel sürüm | **1.9.14** ([CHANGELOG](CHANGELOG.md) · [Releases](https://github.com/atezer/FMCP/releases/tag/v1.9.14)) — Contract Extractor (Component Set → design contract JSON) |
| npm | [@atezer/figma-mcp-bridge](https://www.npmjs.com/package/@atezer/figma-mcp-bridge) |
| Lisans | MIT — kişisel ve ticari kullanıma açık |

**Sorun mu var?** [GitHub Issues](https://github.com/atezer/FMCP/issues)