内容
# cemu_re_mcp
MCP 服务器，用于封装 Cemu 内置的 GDB stub，以便对 Wii U 游戏进行实时运行时分析。该项目与 [dolphin_re_mcp](../dolphin_re_mcp/) 是配套的，但全新构建 —— 相同的 MCP 工具界面，不同的协议层。
目标游戏：怪物猎人 3 终极版（MH3U），但格式不限于任何 Wii U 游戏。
## 快速开始
1. **在 Cemu 中启用 GDB stub：**
- 菜单：`调试 → 使用 GDB stub 启动`
- 默认端口：`1337`
- 重启 Cemu 并启动游戏
2. **安装 MCP 服务器：**
```bash
cd E:\cemu_re_mcp
pip install -e .
```
3. **通过 `.mcp.json` 连接到 Claude Code：**
```json
{
"mcpServers": {
"cemu": {
"command": "python",
"args": ["-m", "cemu_re_mcp.server"]
}
}
}
```
## 功能描述
Cemu 自带一个 [GDB 远程串行协议](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Remote-Protocol.html) 的 stub。该 MCP 服务器通过 TCP 套接字与该协议进行通信，并为 Claude 提供运行时逆向工程所需的原始操作：
- 连接 / 断开 / 健康检查
- 暂停 / 继续 / 单步
- 读取和写入内存（原始字节，类型化 `u8/u16/u32/f32/s32`）
- 读取和写入寄存器（GPR，FPR，PC，LR，CTR，SPRs）
- 设置 / 清除断点 + 读取/写入观察点
- 等待命中（阻塞直到 BP/WP 触发；捕获上下文）
- 更高级的辅助函数（结构体读取，指针追踪，内存搜索，十六进制转 dump，反汇编）
## 为什么不 fork dolphin_re_mcp
Cemu 和 Dolphin 在 GDB-stub 级别有细微的差别（寄存器集，地址空间布局，断点类型）。全新实现比在 Dolphin 的假设上逆向移植 Cemu 的特殊性更快。该项目仅作为参考设计的姊妹项目。
## 架构
```
src/cemu_re_mcp/
gdb_rsp.py — GDB 远程串行协议客户端（标准库套接字，无依赖）
server.py — MCP 服务器入口，工具包装
state.py — 连接状态 + 暂停/运行跟踪
```
## 状态
- [x] 项目骨架
- [x] GDB RSP 客户端（数据包框架，校验和，RLE 扩展）
- [x] MCP 服务器，带有 `connect` / `health_check` / `pause` / `resume`
- [x] 内存读写工具（原始 + 类型化 u8/u16/u32/s32/f32）
- [x] 寄存器工具（PC，LR，所有 GPR）
- [x] 断点 / 观察点工具（Z0/Z2/Z3/Z4）
- [ ] `wait_for_hit`（基本实现存在；需要真正的 BP-hit 测试）
- [ ] `capture_on_hit` 更高级的辅助函数
- [ ] 符号感知辅助函数（使用 Cemu 的 coreinit + 游戏符号）
- [ ] 结构体读取 / 指针追踪 / 内存搜索辅助函数
## Cemu GDB stub 特殊性（2026-05-27 与 MH3U 确认）
这些行为与 Dolphin 的 GDB stub 不同；它们决定了 MCP 服务器的设计。
1. **每个游戏会话一次性。** 任何 TCP 断开后，stub 停止监听。重新连接需要重启 Cemu + 重新加载游戏。因此，MCP 服务器在整个会话中保持一个长连接。
2. **`QStartNoAckMode` 不受支持。** 连接跳过协商，保持始终确认模式（避免 5 秒连接超时）。
3. **裸 `c` 不继续所有线程。** Wii U 是多核的；发送 `c` 只恢复当前线程，游戏冻结。客户端使用 `vCont;c` 进行所有恢复（和 `vCont;s` 进行步骤）。`vCont?` 回复确认 stub 支持 `vCont;c;C;s;S`（无每线程目标）。
4. **无程序暂停。** `vCtrlC` 接受数据包但不停止。原始 `0x03` 中断字节被静默忽略。要停止：要么设置断点/观察点并让目标自行停止，要么从 Cemu 的 UI 暂停。
5. **检查在目标运行时有效。** 与大多数 GDB stubs 不同，`m`，`p`，`g`，`?` 在目标正在执行时返回真实值。不需要暂停进行基本内存/寄存器读取。这实际上简化了大多数工具 — 只有断点/步骤工作流程需要停止语义。
6. **启动时暂停。** stub 在启动时停止目标，在介绍播放之前。游戏在暂停时出现在启动画面，直到第一个 `vCont;c`。发送它作为连接后的第一个操作，或使用 `scripts/cemu_resume.py`。
## 备注
- Cemu 的主游戏模块在 MH3U US v1.3（`mh3g_cafe_us`，大小 `0x11b2550`）中加载到 `0x02000000`。前两个指令：`nop; blr`。
- WiiU 虚拟内存是平坦的（无 MEM1/MEM2 分割，如 Wii）—— 地址是 32 位虚拟的。
- coreinit 符号（FSAddClient，DCFlushRange 等）位于 `0x00Exxxxx` 附近，并在 Cemu 的 PPC 调试器 UI 中预加载。可能通过 `qSymbol` 查询（未测试）。
- Cemu 是开源的 —— 如果 GDB stub 缺少我们需要的功能（例如真正的暂停支持），请修补模拟器。那是逃生舱。
