# ce-mcp

MCP Server for Cheat Engine 7.6，通过 CE Lua 命名管道桥接，工具集类似 IDA MCP / x64dbg MCP，可配置到 Trae / Cursor / Claude Desktop 等 agent 软件。

兼容原版 Cheat Engine 7.6，也兼容基于 7.6 的魔改版（只要保留标准 Lua API）。

## 架构

```text
Trae / Cursor / Claude Desktop
    │  MCP stdio JSON-RPC
    ▼
ce_mcp_server.py (Python MCP Server)
    │  Windows Named Pipe: \\.\pipe\CE_MCP
    ▼
Cheat Engine 7.6
    └─ autorun/ce_mcp.lua
         └─ createPipe + CE Lua API
```

## 快速开始

### 1. 安装依赖

```powershell
python -m pip install -e .
```

如果不想装 `pywin32`（当前代码使用纯 `ctypes`，不需要它），只需：

```powershell
python -m pip install mcp
```

### 2. 启动 CE

1. 打开 CE 安装目录下的 `autorun` 文件夹。
2. 把项目里的 `lua/ce_mcp.lua` 复制进去。
3. 启动 Cheat Engine。

也可以让 MCP Server 自动完成：

```powershell
python -m ce_mcp --config config.example.json
```

它会自动复制 Lua 脚本到 CE 的 autorun 目录，并启动配置的 CE 可执行文件。

也可以直接用安装脚本生成 MCP 配置：

```powershell
python scripts/install.py --ce-exe "C:\Cheat Engine 7.6\cheatengine-x86_64.exe" --output mcp.json
```

### 3. POC 测试

先手动或自动启动 CE，然后：

```powershell
python scripts/poc.py status
python scripts/poc.py processes
python scripts/poc.py open --pid 1234
python scripts/poc.py modules
python scripts/poc.py read --address 0x10000 --size 16
python scripts/poc.py aob --pattern "48 8B 05 ?? ?? ?? ??"
python scripts/poc.py disassemble --address 0x7FF600000000 --count 8
```

也可以跑自动验证：

```powershell
python scripts/smoke_test.py       # 自动打开 notepad 并测试 open/read/disassemble
python scripts/test_addresslist.py # 地址列表/作弊表/汇编写入测试
python scripts/test_mcp.py         # 端到端启动 MCP Server 并调用工具
```

### 4. 配置到 Trae / Cursor

> ⚠️ 注意：下面 JSON 里的 `C:\\path\\to\\ce-mcp\\src\\ce_mcp\\__main__.py` 是**占位符**，必须改成你电脑上的实际路径，否则会报：
>
> ```text
> python: can't open file 'C:\path\to\ce-mcp\src\ce_mcp\__main__.py': [Errno 2] No such file or directory
> ```

#### 通用配置模板

先找到你本机实际的 `__main__.py` 路径，例如：

```text
D:\projects\ce-mcp\src\ce_mcp\__main__.py
```

然后把 `args` 里的路径替换成它，同时把 `CE_MCP_EXE` / `CE_MCP_DIR` 改成你的 CE 实际路径：

```json
{
  "mcpServers": {
    "ce-mcp": {
      "command": "python",
      "args": ["D:\\projects\\ce-mcp\\src\\ce_mcp\\__main__.py"],
      "env": {
        "CE_MCP_EXE": "D:\\Cheat Engine 7.6\\cheatengine-x86_64.exe",
        "CE_MCP_DIR": "D:\\Cheat Engine 7.6",
        "CE_MCP_PIPE": "CE_MCP",
        "CE_MCP_AUTO_START": "true"
      }
    }
  }
}
```

如果使用虚拟环境，把 `command` 换成虚拟环境里的 `python.exe`。

> 提示：如果 CE 已经手动启动并且 `ce_mcp.lua` 已经运行，MCP Server 会自动检测到 `CE_MCP` 管道，即使 `CE_MCP_EXE` 暂时没配也能启动。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `CE_MCP_EXE` | 空 | CE 可执行文件路径 |
| `CE_MCP_DIR` | 空 | CE 安装目录，缺省用 exe 所在目录 |
| `CE_MCP_PIPE` | `CE_MCP` | 命名管道名 |
| `CE_MCP_AUTO_START` | `true` | 是否自动启动 CE |
| `CE_MCP_ALLOW_DANGEROUS` | `false` | 是否启用 `ce_execute_lua` / `ce_auto_assemble` |
| `CE_MCP_TIMEOUT` | `30` | 每次工具调用超时秒数 |
| `CE_MCP_LUA_SCRIPT` | 空 | 自定义 Lua 桥接脚本路径 |

旧的 `XSCE_*` 环境变量仍会被识别，方便升级。

## 工具列表

### 进程 / 模块 / 符号

- `ce_get_status`
- `ce_list_processes`
- `ce_open_process`
- `ce_get_opened_process`
- `ce_create_process`
- `ce_list_modules`
- `ce_list_memory_regions`
- `ce_get_symbol`
- `ce_get_symbol_info`
- `ce_enable_windows_symbols`
- `ce_reload_symbols`
- `ce_get_comment` / `ce_set_comment`
- `ce_get_header` / `ce_set_header`

### 内存读写 / 分配

- `ce_read_memory`
- `ce_write_memory`
- `ce_read_value`
- `ce_write_value`
- `ce_allocate_memory`
- `ce_free_memory`

### 扫描 / 反汇编 / 汇编 / 指针

- `ce_aob_scan`
- `ce_aob_scan_module`
- `ce_scan_value`
- `ce_scan_next`
- `ce_get_scan_results`
- `ce_get_scan_progress`
- `ce_reset_scan`
- `ce_save_scan_results`
- `ce_list_saved_scan_results`
- `ce_read_pointer_chain`
- `ce_find_pointer_to_address`
- `ce_disassemble`
- `ce_assemble`
- `ce_write_assembly`

### 地址列表 / 作弊表 / 热键

- `ce_list_address_list`
- `ce_add_address`
- `ce_add_pointer`
- `ce_add_aa_script`
- `ce_set_address_active` / `ce_toggle_address_active`
- `ce_set_address_script`
- `ce_set_address_description`
- `ce_set_address_address`
- `ce_set_address_var_type`
- `ce_set_address_value`
- `ce_set_address_color`
- `ce_set_address_offsets`
- `ce_delete_address`
- `ce_add_hotkey`
- `ce_list_hotkeys`
- `ce_remove_hotkey`
- `ce_save_table` / `ce_load_table`

### 调试器

- `ce_pause` / `ce_unpause`
- `ce_debug_start` / `ce_debug_stop`
- `ce_debug_is_debugging`
- `ce_debug_get_context`
- `ce_debug_get_stack`
- `ce_debug_set_register`
- `ce_debug_set_breakpoint` / `ce_debug_list_breakpoints` / `ce_debug_remove_breakpoint` / `ce_debug_clear_breakpoints`
- `ce_debug_continue`

### 危险工具（默认关闭）

- `ce_execute_lua`
- `ce_auto_assemble`
- `ce_inject_dll`
- `ce_execute_code`
- `ce_execute_code_ex`
- `ce_compile_c`

## 项目结构

```text
src/ce_mcp/
├── __main__.py
├── server.py          # MCP 工具定义
├── ce_bridge.py       # 命名管道客户端（纯 ctypes）
├── ce_launcher.py     # 启动 CE / 安装 Lua 脚本
└── config.py
lua/
└── ce_mcp.lua         # CE 侧 Lua 桥接服务
scripts/
├── install.py             # 一键安装 Lua 桥接 + 生成 MCP 配置
├── poc.py                 # 命令行 POC 客户端
├── smoke_test.py          # 基础内存/模块/反汇编冒烟测试
├── test_addresslist.py    # 地址列表/作弊表/汇编写入测试
├── test_new_features.py   # 扫描/热键/符号/高级作弊表测试
├── test_advanced.py       # 保存扫描/指针查找/C编译测试
├── test_exec_code_ex.py   # C编译+executeCodeEx 测试
├── test_memory_regions.py # 内存区域/注释/头注释测试
├── test_mcp.py            # 端到端 MCP 测试
├── check_lua.py           # Lua 语法检查
└── test_lua_json.py       # Lua JSON 编解码测试
LICENSE                    # GPL-3.0
CONTRIBUTING.md
```

## 开源

- License: GPL-3.0
- 本项目兼容原版 Cheat Engine 7.6 与基于 7.6 的魔改版。

## 注意事项

- 所有地址统一使用十六进制字符串（如 `0x7FF6A1B2C000`），避免 64 位精度丢失。
- `execute_lua` / `auto_assemble` / `write_memory` 具有破坏性，请仅在可信环境中使用。
- 如果 CE 的 autorun 不自动执行，请手动在 CE 里打开 `lua/ce_mcp.lua` 运行一次。
- 部分魔改版 CE 的 `autorun/custom/` 不会自动执行，桥接脚本建议放在 `autorun/` 根目录。
- `ce_write_assembly` 使用 CE 汇编器语法，例如 `int 3` 是合法的，`int3` 可能不被识别。
- 地址列表相关操作（增删改、AA 开关）会通过 `synchronize` 在主线程执行，避免 CE 报 “Killed thread that tried to access a GUI control”。

## 已实现的功能模块

- 扫描与指针链
- 热键系统
- 高级作弊表管理
- 调试器增强
- 符号与 PDB
- 代码注入/执行
- 安装与配置体验