内容
# tracy-mcp
一款 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 代理查询 [Tracy profiler](https://github.com/wolfpld/tracy) 的 `.tracy` 捕获文件。
使用 C++ 编写，直接链接到 Tracy 的服务器/工作线程库（v0.13.1），因此它使用与 Tracy GUI 相同的代码读取捕获文件 - 无需重新实现二进制格式，无需使用命令行工具。可与任何 MCP 客户端配合使用：Claude Code、Codex、Cursor 等。
## 工具列表
| 工具 | 回答内容 |
|------|-----------------|
| `capture_info` | 程序、持续时间、区域/线程/帧计数 - 概览。 |
| `hotspots` | 按总时间（或自身时间）排名靠前的区域。 "什么很慢？" |
| `zone` | 匹配名称子字符串的区域的统计信息。 |
| `compare_captures` | 比较两个捕获文件之间的区域时间。 "什么退化了？" |
所有工具都需要 `.tracy` 文件的绝对路径。统计信息（平均值/最小值/最大值/标准差，自身时间）与 `tracy-csvexport` 完全匹配。
## 构建
需要 C++20 编译器、CMake ≥ 3.16、Ninja 和 git。依赖项（capstone、zstd、ppqsort、nlohmann/json）通过 CPM 在首次配置时自动获取。
```sh
git clone --recurse-submodules <此仓库> # Tracy 位于 third_party/tracy
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
# -> build/tracy-mcp(.exe)
cmake --install build --prefix <目录> # 可选： 将 tracy-mcp 放入 PATH
```
如果克隆时未包含子模块：
`git submodule update --init`（或仓库在 `third_party/tracy` 处提供 Tracy）。
## 连接
使用您构建的二进制文件的路径（`build/tracy-mcp` 或 `build/tracy-mcp.exe`），
或直接使用 `tracy-mcp`，如果您运行了 `cmake --install` 且它位于 PATH 中。
### Claude Code
```sh
claude mcp add tracy -- /路径/to/tracy-mcp.exe
```
### Codex / 其他客户端（stdio）
将客户端指向二进制文件作为 stdio MCP 服务器。示例配置块：
```json
{
"mcpServers": {
"tracy": { "command": "/路径/to/tracy-mcp.exe" }
}
}
```
然后询问类似 *"在 C:/captures/frame_spike.tracy 上运行热点， top 10 按自身时间排序"* 或 *"比较 baseline.tracy 和 today.tracy.*"
## 安装
两个渠道，均由 CI 中每个操作系统构建的二进制文件支持（`.github/workflows/release.yml`，由推送 `v*` 标签触发）。
### Claude Code 插件（自行构建）
此仓库也是一个插件市场（`.claude-plugin/marketplace.json`）。插件从 PATH 运行 `tracy-mcp`，因此先构建 + 安装（`cmake --install`），然后：
```sh
/plugin marketplace add HTRMC/tracy-mcp
/plugin install tracy-mcp@HTRMC
```
### MCPB 包（一步安装，Claude Desktop）
无需构建，无需工具链。从 [Releases](https://github.com/HTRMC/tracy-mcp/releases) 页面获取适用于您操作系统的 `tracy-mcp-<os>.mcpb`，然后在 Claude Desktop 中：设置 -> 扩展 -> 高级设置 -> 安装扩展，选择文件。
## 注意事项
- 捕获文件在服务器生命周期内按路径缓存在内存中。重启服务器以获取写入相同路径的重新捕获文件。
- 构建和测试针对 Tracy **0.13.1**。`.tracy` 格式是版本化的；将 `third_party/tracy` 子模块更新到与您的捕获文件版本匹配。
