# MCP Kolay Rehber (GinImage API)

Bu dokumanin amaci:
- MCP'nin ne oldugunu 2 dakikada anlatmak
- Bu projede nasil kullanacagini adim adim gostermek
- Kendi amacina uygun hale getirmen icin net bir yol vermek

## 1) MCP nedir?

MCP, LLM'in (AI asistanin) senin uygulamana standart bir yoldan baglanmasini saglar.
Bu projede MCP, ayri bir uygulama degil; mevcut backend icinde bir endpoint olarak calisiyor:

- POST /mcp

Yani AI, dogrudan tum API'yi ezberlemek yerine MCP uzerinden tool cagiriyor.

## 2) Bu projede MCP su an ne yapiyor?

Mevcut tool'lar:
- api_overview: API endpoint ozetini metin olarak doner
- health_check: verdigin path'e istek atar, HTTP durum kodu doner

Kaynak kod:
- app/mcp/server.go

## 3) 5 dakikada calistir

1. Projeyi baslat:

```bash
go run .
```

2. MCP endpoint:

- http://127.0.0.1:8080/mcp

3. Test et (tool listesi):

```bash
curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/list"
  }'
```

Beklenen sonuc: tools listesinde `api_overview` ve `health_check` gorursun.

## 4) Cursor'a baglama

Cursor MCP ayari icin ornek dosya:
- app/mcp/README.md

Ozet:
- Cursor MCP config'e bu endpoint'i eklersin: http://127.0.0.1:8080/mcp
- Cursor'da MCP reload yaparsin

## 5) MCP'yi hangi amac icin kullanmaliyim?

En iyi kullanim: "AI operator" gibi.

Ornek amaclar:
- Operasyon: servis sagligi, baglantilar, log ozetleri
- Icerik yonetimi: blog taslagi olusturma, yayinlama adimlari
- Medya pipeline: toplu resim isleme, kalite kontrol raporu

Kural:
- Sik yaptigin ama hata riski olan isleri tool'a cevir.

## 6) Kendi amacina uygun hale getirme plani

Asagidaki sirayla ilerle:

1. Amaci yaz (tek cumle)
- Ornek: "AI ile blog operasyonlarini hizlandirmak"

2. 3-5 ana tool sec
- blog_list_drafts
- blog_create_draft
- blog_publish
- image_process_batch
- system_health_summary

3. Her tool icin input schema belirle
- zorunlu alanlar
- tipler (string, number, boolean)
- enum alanlar (ornek: status = draft|published)

4. Yetki katmani koy
- read-only tool'lari ayri
- admin gerektiren write tool'lari ayri

5. Hata formatini standartlastir
- invalid params
- unauthorized
- not found
- internal error

6. Log ve izleme ekle
- hangi tool cagrildi
- ne kadar surdu
- basarili/basarisiz

## 7) Tool ekleme ornegi (fikri)

Ornek yeni tool: `blog_list_recent`

Ne yapar:
- son N blog kaydini dondurur

Input:
- limit (opsiyonel, default 10, max 50)

Output:
- baslik, slug, olusturma tarihi listesi

Neden faydali:
- AI once mevcut icerigi gorur, sonra dogru aksiyon alir

## 8) Guvenlik kontrol listesi

MCP endpoint aciksa su kontrolleri yap:
- Rate limit aktif mi?
- Sadece gerekli tool'lar acik mi?
- Write tool'lar icin yetki kontrolu var mi?
- Hassas veriler response'a siziyor mu?

## 9) Sik sorunlar

1. connection refused
- Uygulama calismiyor, `go run .` ile baslat

2. 404 /mcp
- route ekli mi kontrol et: routers/router.go

3. tools/list bos ya da hata
- gonderdigin JSON-RPC body formatini kontrol et

4. health_check yanlis hosta gidiyor
- GINIMAGE_API_BASE_URL degerini acik ver

## 10) Kisa ozet

- MCP = AI icin standart tool kapisi
- Bu projede giris noktasi = POST /mcp
- Bugun hemen kullanmak icin: tools/list + tools/call testleri yeterli
- Gercek fayda icin: kendi operasyonuna uygun 3-5 tool ekle

## 11) Kod gelistirme odakli kullanim (senin senaryo)

Eger hedefin kod gelistirme ise, MCP'yi "AI coding teammate" gibi konumlandir.
Bu durumda tool'larin, uygulamayi calistirmak yerine gelistirme kararlarini hizlandirmali.

Oncelikli 5 tool:

1. codebase_map
- Ne yapar: proje modul yapisini ve kritik dosyalari ozetler
- Neden lazim: AI once yapini anlar, yanlis dosyada degisiklik yapmaz

2. endpoint_contract_find
- Ne yapar: bir endpointin handler/model/response baglantilarini bulur
- Input: method + path (ornek: GET /api/v1/images)
- Neden lazim: API degisikliklerinde tum etkileri hizli gorursun

3. test_plan_suggest
- Ne yapar: secilen dosya veya endpoint icin test senaryolari uretir
- Input: hedef dosya veya endpoint
- Neden lazim: test acigini erken kapatir

4. safe_refactor_check
- Ne yapar: degisecek sembolun kullanildigi yerleri listeler
- Input: symbol name
- Neden lazim: refactor kirilma riskini dusurur

5. runbook_dev
- Ne yapar: bir gorev icin adim adim gelistirme akisi dondurur
- Input: gorev tanimi (ornek: image process endpointine webp kalite limiti ekle)
- Neden lazim: AI'dan tutarli ve tekrar edilebilir cikti alirsin

## 12) Kod gelistirme icin kisa uygulama plani

1. Hafta 1: read-only tool'lar
- codebase_map
- endpoint_contract_find
- safe_refactor_check

2. Hafta 2: kalite ve otomasyon
- test_plan_suggest
- runbook_dev

3. Son adim: kontrol noktasi
- her tool icin ornek input-output
- hata kodlari
- loglama ve sure olcumu

## 13) Baslangic hedefi (onerilen)

Ilk sprintte su tek hedefle basla:

- "Bir endpoint degisikligi yapmadan once etkilenecek dosyalari ve test planini MCP uzerinden otomatik almak"

Bu hedef, hem hiz hem kalite kazandirir; yazma (write) tool'larina gecmeden once guvenli bir temel olusturur.

---

Istersen bir sonraki adimda senin hedefini tek cumleyle yazalim, buna gore dogrudan server.go icine 5 net tool tasarlayip ekleyebilirim.