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

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP Compliant](https://img.shields.io/badge/MCP-Compliant-orange.svg)](https://modelcontextprotocol.io)

> **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.

---

## ⏱️ 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):**
  ```bash
  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:**
  ```bash
  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:

```mermaid
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:

```mermaid
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:

```bash
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:
```bash
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.