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 研究社区精心打造