338 lines
8.0 KiB
Markdown
338 lines
8.0 KiB
Markdown
# 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
|