first commit
This commit is contained in:
Beyhan Oğur
337
app/mcp/README.md
Normal file
337
app/mcp/README.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user