mcdk-mcp-tracy

一个 MCP 服务器：对运行中的网易我的世界基岩版 MOD 做性能监测——采集每个函数的 CPU 耗时与帧率数据，用来定位热点、review 代码、量化验证优化效果。

三类性能监测能力：

• 热点定位：函数耗时排行（self / total / 调用次数），直接看到最贵的函数在哪

• 优化验证：前后两次采样按函数 diff，用毫秒回答"改完真的变快了吗"

• 帧级健康：FPS 百分位（p1 / p5 / p50）与 jank 日志，交叉验证体验改善

原始逐帧数据在服务端归约，AI 只接收 top-N 排行与 diff 结果，不占上下文。

工作原理

# 函数耗时（主路径）—— 直连游戏内嵌的原生 Tracy server
AI (Claude) --MCP/stdio--> mcdk-mcp-tracy --TCP 8086--> 游戏内嵌原生 Tracy server
                                  └─ bin/tracy-capture.exe + tracy-csvexport.exe

# 帧率 / jank（辅助路径）—— 经 MCDK 注入 get_Fps()
AI --MCP/stdio--> mcdk-mcp-tracy --MCP/SSE--> MCDK(mcdk.exe) --execute_code--> 游戏(Python2)

• 函数耗时直连原生 ModPC Tracy（8086），不管是通过MCDK还是MC Studio启动的游戏：只要游戏启动没关闭就能抓取性能消耗信息。 采集覆盖窗口内全部已插桩 zone（含客户端 MAIN_THREAD 与 MC_SERVER 线程）。

• 采样时建议跑图/搭建场景测压：Tracy 只记录窗口内实际执行的代码，不建议静止不动。

bin/ 的 CLI 取自 Tracy v0.11.1 官方 Windows 包，版本须与游戏内嵌的 Tracy client 一致（协议版本敏感）；换游戏版本时同步替换。

Related MCP server: memorylens-mcp

前置条件

1. 游戏在运行，内嵌原生 Tracy server 监听 8086（用 tracy-profiler.exe GUI 能连上即确认）。

2. bin/tracy-capture.exe、bin/tracy-csvexport.exe 存在（随仓库附带；可用 TRACY_BIN_DIR 指向别处）。

3. （仅 tracy_jank_fps 需要） 游戏由 MCDK（mcdk.exe）启动，工程 .mcdev.json 开了 MCP：

   { "mcp_server_config": { "enabled": true, "server_ip": "localhost", "server_port": 19133 } }

4. Python 3.10+（开发用 3.13），推荐 uv。

安装

uv --directory <path>/mcdk-mcp-tracy sync           # 装依赖 + 建 .venv
uv --directory <path>/mcdk-mcp-tracy run pytest -q  # 自检，应 36 passed（无需游戏）

注册到 Claude Code

claude mcp add mcdk-mcp-tracy --scope user -- \
  "<path>/mcdk-mcp-tracy/.venv/Scripts/python.exe" -m mcdk_mcp_tracy \
  --stdio --mcdk-url http://127.0.0.1:19133

• 直接用 venv 里的 python.exe，不依赖 PATH。

• --mcdk-url 仅 tracy_jank_fps 用得到；也可换成 --project-dir <MOD工程> 按其 .mcdev.json 自动找端口（优先级：--mcdk-url > --mcdev-json > --project-dir > $MCDK_MCDEV_JSON > 从 CWD 向上找）。

• 注册后新开会话才会出现 mcp__mcdk-mcp-tracy__* 工具。 卸载：claude mcp remove mcdk-mcp-tracy --scope user。

• 推荐一并安装配套技能：把 skills/mcdk-tracy-profiling/ 整个目录拷到 ~/.claude/skills/， AI 会自动按下面的人机协作流程工作（先对齐采样计划，报告后由你拍板再改代码）。

注册到 Codex

codex mcp add mcdk-mcp-tracy -- \
  "<path>/mcdk-mcp-tracy/.venv/Scripts/python.exe" -m mcdk_mcp_tracy \
  --stdio --mcdk-url http://127.0.0.1:19133

• Codex 会将服务器写入用户级 ~/.codex/config.toml，无需 --scope user。

• 参数含义和寻址优先级与上方 Claude Code 配置相同；不需帧率 / jank 采样时可省略 --mcdk-url。

• 运行 codex mcp list 确认已注册；注册后新开 Codex 会话（IDE 扩展中需重启扩展） 即可使用 mcp__mcdk-mcp-tracy__* 工具。

• 卸载：codex mcp remove mcdk-mcp-tracy。

• 推荐一并安装配套技能：把 skills/mcdk-tracy-profiling/ 整个目录拷到 ~/.codex/skills/。

性能监测标准流程工作流

负载要你亲自在游戏里触发，改代码要你拍板——AI 驱动流程，关键节点等你：

1. 探针：tracy_status()，确认 8086 可达 + CLI 齐全。

2. 对齐采样计划：AI 先问你采样时长——10 秒（瞬时逻辑：开 UI、放技能）／30 秒（常规 玩法、跑图）／60 秒（长周期系统、复现偶发卡顿）／自定义（≤60）——以及准备触发的场景 （跑图、刷实体、开打、跑机器……），你就位后才开采。

3. 基线采样：你在游戏里触发玩法，AI 执行 tracy_native_capture(seconds=<约定>, name_contains="YourMod", label="before")。

4. 热点报告（对话正文输出）：热点排行（self / calls / 每帧均摊 / 单次均摊，必要时 tracy_get_function_costs 细查）+ 按性价比排序的优化计划——每条含根因、改法、预期收益 （估算 ms）、风险与改动量；改动小收益高的在前，动底层影响向下兼容的在后。你选定做哪几条。

5. 改代码 + 复测：AI 按你选的方案改热点，同场景同时长再抓 label="after"。

6. diff 验收：tracy_diff_captures(base_id, new_id, metric="self")，delta_ms 为负 = 变快， 按毫秒和百分比回报实际收益。（可选：tracy_jank_fps FPS 百分位交叉验证，仅 MCDK）

采样返回（已按 self 耗时降序）：

{ "ok": true, "capture_id": "cap-1", "frames": 2632, "zones": 645899, "unit": "ms",
  "total_self_ms": 327.0,
  "top": [ { "name": "onRenderTick @ YourMod.Client.Main",
             "self_ms": 134.2, "total_ms": 328.1, "calls": 2628 } ] }

diff 返回：

{ "ok": true, "metric": "self",
  "summary": { "base_total_ms": 86.4, "new_total_ms": 61.0, "delta_ms": -25.4, "pct": -29.4 },
  "improved": [ { "name": "YourMod.combat.update", "delta_ms": -16.8, "base_ms": 21.3, "new_ms": 4.5 } ],
  "regressed": [], "added": [], "removed": [] }

目标函数出现在 improved、summary.pct 下降，即优化生效。

内置优化模式参考库

技能自带四份按症状索引的优化模式参考（AI 生成第 4 步优化计划时按需查阅；你也可以直接翻着看）。 所有模式按"采样症状 → 改法"组织、附可移植代码骨架，来自官方性能优化指南与已上线大型 MOD 的 实战验证——例如负缓存实测省 ~720ms/10s、配置存储改造内存 715MB → 224MB。

工具速查表

统一返回：成功 {"ok": true, ...}，失败 {"ok": false, "reason": "...", "error": "..."}。

性能监测要点

1. 采样期间制造真实负载：站到卡顿场景、开打、刷实体、跑机器——要测什么就让游戏跑什么。

2. 用 name_contains 聚焦自己的 MOD：函数显示为 "函数名 @ 源文件"，按脚本包前缀过滤； 过滤只影响 inline 返回，全量数据仍存进 capture，事后可再查。

3. diff 要可比：前后两次用尽量一致的玩法 + 相同 seconds，否则 delta 不可信。

4. 结论用数字说话：优化是否生效看 improved / summary.pct，不凭体感。

5. Tracy 版本匹配：换游戏版本时同步替换 bin/ 的 CLI（当前 v0.11.1）。

排查表

开发

uv --directory mcdk-mcp-tracy run pytest -q   # 36 passed，无需游戏
# 若 uv 在中文路径下报 trampoline 错误，改用：
./.venv/Scripts/python.exe -m pytest -q

AI 工作流策略见 skills/mcdk-tracy-profiling/SKILL.md