# API ve MCP Sunucusu Olarak Trackio

Trackio paneli, hem bir HTTP API sunucusu hem de bir MCP (Model Context Protocol) sunucusu olarak çalışacak şekilde yapılandırılabilir. Bu sayede harici araçlar ve uygulamalar deney izleme verilerinizle programatik olarak etkileşime girebilir veya ChatGPT, Claude, Deepseek gibi MCP destekleyen çeşitli LLM'ler aracılığıyla deney verilerinizle doğal dilde "sohbet edebilirsiniz". Bu özellik, Trackio'yu otonom ML deneyleri yürüten LLM ajanları için ideal bir seçim haline getirir; zira bu ajanlar metrikleri sorunsuz bir şekilde kaydedebilir ve deney sonuçlarını sorgulayabilir.

## Kurulum

Opsiyonel MCP bağımlılığını yükleyin, ardından Trackio panelini başlatırken MCP sunucusunu etkinleştirin. Bunu birkaç farklı şekilde yapabilirsiniz:

```bash
pip install "trackio[mcp]"
```

### Seçenek 1: CLI Komutu
```bash
trackio show --mcp-server
```

### Seçenek 2: Python Fonksiyonu
```python
import trackio
trackio.show(mcp_server=True)
```

### Seçenek 3: Ortam Değişkeni
```bash
export GRADIO_MCP_SERVER=True
trackio show
```

MCP sunucu modu etkinleştirildiğinde, Trackio:
- Panelin yanında streamable-HTTP MCP sunucusu bağlar
- MCP istemcilerine salt okunur proje/çalışma/metrik inceleme araçları sunar
- Yazma belirteciyle korunan küçük bir mutasyon aracı seti (sil/yeniden adlandır/senkronize) sunar

## API Kullanımı

Trackio, her MCP aracını `POST /api/{tool_name}` adresinde düz bir HTTP uç noktası olarak sunar. Gövde JSON formatındadır; argümanları `{"kwargs": {...}}`, `{"args": [...]}` veya basitçe düz bir `{"name": value}` nesnesi olarak iletebilirsiniz.

```python
import httpx2

base = "http://127.0.0.1:7860"

projects = httpx2.post(f"{base}/api/get_all_projects").json()["data"]
print("Projects:", projects)

runs = httpx2.post(
    f"{base}/api/get_runs_for_project",
    json={"project": "my-project"},
).json()["data"]
print("Runs:", runs)

values = httpx2.post(
    f"{base}/api/get_metric_values",
    json={"project": "my-project", "run": "run-1", "metric_name": "loss"},
).json()["data"]
print("Loss values:", values)
```

```javascript
const base = "http://127.0.0.1:7860";

async function call(name, payload = {}) {
  const res = await fetch(`${base}/api/${name}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  return (await res.json()).data;
}

console.log("Projects:", await call("get_all_projects"));
console.log("Runs:", await call("get_runs_for_project", { project: "my-project" }));
console.log("Loss:", await call("get_metric_values", {
  project: "my-project",
  run: "run-1",
  metric_name: "loss",
}));
```

```bash
# Get all projects
curl -s -X POST http://127.0.0.1:7860/api/get_all_projects \
  -H "Content-Type: application/json" -d '{}'

# Get runs for a project
curl -s -X POST http://127.0.0.1:7860/api/get_runs_for_project \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project"}'

# Get values for a metric
curl -s -X POST http://127.0.0.1:7860/api/get_metric_values \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project", "run": "run-1", "metric_name": "loss"}'
```

## MCP Kullanımı

MCP sunucusu olarak çalıştırıldığında Trackio, araçlarını MCP uyumlu istemcilerin (Claude Desktop, Claude Code vb.) bağlanabileceği tek bir streamable-HTTP uç noktasında (endpoint) sunar.

### MCP Sunucu URL'si

MCP sunucusu şu adreste kullanılabilir:
```txt
http://127.0.0.1:7860/mcp/
```

Bir Hugging Face Space'e dağıtıldığında URL `https://<your-space>.hf.space/mcp/` şeklindedir.

### Kullanılabilir MCP Araçları

Okuma araçları:

1. **get_all_projects** – Bu sunucudaki tüm Trackio projelerini listeler.
2. **get_runs_for_project** – Belirtilen proje için çalıştırmaları listeler.
3. **get_metrics_for_run** – Bir çalıştırma için kaydedilen metrik adlarını listeler.
4. **get_metric_values** – Bir çalıştırma için metrik değerlerini, isteğe bağlı olarak bir adım veya zamanın etrafında getirir.
5. **get_project_summary** – Bir proje için özet meta verileri.
6. **get_run_summary** – Bir çalıştırma için özet meta verileri.
7. **get_system_metrics_for_run** – Bir çalıştırma için kaydedilen sistem metrik adlarını listeler.
8. **get_system_logs** – Bir çalıştırma için sistem metrik günlüklerini getirir.
9. **get_snapshot** – Bir adım veya zaman damgası etrafındaki tek bir anlık görüntüyü getirir.
10. **get_logs** – Bir çalıştırma için metrik günlüklerini getirir.
11. **get_alerts** – Bir proje için uyarıları getirir; isteğe bağlı olarak çalıştırma veya seviye ile filtrelenir.
12. **get_settings** – Panel ayarlarını ve varlık yapılandırmasını döndürür.

Mutasyon araçları (yazma erişimi gerektirir — aşağıya bakın):

13. **delete_run** – Bir çalıştırmayı siler.
14. **rename_run** – Bir çalışmayı yeniden adlandırır.
15. **trigger_sync** – Hugging Face'e bir dışa aktarma/ senkronizasyon geçişi başlatır.

### Mutasyon Araçları İçin Yazma Erişimi

Mutasyon araçları kapalıdır:

- **Yerel panel:** `write_token` argümanını iletin. Token, `trackio show` komutunu çalıştırdığınızda terminalde yazdırılır (başlangıçta yazdırılan panel URL'sine `?write_token=...` olarak da gömülüdür). Örneğin:
  ```json
  {"project": "my-project", "run": "run-1", "write_token": "<token from startup output>"}
  ```
- **Hugging Face Spaces:** Space deposuna yazma erişimine sahip bir `hf_token` argümanı geçirin. Bu durumda yerel `write_token` kullanılmaz.

Okuma araçları asla bir jeton gerektirmez.

### MCP İstemcisi Yapılandırması

streamable-HTTP MCP sunucularını destekleyen istemcilere Trackio eklemek için şu yapılandırmayı kullanın:

```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://127.0.0.1:7860/mcp/"
    }
  }
}
```