# Cheat Engine MCP (Model Context Protocol) 核心服务框架

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-brightgreen.svg)](https://www.python.org/)
[![Cheat Engine: 7.5+](https://img.shields.io/badge/Cheat%20Engine-7.5%2F7.6+-orange.svg)](https://www.cheatengine.org/)

专为 **Cheat Engine** 与现代 AI Agent（如 Claude Desktop、Cursor、Antigravity 等）打造的工业级、全功能、**纯中文指令集** Model Context Protocol (MCP) 服务框架。

通过 **Windows 命名管道 (Named Pipe) + 独立工作线程 I/O + 主线程安全同步分发 (`thread.synchronize`)** 架构，将 Cheat Engine 的全部核心逆向调试与内存分析能力无缝暴露给大语言模型，支持零卡顿、防死锁、多线程安全的自动化逆向。

---

## 🌟 核心特性

1. **绝对线程安全与零界面阻塞**：
   - 管道读写在 CE 独立工作线程中运行；所有内存、调试与 GUI 交互通过 `thread.synchronize` 自动调度到 CE 主线程安全执行，绝不造成游戏或 CE 挂起。
2. **纯中文标准化指令集**：
   - 全部 43 个 MCP 工具均采用直观精确的纯中文命名与中文参数体系，内置完整的类型校验与错误回显。
3. **CE 原生拟真 3D LED 发光状态指示灯**：
   - 在 Cheat Engine 主窗口原生嵌入动态双缓冲画布指示灯，实时反馈 MCP 处于 `就绪`、`处理中`、`错误`、`挂起` 状态，清晰直观。
4. **全面的游戏逆向分析全栈覆盖**：
   - 内存读写、汇编注入、多级指针、全功能扫描、硬件/软件调试断点、.NET 托管元数据反射、Mono (Unity) 堆对象与 JIT 原生汇编定位。

---

## 🛠️ 全功能 43 项纯中文 MCP 工具套件矩阵

### 1. 基础环境与交互 (4 个)
* **`心跳检测`**：检测 CE 管道通信链路健康状态，回显 CE 内部版本与时间戳。
* **`获取目标进程`**：查询当前 CE 打开/附加的目标进程名称、PID 与 32/64 位架构。
* **`执行Lua脚本`**：在 CE 主线程安全执行任意复杂 Lua 代码，支持动态运算与复杂数据回传。
* **`更新UI工作状态`**：动态操控 CE 主窗口状态栏的原生发光指示球与文字提示。

### 2. 内存精确读写 (2 个)
* **`读取内存`**：支持 1~8 字节整型、单/双精度浮点、布尔、UTF-8/Unicode 字符串及字节数组 (AOB) 安全读取。
* **`写入内存`**：支持各类数据类型及字节数组特征码覆盖写入，内置原值备份与回读校验。

### 3. 指令监控与访问排查 (3 个 - F5/F6)
* **`查找访问此地址的内容`**：【CE 经典 F5】在指定内存或多级指针链地址下硬件断点，统计所有访问该地址的汇编指令与命中频次。
* **`查找写入此地址的内容`**：【CE 经典 F6】监控修改/写入指定内存的汇编指令，捕获寄存器快照与代码位置。
* **`查找此指令访问的地址`**：反向捕获某条汇编指令正在操作的所有内存地址清单。

### 4. 深度内存扫描引擎 (4 个)
* **`初次扫描`**：支持精确数值、变动值、未知的初始值、数值范围、大于/小于等扫描类型，支持全类型与内存区域过滤（MEM_PRIVATE / MEM_IMAGE / MEM_MAPPED）。
* **`再次扫描`**：在前后数值变化后极速收敛筛选目标内存地址。
* **`获取扫描结果`**：分页拉取当前扫描匹配到的地址、实时值与模块符号清单。
* **`重置扫描`**：清空并释放当前扫描器会话与内存资源。

### 5. 现代化地址表项体系 (4 个)
* **`添加地址表项`**：在 CE 列表添加纯静态地址、多级倒序指针链、Auto Assembler 脚本、层级组标题与下拉选项。
* **`修改地址表项`**：就地更新表项描述、地址、指针偏移链、激活/冻结状态、显示格式。
* **`获取地址列表`**：层级化导出当前打开的 CT 地址表树状结构。
* **`删除地址表项`**：安全移除指定表项及其级联子项。

### 6. 自动汇编与校验引擎 (4 个)
* **`生成AA脚本模板`**：标准生成 AOB 特征码注入、代码覆盖、AA+Lua 混合 (`{$lua}`)、全局变量注册、游戏内 Call 回调等标准汇编模板。
* **`预编译并校验脚本`**：双模校验引擎！无副作用预编译检查语法错误、守卫遗漏与资源泄漏。
* **`查询Lua函数`**：内置 CE 官方原生 400+ 导出函数速查字典（参数签名、中文说明与调用示例）。
* **`查阅CELua官方文档`**：直接检索 CE 官方 4200+ 行 `celua.txt` 完整权威文档。

### 7. 软硬件调试断点套件 (9 个)
* **`设置记录断点`**：只记录不中断程序！高速采集执行日志、堆栈及完整通用寄存器快照。
* **`获取断点记录`**：查看记录断点抓取的历史命中条目。
* **`设置调试断点`**：中断目标程序，支持硬件执行 (DR0~DR3) 或软件 INT3 断点，支持 Lua 条件断点降噪。
* **`单步执行`**：中断状态下执行单步步入 (Step Into) 或单步步过 (Step Over)。
* **`恢复运行`**：解除目标程序的中断挂起，恢复正常全速运行。
* **`断点并跟踪指令`**：自动跟踪后续 N 条指令的代码执行流程与调用链。
* **`获取断点列表`**：查看活跃断点列表与 4 个硬件调试寄存器槽位分配情况。
* **`删除断点`**：安全注销并回收指定断点与寄存器槽位。
* **`清除全部断点`**：一键清空所有软硬件断点并放行程序。

### 8. .NET 逆向与数据收集套件 (8 个)
* **`检测.NET运行时`**：静默探查目标进程是否包含 CLR / CoreCLR (`clr.dll`, `coreclr.dll`)。
* **`枚举.NET模块`**：遍历 AppDomains 列出所有托管程序集模块、句柄与基地址。
* **`枚举.NET类列表`**：枚举模块下全部 TypeDef，兼容 ConfuserEx 等 Unicode 乱码混淆程序。
* **`获取.NET类结构与字段`**：提取类父类继承、字段类型、内存偏移量 (`+0x...`) 及静态字段地址。
* **`获取.NET类方法列表`**：提取方法 Token、ILCode 及 JIT 编译后的 `NativeCode` 物理机器码入口地址。
* **`读取.NET静态字段`**：根据字段元数据类型安全读取静态字段数值。
* **`写入.NET静态字段`**：安全修改目标 .NET 程序的静态属性值并自动回读校验。
* **`扫描.NET堆实例`**：遍历 GC 托管堆，检索指定类当前存活的所有对象实例物理首地址。

### 9. Mono (Unity) 游戏逆向与数据收集套件 (9 个)
* **`检测Mono运行时`**：静默检测 `mono-2.0-bdwgc.dll`、`mono.dll` 等运行时与连接状态。
* **`附加Mono运行时`**：安全初始化并挂载 CE 原生 `MonoDataCollector`，带防死锁与防重入保护。
* **`枚举Mono程序集`**：获取 Unity 游戏加载的全部程序集（如 `Assembly-CSharp`、`UnityEngine.CoreModule`）。
* **`枚举Mono类列表`**：检索目标程序集下的所有类，支持命名空间与关键词搜索。
* **`获取Mono类结构与字段`**：提取父类信息与字段内存偏移量 (`+0x...`)。
* **`获取Mono类方法列表`**：**自动即时 JIT 编译 (`mono_compile_method`)**，直接返回可在内存中下断点的物理机器码地址。
* **`扫描Mono堆实例`**：检索指定类当前存活在内存中的所有活跃对象物理地址。
* **`读取Mono实例字段`**：结合对象实例首地址与字段偏移，根据元数据类型自动推导读取属性数值。
* **`写入Mono实例字段`**：安全覆写对象实例字段数值并执行回读校验。

---

## 🚀 快速开始

### 1. 环境准备
* 操作系统：Windows 10 / 11 (x64)
* Python：3.10 或更高版本
* Cheat Engine：7.5 / 7.6 或更高版本（64位）

```bash
# 克隆仓库
git clone https://github.com/meesst/Cheat-Engine-mcp.git
cd Cheat-Engine-mcp

# 安装 Python 依赖
pip install -r requirements.txt
```

### 2. 部署 CE 桥接脚本
将 `lua/ce_bridge.lua` 复制到您的 Cheat Engine `autorun` 目录下（例如 `F:\Program Files (x86)\Cheat Engine\autorun\ce_bridge.lua`），启动 Cheat Engine 时会自动加载并建立命名管道 `\\.\pipe\CE_MCP_Bridge`。

> 提示：也可以在已打开的 CE 中点击菜单 `Table` -> `Show Cheat Engine Lua Script`，粘贴 `lua/ce_bridge.lua` 内容并点击 **Execute Script** 即可热加载启动。

### 3. 配置 MCP 客户端

#### 在 Claude Desktop 中使用
在配置文件 `%APPDATA%\Claude\claude_desktop_config.json` 中添加：
```json
{
  "mcpServers": {
    "cheatengine": {
      "command": "python",
      "args": ["-m", "server.mcp_server"],
      "cwd": "C:\\path\\to\\Cheat-Engine-mcp"
    }
  }
}
```

#### 在 Antigravity / Cursor 等 IDE 中使用
直接将 Python 入口指向 `server/mcp_server.py` 即可在聊天对话中直接唤醒全部 43 个中文工具。

---

## 🧪 自动化测试验证

项目内置了针对核心功能的完整自动化单元测试套件：

```bash
# 测试基础通信管道
python tests/test_pipe.py

# 测试断点套件 (硬件/记录/跟踪)
python tests/test_breakpoint_suite.py

# 测试 .NET 逆向套件
python tests/test_dotnet_suite.py

# 测试 Mono (Unity) 逆向套件
python tests/test_mono_suite.py
```

---

## 📄 开源许可证

本项目采用 [MIT License](LICENSE) 许可证。