ginimageApi/app/mcp

MCP (Model Context Protocol) Server - GinImage API

Bu dizin, GinImage API'nin Model Context Protocol (MCP) sunucusu uygulamasını içerir.

⚠️ Önemli: v0.1.0 - mcp-go Migration Tamamlandı

Eski uygulama (hand-written JSON-RPC): Tamamen kaldırıldı.
Yeni uygulama (mark3labs/mcp-go): Tek kaynak. Tüm MCP istekleri mcp-go tarafından işlenir. Protocol compliance: %100.

Değişiklik Özeti

Unsur	Eski	Yeni
Kod satırı sayısı	~1100	~250
JSON-RPC handler	Elle yazılmış	mcp-go sağlıyor
Tool registration	Switch-case	server.AddTool()
Protocol compliance	Elle test	%100 (mcp-go)

---

1) Servisi Başlat

Proje kökünde:

go run .

Varsayılan port 8080 olduğu için MCP endpoint:

• http://127.0.0.1:8080/mcp

Farklı port kullanmak istersen:

PORT=9090 go run .

---

2) Cursor MCP Ayarı

~/.cursor/mcp.json dosyasına şu şekilde ekle:

{
  "mcpServers": {
    "ginimage-api": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Sonra Cursor'da MCP server'i yenile/reload et.

---

3) Mevcut Tool'lar

3.1) api_overview

• Açıklama: GinImage API endpoint özeti ve kullanımı
• Giriş: Yok
• Çıkış: Metin

3.2) health_check

• Açıklama: API health endpoint durumunu kontrol eder
• Giriş: path (string, opsiyonel) - Varsayılan: /swagger/index.html
• Çıkış: Metin

3.3) md_guide_list

• Açıklama: docs/mcp-tools altındaki markdown rehber dosyalarını listeler
• Giriş: Yok
• Çıkış: Metin

3.4) md_guide_get

• Açıklama: Seçilen markdown rehber dosyasının içeriğini döndürür
• Giriş: guide (string, zorunlu) - Rehber dosya adı (örn: codebase_map.md)
• Çıkış: Metin (dosya içeriği)

3.5) codebase_map

• Açıklama: Proje klasör ve kritik dosya yapısını özetler
• Giriş:
  • focus (string, opsiyonel) - Odak klasörü
  • depth (number, opsiyonel) - Tarama derinliği (varsayılan: 2, maksimum: 5)
• Çıkış: Metin (proje yapısı)

3.6) tool_stats

• Açıklama: MCP tool kullanım istatistiklerini veritabanından özetler
• Giriş: limit (number, opsiyonel) - Kayıt limiti (varsayılan: 10, maksimum: 50)
• Çıkış: Metin (istatistikler)

---

3.7) Markdown Rehberi Yükleme Endpoint'i

POST /api/v1/mcp/guides/upload

• docs/mcp-tools altına .md dosyası yükler
• multipart/form-data bekler
• Zorunlu alan: file (.md uzantılı)
• Opsiyonel alan: overwrite (true/false, varsayılan: false)
• Güvenlik: Bearer Token gerekli

---

4) Örnek MCP Çağrıları (JSON-RPC 2.0)

Tool Listesini Almak

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

api_overview Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"api_overview",
      "arguments":{}
    }
  }'

health_check Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"health_check",
      "arguments":{"path":"/swagger/index.html"}
    }
  }'

md_guide_list Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"md_guide_list",
      "arguments":{}
    }
  }'

md_guide_get Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":5,
    "method":"tools/call",
    "params":{
      "name":"md_guide_get",
      "arguments":{"guide":"codebase_map.md"}
    }
  }'

codebase_map Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":6,
    "method":"tools/call",
    "params":{
      "name":"codebase_map",
      "arguments":{"focus":"app/images","depth":2}
    }
  }'

tool_stats Çağrısı

curl -X POST "http://127.0.0.1:8080/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":7,
    "method":"tools/call",
    "params":{
      "name":"tool_stats",
      "arguments":{"limit":10}
    }
  }'

Markdown Rehberi Yükleme

curl -X POST "http://127.0.0.1:8080/api/v1/mcp/guides/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@./docs/mcp-tools/ornek-rehber.md" \
  -F "overwrite=false"

---

5) Ortam Değişkenleri

• PORT (opsiyonel)

  • Gin API ve MCP endpoint'inin dinleyeceği port (varsayılan: 8080)

• GINIMAGE_API_BASE_URL (opsiyonel)

  • health_check tool'unun kontrol için kullanacağı base URL
  • Tanımlanmamışsa gelen isteğin host bilgisinden otomatik üretilir

---

6) Mimari

app/mcp/
├── server.go           # HTTP handlers, DELETE handler, helper functions
├── server_mcpgo.go     # mcp-go tool registration, logging wrapper
├── models/
│   ├── tool_run.go     # ToolRun DB modeli
│   └── ...
└── README.md (this file)

---

7) Yeni Tool Ekleme Rehberi

Adım 1: Tool'u Kayıt Et

server_mcpgo.go içinde newMCPGoServer() içine ekle:

s.AddTool(
	mcpgo.NewTool(
		"my_tool",
		mcpgo.WithDescription("Tool açıklaması."),
		mcpgo.WithString("param1", mcpgo.Description("Parametre 1"), mcpgo.Required()),
		mcpgo.WithNumber("param2", mcpgo.Description("Parametre 2")),
	),
	withToolRunLog("my_tool", func(ctx context.Context, req mcpgo.CallToolRequest) (*mcpgo.CallToolResult, error) {
		// Parametreleri ayrıştır
		param1, err := req.RequireString("param1")
		if err != nil {
			return mcpgo.NewToolResultError(err.Error()), nil
		}
		param2 := req.GetInt("param2", 0)

		// İşlem yap
		result := "Sonuç"

		// Sonuç dön
		return mcpgo.NewToolResultText(result), nil
	}),
)

Adım 2: Parametre Yardımcıları

CallToolRequest yöntemleri:

• GetString(key, defaultValue) string
• RequireString(key) (string, error)
• GetInt(key, defaultValue) int
• RequireInt(key) (int, error)
• GetFloat(key, defaultValue) float64
• RequireFloat(key) (float64, error)
• GetBool(key, defaultValue) bool
• RequireBool(key) (bool, error)
• GetArguments() map[string]any
• BindArguments(target any) error (strongly-typed)

Adım 3: Sonuç Türleri

• Metin: mcpgo.NewToolResultText(text string)
• JSON: mcpgo.NewToolResultJSON(data any)
• Yapılandırılmış: mcpgo.NewToolResultStructured(structured any, fallbackText string)
• Hata: mcpgo.NewToolResultError(text string)
• Resim: mcpgo.NewToolResultImage(text, imageData, mimeType string)
• Ses: mcpgo.NewToolResultAudio(text, audioData, mimeType string)

Adım 4: DB Loglama (Otomatik)

withToolRunLog wrapper'ı otomatik olarak:

• Tool çağrı zamanını ölçer
• Başarı/hata durumunu kaydeder
• Argümanları (4096 byte'a kadar) kayıt eder
• mcp_tool_runs tablosuna yazar

---

8) Sık Karşılaşılan Sorunlar

Hata	Çözüm
connection refused	Backend çalışmıyor. go run . ile başlat
MCP server Cursor'da görünmüyor	~/.cursor/mcp.json dosya formatını kontrol et, Cursor MCP reload yap
404 dönüyor	URL doğru mu? /mcp route'u kullanılmalı
health_check beklenmedik hosta gidiyor	GINIMAGE_API_BASE_URL değerini açıkça ver
md_guide_get "guide not found" dönüyor	Dosya docs/mcp-tools altında mı? .md uzantısı mı?

---

9) Referanslar

• MCP Specification
• mark3labs/mcp-go
• GinImage API Overview: apiOverviewText() fonksiyonu bak

---

Sürüm: 0.1.0 (mcp-go migration)
Tarih: 2026-04-16
Durum: ✅ Production Ready