# API 및 MCP 서버로서의 Trackio

Trackio 대시보드는 HTTP API 서버와 MCP(Model Context Protocol) 서버로 동시에 구성할 수 있으며, 이를 통해 외부 도구 및 애플리케이션이 실험 추적 데이터에 프로그래매틱하게 상호작용하거나, ChatGPT, Claude, Deepseek 또는 MCP를 지원하는 다양한 LLM을 사용하여 자연어로 "실험 데이터와 대화"할 수 있습니다. 이는 자율적으로 ML 실험을 수행하는 LLM 에이전트에 대해 Trackio가 이상적인 선택지가 되도록 하며, 에이전트가 메트릭을 기록하고 실험 결과를 쿼리하는 과정을 원활하게 수행할 수 있기 때문입니다.

## 설정

선택적 MCP 의존성을 설치한 후 Trackio 대시보드를 시작할 때 MCP 서버를 활성화합니다. 이를 수행하는 방법은 다음과 같습니다:

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

### 옵션 1: CLI 명령
```bash
trackio show --mcp-server
```

### 옵션 2: Python 함수
```python
import trackio
trackio.show(mcp_server=True)
```

### 옵션 3: 환경 변수
```bash
export GRADIO_MCP_SERVER=True
trackio show
```

MCP 서버 모드가 활성화되면 Trackio는 다음과 같습니다:
- Mounts a streamable-HTTP MCP server alongside the dashboard
- MCP 클라이언트에 읽기 전용 프로젝트/실행/메트릭 검사 도구를 노출합니다
- 쓰기 토큰으로 제어되는 소수의 변경 도구(삭제/이름 변경/동기화)를 노출합니다

## API 사용

Trackio는 각 MCP 도구를 `POST /api/{tool_name}`의 일반 HTTP 엔드포인트로 노출합니다. 본문은 JSON이며, 인수는 `{"kwargs": {...}}`, `{"args": [...]}` 또는 단순히 평탄한 `{"name": value}` 객체로 전달합니다.

```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 사용

MCP 서버로 실행할 때, Trackio는 MCP 호환 클라이언트(Claude Desktop, Claude Code 등)가 연결할 수 있는 단일 streamable-HTTP 엔드포인트에서 도구를 노출합니다.

### MCP 서버 URL

MCP 서버는 다음에서 사용할 수 있습니다:
```txt
http://127.0.0.1:7860/mcp/
```

Hugging Face Space에 배포하면 URL은 `https://<your-space>.hf.space/mcp/`입니다.

### 사용 가능한 MCP 도구

읽기 도구:

1. **get_all_projects** – 이 서버의 모든 Trackio 프로젝트를 나열합니다.
2. **get_runs_for_project** – 주어진 프로젝트의 실행 목록을 가져옵니다.
3. **get_metrics_for_run** – 실행에 대해 기록된 지표 이름을 나열합니다.
4. **get_metric_values** – 실행(run)의 메트릭 값을 가져오며, 필요에 따라 특정 스텝 또는 시간 주변 값을 조회합니다.
5. **get_project_summary** – 프로젝트에 대한 요약 메타데이터.
6. **get_run_summary** – 실행에 대한 요약 메타데이터.
7. **get_system_metrics_for_run** – 실행에 대해 기록된 시스템 메트릭 이름을 나열합니다.
8. **get_system_logs** – 실행에 대한 시스템 메트릭 로그를 가져옵니다.
9. **get_snapshot** – 특정 스텝 또는 타임스탬프 주변의 단일 스냅샷을 가져옵니다.
10. **get_logs** – 실행에 대한 메트릭 로그를 가져옵니다.
11. **get_alerts** – 프로젝트의 알림을 가져오며, 필요에 따라 run 또는 level으로 필터링할 수 있습니다.
12. **get_settings** – 대시보드 설정 및 자산 구성을 반환합니다.

변형 도구(쓰기 권한 필요 — 아래 참조):

13. **delete_run** – 실행을 삭제합니다.
14. **rename_run** – 실행 이름 변경.
15. **trigger_sync** – Hugging Face로의 내보내기/동기화 패스를 트리거합니다.

### 변형 도구를 위한 쓰기 액세스

변형 도구는 게이트 처리됩니다:

- **로컬 대시보드:** `write_token` 인수를 전달합니다. `trackio show`를 실행하면 터미널에 토큰이 출력됩니다(시작 시 출력되는 대시보드 URL에 `?write_token=...`로 내장되어 있습니다). 예를 들어:
  ```json
  {"project": "my-project", "run": "run-1", "write_token": "<token from startup output>"}
  ```
- **Hugging Face Spaces:** Space의 저장소에 대한 쓰기 권한이 있는 `hf_token` 인수를 전달합니다. 이 경우 로컬 `write_token`은 사용되지 않습니다.

Read 도구에는 토큰이 필요하지 않습니다.

### MCP 클라이언트 구성

streamable-HTTP MCP 서버를 지원하는 클라이언트에 Trackio를 추가하려면 다음과 같은 설정을 사용하세요:

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