first commit

2026-04-26 21:40:14 +03:00
commit e04ba85564
129 changed files with 17541 additions and 0 deletions
--- a/docs/mcp-tools/MCP_KOLAY_REHBER.md
+++ b/docs/mcp-tools/MCP_KOLAY_REHBER.md
@@ -0,0 +1,209 @@
+# 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.