210 lines
5.1 KiB
Markdown
210 lines
5.1 KiB
Markdown
# 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.
|