Trackio MCP

🚀 trackio-mcp

trackio-mcp 為 trackio 實驗跟蹤提供了 MCP（模型上下文協議）服務器支持。藉助該工具，AI 代理能夠通過 MCP 協議觀察和與 trackio 實驗進行交互。只需在導入 trackio 之前導入 trackio_mcp，即可自動啟用 MCP 服務器功能。

✨ 主要特性

• 零代碼集成：只需在導入 trackio 之前導入 trackio_mcp。
• 自動 MCP 服務器：在所有 trackio 部署（本地和 Spaces）上啟用 MCP 服務器。
• 豐富的工具集：將 trackio 功能作為 MCP 工具暴露給 AI 代理。
• 與 Spaces 兼容：可與 Hugging Face Spaces 部署無縫協作。
• 即插即用：無需對現有的 trackio 代碼進行更改。

📦 安裝指南

使用以下命令安裝 trackio-mcp：

pip install trackio-mcp

若要安裝包含開發依賴的版本，可使用：

pip install trackio-mcp[dev]

🚀 快速開始

基礎用法

只需在導入 trackio 之前導入 trackio_mcp：

import trackio_mcp  # 啟用 MCP 服務器功能
import trackio as wandb

# 現有的 trackio 代碼無需更改
wandb.init(project="my-experiment")
wandb.log({"loss": 0.1, "accuracy": 0.95})
wandb.finish()

MCP 服務器將自動在以下地址可用：

• 本地：http://localhost:7860/gradio_api/mcp/sse
• Spaces：https://your-space.hf.space/gradio_api/mcp/sse

部署到支持 MCP 的 Hugging Face Spaces

import trackio_mcp
import trackio as wandb

# 自動啟用 MCP 部署到 Spaces
wandb.init(
    project="my-experiment", 
    space_id="username/my-trackio-space"
)

wandb.log({"loss": 0.1})
wandb.finish()

獨立 MCP 服務器

為 trackio 工具啟動一個專用的 MCP 服務器：

from trackio_mcp.tools import launch_trackio_mcp_server

# 在端口 7861 上啟動獨立 MCP 服務器
launch_trackio_mcp_server(port=7861, share=False)

💻 使用示例

可用的 MCP 工具

連接後，AI 代理可以使用以下 trackio 工具：

核心工具（通過 Gradio API）

• log：將指標記錄到 trackio 運行中。
• upload_db_to_space：將本地數據庫上傳到 Space。

擴展工具（通過 trackio-mcp）

• get_projects：列出所有 trackio 項目。
• get_runs：獲取特定項目的運行記錄。
• filter_runs：按名稱模式過濾運行記錄。
• get_run_metrics：獲取特定運行的指標數據。
• get_available_metrics：獲取項目的所有可用指標名稱。
• load_run_data：加載並處理運行數據，可選擇進行平滑處理。
• get_project_summary：獲取全面的項目統計信息。

示例代理交互

用戶: "給我展示 'image-classification' 項目的最新結果"

代理: 我將檢查你的 trackio 項目並獲取最新結果。

[工具: get_projects] → 找到 "image-classification" 項目
[工具: get_runs] → 獲取 "image-classification" 的運行記錄
[工具: get_run_metrics] → 獲取最新運行的指標
[工具: get_available_metrics] → 獲取指標名稱

代理: 你最新的圖像分類運行達到了 94.2% 的準確率，最終損失為 0.18。模型訓練了 50 個 epoch，在第 45 個 epoch 時驗證準確率最高，達到 94.7%。

📚 詳細文檔

MCP 客戶端配置

Claude Desktop

將以下內容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或等效文件中：

• 公共 Spaces：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Claude Code

更多信息請參閱 Claude Code MCP 文檔。

• 公共 Spaces：

claude mcp add --transport sse trackio https://your-space.hf.space/gradio_api/mcp/sse

• 私有 Spaces/數據集：

claude mcp add --transport sse --header "Authorization: Bearer YOUR_HF_TOKEN" trackio https://your-private-space.hf.space/gradio_api/mcp/sse

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Cursor

將以下內容添加到你的 Cursor ~/.cursor/mcp.json 文件中，或在項目文件夾中創建 .cursor/mcp.json 文件。更多信息請參閱 Cursor MCP 文檔。

• 公共 Spaces：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Windsurf

將以下內容添加到你的 Windsurf MCP 配置文件中。更多信息請參閱 Windsurf MCP 文檔。

• 公共 Spaces：

{
  "mcpServers": {
    "trackio": {
      "serverUrl": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcpServers": {
    "trackio": {
      "serverUrl": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "serverUrl": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

VS Code

將以下內容添加到 .vscode/mcp.json 文件中。更多信息請參閱 VS Code MCP 文檔。

• 公共 Spaces：

{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http",
        "url": "https://your-space.hf.space/gradio_api/mcp/sse"
      }
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http", 
        "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
        "headers": {
          "Authorization": "Bearer YOUR_HF_TOKEN"
        }
      }
    }
  }
}

• 本地開發：

{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http",
        "url": "http://localhost:7860/gradio_api/mcp/sse"
      }
    }
  }
}

Gemini CLI

將以下內容添加到項目目錄中的 mcp.json 文件中。詳細信息請參閱 Gemini CLI 配置。

• 公共 Spaces：

{
  "mcpServers": {
    "trackio": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-space.hf.space/gradio_api/mcp/sse"]
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcpServers": {
    "trackio": {
      "command": "npx", 
      "args": ["mcp-remote", "https://your-private-space.hf.space/gradio_api/mcp/sse"],
      "env": {
        "HF_TOKEN": "YOUR_HF_TOKEN"
      }
    }
  }
}

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:7860/gradio_api/mcp/sse"]
    }
  }
}

Cline

創建 .cursor/mcp.json（或適用於你的 IDE 的等效文件）：

• 公共 Spaces：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}

• 私有 Spaces/數據集：

{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}

• 本地開發：

{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

配置

環境變量

• TRACKIO_DISABLE_MCP：設置為 "true" 可禁用 MCP 功能（默認：啟用 MCP）。

編程控制

import os
os.environ["TRACKIO_DISABLE_MCP"] = "true"  # 禁用 MCP
import trackio_mcp  # MCP 將不會啟用
import trackio

工作原理

trackio-mcp 使用猴子補丁自動執行以下操作：

1. 啟用 MCP 服務器：在所有 Gradio 啟動時設置 mcp_server=True。
2. 啟用 API：設置 show_api=True 以暴露 Gradio API 端點。
3. 添加工具：註冊額外的特定於 trackio 的 MCP 工具。
4. 保持兼容性：無需對現有的 trackio 代碼進行更改。

該包會對以下內容進行補丁：

• gradio.Blocks.launch() - 核心 Gradio 啟動方法。
• trackio.ui.demo.launch() - trackio 儀表盤啟動。
• 在 /gradio_api/mcp/sse 添加新的 MCP 端點。

部署示例

本地開發

import trackio_mcp
import trackio

# 啟用 MCP 啟動本地跟蹤
trackio.show()  # 儀表盤 + MCP 服務器位於 http://localhost:7860

公共 Spaces 部署

import trackio_mcp
import trackio as wandb

# 部署到支持 MCP 的公共 Spaces
wandb.init(
    project="public-model",
    space_id="username/model-tracking"
)

wandb.log({"epoch": 1, "loss": 0.5})
wandb.finish()

私有 Spaces/數據集部署

import trackio_mcp
import trackio as wandb

# 部署到包含私有數據集的私有 Spaces
wandb.init(
    project="private-model",
    space_id="organization/private-model-tracking",  # 私有空間
    dataset_id="organization/private-model-metrics"  # 私有數據集
)

wandb.log({"epoch": 1, "loss": 0.5})
wandb.finish()

CLI 接口

# 啟動獨立 MCP 服務器
trackio-mcp server --port 7861

# 檢查狀態和配置
trackio-mcp status

# 測試 MCP 服務器功能
trackio-mcp test --url http://localhost:7860

🔧 技術細節

安全注意事項

• 私有 Spaces：使用 HF 令牌對私有空間/數據集進行身份驗證。
• 訪問控制：MCP 服務器繼承 trackio 的訪問控制。
• 網絡安全：在生產部署中考慮防火牆規則。
• 令牌管理：安全存儲 HF 令牌，使用環境變量。

故障排除

MCP 服務器不可用

import trackio_mcp
import trackio

# 檢查 MCP 是否被禁用
import os
print("MCP Disabled:", os.getenv("TRACKIO_DISABLE_MCP"))

# 手動驗證
trackio.show()  # 在輸出中查找 MCP 服務器 URL

連接問題

1. 檢查 URL：確保 /gradio_api/mcp/sse 端點正確。
2. 身份驗證：為私有 Spaces/數據集添加 Bearer 令牌。
3. 網絡：驗證防火牆/代理設置。
4. 依賴項：確保安裝了 gradio[mcp]。

工具發現問題

# 手動測試工具
from trackio_mcp.tools import register_trackio_tools

tools = register_trackio_tools()
tools.launch(mcp_server=True)  # 測試工具界面

🤝 貢獻

1. 分叉倉庫。
2. 安裝開發依賴：pip install -e .[dev]。
3. 進行更改。
4. 運行測試：pytest。
5. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件獲取詳細信息。

🙏 致謝

• trackio - 優秀的實驗跟蹤庫。
• Gradio - 提供內置的 MCP 服務器支持。
• Model Context Protocol - 提供標準化的 AI 工具協議。

為 AI 研究社區精心打造