beyhan/ginimageApi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e04ba855649d00180091747bdc326672b353fe8b
ginimageApi/app/mcp/README.md
Beyhan Oğur e04ba85564 first commit
2026-04-26 21:40:14 +03:00

8.0 KiB
Raw Blame History

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

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

Reference in New Issue View Git Blame Copy Permalink