🤖 Primitive MCP: Sıfırdan Kendi SDK'nızı Yazın!

Resmi SDK'ların soyutlama katmanları arasında kaybolmayın. Bare-Metal (saf) kodla kendi MCP sunucunuzu yazın ve Yapay Zekanın kodunuzla nasıl konuştuğunu tam olarak anlayın!

Bu proje, Anthropic'in geliştirdiği Model Context Protocol (MCP) mantığını en temel seviyede kavramak ve kendi "ilkel" (primitive) SDK'nızı yazmanız için hazırlanmış adım adım bir eğitim serisidir.

🎯 Neden Bu Proje?

Resmi MCP SDK'ları (Python veya TypeScript) harikadır ancak arka planda ne döndüğünü anlamayı zorlaştıracak kadar çok soyutlama içerirler. Bu repo:

• AI modellerinin (Claude, GPT vb.) sizin fonksiyonlarınızı nasıl keşfettiğini (Discovery),

• JSON-RPC 2.0 protokolünün Stdio üzerinden nasıl aktığını,

• Ajanların (Agents) kendi hatalarını nasıl düzelttiğini (Self-Healing) size sıfırdan kod yazdırarak öğretir.

Related MCP server: MCP Learning Project

⏱️ Git ile Adım Adım İlerleme (Zaman Makinesi)

Bu eğitim reposu adım adım inşa edilmiştir. Her adımdaki kod durumunu görmek için Git etiketlerini (Tags) kullanabilirsiniz.

• Geçmişe Gitmek (Adım 1'e dönmek):

  git checkout step_1

  (Not: Git size "Detached HEAD" uyarısı verebilir, bu normaldir. Sadece kodu inceleyebilirsiniz).

• Tekrar Günümüze (En son koda) Dönmek:

  git checkout main

Eğitimi takip ederken, ilgili adımın kodunu incelemek için terminalden o adıma checkout yapabilirsiniz.

🗺️ 10 Adımlık Yolculuk

Bu repo sadece bitmiş bir kod değildir, aynı zamanda bir zaman tünelidir. Git tag'lerini kullanarak her adıma gidebilirsiniz:

graph LR
    S1[Adım 1 & 2<br/>Temeller] --> S2[Adım 3 & 4<br/>Router & El Sıkışma]
    S2 --> S3[Adım 5<br/>Ping]
    S3 --> S4[Adım 6<br/>Resources]
    S4 --> S5[Adım 7 & 8<br/>Tools]
    S5 --> S6[Adım 9 & 10<br/>Hata & Paketleme]
    
    style S1 fill:#f9f,stroke:#333,stroke-width:2px
    style S6 fill:#bbf,stroke:#333,stroke-width:2px

Dersleri takip ederken kullanabileceğiniz adımlar:

• Bölüm 1: Temeller (Adım 1-3) -> JSON-RPC mesaj yapıları ve Stdio transport katmanı.

• Bölüm 2: Yaşam Döngüsü (Adım 4-5) -> El sıkışma (Initialize) ve Canlılık (Ping) kontrolleri.

• Bölüm 3: Özellikler (Adım 6-8) -> Kaynaklar (Resources) ve Araçların (Tools) listelenmesi ve çalıştırılması.

• Bölüm 4: Olgunlaşma (Adım 9-10) -> Hata yönetimi ve projeyi pip ile yüklenebilir bir SDK'ya dönüştürme.

🧬 MCP Nasıl Çalışır? (Mimari Görsel)

Bir AI modelinin sizin bilgisayarınızdaki bir dosyayı okuması veya bir fonksiyonu çalıştırması şu sırayla gerçekleşir:

sequenceDiagram
    participant LLM as Yapay Zeka (Model)
    participant Client as Host Uygulama (Örn: Claude Desktop)
    participant Server as Sizin MCP Sunucunuz (Bu Repo)

    Client->>Server: 1. initialize (El sıkışma isteği)
    Server-->>Client: 2. capabilities (Ben araç çalıştırabilirim)
    Client->>Server: 3. tools/list (Bana menüyü getir)
    Server-->>Client: 4. tools listesi (JSON Şemaları)
    Client->>LLM: 5. Bak elinde şu araçlar var
    LLM->>Client: 6. 'get_product_price' aracını çağır
    Client->>Server: 7. tools/call (Parametreler ile)
    Server-->>Client: 8. Sonuç (150 TL veya Hata Mesajı)
    Client-->>LLM: 9. Sonucu modele ilet

⚠️ Altın Kural (Çok Kritik!)

Sunucumuz (Server) sadece sys.stdin üzerinden okuma yapacak ve sys.stdout üzerinden modele JSON dönecektir. Eğer kodunuzun herhangi bir yerinde normal print() kullanarak ekrana log basarsanız, modelin JSON okuyucusu bozulur ve sistem çöker! Bu yüzden tüm loglar sys.stderr üzerinden akmalıdır.

📚 Öne Çıkan Eğitim Konseptleri

1. Discovery (Keşif) Mantığı

Model sizin hangi fonksiyonlara sahip olduğunuzu önceden bilmez. tools/list isteği attığında ona fonksiyonun kodunu değil, JSON Şemasını döneriz. Model bu şemaya bakarak hangi parametreleri göndermesi gerektiğini öğrenir.

2. Self-Healing (Kendi Kendini Onarma)

Bir fonksiyon çöktüğünde (Exception fırlattığında) bunu bir protokol hatası olarak dönmeyiz. isError: true bayrağı ile birlikte hatayı modele mesaj olarak döneriz. Model hatayı okur (Örn: "Sıfıra bölme hatası") ve parametreyi düzelterek aracı tekrar çağırır.

🚀 Simülasyonu Çalıştırma

Projeyi bilgisayarınıza klonladıktan sonra hiçbir karmaşık kuruluma gerek kalmadan simülasyonu çalıştırabilirsiniz:

python3 src/simulation.py

📦 Kendi Projenize Dahil Etme (Adım 10 Sonrası)

Proje klasöründe şu komutu çalıştırarak kendi yazdığınız SDK'yı sisteminize bir kütüphane gibi kurabilirsiniz:

pip3 install -e .

🤝 Katkıda Bulunma

Bu bir eğitim projesidir. Eksik gördüğünüz veya daha iyi anlatılabileceğini düşündüğünüz kısımlar için PR (Pull Request) açabilir veya Issue oluşturabilirsiniz.

📄 Lisans

Bu proje MIT lisansı ile lisanslanmıştır. Eğitim amaçlı her türlü kullanım serbesttir.