cheatengine-mcp-bridge: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

What this project is

A three-tier bridge that lets AI agents (via MCP) drive Cheat Engine to inspect and manipulate a running Windows process. See README.md for user-facing docs. Current wire/app version: 12.0.0. After the v12 overhaul the bridge exposes ~180 MCP tools covering memory, process lifecycle, code injection, symbol management, assembly/compilation, GUI automation, input, cheat tables, and kernel-mode operations.

Commands

# Install Python deps (Windows only — uses pywin32)
pip install -r MCP_Server/requirements.txt

# Integration test suite (requires: CE running, ce_mcp_bridge.lua loaded, a process attached)
python MCP_Server/test_mcp.py

Loading the Lua side in Cheat Engine: File -> Execute Script -> open MCP_Server/ce_mcp_bridge.lua -> Execute. Some CE builds expose this through Table -> Show Cheat Table Lua Script; in that case execute dofile([[C:\path\to\cheatengine-mcp-bridge\MCP_Server\ce_mcp_bridge.lua]]) instead of pasting the full bridge. Success log: [MCP v12.0.0] MCP Server Listening on: CE_MCP_Bridge_v99. Re-executing the script auto-calls StopMCPBridge / cleanupZombieState first, so reloading is safe.

There is no build step, no linter, and no unit-test harness. test_mcp.py is a single end-to-end script that talks to the live Named Pipe; running a "single test" means editing the all_tests dict in test_mcp.py:main or commenting out sections.

The MCP server is normally spawned by the AI client over stdio, but can be launched directly with python MCP_Server/mcp_cheatengine.py for debugging (it blocks waiting for stdio JSON-RPC).

Architecture

Three processes, two IPC layers:

AI client ──(MCP / JSON-RPC over stdio)──▶ mcp_cheatengine.py
                                                  │
                                                  ▼ (length-prefixed JSON-RPC)
                                         \\.\pipe\CE_MCP_Bridge_v99
                                                  │
                                                  ▼
                                          ce_mcp_bridge.lua (inside Cheat Engine)
                                                  │
                                                  ▼ (CE Lua API / DBVM)
                                            Target process memory