# 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: ```bash go run . ``` Varsayılan port `8080` olduğu için MCP endpoint: - `http://127.0.0.1:8080/mcp` Farklı port kullanmak istersen: ```bash PORT=9090 go run . ``` --- ## 2) Cursor MCP Ayarı `~/.cursor/mcp.json` dosyasına şu şekilde ekle: ```json { "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 ```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" }' ``` ### `api_overview` Çağrısı ```bash 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ı ```bash 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ı ```bash 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ı ```bash 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ı ```bash 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ı ```bash 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 ```bash 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: ```go 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](https://modelcontextprotocol.io/) - [mark3labs/mcp-go](https://github.com/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