cheatengine-mcp-bridge

面向 npx 运行的 Cheat Engine MCP 桥接服务。用于将 Cheat Engine 能力暴露给 AI Agent / MCP Client。

功能概览

• 进程与模块信息查询
• 内存读写、指针链解析
• 数值扫描与 AOB 扫描
• 反汇编与函数分析
• 断点与 DBVM watch
• Lua / Auto Assembler 执行（含文件模式）

安装与启动

无需全局安装，直接使用 npx：

npx -y cheatengine-mcp-bridge

MCP 客户端配置示例

{
  "servers": {
    "cheatengine": {
      "command": "npx",
      "args": ["-y", "cheatengine-mcp-bridge"]
    }
  }
}

使用步骤

1. 打开 Cheat Engine。
2. 加载并执行 ce_mcp_bridge.lua（Lua 桥接脚本）。
3. 附加目标进程。
4. 在 MCP 客户端先调用 ping，确认联通后再调用业务工具。

MCP 工具清单

进程与符号

| 工具 | 说明 | |---|---| | get_process_info | 获取当前附加进程摘要信息。 | | enum_modules | 枚举已加载模块及其基址、大小。 | | get_thread_list | 枚举目标进程线程列表。 | | get_symbol_address | 将 symbol 或模块表达式解析为地址。 | | get_address_info | 将地址反查模块/符号元信息。 | | get_rtti_classname | 尝试解析地址对应的 RTTI 类名。 |

内存读写

| 工具 | 说明 | |---|---| | read_memory | 读取指定地址的原始字节。 | | read_integer | 读取数值类型（byte/word/dword/qword/float/double）。 | | read_string | 读取 ANSI 或 UTF-16 字符串。 | | read_pointer | 读取单层指针值。 | | read_pointer_chain | 解析多级指针链。 | | write_memory | 写入原始字节到内存。 | | write_integer | 写入数值。 | | write_string | 写入 ANSI 或 UTF-16 字符串。 | | checksum_memory | 计算内存区域 MD5 校验值。 |

扫描能力

| 工具 | 说明 | |---|---| | scan_all | 发起初次值扫描（dword/string/array）。 | | get_scan_results | 获取当前扫描结果集。 | | next_scan | 在上一次扫描结果上进行筛选。 | | aob_scan | 扫描 AOB 字节特征。 | | search_string | 在内存区域中搜索字符串。 | | generate_signature | 为目标地址生成 AOB signature。 | | get_memory_regions | 列出常用有效内存区域。 | | enum_memory_regions_full | 枚举完整内存映射。 |

反汇编与分析

| 工具 | 说明 | |---|---| | disassemble | 对目标地址范围进行反汇编。 | | get_instruction_info | 解码单条指令并返回详细元信息。 | | find_function_boundaries | 启发式定位函数边界。 | | analyze_function | 分析函数体及调用关系。 | | find_references | 查找引用目标地址的指令。 | | find_call_references | 查找调用目标函数地址的位置。 | | dissect_structure | 启发式推断内存结构字段。 |

断点与 DBVM

| 工具 | 说明 | |---|---| | set_breakpoint | 设置执行型硬件断点。 | | set_data_breakpoint | 设置数据访问硬件断点。 | | remove_breakpoint | 按 id 删除断点。 | | list_breakpoints | 列出当前活动断点。 | | clear_all_breakpoints | 清空全部断点。 | | get_breakpoint_hits | 获取断点命中记录。 | | get_physical_address | 将虚拟地址转换为物理地址。 | | start_dbvm_watch | 启动 DBVM watch（访问/写入追踪）。 | | poll_dbvm_watch | 不停止会话地轮询 DBVM watch 结果。 | | stop_dbvm_watch | 停止 DBVM watch 并返回最终结果。 |

脚本与通用

| 工具 | 说明 | |---|---| | evaluate_lua | 在 Cheat Engine 中执行 Lua 代码片段。 | | evaluate_lua_file | 在 Cheat Engine 中执行本地 Lua 文件。 | | auto_assemble | 执行 Auto Assembler 文本脚本。 | | auto_assemble_file | 执行本地 Auto Assembler 脚本文件。 | | ping | 服务健康检查与能力探测。 |

兼容别名

| 别名 | 映射到 | |---|---| | read_bytes | read_memory | | pattern_scan | aob_scan | | set_execution_breakpoint | set_breakpoint | | set_write_breakpoint | set_data_breakpoint | | find_what_writes_safe | start_dbvm_watch（write 模式） | | find_what_accesses_safe | start_dbvm_watch（access 模式） | | get_watch_results | stop_dbvm_watch |

环境要求

• Windows
• Node.js 20+
• Cheat Engine 已运行并加载 Lua 桥接

环境变量

| 变量 | 说明 | 默认值 | |---|---|---| | CE_MCP_PIPE_NAME | Node 服务连接的 Named Pipe 路径。 | \\.\\pipe\\CE_MCP_Bridge_v99 | | CE_MCP_CONNECT_TIMEOUT_MS | 初始连接超时。 | 5000 | | CE_MCP_REQUEST_TIMEOUT_MS | 单请求超时。 | 15000 | | CE_MCP_RETRY_COUNT | 瞬态失败重试次数。 | 2 | | CE_MCP_RETRY_DELAY_MS | 重试间隔毫秒。 | 200 | | CE_MCP_MAX_RESPONSE_BYTES | 最大响应体字节数。 | 10485760 | | CE_MCP_SERVER_NAME | MCP 服务展示名。 | cheatengine-mcp-bridge | | CE_MCP_LOG_LEVEL | 日志级别（error/warn/info/debug）。 | info |

常见问题

• 启动后连接失败：确认 CE 已加载 Lua 桥接，且 CE_MCP_PIPE_NAME 与桥接脚本一致。
• 发布报 E403：需要 npm Automation Token，或可发布且支持 bypass 2FA 的 granular token。
• npm 页面 README 未更新：npm 读取的是包目录内 README.md，发版前需更新此文件。

License

MIT