Storybook MCP

Storybook MCP - Katkıda Bulunan Rehberi

Storybook MCP Eklenti monoreposuna hoş geldiniz! Bu proje, yapay zeka aracılarının, UI bileşen bilgilerini ve geliştirme iş akışlarını sunan bir MCP (Model Bağlam Protokolü) sunucusu sağlayarak Storybook ile daha verimli çalışmasını sağlar.

📦 Paketler

Bu monorepo dört 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 geliştirme sunucunuz içinde bir MCP sunucusu çalıştıran ve yerel Storybook'unuzdan @storybook/mcp işlevselliğini içeren Storybook eklentisi
• @storybook/claude-code-plugin - Storybook kurulum becerileri ve MCP yapılandırması içeren Claude Code eklentisi
• @storybook/codex-plugin - Storybook kurulum becerileri ve MCP yapılandırması içeren Codex eklentisi

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

🚀 Hızlı Başlangıç

Claude ve Codex eklentilerini GitHub'dan test etme

Harici test kullanıcıları, eklenti pazar yerini doğrudan bu deponun main dalından yükleyebilir. Yerel klonlama gerekmez.

Codex (daha fazla detay)

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

Pazar yerini ve eklentiyi doğrulayın:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code (daha fazla detay)

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

Eklentiyi ve MCP sunucusunu doğrulayın:

claude plugin list --json
claude mcp list

Depo, pazar yeri kataloglarını kasıtlı olarak iki yerde tutar. Kök kataloglar storybookjs/mcp dalından GitHub yüklemelerini destekler; paket yerel katalogları yerel paket geliştirme betiklerini destekler. Göreli eklenti kaynak yolu dışında aynı kalmalıdırlar ve paket doğrulaması bunu kontrol eder.

Ön Koşullar

• Node.js 24+ - Proje Node.js 24 veya üstünü gerektirir (bkz. .nvmrc)
• pnpm 10.19.0+ - Katı paket yöneticisi gereksinimi (package.json içinde zorunlu kılınır)

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g pnpm@10.19.0

Kurulum

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

Geliştirme İş Akışı

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

Storybook komutu şunları başlatır:

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

🛠️ Yaygın Görevler

Geliştirme

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

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

Derleme

# Build all packages
pnpm build

Test Etme

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

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

MCP Sunucularında Hata Ayıklama

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

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

Bu, yerel MCP sunucularınıza bağlanmak için .mcp.inspect.json içindeki yapılandırmayı kullanır.

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

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
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 şununla başlatabilirsiniz:

pnpm storybook

Bu, her şeyi derleyecek ve addon-mcp ile Storybook'u başlatacaktır, ardından kodlama aracınızı http://localhost:6006/mcp adresinden (veya yapılandırdığınız eklenti uç noktasından) ona bağlayabilir ve deneyebilirsiniz.

MCP Uygulaması ile Çalışma

Önizleme hikayeleri aracının bir parçası olarak işlenen MCP uygulamasıyla çalışmak ve hata ayıklamak için şunları yapabilirsiniz:

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

Storybook MCP'yi kullanarak tüm düğme hikayelerinin nasıl göründüğünü bana göster

6. Bu ilk istemden sonra, değişiklik yaptığınızda Storybook otomatik olarak yeniden başlar. Tamamen hazır olmasını bekleyin, ardından "Aracı tekrar çalıştır" diye istemde bulunabilirsiniz.

Araç çağrıları üzerinde daha düşük seviyeli kontrole sahip olmak için MCPJam'deki inspector'ı da kullanabilirsiniz.

Biçimlendirme ve Lint

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 Kalite Kontrolleri

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

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 Kod Kuralları

TypeScript ve İçe Aktarmalar

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

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

• JSON içe aktarmaları içe aktarma öznitelikleri sözdizimini kullanır:

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

🚢 Sürüm Süreci

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

# 1. Create a changeset describing your changes
pnpm changeset

Bir PR oluşturduğunuzda, değişiklikleriniz bir sürümü tetiklemeliyse bir changeset ekleyin:

• Yama: Hata düzeltmeleri, belge güncellemeleri
• Küçük: Yeni özellikler, geriye dönük uyumlu değişiklikler
• Büyük: Kırıcı değişiklikler

🤝 Katkıda Bulunma

Katkılarınızı memnuniyetle karşılıyoruz! İşte başlama şekli:

1. Depoyu çatallayın ve bir özellik dalı oluşturun
2. Değişikliklerinizi yapın, yukarıdaki kod kurallarını takip edin
3. Değişikliklerinizi test edin, dahili Storybook örneğini kullanarak
4. Bir changeset oluşturun, değişiklikleriniz bir sürümü gerektiriyorsa
5. Bir çekme isteği gönderin, net bir açıklama ile

Göndermeden Önce

• Kod hatasız derleniyor (pnpm build)
• Testler geçiyor (pnpm test:run)
• Kod biçimlendirilmiş (pnpm format)
• Kod lint edilmiş (pnpm lint)
• Tip kontrolü geçiyor (pnpm typecheck)
• Değişiklikler MCP inspector veya dahili Storybook ile test edildi
• Gerekirse changeset oluşturuldu (pnpm changeset)

Yardım Alma

• Fikirler ve Özellik İstekleri: Bir tartışma başlatın
• Hata Raporları: Bir sorun açın
• Sorular: GitHub Tartışmaları bölümünde sorun

📄 Lisans

MIT - Detaylar için LICENSE dosyasına bakın

---

Not: Bu proje deneyseldir ve aktif olarak geliştirilmektedir. Yapay zeka aracılarını Storybook ile entegre etmenin en iyi yollarını keşfederken API'ler ve mimari değişebilir.