ginimageApi/docs/mcp-tools/MCP_KOLAY_REHBER.md

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:

go run .

2. MCP endpoint:

• http://127.0.0.1:8080/mcp

3. Test et (tool listesi):

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.