# tonytranrp/cheat-engine-mcp architecture

> Architecture diagram of the GitHub repository tonytranrp/cheat-engine-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonytranrp/cheat-engine-mcp
- Repository: https://github.com/tonytranrp/cheat-engine-mcp

## Overview

Cheat Engine MCP exposes Cheat Engine operations to an MCP client through a Python server and a TCP-connected native plugin. The main workflow is client request → registered Python tool → bridge/context → native loader and hot-swappable core → Cheat Engine API, with results returned along that route. Domain tool modules cover process/session access, memory and scans, pointers, tables and structures, debugging, Lua, and exported SDK metadata. Runtime-module wiring and several domain paths are inferred from the README and tree; only sampled source confirms specific implementation details.

Main entry points: [`python/src/ce_mcp_server/tools/__init__.py`](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/__init__.py) (Tool registration), [`python/src/ce_mcp_server/context.py`](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/context.py) (Tool context), [`python/src/ce_mcp_server/server.py`](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/server.py) (MCP server), [`python/src/ce_mcp_server/tools/scan_tools.py`](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/scan_tools.py) (Scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["MCP backend"]
  node_server["MCP server<br/>[server.py]"]
  node_registration["Tool registration<br/>[__init__.py]"]
  node_bridge["TCP bridge<br/>[bridge.py]"]
  node_context["Tool context<br/>[context.py]"]
end

subgraph group_native["Native plugin"]
  node_plugin["Stable loader<br/>[plugin_loader.cpp]"]
  node_mcpclient["Bridge client<br/>[mcp_client.cpp]"]
  node_core["Native core<br/>[core_runtime.cpp]"]
end

subgraph group_domains["CE tool domains"]
  node_process["Process and symbols<br/>[process_tools.py]"]
  node_memory["Memory access<br/>[memory_tools.py]"]
  node_scans["Scanning<br/>[scan_tools.py]"]
  node_scanhelpers["Scan helpers"]
  node_pointers["Pointer chains<br/>[pointer_tools.py]"]
  node_tables["Tables and records<br/>[table_tools.py]"]
  node_structures["Structure tools<br/>[structure_tools.py]"]
  node_debug["Debug watches<br/>[debug_tools.py]"]
  node_lua["Lua scripting<br/>[script_tools.py]"]
  node_luapackages["Lua libraries"]
  node_exported["Exported SDK<br/>[exported_tools.py]"]
end

subgraph group_runtimes["Lua runtimes"]
  node_scanruntime["Scan runtime<br/>[scan_runtime.py]"]
  node_structruntime["Structure runtime"]
  node_luaruntime["Lua runtime<br/>[lua_runtime.py]"]
end

node_client(("Codex MCP client"))
node_ce["Cheat Engine"]

node_client -->|"MCP requests"| node_server
node_server -->|"registers tools"| node_registration
node_server -->|"starts and stops"| node_bridge
node_registration -->|"registers"| node_process
node_registration -->|"registers"| node_memory
node_registration -->|"registers"| node_scans
node_registration -->|"registers"| node_pointers
node_registration -->|"registers"| node_tables
node_registration -->|"registers"| node_structures
node_registration -->|"registers"| node_debug
node_registration -->|"registers"| node_lua
node_registration -->|"registers"| node_luapackages
node_registration -->|"registers"| node_exported
node_registration -->|"registers"| node_scanhelpers
node_process -->|"calls"| node_context
node_memory -->|"calls"| node_context
node_scans -->|"calls"| node_context
node_scanhelpers -->|"calls"| node_context
node_pointers -->|"calls"| node_context
node_tables -->|"calls"| node_context
node_structures -->|"calls"| node_context
node_debug -->|"calls"| node_context
node_lua -->|"calls"| node_context
node_luapackages -->|"calls"| node_context
node_exported -->|"calls"| node_context
node_context -->|"native calls"| node_bridge
node_bridge -->|"TCP requests"| node_mcpclient
node_plugin -->|"starts client"| node_mcpclient
node_mcpclient -->|"dispatches requests"| node_core
node_core -->|"invokes CE APIs"| node_ce
node_scans -.->|"uses runtime"| node_scanruntime
node_structures -.->|"uses runtime"| node_structruntime
node_lua -.->|"uses runtime"| node_luaruntime

click node_server "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/server.py"
click node_registration "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/__init__.py"
click node_bridge "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/bridge.py"
click node_context "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/context.py"
click node_plugin "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/loader/plugin_loader.cpp"
click node_mcpclient "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/core/mcp_client.cpp"
click node_core "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/core/core_runtime.cpp"
click node_process "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/process_tools.py"
click node_memory "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/memory_tools.py"
click node_scans "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/scan_tools.py"
click node_scanhelpers "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/scan_helper_tools.py"
click node_pointers "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/pointer_tools.py"
click node_tables "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/table_tools.py"
click node_structures "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/structure_tools.py"
click node_debug "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/debug_tools.py"
click node_lua "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/script_tools.py"
click node_luapackages "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/lua_library_tools.py"
click node_exported "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/exported_tools.py"
click node_scanruntime "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/scan_runtime.py"
click node_structruntime "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/structure_runtime.py"
click node_luaruntime "https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/lua_runtime.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registration,node_bridge,node_context,node_client toneBlue
class node_plugin,node_mcpclient,node_core toneAmber
class node_process,node_memory,node_scans,node_scanhelpers,node_pointers,node_tables,node_structures,node_debug,node_lua,node_luapackages,node_exported toneMint
class node_scanruntime,node_structruntime,node_luaruntime toneRose
class node_ce toneIndigo
```

## Components

### MCP backend

- [MCP server](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/server.py): `python/src/ce_mcp_server/server.py`
- [Tool registration](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/__init__.py): `python/src/ce_mcp_server/tools/__init__.py`
- [TCP bridge](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/bridge.py): `python/src/ce_mcp_server/bridge.py`
- [Tool context](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/context.py): `python/src/ce_mcp_server/context.py`

### Native plugin

- [Stable loader](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/loader/plugin_loader.cpp): `native/src/loader/plugin_loader.cpp`
- [Bridge client](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/core/mcp_client.cpp): `native/src/core/mcp_client.cpp`
- [Native core](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/native/src/core/core_runtime.cpp): `native/src/core/core_runtime.cpp`

### CE tool domains

- [Process and symbols](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/process_tools.py): `python/src/ce_mcp_server/tools/process_tools.py`
- [Memory access](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/memory_tools.py): `python/src/ce_mcp_server/tools/memory_tools.py`
- [Scanning](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/scan_tools.py): `python/src/ce_mcp_server/tools/scan_tools.py`
- [Scan helpers](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/scan_helper_tools.py): `python/src/ce_mcp_server/tools/scan_helper_tools.py`
- [Pointer chains](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/pointer_tools.py): `python/src/ce_mcp_server/tools/pointer_tools.py`
- [Tables and records](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/table_tools.py): `python/src/ce_mcp_server/tools/table_tools.py`
- [Structure tools](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/structure_tools.py): `python/src/ce_mcp_server/tools/structure_tools.py`
- [Debug watches](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/debug_tools.py): `python/src/ce_mcp_server/tools/debug_tools.py`
- [Lua scripting](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/script_tools.py): `python/src/ce_mcp_server/tools/script_tools.py`
- [Lua libraries](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/lua_library_tools.py): `python/src/ce_mcp_server/tools/lua_library_tools.py`
- [Exported SDK](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/tools/exported_tools.py): `python/src/ce_mcp_server/tools/exported_tools.py`

### Lua runtimes

- [Scan runtime](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/scan_runtime.py): `python/src/ce_mcp_server/runtime/scan_runtime.py`
- [Structure runtime](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/structure_runtime.py): `python/src/ce_mcp_server/runtime/structure_runtime.py`
- [Lua runtime](https://github.com/tonytranrp/cheat-engine-mcp/blob/main/python/src/ce_mcp_server/runtime/lua_runtime.py): `python/src/ce_mcp_server/runtime/lua_runtime.py`

### Other components

- **Codex MCP client**
- **Cheat Engine**

## Connections

- Codex MCP client → MCP server: MCP requests
- MCP server → Tool registration: registers tools
- MCP server → TCP bridge: starts and stops
- Tool registration → Process and symbols: registers
- Tool registration → Memory access: registers
- Tool registration → Scanning: registers
- Tool registration → Pointer chains: registers
- Tool registration → Tables and records: registers
- Tool registration → Structure tools: registers
- Tool registration → Debug watches: registers
- Tool registration → Lua scripting: registers
- Tool registration → Lua libraries: registers
- Tool registration → Exported SDK: registers
- Tool registration → Scan helpers: registers
- Process and symbols → Tool context: calls
- Memory access → Tool context: calls
- Scanning → Tool context: calls
- Scan helpers → Tool context: calls
- Pointer chains → Tool context: calls
- Tables and records → Tool context: calls
- Structure tools → Tool context: calls
- Debug watches → Tool context: calls
- Lua scripting → Tool context: calls
- Lua libraries → Tool context: calls
- Exported SDK → Tool context: calls
- Tool context → TCP bridge: native calls
- TCP bridge → Bridge client: TCP requests
- Stable loader → Bridge client: starts client
- Bridge client → Native core: dispatches requests
- Native core → Cheat Engine: invokes CE APIs
- Scanning → Scan runtime: uses runtime
- Structure tools → Structure runtime: uses runtime
- Lua scripting → Lua runtime: uses runtime