Claude Code ve Cursor’ın gerçekten kullanabileceği bir shadcn/ui registry’si nasıl kurulur

1. Doğrulamadan geçen bir registry yayınlayın

Temellerle başlayın. Her öğe, registry şemasına uyan, name, type, files, dependencies ve registryDependencies alanları olan bir JSON dosyasıdır. Dizini sabit bir URL’ye, her öğeyi de tahmin edilebilir bir URL’ye koyun:

https://your-site.com/r/registry.json
https://your-site.com/r/button.json
https://your-site.com/r/all.json

Bunları bir registry.json kaynağından üretmek için shadcn build çalıştırın ve dağıtmadan önce doğrulayın. CLI, Mayıs 2026’da bir registry doğrulama adımı kazandı. Doğrulamadan geçemeyen bir registry ajanlar için sessizce başarısız olur; onlar da bileşeni elle yazar ve yanlış yapar.

Gerçekten fark yaratan iki ayrıntı:

• Tam URL’li registryDependencies. Dialog’unuz Button’ınıza bağımlıysa button yerine https://your-site.com/r/button.json adresini gösterin, yoksa CLI shadcn/ui Button’ını çeker.
• Her şeye bağımlı olan bir all.json öğesi. "Tasarım sistemini kur" denilen ajanlar ona uzanır.

2. Bir namespace kaydedin

Registry namespace özelliği geldiğinden beri kullanıcı components.json dosyasına şunu ekliyor:

{
  "registries": {
    "@hextaui": "https://hextaui.com/r/{name}.json"
  }
}

Sonra da kısa bir adla kurar:

npx shadcn@latest add @hextaui/dialog

Bu parçacığı kurulum sayfanızda ve llms.txt dosyanızda belgeleyin. shadcn MCP sunucusunun arama yaptığı şey kısa biçimdir; dolayısıyla namespace’i olmayan bir registry, çoğu ajanın registry’lere göz atmak için kullandığı tek araca görünmezdir.

Registry özelse nesne biçimi, CLI’ın genişlettiği ve asla loglamadığı ortam değişkenleriyle header’lar alır:

{
  "registries": {
    "@acme-pro": {
      "url": "https://acme.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    }
  }
}

3. Her dokümantasyon sayfasına bir Markdown ikizi verin

Ajanlar HTML’i kötü, Markdown’ı iyi çeker. Her dokümantasyon URL’sinin .md ile aynı içeriği vermesini sağlayın: açıklama, kurulum komutu, tam kaynak, kullanım, örnekler, klavye desteği ve API tablosu.

https://hextaui.com/docs/button      -> HTML for people
https://hextaui.com/docs/button.md   -> Markdown for agents

Markdown’ı elle yazmayın. İkisi asla birbirinden sapmasın diye sayfayla aynı kaynaktan üretin. HextaUI’da .md rotası sayfanın React ağacında gezinip onu serileştirir; böylece sayfaya eklenen bir örnek Markdown’a bedavaya eklenir.

Burada en çok API referansı önemlidir. Props tablosunu okuyabilen bir ajan, var olmayan bir size="xl" uydurmaz.

4. llms.txt ve llms-full.txt yayınlayın

llms.txt, site kökünüzdeki bir Markdown dizinidir: projenin ne olduğu, ne zaman kullanılacağı, ne zaman kullanılmayacağı, nasıl kurulacağı ve her dokümantasyon sayfası için .md bağlantısıyla bir satır. llms-full.txt ise her şeyi tek seferde yüklemek isteyen ajanlar için tüm dokümantasyon sayfalarının birleştirilmiş halidir.

"Ne zaman kullanılmamalı" bölümü, insanların atladığı ve sizi destek taleplerinden kurtaran kısımdır. Registry’niz yalnızca React ve Tailwind içinse bunu söyleyin, yoksa bir ajan onu bir Vue projesine kurmaya çalışır.

Kurulum komutunu ilk on satırda tutun. Ajanlar en üstü okur.

5. Salt okunur, anahtarsız bir MCP sunucusu çalıştırın

shadcn CLI’ın, components.json içindeki herhangi bir registry’de arama yapan kendi MCP sunucusu var (npx shadcn@latest mcp). Bu kurulumları kapsar. Dokümanları, klavye haritalarını ya da örnekleri kapsamaz.

Bu yüzden https://hextaui.com/mcp adresinde ikinci bir tane çalıştırıyorum: Streamable HTTP, salt okunur, API anahtarsız, beş araçlı: search_docs, get_component, get_component_api, get_examples ve get_install_command. Claude Code tek satırla bağlanır:

claude mcp add --transport http hextaui https://hextaui.com/mcp

Cursor ve VS Code, MCP yapılandırmalarında aynı URL’yi alır. Bağlandıktan sonra "asenkron sonuçlu bir HextaUI combobox ekle" isteği, arada hiç tahmin olmadan bir doküman aramasına, bir API okumasına ve doğru kurulum komutuna dönüşür.

Keşfedilebilir de yapın. /.well-known/mcp/server-card.json adresinde bir sunucu kartı ve MCP registry biçiminde bir server.json yayınlayın. Ajanlar ve etraflarındaki araçlar önce oraya bakmaya başlıyor.

6. HTTP yüzeyini OpenAPI ve gerçek hatalarla tanımlayın

Yukarıdakilerin hepsi aynı zamanda düz HTTP’dir ve ajanlar giderek daha çok doğrudan HTTP çağırıyor. Operation id’leri ve tipli yanıtları olan bir openapi.json yayınlayın. Hataları, bir sonraki adımı söyleyen resolution alanına sahip RFC 9457 application/problem+json olarak döndürün:

{
  "type": "https://hextaui.com/docs/api#not-found",
  "title": "Component not found",
  "status": 404,
  "detail": "No component named 'modal'.",
  "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json."
}

İpucu içeren bir 404 alan ajan toparlanır. HTML hata sayfası alan ajan bileşeni ezberden yazar.

7. Bir skill dosyası yayınlayın

Claude Code ve giderek artan sayıda ajan, bir aracın nasıl kullanılacağını anlatan SKILL.md dosyalarını okur. /.well-known/agent-skills/<name>/SKILL.md adresine bir tane koyun: bir bileşenin nasıl bulunacağı, dokümanlarının nasıl okunacağı ve tam komutlarla nasıl kurulacağı. Bir sayfa Markdown’dır ve sitedeki en yüksek kaldıraçlı sayfadır.

8. Kendinizle değil, ajanlarla test edin

Claude Code’da MCP sunucunuz bağlı ve başka hiçbir bağlam olmadan taze bir Next.js projesi açın. Ondan "<your registry> kaynağından aralık seçimli ve hafta sonları devre dışı kuralı olan bir tarih seçici ekle" isteyin. Ne yaptığını izleyin. Her yanlış tahmin, .md dokümanlarınızdaki ya da llms.txt dosyanızdaki bir boşluktur.

Sonra aynısını Cursor’da yalnızca llms.txt ile ve MCP olmadan yapın. Sonra yalnızca URL ile. Registry üç durumda da zarifçe gerilemeli.

Bunun size kazandırdığı

MCP sunucusu ya da .md dokümanları bağlı bir ajan, props tablosunu tahmin etmek yerine okur, bileşeni yeniden yazmak yerine kurulum komutunu çalıştırır ve bağımlılıkları doğru sırada kurar. HextaUI’ın registry tarafı yaklaşık bir haftalık işti. Ajan tarafı daha uzun sürdü ve registry’yi, artık kurulumların çoğunu yapan kişiler için kullanılabilir kılan kısım o oldu.

Hepsini canlı görmek isterseniz: hextaui.com/llms.txt, sonuna .md eklenmiş herhangi bir dokümantasyon sayfası, MCP dokümanları ve OpenAPI spesifikasyonuyla birlikte API dokümanları.

SSS

shadcn CLI’ın kendi MCP’si varken kendi MCP sunucuma ihtiyacım var mı? shadcn MCP, components.json içindeki registry’ler arasında arama ve kurulumu kapsar. Kendi sunucunuz dokümanları, API’leri ve örnekleri kapsar. Çoğu registry ikisinden de yararlanır.

MCP sunucusu API anahtarı istemeli mi? Herkese açık dokümanlar için hayır. Zorunlu kıldığınız her anahtar, vazgeçen bir ajan demektir. Kimlik doğrulamayı özel öğeler için saklayın ve components.json header’ları üzerinden bearer token kullanın.

İçeriği çoğaltmadan Markdown dokümanlarını nasıl üretirim? Sayfanın kullandığı bileşen ağacını aynen render edip Markdown’a serileştirin. Tek kaynak, iki format.

llms.txt içine ne girer? Bir açıklama, ne zaman kullanılacağı ve ne zaman kullanılmayacağı, kurulum komutu, namespace parçacığı ve her dokümantasyon sayfası için .md dosyasına bağlanan bir satır.