Storybook MCP - Katkıda Bulunma Rehberi

Storybook MCP Addon monorepo'suna hoş geldiniz! Bu proje, AI ajanlarının Storybook ile daha verimli çalışmasını sağlayan bir MCP (Model Context Protocol) sunucusu sunarak UI bileşen bilgisi ve geliştirme iş akışlarını ortaya koyan bir projedir.

📦 Paketler

Bu monorepo beş ana paket içerir:

@storybook/mcp - Storybook bileşen bilgisini sunmak için bağımsız MCP kütüphanesi (bağımsız olarak kullanılabilir)
@storybook/addon-mcp - Storybook eklentisi, Storybook dev sunucunuzun içinde bir MCP sunucusu çalıştırır ve yerel Storybook'unuzdan @storybook/mcp işlevselliğini içerir
@storybook/mcp-proxy - Storybook aracı entegrasyonları için kararlı MCP proxy paketi
@storybook/claude-code-plugin - Storybook kurulum becerileri ve @storybook/mcp-proxy başlatan MCP yapılandırması içeren Claude Code eklentisi
@storybook/codex-plugin - Storybook kurulum becerileri ve @storybook/mcp-proxy başlatan MCP yapılandırması içeren Codex eklentisi

Her paketin, kullanıcıya yönelik belgeleri içeren kendi README dosyası vardır. Bu belge, bu paketleri geliştirmek, test etmek veya geliştirmek isteyen katkıda bulunanlar içindir.

🚀 Hızlı Başlangıç

Ön Koşullar

Node.js 24+ - Proje Node.js 24 veya daha yükseğini gerektirir (bkz. .nvmrc)
pnpm 10.19.0+ - Sıkı paket yöneticisi gereksinimi (package.json içinde uygulanır)

# Doğru Node sürümünü kullanın
nvm use

# Sahip değilseniz pnpm'yi kurun
npm install -g pnpm@10.19.0

Kurulum

# Depoyu klonlayın
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Tüm bağımlılıkları kurun (monorepo'daki tüm paketler için)
pnpm install

Geliştirme İş Akışı

# Tüm paketleri derleyin
pnpm build

# Geliştirme modunu başlatın (tüm paketlerdeki değişiklikleri izler)
pnpm dev

# İzleme modunda birim testlerini çalıştırın
pnpm test

# Birim testlerini bir kez çalıştırın
pnpm test:run

# Test için eklentili Storybook'u çalıştırın
pnpm --filter internal-storybook storybook

Storybook komutu şu şekilde başlatılır:

http://localhost:6006 adresinde dahili test Storybook örneği
İzleme modunda eklenti, böylece değişiklikler otomatik olarak yansıtılır
MCP sunucusu http://localhost:6006/mcp adresinde mevcut

🛠️ Yaygın Görevler

Geliştirme

turbo watch build komutu tüm paketleri izleme modunda çalıştırır ve değişiklikleri yaptığınızda otomatik olarak yeniden derler:

# Tüm paketler için geliştirme modunu başlatın
pnpm turbo watch build

# Bu genellikle ihtiyacınız olan tek şeydir - Storybook'u başlatır VE eklentiyi izleme için başlatır
pnpm storybook

Derleme

# Tüm paketleri derleyin
pnpm build

Test Etme

Monorepo, her paket için yapılandırılmış projelerle birlikte kök düzeyinde merkezi bir Vitest yapılandırması kullanır:

# Tüm paketler arasında testleri izleyin
pnpm test

# Tüm paketler arasında testleri bir kez çalıştırın
pnpm test:run

# Kapsamı ve CI raporlarıyla testleri çalıştırın
pnpm test:ci

MCP Sunucularını Hata Ayıklama

MCP sunucusu işlevselliğini hata ayıklamak ve test etmek için MCP Inspector'ı kullanın:

# MCP inspector'ı başlatır (Storybook'un çalışıyor olması gerekir)
pnpm inspect

Bu, her şeyin çalışıp çalışmadığını kontrol etmek için .mcp.inspect.json içindeki yapılandırmayı kullanır.

Alternatif olarak, her şeyin çalışıp çalışmadığını kontrol etmek için bu curl komutlarını da kullanabilirsiniz:

# mcp sunucusunun çalışıp çalışmadığını test edin
# addon-mcp sunucusunu test etmek için port 6006'yı kullanın
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# belirli bir araç çağrısını test edin
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

Storybook ile Hata Ayıklama

Storybook'u şu şekilde başlatabilirsiniz:

pnpm storybook

Bu, her şeyi derleyecek ve addon-mcp ile Storybook'u başlatacak, ardından kodlama ajanınızı http://localhost:6006/mcp adresine (veya yapılandırılmış eklenti endpoint'ine) bağlayarak deneyebilirsiniz.

MCP Uygulaması ile Çalışma

preview-stories aracının parçası olarak oluşturulan MCP uygulamasıyla çalışmak ve hata ayıklamak için:

VSCode'un Insiders sürümünü kullanın
chat.mcp.apps.enabled ayarının etkin olduğundan emin olun
Kök dizinde pnpm storybook çalıştırarak repo'nun Storybook'unu izleme modunda başlatın
VSCode'u yeniden başlatın ve .vscode/mcp.json dosyasını açın ve Storybook MCP'nin Çalışıyor olarak işaretlendiğinden emin olun, aksi takdirde Başlat'ı tıklayın.
VSCode'da bir sohbet açın ve şöyle bir istem yazın:

Show me how all the button stories look, using the Storybook MCP

Bu ilk istemden sonra, her değişiklik yaptığınızda Storybook otomatik olarak yeniden başlatılır. Tamamen hazır olana kadar bekleyin, ardından "Run the tool again" istemini kullanabilirsiniz.

Araç çağrılarında daha düşük seviye kontrol sağlamak için MCPJam'ın inspector'ını da kullanabilirsiniz.

Biçimlendirme ve Linting

# Tüm dosyaları Prettier ile biçimlendirin
pnpm format

# Dosyaları değiştirmeden biçimlendirmeyi kontrol edin
pnpm format:check

# Kodu oxlint ile lint edin
pnpm lint

# GitHub Actions biçimiyle lint edin (CI için)
pnpm lint:ci

# publint ile paket dışa aktarımlarını kontrol edin
pnpm publint

🔍 Kalite Kontrolleri

Monorepo, CI'de çalışan birkaç kalite kontrolü içerir:

# Tüm kontrolleri çalıştırın (build, test, lint, format, typecheck, publint)
pnpm check

# İzleme modunda kontrolleri çalıştırın (deneysel)
pnpm check:watch

# Tür denetimi (turbo değil, tsc'yi doğrudan kullanır)
pnpm typecheck

# Turbo ile tür denetimi (bireysel paketler için)
pnpm turbo:typecheck

# Turbo ile test etme (bireysel paketler için)
pnpm turbo:test

📝 Kod Kuralları

TypeScript & İçeri Aktarmalar

Göreli içeri aktarmalarda her zaman dosya uzantılarını ekleyin:

// ✅ Doğru
import { foo } from './bar.ts';

// ❌ Yanlış
import { foo } from './bar';

JSON içeri aktarmaları import attributes söz dizimini kullanır:

import pkg from '../package.json' with { type: 'json' };

🚢 Yayın Süreci

Bu proje sürüm yönetimi için Changesets kullanır:

# 1. Değişikliklerinizi açıklayan bir changeset oluşturun
pnpm changeset

Bir PR oluşturduğunuzda, değişiklikleriniz bir yayını tetiklemesi gerekiyorsa bir changeset ekleyin:

Patch: Hata düzeltmeleri, belgelendirme güncellemeleri
Minor: Yeni özellikler, geriye dönük uyumlu değişiklikler
Major: Kırılma değişiklikleri

🤝 Katkıda Bulunma

Katkılarınız memnuniyetle karşılanır! Başlamak için:

Depoyu fork edin ve bir feature branch oluşturun
Değişikliklerinizi yapın yukarıdaki kod kurallarını izleyerek
Değişikliklerinizi test edin dahili Storybook örneğini kullanarak
Changeset oluşturun değişiklikleriniz bir yayını gerektirir ise
Pull request gönderin net bir açıklamayla

Göndermeden Önce

[ ] Kod hatasız derlenir (pnpm build)
[ ] Testler geçer (pnpm test:run)
[ ] Kod biçimlendirilir (pnpm format)
[ ] Kod lint edilir (pnpm lint)
[ ] Tür denetimi geçer (pnpm typecheck)
[ ] Değişiklikler MCP inspector veya dahili Storybook ile test edilir
[ ] Gerekirse changeset oluşturulur (pnpm changeset)

Yardım Alma

Fikirler & Özellik İstekleri: Tartışma başlatın
Hata Raporları: Bir sorun açın
Sorular: GitHub Discussions içinde sorun

📄 Lisans

MIT - Ayrıntılar için LICENSE dosyasını inceleyin

Not: Bu proje deneyseldir ve aktif geliştirme altındadır. AI ajanlarını Storybook ile entegre etmenin en iyi yollarını keşfettiğimiz için API'ler ve mimari değişebilir.

storybookjs/mcp

Bu MCP sunucusu hakkında