shadcn MCP sunucusu: yapay zekâ asistanıyla bileşen arama ve kurma

MCP nedir, shadcn sunucusu ne yapar?

Model Context Protocol (MCP), yapay zekâ asistanlarının dış veri kaynaklarına ve araçlara bağlanmasını sağlayan açık bir protokoldür. shadcn MCP sunucusu bu protokol üzerinden asistanınıza dört yetenek kazandırır: yapılandırılmış registry'lerdeki bileşen, blok ve şablonları listelemek; birden çok kaynakta ada veya işleve göre arama yapmak; "bir giriş formu ekle" gibi konuşma diliyle kurulum yapmak; herkese açık, şirket içi ve üçüncü taraf registry'lere aynı anda erişmek.

Belge çalışma biçimini dört adımda özetler: sunucu yapılandırılmış registry'lere bağlanır, siz ihtiyacınızı doğal dille anlatırsınız, asistan isteğinizi registry komutlarına çevirir ve kaynaklar getirilip projenize kurulur. Yani MCP sunucusu asistan, registry'ler ve shadcn CLI arasında bir köprüdür; dosyaları projenize yine CLI'nin bildiğiniz add mantığı yazar.

Hızlı kurulum: mcp init

Belgedeki hızlı başlangıç her istemci için tek bir komut verir:

npx shadcn@latest mcp init --client claude
npx shadcn@latest mcp init --client cursor
npx shadcn@latest mcp init --client vscode
npx shadcn@latest mcp init --client codex

--client seçeneğini vermezseniz CLI 3.6.2 kaynak koduna göre Which MCP client are you using? sorusuyla bir seçim listesi açılır. Kaynak kod komutun iki iş yaptığını da gösterir: istemcinin yapılandırma dosyasına shadcn sunucusunu ekler ve projeye shadcn@latest paketini geliştirme bağımlılığı olarak kurar. İşlem bitince Configuration saved to ... satırı yazdırılır. Komutu çalıştırdıktan sonra istemciye göre şu adımları izlersiniz:

Elle yapılandırma

Komutu kullanmak istemiyorsanız aynı yapılandırmayı kendiniz yazabilirsiniz. Claude Code için proje kökündeki .mcp.json dosyası şöyledir; Cursor için aynı içerik .cursor/mcp.json dosyasına yazılır:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Claude Code'u yeniden başlatıp /mcp komutunu çalıştırdığınızda listede shadcn sunucusunu ve Connected durumunu görmelisiniz. Cursor'da sunucuyu ayarlardan etkinleştirdikten sonra MCP sunucu listesinde shadcn'in yanında yeşil bir nokta ve kullanılabilir araçların listesi görünür.

VS Code'da dikkat edilecek fark, kök anahtarın mcpServers değil servers olmasıdır. .vscode/mcp.json dosyası:

{
  "servers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Codex ise TOML biçimi kullanır ve yapılandırma kullanıcı klasöründeki ~/.codex/config.toml dosyasına eklenir:

[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]

Dört yapılandırmada da sunucu aynı şekilde başlatılır: npx shadcn@latest mcp. Yani MCP sunucusu ayrı bir ürün değil, shadcn CLI'nin bir alt komutudur. Kaynak koda göre bu komut çalışma klasöründeki ortam dosyalarını yükler ve standart giriş/çıkış (stdio) üzerinden iletişim kurar. İstemcilerin kendi MCP belgeleri için shadcn sayfasında Claude Code MCP belgesi, VS Code MCP belgesi ve Cursor belgesine bağlantı verilir.

Sunucunun araçları

Asistanın kullandığı araçlar belgede tek tek listelenmez, ancak CLI 3.6.2 kaynağındaki src/mcp/index.ts dosyasında tanımlıdır. Asistanınızın neden bazı adımları belli bir sırayla yaptığını anlamak için faydalıdır:

Son araçtaki kontrol listesi kaynak kodda şu maddeleri içerir: içe aktarmaların doğru olması (named ve default ayrımı), next/image kullanılıyorsa images.remotePatterns ayarı, tüm bağımlılıkların kurulu olması, lint ve TypeScript hatalarının kontrolü ve varsa Playwright MCP ile deneme. Asistan bileşen ekledikten sonra bu listeyi kullanarak kendi işini denetleyebilir. Araçlar sürümden sürüme değişebilir; bu tablo depo kopyasının tarihini yansıtır.

Mini örnek: bir isteğin araçlara dönüşmesi

Araç açıklamaları birbirine yönlendirme de yapar; bu yönlendirmeler, asistanın tipik bir isteği nasıl adımlara böldüğünü tahmin etmenizi sağlar. Diyelim ki Claude Code'a "shadcn registry'sindeki bileşenlerle bir iletişim formu oluştur" yazdınız. get_project_registries önce projede hangi registry'lerin tanımlı olduğunu öğrenir; components.json yoksa bu araç hata döndürür ve asistan size projeyi başlatmanızı söyler. Ardından search_items_in_registries ile @shadcn içinde form, input, field gibi sorgularla arama yapılır. Bu aracın açıklaması, bir öğe bulunduktan sonra kullanım örnekleri için get_item_examples_from_registries aracına geçilmesini önerir; asistan böylece field-demo gibi resmi örnek dosyalarını okuyabilir. Kurulum aşamasında get_add_command_for_items ilgili öğeler için npx shadcn@latest add ... komutunu üretir ve istemciniz izin verirse komut projenizde çalıştırılır. Form bileşeni yazıldıktan sonra get_audit_checklist çağrılarak içe aktarmalar, bağımlılıklar ve TypeScript hataları kontrol edilir.

Bu akışın asıl değeri, asistanın bileşen API'sini tahmin etmek yerine registry'deki gerçek kodu ve resmi örnekleri okumasıdır. Yine de sonuç sizin projenize yazılan koddur: hangi komutun çalıştırıldığını istemcinizin onay ekranında görür, eklenen dosyaları sürüm kontrolünde incelersiniz. Belgedeki sorun giderme listesinin "shadcn projenizde kurulu mu" maddesi de bu yüzden önemlidir; üretilen add komutu projenizin kendi ortamında ve kendi paketlerinizle çalışır.

Registry yapılandırması ve kimlik doğrulama

Standart shadcn/ui registry'si için hiçbir yapılandırma gerekmez. Başka registry'leri MCP sunucusuna açmak için onları CLI'de olduğu gibi components.json dosyasının registries alanına eklersiniz:

{
  "registries": {
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": {
      "url": "https://internal.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Özel registry'lerin token'larını .env.local dosyasına yazarsınız. MCP sunucusu başlarken ortam dosyalarını yüklediği için başlıklardaki ${REGISTRY_TOKEN} değerleri buradan doldurulur:

REGISTRY_TOKEN=your_token_here
API_KEY=your_api_key_here

Kimlik doğrulama başlıkları, sorgu parametreleri ve hata mesajları namespace ve özel registry yazısında ayrıntılı anlatılıyor.

Örnek istemler

Belgedeki istemler İngilizcedir; Türkçe yazdığınızda da asistan aynı araçları kullanır. Belgedeki örneklerin anlamca karşılıkları şunlardır:

• Göz atma ve arama: "shadcn registry'sindeki tüm bileşenleri göster", "shadcn registry'sinden bir giriş formu bul".
• Kurulum: "Projeme button bileşenini ekle", "shadcn bileşenleriyle bir giriş formu oluştur", "acme registry'sindeki Cursor kurallarını kur".
• Namespace ile çalışma: "acme registry'sindeki bileşenleri göster", "@internal/auth-form öğesini kur", "acme registry'sindeki hero, features ve testimonials bölümleriyle bir açılış sayfası kur".

İyi sonuç almak için istemde registry adını ve istediğiniz öğe türünü açıkça yazın. "Bir form yap" yerine "shadcn registry'sindeki field ve input bileşenleriyle bir iletişim formu oluştur" demek, asistanın önce arama ve örnek araçlarını kullanmasına yol açar. Formun kendisini nasıl kuracağınızı Field bileşeni yazısında görebilirsiniz.

Registry geliştiricileri için

Kendi registry'nizi yayımlıyorsanız MCP desteği için ek bir şey yapmanız gerekmez; sunucu shadcn uyumlu her registry ile çalışır. Tek ön koşul, registry'nizin kökünde registry adlı bir dizin dosyası bulunmasıdır. Registry'niz https://acme.com/r/[name].json adresindeyse https://acme.com/r/registry.json dosyası (uzantısız URL kullanıyorsanız https://acme.com/r/registry) erişilebilir olmalı ve registry şemasına uymalıdır. shadcn build bu dosyayı sizin için üretir.

Belgenin önerdiği iyi uygulamalar şunlardır: asistanların öğenin ne işe yaradığını anlaması için kısa ve bilgilendirici açıklamalar yazın; MCP'nin bağımlılıkları otomatik kurabilmesi için dependencies listesini eksiksiz tutun; öğeler arası ilişkileri registryDependencies ile belirtin; bileşen adlarında tutarlı biçimde kebab-case kullanın.

Kısa tarihçe

Değişiklik günlüğüne göre Nisan 2025'te registry'ler için sıfır yapılandırmalı MCP desteği üzerinde çalışıldığı duyuruldu. Ağustos 2025'te shadcn CLI 3.0 ile yeniden yazılan MCP sunucusu geldi: tüm registry'lerle yapılandırmasız çalışma, popüler istemcilere tek komutla ekleme, iyileştirilmiş araçlar, CLI ve registry'lerle daha iyi entegrasyon ve aynı projede birden çok registry desteği. Diğer sürüm notları için yenilikler ve sürüm geçmişi yazısına bakın.

Sorun giderme

Belgede dört tür soruna karşı kontrol listesi verilir:

npx clear-npx-cache

Kaynak koddaki araç açıklamaları birçok aracın components.json gerektirdiğini belirtir. Bu yüzden boş bir klasörde MCP sunucusunu denemeden önce projeyi init komutuyla başlatın.

Sık yapılan hatalar

• Yapılandırmadan sonra istemciyi yeniden başlatmamak: Belgedeki her istemci talimatı yeniden başlatma ya da sunucuyu etkinleştirme adımı içerir.
• VS Code dosyasına mcpServers yazmak: VS Code yapılandırmasında kök anahtar servers'tır.
• Codex için mcp init'in dosyayı düzenleyeceğini sanmak: ~/.codex/config.toml elle düzenlenir.
• Token'ı .mcp.json içine yazmak: Gizli değerler components.json içinde değişken adıyla, gerçek değerleri .env.local dosyasında durmalıdır.
• Asistanın kurduğu kodu incelememek: MCP üzerinden gelen dosyalar da projenize kopyalanan sıradan koddur. Belgedeki güven modeli burada da geçerlidir: yalnızca güvendiğiniz registry'leri yapılandırın ve değişiklikleri commit etmeden önce okuyun.

Sık Sorulan Sorular

MCP sunucusu için ayrı bir paket kurmam gerekir mi?

Hayır. Sunucu shadcn CLI paketinin mcp alt komutudur. mcp init bu paketi projeye geliştirme bağımlılığı olarak ekler, istemci de onu npx shadcn@latest mcp ile başlatır.

.mcp.json dosyamda başka sunucular var; mcp init onları siler mi?

CLI 3.6.2 kaynak koduna göre hayır. Komut mevcut JSON dosyasını okur, shadcn girdisini onunla derin birleştirir (deep merge) ve sonucu aynı dosyaya yazar; dosya yoksa klasörüyle birlikte oluşturur. Diğer sunucu tanımlarınız yerinde kalır. Yine de değişiklikten sonra dosyayı açıp kontrol etmeniz iyi olur.

Hangi istemciler destekleniyor?

Belgede ve mcp init komutunda Claude Code, Cursor, VS Code ve Codex vardır. Belge diğer MCP istemcilerinin de kullanılabileceğini söyler; bu durumda yapılandırmayı istemcinin biçimine göre elle yazarsınız.

Özel registry'mi MCP ile kullanabilir miyim?

Evet. components.json içinde başlıklarla tanımlanan registry'ler MCP sunucusu tarafından da kullanılır; token'lar .env.local dosyasından okunur.

Asistan dosyaları nereye yazar?

CLI'nin yazdığı yere: components.json takma adlarının gösterdiği klasörlere. Bu ayarların ayrıntısı components.json yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: shadcn/ui öğrenme rehberi · Namespace ve özel registry · Kendi registry'nizi kurun · CLI komutları · Sık hatalar