Design ★ 153,732

mcp-builder

MCP (Model Context Protocol) sunucuları oluşturmak için kapsamlı bir rehber; LLM'lerin iyi tasarlanmış araçlarla harici hizmetlerle etkileşim kurmasını sağlar. Python (FastMCP) veya Node/TypeScript (MCP SDK) ile harici API'ler ve servisleri entegre etmek için MCP sunucuları geliştirirken kullanın.

cd ~/.claude/skills
git clone https://github.com/anthropics/skills.git skills

Bu skill hakkında

MCP Sunucu Geliştirme Kılavuzu

Genel Bakış

LLM'lerin iyi tasarlanmış araçlar aracılığıyla harici hizmetlerle etkileşimde bulunmasını sağlayan MCP (Model Context Protocol) sunucuları oluşturun. Bir MCP sunucusunun kalitesi, LLM'lerin gerçek dünya görevlerini ne kadar iyi yerine getirebilmesine göre ölçülür.

Süreç

🚀 Üst Seviye İş Akışı

Yüksek kaliteli bir MCP sunucusu oluşturmak dört ana aşamayı içerir:

Aşama 1: Derin Araştırma ve Planlama

1.1 Modern MCP Tasarımını Anlayın

API Kapsamı vs. İş Akışı Araçları: Kapsamlı API endpoint kapsamını özel iş akışı araçlarıyla dengeleyin. İş akışı araçları belirli görevler için daha uygun olabilir, ancak kapsamlı kapsam ajanlar için işlemleri birleştirme esnekliği sağlar. Performans istemciye göre değişir—bazı istemciler temel araçları birleştiren kod yürütmesinden yararlanırken, diğerleri daha yüksek seviye iş akışlarıyla daha iyi çalışır. Emin olmadığınızda, kapsamlı API kapsamını önceliklendirin.

Araç Adlandırması ve Keşfedilebilirlik: Açık, açıklayıcı araç adları ajanların doğru araçları hızlı bir şekilde bulmasına yardımcı olur. Tutarlı önekler kullanın (örn. github_create_issue, github_list_repos) ve eylem odaklı adlandırma yapın.

Bağlam Yönetimi: Ajanlar kısa araç açıklamalarından ve sonuçları filtreleme/sayfalandırma yeteneğinden yararlanır. Odaklanmış, ilgili verileri döndüren araçlar tasarlayın. Bazı istemciler ajanların verileri verimli bir şekilde filtrelemesine ve işlemesine yardımcı olabilecek kod yürütmeyi destekler.

Eyleme Döndürülebilir Hata Mesajları: Hata mesajları ajanları belirli öneriler ve sonraki adımlarla çözümlere doğru yönlendirmelidir.

1.2 MCP Protokol Belgelerini İncelediler

MCP belirtiminde gezinin:

Site haritasından başlayarak ilgili sayfaları bulun: https://modelcontextprotocol.io/sitemap.xml

Daha sonra markdown formatı için .md sonekiyle belirli sayfaları getirin (örn. https://modelcontextprotocol.io/specification/draft.md).

İncelenecek temel sayfalar:

  • Belirtim genel bakışı ve mimarisi
  • Taşıma mekanizmaları (akışlı HTTP, stdio)
  • Araç, kaynak ve komut tanımları

1.3 Framework Belgelerini İncelediler

Önerilen stack:

  • Dil: TypeScript (yüksek kaliteli SDK desteği ve birçok yürütme ortamında (örn. MCPB) iyi uyumluluk. Ayrıca AI modelleri, geniş kullanımı, statik yazım ve iyi linting araçlarından yararlanarak TypeScript kodu oluşturmada iyidir)
  • Taşıma: Uzak sunucular için Akışlı HTTP, durum bilgisiz JSON kullanarak (ölçeklenmesi ve bakımı daha kolaydır, durum bilgili oturumlar ve akışlı yanıtların aksine). Yerel sunucular için stdio.

Framework belgelerini yükleyin:

TypeScript için (önerilir):

  • TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md yüklemek için WebFetch kullanın
  • ⚡ TypeScript Kılavuzu - TypeScript desenleri ve örnekleri

Python için:

  • Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md yüklemek için WebFetch kullanın
  • 🐍 Python Kılavuzu - Python desenleri ve örnekleri

1.4 Uygulamanızı Planlayın

API'yi Anlayın: Hizmetin API belgelerini inceleyerek anahtar uç noktaları, kimlik doğrulama gereksinimlerini ve veri modellerini belirleyin. Gerektiğinde web arama ve WebFetch kullanın.

Araç Seçimi: Kapsamlı API kapsamını önceliklendirin. Uygulanacak uç noktaları, en yaygın işlemlerden başlayarak listeleyin.

Aşama 2: Uygulama

2.1 Proje Yapısını Ayarlayın

Dile özgü kılavuzlara bakın:

2.2 Temel Altyapıyı Uygulayın

Paylaşılan yardımcı programlar oluşturun:

  • Kimlik doğrulama ile API istemcisi
  • Hata işleme yardımcıları
  • Yanıt biçimlendirmesi (JSON/Markdown)
  • Sayfalandırma desteği

2.3 Araçları Uygulayın

Her araç için:

Giriş Şeması:

  • Zod (TypeScript) veya Pydantic (Python) kullanın
  • Kısıtlamalar ve açık açıklamalar ekleyin
  • Alan açıklamalarında örnekler ekleyin

Çıkış Şeması:

  • Yapılandırılmış veriler için mümkün olduğunda outputSchema tanımlayın
  • Araç yanıtlarında structuredContent kullanın (TypeScript SDK özelliği)
  • İstemcilerin araç çıktılarını anlamasına ve işlemesine yardımcı olur

Araç Açıklaması:

  • İşlevselliğin kısa özeti
  • Parameter açıklamaları
  • Dönüş türü şeması

Uygulama:

  • I/O işlemleri için async/await
  • Eyleme döndürülebilir mesajlarla uygun hata işleme
  • Uygulanabilir yerlerde sayfalandırma desteği
  • Modern SDK'ları kullanırken hem metin içeriğini hem de yapılandırılmış verileri döndürün

Ek Açıklamalar:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

Aşama 3: İnceleme ve Test

3.1 Kod Kalitesi

Şunlar için inceleyin:

  • Yinelenmiş kod yok (DRY prensibi)
  • Tutarlı hata işleme
  • Tam tür kapsamı
  • Açık araç açıklamaları

3.2 Derle ve Test Et

TypeScript:

  • Derlemeyi doğrulamak için npm run build çalıştırın
  • MCP Inspector ile test edin: npx @modelcontextprotocol/inspector

Python:

  • Sözdizimini doğrulayın: python -m py_compile your_server.py
  • MCP Inspector ile test edin

Ayrıntılı test yaklaşımları ve kalite kontrol listeleri için dile özgü kılavuzlara bakın.

Aşama 4: Değerlendirmeler Oluşturun

MCP sunucunuzu uyguladıktan sonra, etkinliğini test etmek için kapsamlı değerlendirmeler oluşturun.

Tam değerlendirme yönergeleri için ✅ Değerlendirme Kılavuzu yükleyin.

4.1 Değerlendirmenin Amacını Anlayın

Değerlendirmeleri, LLM'lerin MCP sunucunuzu gerçekçi, karmaşık sorulara yanıt vermek için etkili bir şekilde kullanıp kullanamayacağını test etmek için kullanın.

4.2 10 Değerlendirme Sorusu Oluşturun

Etkili değerlendirmeler oluşturmak için değerlendirme kılavuzunda belirtilen işlemi takip edin:

  1. Araç İncelemesi: Mevcut araçları listeleyin ve yeteneklerini anlayın
  2. İçerik Keşfi: Mevcut verileri keşfetmek için SALT OKUNUR işlemler kullanın
  3. Soru Oluşturma: 10 karmaşık, gerçekçi soru oluşturun
  4. Yanıt Doğrulama: Yanıtları doğrulamak için her soruyu kendiniz çözün

4.3 Değerlendirme Gereksinimleri

Her sorunun şunları sağladığından emin olun:

  • Bağımsız: Diğer sorulara bağlı değil
  • Salt Okunur: Yalnızca yıkıcı olmayan işlemler gereklidir
  • Karmaşık: Birden fazla araç çağrısı ve derin keşif gerektirir
  • Gerçekçi: İnsanların önemseyeceği gerçek kullanım durumlarına dayanır
  • Doğrulanabilir: String karşılaştırması ile doğrulanabilen tek, açık yanıt
  • Kararlı: Yanıt zamanla değişmez

4.4 Çıkış Biçimi

Bu yapıyla bir XML dosyası oluşturun:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Referans Dosyaları

📚 Dokümantasyon Kütüphanesi

Geliştirme sırasında gerektiği gibi bu kaynakları yükleyin:

Temel MCP Belgeleri (Önce Yükleyin)

  • MCP Protokolü: https://modelcontextprotocol.io/sitemap.xml adresindeki site haritasından başlayın, ardından .md sonekiyle belirli sayfaları getirin
  • 📋 MCP En İyi Uygulamalar - Evrensel MCP yönergeleri dahil:
    • Sunucu ve araç adlandırma kuralları
    • Yanıt biçim yönergeleri (JSON vs Markdown)
    • Sayfalandırma en iyi uygulamaları
    • Taşıma seçimi (akışlı HTTP vs stdio)
    • Güvenlik ve hata işleme standartları

SDK Belgeleri (Aşama 1/2 sırasında Yükleyin)

  • Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md adresinden getirin
  • TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md adresinden getirin

Dile Özgü Uygulama Kılavuzları (Aşama 2 sırasında Yükleyin)

  • 🐍 Python Uygulama Kılavuzu - Tam Python/FastMCP kılavuzu ile:

    • Sunucu başlatma desenleri
    • Pydantic model örnekleri
    • @mcp.tool ile araç kaydı
    • Tam çalışan örnekler
    • Kalite kontrol listesi

  • ⚡ TypeScript Uygulama Kılavuzu - Tam TypeScript kılavuzu ile:

    • Proje yapısı
    • Zod şema desenleri
    • server.registerTool ile araç kaydı
    • Tam çalışan örnekler
    • Kalite kontrol listesi

Değerlendirme Kılavuzu (Aşama 4 sırasında Yükleyin)

  • ✅ Değerlendirme Kılavuzu - Tam değerlendirme oluşturma kılavuzu ile:
    • Soru oluşturma yönergeleri
    • Yanıt doğrulama stratejileri
    • XML biçim belirtimleri
    • Örnek sorular ve cevaplar
    • Sağlanan komutlarla değerlendirme çalıştırma

Benzer skill'ler

brainstorming Design

Herhangi bir yaratıcı çalışmaya başlamadan önce bunu mutlaka kullanın - feature oluştururken, component inşa ederken, functionality eklerken veya davranış değiştirirken. Kullanıcı niyetini, gereksinimleri ve tasarımı implementation öncesinde araştırır.

obra/superpowers ★ 235,495
finishing-a-development-branch Design

Uygulama tamamlandığında, tüm testler geçtiğinde ve çalışmanızı nasıl entegre edeceğinize karar vermeniz gerektiğinde kullanın - merge, PR veya cleanup seçeneklerini sunarak geliştirme sürecinin tamamlanmasını rehberlik eder.

obra/superpowers ★ 235,495
receiving-code-review Design

Kod incelemesi geri bildirimi alırken, önerileri uygulamadan önce kullanın; özellikle geri bildirim belirsiz veya teknik olarak şüpheli görünüyorsa - performatif anlaşmadan veya körü körüne uygulamadan ziyade teknik titizlik ve doğrulama gerekir.

obra/superpowers ★ 235,495
requesting-code-review Design

Görevleri tamamlarken, büyük özellikleri hayata geçirirken veya merge etmeden önce çalışmanın gereksinimleri karşıladığını doğrulamak için kullanın.

obra/superpowers ★ 235,495
using-git-worktrees Design

Yeni bir feature üzerinde çalışmaya başlarken veya implementasyon planını yürütmeden önce kullanın - native araçlar veya git worktree fallback aracılığıyla izole edilmiş bir workspace sağlar.

obra/superpowers ★ 235,495
using-superpowers Design

Herhangi bir konuşma başlatırken kullanın - skill'lerin nasıl bulunacağını ve kullanılacağını belirler, clarification soruları da dahil olmak üzere HERHANGİ bir yanıt vermeden önce skill invocation gerektirir.

obra/superpowers ★ 235,495
Daha fazla: Design →