Introduction
ce-mcp — Unofficial MCP server for Cheat Engine — design preview.
This book is the design and migration documentation for ce-mcp. The project
does not have an implementation yet.
License: no license is granted at this time. This is a public design preview, not an open-source project yet. See License status.
Start here
- Vision — what the project is for and what it is not.
- Architecture — MCP layer, backend contract and bridge.
- Migration overview — how the design evolved.
- Target inventory — what was found in Cheat Engine 7.7.
- MCP research — the
2026-07-28protocol. - Tool catalog — planned tools and profiles.
- Coverage — what is designed, mapped or missing.
Status at a glance
| Area | Status |
|---|---|
| Target inventory | Complete for the shipped Cheat Engine 7.7 macOS bundle |
| MCP protocol research | Complete for 2026-07-28 |
| Tool catalog | Designed; no implementation |
| Lua bridge | Designed; not implemented |
| MCP server | Designed; not implemented |
| Documentation site | This book |
| License | TBD; public preview |
Scope
The first deliverable is an MCP server that drives Cheat Engine through a local Lua bridge. A native Rust backend may follow behind the same contract. The project is not a Cheat Engine clone and does not redistribute Cheat Engine.
See Vision for the full scope and non-goals.
Vision
The problem
Cheat Engine is a powerful environment for inspecting and modifying processes, but almost all of its capability is exposed through a desktop GUI. Automation exists through Lua, yet an AI agent cannot discover or use it without a bespoke integration for every workflow.
The Model Context Protocol gives agents a standard way to discover and call tools. What is missing is a well-designed MCP surface for Cheat Engine’s capabilities.
The idea
ce-mcp exposes Cheat Engine to MCP clients with three layers:
- Curated tools for the common workflows: process selection, memory access, scans, the address list, symbols, the debugger, assembly and structures.
- A Lua escape hatch for the full documented API.
- Generated tools for every documented Lua function, behind an optional profile.
The MCP contract is the product. The first backend is a local Lua bridge into Cheat Engine 7.7. A native Rust backend can replace it later without changing tool names, parameters or semantics.
Who it is for
- People who already use Cheat Engine and want an agent to handle repetitive workflows.
- Reverse-engineering researchers who want scriptable, auditable access to Cheat Engine’s tools.
- MCP client and agent developers who need a realistic, stateful tool surface to test against.
Principles
Capability parity, not UI parity
The goal is every operation, not every dialog. A settings dialog becomes parameters on the operation it configures. The project does not clone the Cheat Engine GUI.
Cheat Engine semantics
Once a process is opened, reads and writes are allowed, as they are in Cheat Engine. The project does not add a read-only mode by default and does not pretend to be safer than the underlying tool. It does document the risks and offers optional auditing.
Local first
The bridge listens on localhost only and authenticates with a per-launch token. There is no cloud service, no remote execution and no telemetry by default.
Spec first
The tool catalog is machine-readable. Documentation, schemas and tests are generated from the same source of truth. Coverage is measured, not claimed.
Backend independence
Tools call a backend contract, not Mach APIs or Lua directly. The Lua bridge is the first implementation; a native backend is a later, independent milestone.
Non-goals
- Reimplementing the Cheat Engine GUI.
- Redistributing Cheat Engine or its assets.
- Anti-cheat or game-protection bypass.
- Kernel drivers, DBVM or Windows-only kernel features.
- A read-only mode that changes Cheat Engine semantics by default.
- A cloud service that executes tools on someone else’s machine.
Success criteria
The project succeeds when an MCP client can:
- discover the available tools and their profiles;
- open a process, enumerate modules and regions, and read memory;
- run a first scan and refine it with the common scan types;
- edit values and manage address-list entries and
.CTfiles; - run Lua and Auto Assembler scripts;
- set breakpoints and inspect registers and stack traces;
- understand exactly which documented Cheat Engine functions are covered, generated or intentionally excluded.
The coverage matrix is the contract. “All tools” means all documented capabilities are accounted for, not that every internal dialog has a tool.
Architecture
Overview
ce-mcp has four layers:
- MCP server — protocol handling, tool discovery, validation, pagination, tasks and transport.
- Tool registry — the machine-readable catalog and the dispatch layer.
- Backend contract — a trait that abstracts Cheat Engine operations.
- Backends — the Lua bridge now, a native Rust engine later.
flowchart TB
subgraph Clients
A1[MCP client over stdio]
A2[MCP client over Streamable HTTP]
end
subgraph ce-mcp
B1[Transport]
B2[Tool registry]
B3[Policy and limits]
B4[Backend trait]
end
subgraph Backends
C1[Lua bridge backend]
C2[Native backend future]
end
subgraph Cheat Engine
D1[ce_bridge.lua]
D2[Cheat Engine 7.7]
end
E[Target process]
A1 --> B1
A2 --> B1
B1 --> B2
B2 --> B3
B3 --> B4
B4 --> C1
B4 -.-> C2
C1 -->|localhost TCP, token| D1
D1 --> D2
D2 --> E
C2 -.-> E
MCP server
The server targets MCP 2026-07-28:
- Stateless requests. No
initializehandshake and no session header. Every request carries protocol version and client capabilities in_meta. server/discover. Advertises supported protocol versions, capabilities and instructions, including the active profile.- Explicit handles. Stateful operations return opaque handles:
process_handle,scan_handle,debug_handle,table_handle. - Tasks. Long operations such as pointer scans can return a task handle
that the client polls with
tasks/get. - Pagination. Result lists use cursors; the server never returns an unbounded array.
- Caching. List results carry
ttlMsandcacheScopeso clients can cache tool and resource lists. - Subscriptions.
subscriptions/listencan deliver tool and resource list changes. Runtime events such as scan progress and breakpoint hits use task state or polling, not core subscription filters.
The transport is stdio by default. Streamable HTTP is optional and binds to localhost. See Transports.
Tool registry
The registry is generated from spec/:
spec/profiles.yamldefinescore,full,luaandall.spec/tools/*.yamldefines the curated tools.spec/lua-api.yamllists the documented Cheat Engine Lua functions and their migration status.
Each tool has a stable name, a summary, a profile, platform support, a backend mapping and a risk class. The same definition produces:
- the Rust registration code;
- the JSON Schema used by MCP;
- the generated tool reference;
- coverage checks.
This avoids documentation drift and makes “all tools” measurable.
Backend contract
The backend contract is deliberately small. A backend accepts an operation and returns a structured result:
#![allow(unused)]
fn main() {
trait CheatEngineBackend {
async fn execute(&self, op: Operation) -> Result<Value, BackendError>;
}
}
The MCP layer owns validation, handles, pagination and error mapping. The backend owns Cheat Engine semantics. This separation allows:
- the Lua bridge to cover the documented API immediately;
- a native backend to replace tools incrementally;
- tests to use a mock backend without Cheat Engine running;
- a future Windows or Linux bridge without changing the MCP contract.
See Backend strategy.
Lua bridge
The bridge is a Lua script loaded into Cheat Engine. It:
- opens a TCP socket bound to
127.0.0.1; - writes its port and a random token to a user-only file;
- accepts length-prefixed JSON requests;
- authenticates the client before evaluating anything;
- evaluates Lua in Cheat Engine and returns a JSON-safe result;
- runs the accept loop in a thread and uses
synchronizefor GUI operations.
The bridge is opt-in. The MCP server never installs it silently.
The protocol is described in Protocol and ADR-0006.
State and handles
MCP is stateless, but Cheat Engine is not. The backend keeps a registry of handles:
| Handle | Created by | Meaning |
|---|---|---|
process_handle | process_open | An open process, including its start time to avoid PID reuse |
scan_handle | scan_start | A scan session and its result set |
debug_handle | debug_attach | An active debugger session |
table_handle | table_new / table_load | An address-list/table context |
Handles have a TTL, can be listed with ce_handles and are released
explicitly or when the backend shuts down. A handle is opaque; clients must not
parse it.
Profiles
Profiles keep the tool list manageable:
| Profile | Purpose |
|---|---|
core | Default agent workflow |
full | All curated tools |
lua | Generated tools for the documented Lua API |
all | full + lua |
The default is core. A client can request a different profile through server
configuration. See Profiles.
Failure model
- Tool-level errors return a structured error with
code,message,remediationandretryable. - Protocol-level errors are reserved for malformed requests and unknown tools.
- The bridge can be unavailable, Cheat Engine can be closed, a process can exit, or a scan can be cancelled. Each case maps to a distinct error code.
- Long operations are cancellable. The server never blocks the transport while a scan runs.
See Errors.
Security
The bridge executes Lua by design. It binds to localhost, requires a token and is opt-in. The project does not bypass SIP, code signing or anti-cheat protections. See Security and SECURITY.md.
What is not decided yet
- The final implementation license.
- Whether the pointer scan gap is filled by a native tool or by driving the Cheat Engine form.
- The exact Lua bridge wire format after the F0 spike.
- Whether the desktop mode ships an embedded HTTP server or a separate process.
These are tracked in the migration journal.
Migration overview
This section records how ce-mcp moved from “a full Cheat Engine clone in Rust”
to an MCP-first design with a Lua bridge, and what evidence supports each
decision.
The migration is documented as a sequence of dated notes, not as a polished after-the-fact story. Where a claim comes from a command, the command and its limits are recorded. Where a conclusion is an inference, it is labelled as such.
Timeline
| Date | Milestone |
|---|---|
| 2026-10-21 | Inspected the Cheat Engine 7.7 macOS bundle and measured its surface |
| 2026-10-21 | Researched the public Cheat Engine source landscape |
| 2026-10-21 | Researched MCP 2026-07-28 and the Rust SDK |
| 2026-10-21 | Narrowed the scope from a full clone to an MCP server |
| 2026-10-21 | Chose a Lua bridge as the first backend |
| 2026-10-21 | Defined profiles, stateless handles and the tool catalog |
| 2026-10-21 | Ran a formal REA CLI/Mach-O, plist and signature pass |
| 2026-10-21 | Mapped three debugger controls and formally deferred the remaining 11 gaps |
| 2026-10-21 | Defined the F0 bridge and MCP acceptance test plan |
| 2026-10-21 | Defined JSON Schema contracts for the six F0 tools |
| 2026-10-21 | Published a documentation-only public preview |
| TBD | F0: bridge and MCP spike |
| TBD | Implementation license selected before code contributions |
How to read these documents
| Document | Question it answers |
|---|---|
| 01-target-inventory.md | What exactly is the Cheat Engine 7.7 build we are targeting? |
| 02-source-landscape.md | What public source exists, and what can we rely on? |
| 03-mcp-research.md | Which MCP revision and transports should we target? |
| 04-decisions.md | What did we decide, when, and why? |
| 05-backend-strategy.md | Why a Lua bridge first, and how does a native backend fit? |
| 06-tool-migration.md | How do Cheat Engine capabilities become MCP tools? |
| 07-open-source.md | What does the project need before it is open source? |
| 08-gap-deferrals.md | Why are the remaining 11 tools gaps, and what would close them? |
| 09-f0-test-plan.md | How will the six-tool F0 spike be accepted? |
| journal/2026-10-21.md | What happened in the first design session? |
Evidence labels
Every technical claim in this section should be read with one of these labels:
- Observation — directly measured from the shipped bundle, the public source tree or an official specification.
- Inference — a conclusion drawn from observations; may be wrong.
- Unknown — not established by the available evidence.
The initial inventory began with shell tools (file, nm, strings, otool,
codesign). A later formal REA 6.7.0 CLI/Mach-O, plist and signature pass
strengthened the metadata evidence. Neither pass establishes runtime behavior;
that boundary is recorded in 01-target-inventory.md.
Scope of the migration
“Migration” here means two things:
- Capability migration: turning Cheat Engine’s operations into stable MCP tools.
- Backend migration: moving from the Lua bridge to a native Rust backend without changing the MCP contract.
It does not mean porting the Cheat Engine GUI to Rust. The desktop UI is out of scope for the current roadmap.
Maintenance
When a new investigation or decision is made:
- add a dated journal entry under
journal/; - update 04-decisions.md;
- add or supersede an ADR if the decision is architectural;
- update 06-tool-migration.md if the tool catalog changes;
- keep the coverage document honest: designed is not implemented.
Target inventory: Cheat Engine 7.7
Evidence status: shell observations plus a formal REA 6.7.0 CLI/Mach-O pass on 2026-10-21. The pass used the built-in artifact, Mach-O, property-list and code-signature providers. No Ghidra or Hopper disassembly was required, and no runtime behavior was observed. No Cheat Engine binary or asset is included in this repository.
Identity
| Field | Value |
|---|---|
| Application | /Applications/CheatEngine77.app |
| Bundle name | Cheat Engine 7.7 |
| Bundle identifier | org.cheatengine.cheatengine |
| Version | 7.7 (CFBundleShortVersionString) |
| Executable | Contents/MacOS/cheatengine |
| Architectures | Universal: x86_64 and arm64 |
| Main executable minimum macOS | 10.15 (LC_BUILD_VERSION, SDK 10.15) |
| Bundled Lua minimum macOS | 13.3 (LC_BUILD_VERSION, SDK 13.3) |
| Info.plist minimum | No LSMinimumSystemVersion key |
| Bundle size | ~104 MB |
| Main binary size | 83,482,352 bytes |
| Main binary SHA-256 | c52dbafcf101cea70c5fc3ccf3c8df704a55cc414b8480b717152a502b916de6 |
| Lua library | Contents/MacOS/liblua53.dylib, 597,904 bytes |
| Lua library SHA-256 | 2bade6b1645cbff550f5bd1499cd759cdfb211e2b82d1142748637eb9b647885 |
| Code signature | Developer ID Application: Eric Heijnen (3W4HR5987G) |
| Signature timestamp | 2026-05-29 09:43:47 |
| Hardened runtime | Yes |
| Entitlements | None observed |
The bundle is code-signed and uses universal Mach-O slices. The main executable
declares macOS 10.15, but the bundled liblua53.dylib declares macOS 13.3. If
that dylib is loaded on launch, 13.3 is the effective floor; this is an
inference, not a runtime test. The Info.plist does not declare a minimum.
This inventory did not assess notarization or Gatekeeper behavior.
Bundle contents
| Path | Notes |
|---|---|
Contents/MacOS/cheatengine | Main application |
Contents/MacOS/liblua53.dylib | Lua 5.3 runtime |
Contents/MacOS/libspeedhack.dylib | Speedhack library; only i386 and x86_64, no arm64 |
Contents/MacOS/libtcc-64.dylib | Tiny C Compiler; universal x86_64/arm64 |
Contents/MacOS/libtcc-arm64.dylib | Tiny C Compiler; universal x86_64/arm64 |
Contents/MacOS/tcclib/ | TCC runtime headers and license files |
Contents/MacOS/tutorial-aarch64.app | arm64 tutorial target |
Contents/MacOS/tutorial-x86_64.app | x86_64 tutorial target |
Contents/MacOS/include/ | C headers and source fragments, including celib.h, cesocket.h, cepipelib.c and luaclient.c |
Contents/Lua/ | main.lua, defines.lua, Autorun scripts, celua.txt |
Contents/Lua/Autorun/ | macOS scripts for speedhack, Mono/.NET, Java, pseudocode and symbol support |
Contents/Lua/Autorun/dylibs/libMonoDataCollectorMac.dylib | Universal Mono data collector; minimum macOS 11.0 |
Contents/Lua/Extensions/AITools/ | Bundled MIT-licensed AI assistant extension; not part of the core Lua API |
Contents/Lua/Extensions/UETools/ | Bundled Unreal Engine inspection extension; not part of the core Lua API |
Contents/Languages/ | 49 language and translation files |
The Lua/Extensions and Lua/Autorun directories are relevant to loading a
bridge script without modifying the application binary. The exact loading
order, permissions and extension enablement have not been tested. The bundled
extensions are third-party scripts, not entries in celua.txt; see
coverage for the scope boundary.
Formal REA pass
A formal REA 6.7.0 CLI/Mach-O pass was run on 2026-10-21. It used the built-in artifact, Mach-O, plist and code-signature providers; no Ghidra/Hopper disassembly and no target execution were involved.
Evidence references:
- artifact parent:
ev_c09daa54d23febdd0dc2644a9fb83c76686b78c9754f0f4ed4abe4d8ac9f2a2c - artifact inventory:
ev_9fbd8b477591cec873e8408c746462ca6fc93d2816cf7df7476ffc48ada323c5 - main Mach-O:
ev_f8dcc9d49ffc55bfc936a11f08ae127fe08f1e7142904e07e7047c8b85f165db liblua53.dylib:ev_59b5676589f543d1cfc3dd8ff7e4b256a7ac3ab31ddd422a2955e4b73ea7ca26- code signature:
ev_138adc2cec7795d98d869835ae97d988ac45adc1ee7aea126fcf8bcc42b38c3f Info.plist:ev_760867c78a69d30853d7b4c747f5748bdae0ea45c9bed07ee25ae27c571f1b0e- dylib resolution:
ev_0d5bb1554db021ad57a9b22401f01ae543fad5e1e6aaf669e57159719ad2ddcd
Artifact graph
The artifact provider reported 254 graph nodes, 261 path occurrences and 260
edges. The root directory SHA-256 was
16b0c557426e935d9b79e8c4193f3b8ee125b4689800f1ac08197329a7168374; the
graph SHA-256 was
d4cfcf575446f182f853ebdc348cf35936cb364a128e2e725d802d3d7617d37c.
The graph contains eight Mach-O files: the main executable, four bundled
libraries, two tutorial executables and the Mono collector. It also contains
the C headers and source fragments under Contents/MacOS/include, and the
bundled Lua scripts under Contents/Lua.
Mach-O facts
| Binary | Architectures | Minimum macOS | Notes |
|---|---|---|---|
cheatengine | x86_64, arm64 | 10.15 | SDK 10.15; LD 1167.5; UUID 205C584C-1289-347E-847C-323C73662D42 |
liblua53.dylib | x86_64, arm64 | 13.3 | SDK 13.3; LD 857.1; one dependency (libSystem) |
libspeedhack.dylib | i386, x86_64 | 10.5 (x86_64 slice) | No arm64 slice |
libtcc-64.dylib | x86_64, arm64 | 11.0 | SDK 13.3 |
libtcc-arm64.dylib | x86_64, arm64 | 11.0 | SDK 13.3 |
libMonoDataCollectorMac.dylib | x86_64, arm64 | 11.0 | SDK 15.5 |
The main executable returned 125,814 export records and 511 import records.
The provider marks both collections as non-exhaustive, so these are lower
bounds. It has 33 load commands, 17 dynamic-library dependencies, five segments
and one entry point. The export count is in the same order as the 126,325
nm symbol lines; the two metrics are not identical.
The main binary imports Mach task and memory APIs (task_for_pid,
task_suspend, task_resume, mach_vm_read_overwrite, mach_vm_write,
mach_vm_protect, mach_vm_region), thread-state APIs and POSIX socket APIs
(socket, bind, listen, accept, connect, recv, send). It does not
import ptrace; the ptrace string observed earlier may come from a dynamic
lookup or an unused code path. Inference, not a runtime observation.
Signature and plist
inspect_signature reported a valid signature with the authority chain
Developer ID Application: Eric Heijnen (3W4HR5987G) → Developer ID Certification Authority → Apple Root CA, hardened runtime enabled, and no
entitlements returned. The signature timestamp was 2026-05-29 09:43:47. The
CDHash was 1f1316e5bbdc6ba7f7a1144a2f8fed36e14176b5. The designated
requirement binds the identifier org.cheatengine.cheatengine to the developer
team. Notarization and Gatekeeper trust were not assessed.
inspect_plist read the XML Info.plist: CFBundleName is Cheat Engine 7.7,
CFBundleIdentifier is org.cheatengine.cheatengine, CFBundleShortVersionString
is 7.7, and CFBundleExecutable is cheatengine. There is no
LSMinimumSystemVersion key.
Bridge-relevant observations
celua.txt documents LuaServerSocket and
createServerSocket(port, localhostOnly). It is a blocking TCP socket;
acceptConnection blocks and recommends a separate thread. LuaPipe exposes
readBytes, writeBytes, Timeout, OnTimeout and OnError. This supports
the planned bridge, but its behavior on macOS 26 remains untested.
The bundle also contains C source fragments for a named-pipe Lua client
(luaclient.c, cepipelib.c) and a cesocket.h that defines only AF_UNIX.
The planned bridge uses the documented Lua TCP socket instead of adding a native
C client. The Lua/Autorun/SpeedhackV3Mac.lua script shows that macOS speedhack
uses compile and API hooks; the bundled libspeedhack.dylib is not an arm64
library.
Binary surface
| Metric | Value | How measured |
|---|---|---|
| Total symbol lines (arm64 slice) | 126,325 | nm -arch arm64 |
FPC-mangled symbols ($$_) | 119,479 | nm + filter |
| Mach-O export records | 125,814 returned; non-exhaustive | REA inspect-macho |
| Mach-O import records | 511 returned; non-exhaustive | REA inspect-macho |
| Unit-like prefixes | 10,393 | Symbol prefixes; includes LCL/RTL |
Tfrm* classes | 136 | strings + filter |
TPF0 form resources | 344 | strings count |
| Documented Lua functions | 585 unique, 613 signatures | celua.txt |
celua.txt size | 4,444 lines, ~240 KB | wc, ls |
The unit count includes the Lazarus Component Library, the Free Pascal runtime and third-party units. It is not a count of Cheat Engine-specific modules.
The form count is a lower bound: it counts distinct Tfrm* strings, not every
form instance or frame. The TPF0 count includes forms, frames and data
modules.
Lua surface
Contents/Lua/celua.txt documents the Cheat Engine-specific Lua API. It is the
primary compatibility target for the bridge.
- 585 unique function names;
- 613 signatures, because some functions are overloaded;
- 22 unique
debug_*functions (24 signatures), some of which are platform-specific; - 39 unique
dbvm_*and 19 uniquedbk_*functions (43 and 20 signature lines), mostly Windows/DBVM-specific; - the rest cover memory, scans, the address list, symbols, assembly, structures, files, forms, threads and settings.
An initial regex count of 586 included ModuleLoader(Inheritance: -), which is
a class heading, not a function. The corrected function count is 585. The
signature count remains 613 because some functions are overloaded.
The names and migration status are recorded in
spec/lua-api.yaml. Descriptions are intentionally
not copied from Cheat Engine’s documentation; the original document is linked
from the Lua API reference.
macOS-specific units observed in symbols
These unit names indicate macOS-specific implementations that a native backend would eventually need to understand:
| Unit | Relevance |
|---|---|
macexceptiondebuggerinterface | Mach exception-based debugger |
maccreateremotethread | Remote thread creation |
macjitwriter | JIT/code writing |
macumm | User-mode memory manager UI |
macPipe | Pipe transport |
coresymbolication | Symbolication via CoreSymbolication |
machotkeys | Global hotkeys |
speedhack2 | Speedhack implementation |
lua_server | Built-in Lua server |
tcclib | TCC integration |
The binary also contains strings for MacExceptionDebugInterface,
TMacExceptionDebugInterface, GetThreadContextArm64 and
SetThreadContextArm64. It contains error strings for
GetThreadContext/SetThreadContext on aarch64. This suggests that some
debugger context paths on Apple Silicon are incomplete or conditional.
Inference, not a runtime observation.
Privilege and debugging model
Observed strings include:
"Have you disabled 'System Integrity Protection'(SIP) yet?"AuthorizationCreatealready root/not root yettask_for_pidmach_vm_read/mach_vm_write/mach_vm_protectthread_get_state/thread_set_stateptrace
Observation: the application imports AuthorizationCreate,
task_for_pid, mach_vm_* and thread_*_state, and its strings contain the
SIP, root and ptrace messages. The formal import list does not contain a
_ptrace symbol; the string does not prove a ptrace call.
Inference: full debugging of protected processes will require the same macOS permissions as Cheat Engine: root or a debuggable target, and in some cases SIP disabled. The MCP server cannot and will not bypass these constraints. The F0 spike must measure what works on macOS 26 with SIP enabled for a self-signed target.
Reproduction commands
These commands produced the inventory. They are read-only.
TARGET="/Applications/CheatEngine77.app"
file "$TARGET/Contents/MacOS/cheatengine"
lipo -info "$TARGET/Contents/MacOS/cheatengine"
shasum -a 256 "$TARGET/Contents/MacOS/cheatengine"
nm -arch arm64 "$TARGET/Contents/MacOS/cheatengine" | wc -l
nm -arch arm64 "$TARGET/Contents/MacOS/cheatengine" | grep -c '\$\$_'
strings -a -n 5 "$TARGET/Contents/MacOS/cheatengine" | grep -E '^Tfrm' | sort -u | wc -l
strings -a -n 4 "$TARGET/Contents/MacOS/cheatengine" | grep -c 'TPF0'
grep -oE '^[A-Za-z_][A-Za-z0-9_]*\(' "$TARGET/Contents/Lua/celua.txt" \
| sed 's/($//' | grep -v '^ModuleLoader$' | sort -u | wc -l
grep -E '^[A-Za-z_][A-Za-z0-9_]*\(' "$TARGET/Contents/Lua/celua.txt" \
| grep -v '^ModuleLoader(' | wc -l
# Formal REA 6.7.0 pass (read-only, no target execution)
npx -y rea-agents@6.7.0 inspect-artifact "$TARGET" --format json
npx -y rea-agents@6.7.0 inspect-macho "$TARGET/Contents/MacOS/cheatengine" --format json
npx -y rea-agents@6.7.0 inspect-macho "$TARGET/Contents/MacOS/liblua53.dylib" --format json
npx -y rea-agents@6.7.0 inspect-plist "$TARGET" --format json
npx -y rea-agents@6.7.0 inspect-signature "$TARGET" --format json
npx -y rea-agents@6.7.0 trace-dylib-resolution "$TARGET" --architecture arm64 --format json
lipo -info "$TARGET/Contents/MacOS/libspeedhack.dylib"
vtool -show-build -arch x86_64 "$TARGET/Contents/MacOS/libspeedhack.dylib"
Unknowns
- Which Lua functions actually work on macOS arm64; the documentation is cross-platform.
- Whether
createServerSocketandcreateThreadbehave as required in the bridge on macOS 26. - Whether the 13.3 minimum of
liblua53.dylibprevents launch on an older macOS host that satisfies the 10.15 main-executable minimum. - The exact behavior of
openProcess(0)for closing a process. - Whether the pointer scanner is reachable through the Lua API or only through its forms.
- Which debugger context fields are available on arm64.
- Whether the Lua/TCC speedhack path works on arm64 even though the bundled
libspeedhack.dylibhas no arm64 slice. - The exact loading order, permissions and enablement of
Lua/AutorunandLua/Extensionswhen the application is code-signed.
These unknowns are carried into the journal and the F0 spike.
Evidence limits
This inventory does not establish:
- that every symbol is reachable or used;
- that every form is functional on macOS;
- that every documented Lua function is implemented in this binary;
- that the public source at 7.5 matches the 7.7 binary;
- runtime behavior of any feature;
- that the returned export and import records are complete.
The formal REA pass strengthens the artifact and Mach-O metadata evidence, but it is static. It did not run the application, attach a debugger, decompile functions with Ghidra/Hopper or test the Lua bridge. Those remain F0 work.
Source landscape
Public repository
Cheat Engine publishes source code at https://github.com/cheat-engine/cheat-engine.
Observed on 2026-10-21:
| Field | Value |
|---|---|
| Default branch | master |
| Latest release tag | 7.5 (2023-02-23) |
Latest commit on master | 2025-04-19 |
| Files in the tree | 2,498 blobs |
| Pascal sources | 529 .pas |
| Lazarus forms | 164 .lfm |
| Program files | 20 .lpr |
| Lua files | 52 .lua |
| Root license file | Not present |
The repository contains a tcclib component with its own COPYING and
RELICENSING files. Those licenses apply to TCC, not to the whole project. The
absence of a root license means the licensing status of the Cheat Engine source
must not be assumed.
What this means for the project
The shipped application is 7.7. The newest public tag is 7.5. The public source is therefore useful as a reference, but it is not the specification for the exact binary being targeted.
Observation: public source exists for 7.5 and earlier.
Inference: the 7.5 source explains most of the architecture, unit names and Lua API, but not the 7.6/7.7 changes or the macOS-specific implementation in the shipped 7.7 build.
Rules for using the source
- Do not copy source code into this repository. The project has no license for the implementation yet, and the upstream licensing status is unclear.
- Do not copy documentation prose. Link to the official document and write original summaries.
- Use the source to understand structure, not as a binary specification. Unit names, form names and API names are facts; implementation details may differ in 7.7.
- Prefer the shipped binary for behavior. If the binary and the 7.5 source disagree, the binary wins.
- Record the version. Every source claim should say whether it comes from the 7.5 tree or the 7.7 bundle.
What the source is useful for
- Understanding the unit and form layout.
- Naming domains and tools consistently with Cheat Engine.
- Finding the Lua API surface and its overloads.
- Identifying which features are Windows-only by design.
- Designing a native backend later, with a clear map of responsibilities.
What the source cannot answer
- The exact 7.7 macOS behavior.
- The arm64 debugger limitations.
- The speedhack implementation shipped in this bundle.
- The exact Lua bridge behavior in 7.7.
- Whether a documented function is compiled and reachable on macOS.
Those questions require the shipped binary, runtime observation or targeted REA analysis.
REA plan
The project intends to use REA for targeted evidence, not a full decompilation:
- Artifact and Mach-O inventory with the built-in REA tools.
- Targeted native analysis of macOS-specific units:
macexceptiondebuggerinterface,maccreateremotethread,macjitwriter,macumm,speedhack2andlua_server. - Runtime observation of the bridge-relevant flows, once a test target and code-signing setup exist.
- Evidence ledger with observation/inference/unknown labels.
This pass has not been run yet. The current inventory is shell-based. The fact that a symbol or string exists is not proof that a feature works.
Links
- Repository: https://github.com/cheat-engine/cheat-engine
- Latest public release: https://github.com/cheat-engine/cheat-engine/releases/tag/7.5
- Lua API document in the public tree: https://github.com/cheat-engine/cheat-engine/blob/master/Cheat%20Engine/bin/celua.txt
MCP research
Target revision
The design targets MCP 2026-07-28, the current stable revision at the time
of writing.
Key changes from 2025-11-25:
- Stateless protocol. The
initializehandshake,notifications/initializedandMcp-Session-Idare removed. - Per-request metadata. Protocol version and client capabilities travel in
_metaon every request; clients should also identify themselves there. server/discover. Servers advertise supported versions, capabilities and identity. Clients may use it for version selection or as a compatibility probe.subscriptions/listen. Replaces the standalone HTTP GET stream andresources/subscribe/unsubscribe. Clients opt in to notification categories.- Tasks extension. Long-running work is a separate extension with
tasks/get,tasks/updateandtasks/cancel. The old blockingtasks/resultpattern is gone. - Caching hints. List and resource results carry
ttlMsandcacheScope. - Multi-round-trip requests. Servers return
InputRequiredResultwith embedded requests instead of initiating separate server-to-client requests. resultType. Every result iscomplete,input_requiredor, when the tasks extension is active,task.- No SSE resumability. A broken response stream loses the in-flight request; clients re-issue it with a new request ID.
Sources:
- Specification: https://modelcontextprotocol.io/specification/2026-07-28
- Changelog: https://modelcontextprotocol.io/specification/2026-07-28/changelog
- Transports: https://modelcontextprotocol.io/specification/2026-07-28/basic/transports
Transports
The standard bindings are:
- stdio — newline-delimited JSON-RPC over the standard streams of a client-launched subprocess.
- Streamable HTTP — each message is an HTTP POST to a single endpoint; replies are a JSON object or a request-scoped SSE stream.
The old HTTP+SSE transport is deprecated. WebSocket is not a standard MCP transport. The specification allows custom transports, and recommends reusing the stdio framing for reliable bidirectional byte streams such as Unix domain sockets.
| Transport | Local latency | Clients | Notes |
|---|---|---|---|
| stdio | Lowest | One per process | No HTTP overhead; best for a local agent |
| Streamable HTTP | ~sub-millisecond on loopback, plus HTTP/SSE overhead | Many | Best for the embedded app and multi-client |
| In-process worker | No network serialization | One | Best for UI ↔ server inside one process |
| HTTP over Unix socket | Lower than TCP | Many local | Optional; not universally supported by clients |
The transport is not the bottleneck for Cheat Engine operations. Scans and debugger waits dominate. The design therefore uses stdio by default and Streamable HTTP on localhost when a shared or multi-client server is needed. It does not invent a new external transport.
Rust SDK
The planned implementation uses rmcp 3.6, the official Rust SDK.
Relevant capabilities observed in its documentation:
- MCP
2026-07-28support with compatibility for2025-11-25and earlier; server/discoverand discovery-based client lifecycle;- stateless Streamable HTTP with JSON responses or request-scoped SSE;
- tasks extension support;
- subscriptions and
subscriptions/listen; - response caching with
ttlMs/cacheScope; - multi-round-trip requests;
- stdio, child process, Streamable HTTP and in-process worker transports.
Features planned for ce-mcp:
rmcp = { version = "3.6", features = [
"server",
"transport-io",
"transport-streamable-http-server",
"transport-worker",
"macros"
] }
Design consequences
Stateless server, stateful engine
MCP has no sessions, so the server cannot keep per-connection state. The backend keeps state and returns explicit handles:
process_openreturns aprocess_handle;scan_startreturns ascan_handleand possibly a task ID;debug_attachreturns adebug_handle;table_new/table_loadreturn atable_handle.
Handles are opaque, have a TTL and can be closed explicitly.
Tasks for long scans
A first scan or pointer scan can outlive a normal request. The server can
materialize a task and return a task handle. The client polls tasks/get and
can cancel with tasks/cancel. This is preferable to holding an HTTP request
open for minutes.
Caching tool lists
tools/list is deterministic and carries ttlMs/cacheScope. The lua and
all profiles list hundreds of tools; caching is important for client startup
and prompt cache stability.
No sampling, roots or logging dependency
The 2026-07-28 revision deprecates roots, sampling and logging. The design
does not depend on them. Logs go to stderr in stdio mode and to a file or
OpenTelemetry in server mode.
Open questions
- How much of the
2025-11-25compatibility path F0 must prove. The current target is the stdio path; HTTP compatibility can wait for F1.rmcpprovides the mechanism, but the bridge spike must test it with a real legacy client. - Whether the embedded desktop mode needs HTTP at all in F1, or whether stdio is sufficient until multi-client is required.
- How to expose progress without forcing SSE for every client.
These questions do not block D0.
Decision log
This is the human-readable index of decisions. Architectural decisions have a
full ADR in docs/decisions/.
| ID | Date | Decision | Rationale | Status |
|---|---|---|---|---|
| D1 | 2026-10-21 | Make MCP the product, not an afterthought | Cheat Engine already exposes a large Lua API; an MCP server delivers value without reimplementing the GUI | Accepted, ADR-0001 |
| D2 | 2026-10-21 | Scope the current project to the MCP server | A full Rust clone is a multi-year effort and would delay validation of the MCP design | Accepted, ADR-0001 |
| D3 | 2026-10-21 | Use a Lua bridge as the first backend | Immediate coverage of the documented API and exact Cheat Engine semantics | Accepted, ADR-0006 |
| D4 | 2026-10-21 | Preserve Cheat Engine write semantics | Once a process is open, Cheat Engine allows writes; adding a different default would break compatibility | Accepted, ADR-0005 |
| D5 | 2026-10-21 | Use core, full, lua and all tool profiles | Hundreds of tools in every context would hurt discovery and selection | Accepted, ADR-0004 |
| D6 | 2026-10-21 | Default to stdio; offer Streamable HTTP on localhost | stdio is the lowest-overhead local transport; HTTP is needed for multi-client and embedded mode | Accepted, ADR-0003 |
| D7 | 2026-10-21 | Use stateless MCP with explicit handles | MCP 2026-07-28 has no sessions; state belongs in the backend | Accepted, ADR-0002 |
| D8 | 2026-10-21 | Publish a documentation-only public preview now | Makes the design reviewable and the migration reusable without publishing unfinished code | Accepted, ADR-0008 |
| D9 | 2026-10-21 | Write repository documentation in English | Standard for open-source reach and contributions | Accepted |
| D10 | 2026-10-21 | Do not choose a license yet | The code license decision can wait until implementation; the repository is explicitly marked as a public preview | Accepted, ADR-0007 |
| D11 | 2026-10-21 | Use REA CLI + Mach-O inventory first; add Ghidra only if needed | The public source covers most of the architecture; REA should target macOS-specific deltas | Accepted, pending execution |
| D12 | 2026-10-21 | Keep .CT and Cheat Engine Lua compatibility | Existing tables and scripts are the main ecosystem; a clean format would lose that value | Accepted |
| D13 | 2026-10-21 | Defer the egui desktop GUI | The MCP server and bridge must be validated first; the GUI is a separate client of the same engine | Superseded by D2 for the current scope |
| D14 | 2026-10-21 | Name the public repository ce-mcp | Short, neutral and not implying affiliation with Cheat Engine | Accepted |
Decisions that were considered and deferred
| Topic | Why it is deferred |
|---|---|
| Full Rust engine | Requires reimplementing memory access, scanning, debugger, assembler and the Lua API before the MCP contract is validated |
| In-app desktop UI | A GUI is a large surface and not needed to prove the MCP design |
| Pointer scan | No obvious Lua API; needs either form automation or a native implementation |
| Windows/Linux bridge | The first target is macOS 7.7; the contract should stabilize first |
.CETRAINER and trainer generation | Depends on a working table and script layer |
| Multi-agent HTTP server | F1/F4 work; stdio is enough for F0 |
How decisions are changed
Open a Design proposal issue. If the change is architectural, add a new ADR that supersedes the old one and update this table. Do not rewrite history: a superseded ADR stays in the repository.
Open decisions
- The implementation license.
- The exact bridge wire format after the F0 spike.
- Whether the pointer scan gap is filled natively or through the existing Cheat Engine forms.
- Whether the first public implementation release supports MCP
2025-11-25clients.
Backend strategy
Contract first
The MCP tools are the stable interface. They do not call Mach APIs, Lua or Cheat Engine forms directly. They call a backend contract:
#![allow(unused)]
fn main() {
trait CheatEngineBackend {
async fn execute(&self, op: Operation) -> Result<Value, BackendError>;
}
}
The Operation enum is the internal capability vocabulary. The MCP layer maps
validated tool arguments to operations; the backend maps operations to Cheat
Engine calls. This separation is what makes the migration possible.
Stage 1: Lua bridge
The first backend is a Lua script loaded into Cheat Engine 7.7.
Why
- Cheat Engine already implements memory access, scanning, the address list, debugger, assembler and Lua.
- The documented Lua API exposes most of those capabilities.
- The MCP design can be validated against a real application in weeks, not months.
- Cheat Engine semantics are preserved by construction, because Cheat Engine executes the operations.
Shape
ce-mcp (Rust)
-> localhost TCP, length-prefixed JSON, token
-> ce_bridge.lua (running inside Cheat Engine)
-> Cheat Engine Lua API
-> target process
The bridge:
- binds to
127.0.0.1only; - writes
{port, token, pid}to a user-only file; - authenticates before evaluating any code;
- accepts
ping,eval,call,cancelandshutdown; - runs the accept loop in a Lua thread;
- uses
synchronizewhen an operation touches the GUI; - returns JSON-safe values, with bytes encoded as hex or base64;
- enforces a best-effort execution timeout.
The wire format is a design proposal, not a tested protocol. F0 must validate it.
Evidence from the shipped application
Contents/Lua/celua.txt documents LuaServerSocket and
createServerSocket(port, localhostOnly): a blocking TCP socket whose
acceptConnection blocks the calling thread. The same document recommends
using a separate thread. LuaPipe, the base class, exposes readBytes,
writeBytes, Timeout, OnTimeout and OnError. This is enough to implement
length-prefixed JSON without adding a native transport.
The application also ships C source fragments for a named-pipe Lua client
(Contents/MacOS/include/luaclient.c and cepipelib.c). They are not used by
this design: a C client would add a native build step and a second protocol.
Two platform facts affect F0:
liblua53.dylibdeclares macOS 13.3 even though the main executable declares 10.15. The bridge should report the effective host floor rather than assuming 10.15.libspeedhack.dylibcontains onlyi386andx86_64slices. The LuaSpeedhackV3Mac.luapath usescompileand API hooks, so arm64 speedhack may still work, but that is unverified.
Coverage
The bridge can cover most of the documented API:
- process list and open;
- memory read/write, allocation, protection;
- first scan, next scan, unknown value, changed/increased/decreased;
- address list and memory records;
.CTload/save;- AOB scan, symbols, address parsing;
- disassembly, assembly, Auto Assembler;
- debugger breakpoints and context where the Lua API supports them; attach, stepping and stack traces are known gaps;
- structures and Lua evaluation;
- hotkeys, speedhack and some UI operations.
Known gaps are listed in Tool migration.
Stage 2: hybrid
Some tools have no reliable Lua API. They are marked backend: native and
implemented in Rust while the rest of the catalog remains on the bridge.
Likely first native tools:
- pointer scan orchestration;
- structure dissect beyond the Lua object model;
- region and module enumeration where the Lua output is insufficient;
- high-volume memory reads that would be inefficient through JSON;
- native debugger context fields on arm64.
The hybrid stage does not change tool names or semantics. A tool’s backend
field changes from lua to native when its native implementation passes the
same contract tests.
Stage 3: native
A full native backend is a separate, long-term project. It would need:
task_for_pidand Mach VM access;- region, module and thread enumeration;
- a scan engine with Cheat Engine-compatible value types and filters;
- a pointer scanner;
- Mach exception debugging, breakpoints and stepping;
- x86/x64 and arm64 disassembly and assembly;
- Auto Assembler compatibility;
- a Lua 5.3 runtime with the Cheat Engine API;
.CTparsing and address-list semantics.
This is explicitly out of scope for the current roadmap. The MCP contract is designed so that this work can happen incrementally without breaking clients.
Compatibility promises
- Tool names, parameters and result shapes are stable within a major version.
- A backend swap must not change observable semantics.
- A tool that is unsupported by the current backend returns
CE_BACKEND_UNAVAILABLEorCE_UNSUPPORTED_PLATFORM, not a silent no-op. - Coverage is reported per backend, not hidden.
Failure handling
| Failure | Behavior |
|---|---|
| Cheat Engine not running | CE_BACKEND_UNAVAILABLE with remediation |
| Bridge script not loaded | CE_BACKEND_UNAVAILABLE with setup instructions |
| Token mismatch | CE_ACCESS_DENIED; no Lua evaluation |
| Process exited | CE_PROCESS_CLOSED; handles invalidated |
| Scan cancelled | CE_SCAN_CANCELLED; partial results retained if requested |
| Lua error | CE_LUA_ERROR with the original message and traceback if available |
| Timeout | CE_TIMEOUT; the operation may still be running, so the tool documents whether it is safe to retry |
Security
The bridge is arbitrary Lua execution by design. It is opt-in, localhost-only and token-authenticated. The project does not attempt to sandbox Lua, because that would diverge from Cheat Engine. See Security.
Alternative considered: native first
A native-first backend would avoid the bridge but delay the MCP server until memory access, scanning, the debugger and Lua are all functional. It also risks designing the MCP contract against an incomplete engine. Rejected for the current phase; recorded in ADR-0006.
Tool migration
Goal
Every documented Cheat Engine capability must be accounted for. “All tools” does not mean one MCP tool per dialog. It means:
- a curated MCP tool for the operation, or
- a generated tool for the documented Lua function, or
- an explicit exclusion with a reason and a platform note.
The coverage matrix is the contract. It is generated from the same definitions as the server.
Method
- Inventory. Extract the documented Lua function names and the visible Cheat Engine domains.
- Domain model. Group capabilities into process, memory, scan, table, symbols, pointer scan, assembly, debugger, structures, Lua, UI and misc.
- Curated design. Define the tools an agent should see by default. Each tool gets a stable name, typed parameters and a backend mapping.
- Mapping. For every Lua function, record whether it is covered by a curated tool, will be generated as its own tool, or is excluded.
- Coverage check. CI compares the documented names with the catalog and fails on an unexplained gap.
Curated catalog
The design contains 81 tools in 13 groups.
| Group | Count | Tools |
|---|---|---|
| Meta | 4 | ce_info, ce_status, ce_capabilities, ce_handles |
| Process | 7 | process_list, process_open, process_close, process_info, module_list, region_list, thread_list |
| Memory | 10 | memory_read, memory_write, memory_read_value, memory_write_value, memory_read_string, memory_alloc, memory_free, memory_protect, memory_fill, memory_dump |
| Scan | 8 | scan_start, scan_next, scan_cancel, scan_status, scan_results, scan_refresh, scan_save, scan_load |
| AOB/Symbols | 5 | aob_scan, symbol_resolve, symbol_lookup, symbol_list, address_parse |
| Table | 10 | table_new, table_load, table_save, table_entries, table_add, table_update, table_delete, table_freeze, table_set_value, table_run_script |
| Pointer scan | 6 | pointer_scan_start, pointer_scan_status, pointer_scan_results, pointer_scan_rescan, pointer_scan_cancel, pointermap_generate |
| Disassembly/Assembly | 4 | disassemble, assemble, auto_assemble, code_cave_find |
| Debugger | 12 | debug_attach, debug_detach, debug_status, breakpoint_set, breakpoint_remove, breakpoint_list, debug_continue, debug_step, registers_get, registers_set, stacktrace, debug_wait |
| Structures | 4 | structure_new, structure_define, structure_read, structure_list |
| Lua | 3 | lua_eval, lua_call, lua_api_list |
| UI/App | 5 | ui_state, ui_open_tool, hotkey_list, hotkey_set, speedhack_set |
| Misc | 3 | trainer_generate, snapshot_create, snapshot_restore |
The machine-readable definitions are in spec/tools/. The
catalog reference is MCP tool catalog. The six F0
tools have concrete JSON Schema contracts in
spec/contracts/f0.yaml; the other 75 still
need their input and output schemas.
Lua API coverage
spec/lua-api.yaml contains the 585 documented function names and a migration
status. The design has three coverage levels:
| Level | Meaning |
|---|---|
curated | The function is behind a curated MCP tool with a stable contract |
generated | The function gets its own tool under the lua profile |
excluded | The function is not exposed, with a documented reason |
The lua profile is optional because listing 585 tools in every agent context
would be counterproductive. The all profile exists for clients that
explicitly want the full surface.
Why this is the full surface
Cheat Engine has three kinds of capability:
- Documented automation. The 585 Lua functions in
celua.txt. These are covered by curated tools, generated tools, or an explicit exclusion. - Operations with no Lua entry point. Pointer scan, parts of structure
dissect, trainer generation and some UI flows. These are listed as
gapor excluded, not silently omitted. - Dialogs and presentation. Settings, forms, colors and layout. These are not separate tools. A setting becomes a parameter on the operation it controls; a form is not a capability by itself.
The catalog therefore accounts for the automation surface, names the native gaps, and refuses to claim that a GUI dialog is a tool. That is what “all tools” means in this project.
Status vocabulary
| Status | Meaning |
|---|---|
designed | Tool contract exists in spec/; no implementation |
mapped | Backend mapping is identified; not tested |
implemented | Backend call works in a development build |
tested | Contract tests and an end-to-end test pass |
unsupported | Not available on the platform or backend |
gap | No reliable mapping exists yet |
Today no curated tool is implemented or tested. A tool with an identified
backend strategy is marked mapped; a tool without one is marked gap.
Platform matrix
| Platform | Curated tools | Lua bridge | Notes |
|---|---|---|---|
| macOS | Designed | Planned | First target; arm64 is the primary test host |
| Windows | Designed | Future | Named pipes or localhost TCP; DBVM/kernel features remain out of scope |
| Linux | Designed | Future | The public source has Linux support; the bridge must be validated |
The platforms field in each tool definition is authoritative.
Known limitations and gaps
| Limitation or gap | Reason | Candidate solution |
|---|---|---|
| Pointer scan | No direct Lua API found in celua.txt; the UI forms orchestrate it | Native backend or controlled form automation |
| Structure dissect UI | The structure_* tools cover definitions and reads; the interactive window is form-driven | Use structure_*; UI parity is out of scope |
| arm64 debugger context | The binary contains explicit aarch64 context error paths | Native Mach exception backend |
| Code cave scanner | No single documented API; code_cave_find composes region and byte scans | Planned composed tool |
| Trainer generation | Windows/PE-centric | Out of scope for macOS; revisit later |
| DBVM and kernel features | Windows-only by design | Excluded |
The 11 tool-level gaps and their closure criteria are recorded in Gap deferrals. This table also includes limitations that are not individual tools.
Coverage in CI
When implementation starts, CI will:
- parse the documented function names from a local Cheat Engine installation or a checked-in names file;
- compare them with
spec/lua-api.yaml; - fail if a name is missing, duplicated or has no status;
- compare
spec/tools/*.yamlwith the generated server registration; - fail if a tool is documented but not registered, or vice versa;
- publish
docs/reference/coverage.mdas a generated report.
The coverage report must distinguish designed, implemented and tested. A design document is not coverage.
Adding a tool
- Add the definition to the right
spec/tools/*.yamlfile. - Assign a profile, platforms, backend and risk class.
- Add the Cheat Engine Lua mapping or mark it
gap. - Update
spec/lua-api.yamlif a documented function becomes covered. - Run the generator and the coverage check.
- Update the generated reference and coverage report.
See CONTRIBUTING.md for the review process.
Open-source readiness
Current status
This repository is a public design preview, not an open-source project yet.
- There is no implementation.
- There is no license for the code.
- The documentation is published so the design can be reviewed and the migration can be reused as a reference.
Publishing a repository publicly is not the same as open source. Without a license, default copyright applies: people can view the repository, but they do not receive the right to copy, modify or redistribute it.
Why the license is deferred
The implementation is not written yet. Choosing a license now would force a decision before the project knows whether it will include code derived from Cheat Engine, third-party Lua libraries or other components.
The project therefore separates two decisions:
- Publish the design now. This is allowed, with an explicit “no license” notice.
- Choose the implementation license before code contributions. This is a hard gate for F0.
The cost of deferring is that the public preview cannot be described as open source and code contributions cannot be accepted. That is intentional and documented.
What must happen before code
Before the first code pull request is merged:
- Choose the implementation license.
- Add the full license text and update
LICENSE.md. - Update
README.md,Cargo.tomland package metadata. - Update
CONTRIBUTING.mdwith the contribution and sign-off rules. - Record the decision in an ADR that supersedes ADR-0007.
- Confirm that no Cheat Engine source or assets are included.
- Confirm third-party dependency licenses are compatible.
- Enable code scanning and dependency review in CI.
Until then, code pull requests are closed with a link to this document.
Trademark and assets
- The project is unofficial and not affiliated with Cheat Engine.
- The name is used only to describe interoperability.
- No Cheat Engine logo, icon, screenshot, language file, tutorial or binary is included.
- Documentation links to the official project instead of copying its prose.
- A
NOTICEfile records the trademark disclaimer.
See Trademark.
Contribution policy
During the design preview:
- issues and design proposals are welcome;
- documentation corrections are welcome as issues;
- code pull requests are paused;
- security reports go through GitHub Security Advisories.
After the license is chosen, the project will use a lightweight sign-off process (DCO or equivalent) rather than a CLA, unless the chosen license requires otherwise.
Documentation infrastructure
- Markdown sources in
docs/. - mdBook build for the documentation site.
- GitHub Pages deployment from the default branch.
markdownlintfor structure and consistency.- Link checking for external references.
- No generated code or copied documentation in the site.
Release plan
| Release | Contents | Gate |
|---|---|---|
v0.0.0-docs | Design preview | This document set is complete and reviewed |
v0.1.0-alpha | Bridge + MCP spike | License chosen; F0 acceptance criteria met |
v0.2.0-alpha | Core profile | F1 acceptance criteria met |
v1.0.0 | Stable contract | F4 acceptance criteria met |
Documentation releases do not imply an implementation license.
Sustainability
- Keep the scope narrow: MCP server, bridge and documented native gaps.
- Prefer generated documentation and coverage over manual claims.
- Keep the bridge and backend contract small enough for one maintainer to review.
- Do not accept code contributions that cannot be maintained.
- Revisit governance when there is more than one active maintainer.
Checklist for making the repository public
- README with status, scope and license notice.
- Migration documentation and decision log.
- Architecture and tool catalog.
- Security policy and code of conduct.
- Governance and maintainer list.
- Documentation CI.
- Review all external links with lychee.
- Confirm no Cheat Engine assets or copied prose.
- Publish the repository under the
ce-mcpname. - Enable GitHub Pages.
- Enable private security reporting.
- Add repository topics and description.
The repository is at https://github.com/jcmunoz200/ce-mcp and the rendered documentation is at https://jcmunoz200.github.io/ce-mcp/.
Gap deferrals
Purpose
The curated catalog has 81 tools. Seventy have an identified backend mapping
(mapped); eleven have no reliable mapping yet (gap). A gap is not a promise,
and a deferred gap is not coverage.
This page records the formal disposition of every remaining gap: the evidence that is missing, why the tool is not mapped now, and the condition that would close it. No tool on this page is implemented or tested.
Summary
| Disposition | Count | Tools |
|---|---|---|
| Deferred to an F0 runtime experiment | 1 | process_close |
| Deferred to the native backend | 7 | six pointer-scan tools, stacktrace |
| Deferred pending form-automation design | 1 | ui_open_tool |
| Deferred pending snapshot design | 1 | snapshot_restore |
| Out of scope for the macOS release | 1 | trainer_generate |
| Total | 11 |
These dispositions do not change the MCP contract. A gap can later become
mapped without changing its name, input schema or output schema.
process_close
Evidence. celua.txt documents openProcess(pid) and
openProcess(name) but no closeProcess. The string CloseProcess appears
only in the low-level API-pointer list used by setAPIPointer. The convention
openProcess(0) is not documented and has not been tested.
Why it is deferred. Closing a process is destructive and easy to confuse
with closeCE(), which closes Cheat Engine rather than the target. Guessing the
semantics would be worse than reporting the gap.
Closure criterion. Run an F0 experiment against a disposable self-signed target:
- open the target and record
getOpenedProcessID(); - call
openProcess(0); - verify the PID, process handle and dependent handles;
- verify that memory and scan operations fail with the documented error;
- repeat after reopening the same target.
If openProcess(0) closes the target, map process_close to it. If it does
not, implement the close in the native backend. Do not infer the behavior from
the GUI or from another Cheat Engine version.
Pointer scan (six tools)
Tools. pointer_scan_start, pointer_scan_status, pointer_scan_results,
pointer_scan_rescan, pointer_scan_cancel and pointermap_generate.
Evidence. celua.txt has no direct pointer-scan API. It documents
getPointerSize/setPointerSize and pointer-map callbacks
(onPointerMapGenerationStart and onPointerMapGenerationFinish), but the
pointer scanner itself is orchestrated by Cheat Engine forms. The callbacks are
hooks, not a scan API.
Why it is deferred. The alternatives are a native scanner or form automation. Form automation would depend on form names, control layout and timing, and would be fragile across Cheat Engine versions. A native scanner is a larger engineering project than the F0 bridge spike.
Closure criterion. Implement a native pointer-map and pointer-scan engine with a defined result format, or a narrowly scoped form adapter that:
- is guarded by an exact Cheat Engine version;
- has a cancellation path;
- returns structured results rather than screen text;
- passes a known pointer-chain fixture on macOS arm64.
Until one of those exists, the tools remain gaps. They should be advertised as
unavailable in ce_capabilities rather than silently returning partial data.
stacktrace
Evidence. There is no getStack or getCallStack function in celua.txt.
TFrmTracer exposes Entry and StackEntry data, but only through a tracer
form; there is no documented global getter for that form. The context APIs
return registers, not a call stack.
Why it is deferred. A reliable trace needs stack unwinding, frame validation and module/symbol resolution. On arm64 this is native work, and the existing arm64 context coverage is already an open question.
Closure criterion. A native unwinder that returns a bounded frame list with module offsets, validated against a known call chain on a self-signed target. The MCP result must mark unresolved frames rather than inventing symbols.
ui_open_tool
Evidence. celua.txt documents getFormCount(), getForm(index),
getMainForm(), getMemoryViewForm() and getLuaEngine(). Form exposes
show() and showModal(). There is no documented “open tool by name” call and
no stable menu-invocation API.
Why it is deferred. The tool could show an existing form, but it cannot portably create or locate every Cheat Engine tool. Form names and class names are implementation details. A partial allowlist would be useful, but it should not be described as “open any tool”.
Closure criterion. Define a small allowlist of stable forms with documented getters, test show/raise/focus behavior, and return a structured “form not available” error for everything else. If broader coverage is needed, use native UI automation with explicit version guards. Do not scrape or synthesize clicks in the F0 bridge.
snapshot_restore
Evidence. snapshot_create has a proposed mapping (saveTable(stream) plus
readBytes()), but the snapshot format and storage policy are not designed.
addSnapshotAsComment creates an Auto Assembler comment containing original
code; it is not a runtime snapshot API. There is no documented restore call.
Why it is deferred. Restoring memory and table state raises questions that the catalog has not answered: which regions are captured, how overlaps are handled, what happens when the target changed, whether restoration is atomic, and how a partial failure is reported. A restore that silently overwrites live state would be unsafe.
Closure criterion. Define a versioned snapshot schema and a restore policy
covering region selection, table state, conflicts, atomicity and rollback. Then
compose readBytes/writeBytes and table loading, and test a failed restore
that must leave the target unchanged.
trainer_generate
Evidence. The trainer generator is Windows/PE-centric. celua.txt exposes
registerEXETrainerFeature as an extension hook, not a documented
cross-platform “generate trainer” call. The tool definition already limits the
platform to Windows.
Why it is deferred. It is outside the macOS release and would require a Windows backend plus PE packaging. It is not a macOS bridge gap.
Closure criterion. A Windows backend with an explicit trainer contract and a reproducible output artifact. Keep it out of the macOS profile until then.
Options considered and rejected
| Option | Why it was rejected |
|---|---|
Assume openProcess(0) closes the target | Undocumented and destructive |
| Automate the pointer-scan and tracer forms in F0 | Fragile, hard to cancel, hard to test |
| Return a synthetic stack trace from registers | Would invent frames and symbols |
Call closeCE() for process_close | Closes Cheat Engine, not the target process |
Treat snapshot_create as proof that restore works | Create and restore are different operations |
Reporting
- The coverage table remains the source of truth: 70 mapped, 11 gaps.
- A gap is never reported as implemented or tested.
- Closing a gap requires a new mapping, a test result and a coverage update.
- If a gap cannot be closed without a native backend, record that dependency instead of leaving an open-ended promise.
See Coverage for the current counts and Tool migration for the status definitions.
F0 bridge and MCP test plan
Purpose
F0 is the first implementation milestone: a Lua bridge loaded into Cheat Engine 7.7 and a Rust MCP server over stdio. It is blocked until the implementation license is chosen. This page defines the acceptance tests now, so the spike does not invent its success criteria after the fact.
F0 exposes six tools:
ce_infoprocess_listprocess_openmemory_readscan_startscan_results
Their input and output schemas are in
spec/contracts/f0.yaml, with the conventions
explained in F0 tool contracts. The tests below must
validate results against those schemas.
Nothing on this page is implemented or tested.
Preconditions
| Item | Requirement |
|---|---|
| License | An explicit implementation license has been chosen |
| Cheat Engine | 7.7 from /Applications/CheatEngine77.app |
| Host | macOS 26 on arm64 for the primary run |
| Target | A disposable, self-signed test process with known values |
| SIP | Record the host state; do not disable it for the first run |
| Permissions | Record whether the target is debuggable without elevation |
| Repository | No Cheat Engine assets, copied docs or target binaries committed |
The test target should contain a known integer, float, string and a small allocated buffer. It must be safe to terminate and restart. Do not use a third-party game or a process whose state matters.
Bridge tests
Loading and discovery
- Load
bridge/ce_bridge.luawithout modifying the application bundle. - Confirm the bridge version, Cheat Engine version and Lua version in
ce_info. - Confirm
~/.ce-mcp/bridge.jsonis created. - Confirm the file mode is
0600; record the owner and directory mode. - Confirm the file contains a port, token and PID, and no secrets in logs.
- Restart Cheat Engine and confirm the bridge can be loaded again without a stale port or token.
Protocol version compatibility
- Modern stdio: call
server/discover, thentools/list, then one read. - Legacy stdio: perform the
2025-11-25initializehandshake, thentools/listand one read. Record whether the same tool schemas are returned. - Send an unsupported version and verify
-32022with the supported version list, not a silent downgrade. - If the SDK does not expose a working legacy path on stdio, record it and narrow the compatibility claim instead of advertising an untested path.
Network boundary
- Confirm the listener is bound to
127.0.0.1, not0.0.0.0or::. - Attempt a connection from another host or interface; it must fail.
- Attempt a connection with a missing token, an empty token and a wrong token; each must be rejected before Lua evaluation.
- Send a valid request after a rejected request; the bridge must remain usable.
Framing and limits
- Send a valid length-prefixed JSON request and verify the response frame.
- Send a length prefix larger than the configured maximum; the bridge must reject it without allocating an unbounded buffer.
- Send a truncated frame, then close the socket; the bridge must recover.
- Send invalid UTF-8 or invalid JSON; return a structured error.
- Send an unknown method; return a structured error and keep the connection usable.
- Send two requests in one read; both must be processed in order.
- Send a partial frame across reads; it must be reassembled correctly.
- Record the actual behavior of
LuaPipe.TimeoutandcreateServerSocket; the documentation describes timeouts in seconds, but the bridge must verify it.
Lifecycle and concurrency
- Disconnect a client while the bridge is idle; no thread or socket leak.
- Disconnect during a long scan; the scan must be cancellable or marked orphaned.
- Connect a second client; the documented behavior is one active client, or a
clean
CE_BACKEND_BUSY, not interleaved evaluation. - Request shutdown; the bridge must close the listener and exit its thread.
- Restart the bridge and verify old process/scan handles are not silently reused.
Tool tests
| Tool | Test | Pass condition |
|---|---|---|
ce_info | Call with no arguments | Returns server, Cheat Engine, Lua, OS and architecture versions |
ce_info | Call with no target open | Still succeeds; no process-dependent fields are invented |
process_list | List all processes | Returns bounded results with PID and name |
process_list | Filter by exact and partial name | Filter is case-insensitive where documented; no duplicate PIDs |
process_list | Paginate | Cursor is stable for an unchanged process list; invalid cursor is rejected |
process_open | Open the test target by PID | Returns a process handle and correct PID |
process_open | Open by name with one match | Returns the same target |
process_open | Open an invalid PID or name | Returns CE_PROCESS_NOT_FOUND; no handle is leaked |
process_open | Open a protected process | Returns a structured permission error; does not bypass SIP |
memory_read | Read a known integer, float and string | Bytes match the target before and after the call |
memory_read | Read an unmapped address | Returns CE_INVALID_ADDRESS; connection remains usable |
memory_read | Request more than the size limit | Returns CE_LIMIT_EXCEEDED; no partial silent truncation |
memory_read | Read after the target exits | Returns CE_PROCESS_CLOSED or the documented equivalent |
scan_start | Scan for a known 4-byte integer | Returns a scan handle and task state |
scan_start | Scan for a known float and string | Each value type follows its documented comparison and alignment |
scan_start | Scan with an invalid range | Returns CE_INVALID_ARGUMENT |
scan_start | Cancel a running scan | Returns CE_SCAN_CANCELLED and releases the scan thread |
scan_results | Read results from a completed scan | Returns bounded, paginated results with addresses and values |
scan_results | Read results from an unknown handle | Returns CE_SCAN_NOT_FOUND |
scan_results | Read before the scan completes | Returns CE_SCAN_BUSY or a progress object, not partial garbage |
scan_results | Paginate to the end | Last page has no duplicate or skipped addresses |
Handle tests
- A
process_handlefromprocess_openis required bymemory_readandscan_start. - A
scan_handlefromscan_startis required byscan_results. - Unknown, expired and cross-session handles return
CE_HANDLE_EXPIRED. - Closing a process invalidates its scan handles.
- Handle IDs are opaque and are not derived from target addresses.
- A handle from one MCP connection is not accepted by another unless the protocol explicitly supports that sharing; F0 should not support it.
Error and security tests
- Every tool error uses the structured error object from Errors.
- Token and absolute user paths do not appear in error messages or logs.
- The bridge does not evaluate Lua from unauthenticated clients.
- The bridge does not expose an arbitrary shell, filesystem or network proxy.
- The server does not install the bridge silently.
- The token file is not committed, printed or included in diagnostics.
- A malformed request cannot crash Cheat Engine; if it can, record it as a blocking defect.
Evidence to capture
For every run, record:
- the commit and bridge version;
- the macOS version, architecture and SIP state;
- the Cheat Engine version and binary SHA-256;
- the test target identity and how it was built;
- the exact request and response, with secrets redacted;
- pass, fail or blocked, with the observed error;
- timing for scan start, scan completion and a 1 MiB read;
- whether elevation was required.
Exit criteria
F0 is complete only when:
- all six tools satisfy the table above on macOS arm64;
- every successful result validates against its schema in
spec/contracts/f0.yaml; - the modern and legacy stdio version paths behave as documented;
- the bridge survives malformed input, reconnects and restart;
- the localhost-only and token checks pass;
- the handle lifecycle and error mappings are demonstrated;
- no Cheat Engine binary, copied documentation or target binary is committed;
- the evidence is recorded in the journal and the coverage page is updated.
Pointer scan, stack traces, debugger controls, UI form opening, snapshot restore and trainer generation are outside F0. Their dispositions are in Gap deferrals.
Open questions this plan must answer
- Does
createServerSocket(port, true)accept only loopback on macOS? - What is the real timeout unit for
LuaPipe.Timeout? - Does
openProcess(0)close the process, and is it safe to call twice? - Which arm64 scan value types and alignments match the Lua documentation?
- Does loading from
Lua/Autorundiffer from loading through the Lua Engine? - Does the code signature or hardened runtime restrict either load path?
Journal: 2026-10-21
This is the first design session for ce-mcp. It records the sequence of
investigation and decisions, including dead ends and open questions. It is not a
polished retrospective.
Environment
| Item | Value |
|---|---|
| Host | macOS 26.6.2, Apple M4 Pro, arm64 |
| Target | /Applications/CheatEngine77.app |
| Cheat Engine version | 7.7 |
| Tools used | file, lipo, nm, strings, otool, vtool, codesign, shasum, REA 6.7.0 CLI, GitHub API, MCP specification |
| REA | Formal CLI/Mach-O, plist and signature pass completed; no Ghidra/Hopper |
| Files modified | None during the investigation; this repository was created afterwards |
1. Initial question
The starting request was to build a full clone of Cheat Engine 7.7 in Rust using REA.
The first inspection showed why “full clone” needed a scope discussion:
- the main binary is 83,482,352 bytes;
- it contains 119,479 FPC-mangled symbols in the arm64 slice;
- it exposes 136
Tfrm*classes and 344TPF0form resources; - it documents 585 unique Lua functions;
- it bundles Lua 5.3, TCC, speedhack and two tutorial applications.
A faithful clone would include a memory scanner, pointer scanner, debugger,
disassembler, assembler, Lua runtime, address-list model, .CT format, trainer
generation and 136 forms. That is a multi-year project, not a first milestone.
2. Bundle inventory
The bundle was inspected read-only.
Key facts:
- universal Mach-O:
x86_64andarm64; - main executable minimum macOS 10.15;
liblua53.dylibminimum macOS 13.3;Info.plisthas no minimum key;- code-signed with the hardened-runtime flag;
- no entitlements observed;
liblua53.dylibandlibspeedhack.dylib;libtcc-64.dylib,libtcc-arm64.dylibandlibMonoDataCollectorMac.dylib;libspeedhack.dylibhas no arm64 slice;tutorial-aarch64.appandtutorial-x86_64.app;- 49 language files;
Contents/Lua/celua.txtwith 4,444 lines.
The macOS-specific unit names found in symbols included
macexceptiondebuggerinterface, maccreateremotethread, macjitwriter,
macumm, macPipe, coresymbolication, machotkeys, speedhack2,
lua_server and tcclib.
The binary imports task_for_pid, mach_vm_*, thread_*_state and
AuthorizationCreate, and contains strings for ptrace, already root,
not root yet and the prompt “Have you disabled ‘System Integrity
Protection’(SIP) yet?”. A formal Mach-O import check did not find a _ptrace
symbol; the string alone does not prove a ptrace call.
This established the privilege model: the MCP server cannot avoid macOS permissions; it must work within them.
3. Lua surface
celua.txt documents 585 unique function names and 613 signatures. It covers
memory, scans, the address list, symbols, assembly, structures, debugger, files,
forms, threads and settings.
The first regex count was 586. Review found ModuleLoader(Inheritance: -), a
class heading, in the list. Removing it gives 585 functions; the signature
count remains 613 because of overloads.
This was the turning point. Cheat Engine already exposes most of its capability through Lua. An MCP server could drive that API instead of reimplementing it.
4. Public source
The public repository was checked:
- latest tag
7.5, from 2023; masterlast pushed 2025-04-19;- 529
.pasand 164.lfmfiles; - no root license file;
- TCC has its own license files.
The shipped binary is 7.7 and is not represented by a public tag. The source is useful for architecture and naming, but not authoritative for the 7.7 macOS build.
The project therefore adopted a clean-room, behavior-first approach: use the binary for behavior, link to the public source, do not copy code or prose.
5. MCP research
The current specification is MCP 2026-07-28. The important changes:
- the protocol is stateless; no
initializeand no session header; server/discoveradvertises versions and capabilities;- stdio and Streamable HTTP are the standard transports;
- WebSocket is not standard;
subscriptions/listenreplaces resource subscriptions and the HTTP GET stream;- long-running work uses the tasks extension;
- list results can carry
ttlMs/cacheScope; - multi-round-trip requests replace server-initiated requests.
rmcp 3.6 implements this revision and remains compatible with 2025-11-25.
A later check against the official pages on 2026-10-21 tightened four details:
clientInfo is a SHOULD, Streamable HTTP mirrors metadata into required
headers and rejects mismatches with HeaderMismatch, cacheScope describes
cache sharing rather than profile configuration, and core
subscriptions/listen does not carry process or scan events.
The transport analysis concluded that stdio is the fastest option for a single local agent, while Streamable HTTP on localhost is the right choice for the embedded app and multiple clients. The transport is not the bottleneck; scans and debugger waits are.
6. Decisions
The session converged on:
- MCP-first. The product is the MCP server, not a clone.
- Scope. Current work is the MCP server and its bridge. The native engine and GUI are deferred.
- Bridge first. A Lua bridge gives immediate coverage and exact Cheat Engine semantics.
- Cheat Engine semantics. Writes are allowed after opening a process. The project does not invent a read-only default.
- Profiles.
core,full,luaandall, to keep tool discovery manageable. - Stateless MCP. Explicit handles for process, scan, debugger and table state.
- stdio + localhost HTTP. stdio by default; HTTP for multi-client and embedded mode.
- Docs-only public preview now. Publish the design and migration before the code.
- No license yet. The repository is explicitly marked as a public preview, not open source.
- English documentation. The conversation may be Spanish, but the repository is English for reach.
- Repository name
ce-mcp. Neutral and not implying affiliation.
Earlier ideas that were deferred:
- a full Rust clone;
- an egui desktop GUI;
- a native scanner and debugger;
- a separate
.CTimplementation; - trainer generation.
7. Tool catalog
The curated catalog was designed as 81 tools in 13 groups. The full Lua API is
handled by lua_eval and, optionally, one generated tool per documented
function under the lua profile.
The important design choice: do not expose 585 tools by default. It would
consume context, slow down tool selection and make the common workflow harder.
The all profile exists for clients that explicitly want the full surface.
Known gaps were recorded instead of hidden:
- pointer scan has no direct Lua API in
celua.txt; - structure dissect is form-driven;
- arm64 debugger context support is uncertain;
- trainer generation is Windows/PE-centric;
- DBVM and kernel features are Windows-only.
8. Open questions
These must be answered in F0 or later:
- Does
createServerSocketwork reliably in Cheat Engine 7.7 on macOS 26? - Does the bridge accept loop coexist with
synchronizewithout freezing the GUI? - Which
debug_*functions work on arm64? - Is
openProcess(0)the correct way to close a process? - Can pointer scan be driven without a native implementation?
- What is the exact behavior of
Lua/AutorunandLua/Extensionsin a signed app bundle? - Which MCP clients support
2026-07-28today, and which need the2025-11-25compatibility path? - What license will the implementation use? Answered 2026-10-21: no license for now; code remains paused.
9. Next actions
Publish this documentation as theDone; see section 10.ce-mcppublic preview.Review every external link and factual claim.Done with markdownlint, lychee and mdBook in CI.- Choose the implementation license before F0 code. Blocked: the owner chose to remain unlicensed for now.
- Build the bridge and a six-tool MCP spike. Blocked by the license gate.
- Test against a self-signed target with SIP enabled.
- Record the results in a new journal entry.
10. Publication
The documentation-only preview was published on 2026-10-21:
- Repository: https://github.com/jcmunoz200/ce-mcp
- Documentation: https://jcmunoz200.github.io/ce-mcp/
- CI: markdownlint, lychee link checking and mdBook build passed; GitHub Pages
deployed from the
mainbranch. - License: still not granted. The repository is source-available for viewing, not open source.
- Implementation: still blocked until the license is chosen. No Rust code, Lua
bridge,
Cargo.tomlor binaries were published.
The public surface is 81 curated tools, 585 generated Lua tools, four profiles and a documented gap list. The next technical step is F0, not more design.
11. Formal REA pass and the license gate
After publication, a formal REA 6.7.0 CLI/Mach-O pass was run on the shipped application. It was static and read-only: no target execution, no debugger attach and no Ghidra/Hopper decompilation.
Evidence IDs:
- artifact parent:
ev_c09daa54d23febdd0dc2644a9fb83c76686b78c9754f0f4ed4abe4d8ac9f2a2c - artifact inventory:
ev_9fbd8b477591cec873e8408c746462ca6fc93d2816cf7df7476ffc48ada323c5 - main Mach-O:
ev_f8dcc9d49ffc55bfc936a11f08ae127fe08f1e7142904e07e7047c8b85f165db liblua53.dylib:ev_59b5676589f543d1cfc3dd8ff7e4b256a7ac3ab31ddd422a2955e4b73ea7ca26- signature:
ev_138adc2cec7795d98d869835ae97d988ac45adc1ee7aea126fcf8bcc42b38c3f - plist:
ev_760867c78a69d30853d7b4c747f5748bdae0ea45c9bed07ee25ae27c571f1b0e - dylib resolution:
ev_0d5bb1554db021ad57a9b22401f01ae543fad5e1e6aaf669e57159719ad2ddcd
Findings:
- the artifact graph has 254 nodes, 261 path occurrences and 260 edges;
- the main executable returns 125,814 export records and 511 import records; the provider marks both as non-exhaustive;
- the main executable has 33 load commands, 17 dependencies, five segments and one entry point;
- the main executable declares macOS 10.15, but
liblua53.dylibdeclares 13.3; if the dylib loads, 13.3 is the effective floor; libspeedhack.dylibhasi386andx86_64slices only, whilelibtcc-64.dylib,libtcc-arm64.dylibandlibMonoDataCollectorMac.dylibare universal;- the signature is Developer ID Application: Eric Heijnen (
3W4HR5987G), timestamped 2026-05-29 09:43:47, with hardened runtime enabled and no entitlements returned; celua.txtdocuments a blockingcreateServerSocketand aLuaPipewithreadBytes/writeBytes, supporting the bridge design;- the bundle ships
AIToolsandUEToolsLua extensions, both MIT-licensed, which are not in the 585-function count and are not exposed by default; - a gap review found documented
debugProcess(0),detachIfPossible()anddebug_continueFromBreakpoint(co_stepinto/co_stepover)calls;debug_attach,debug_detachanddebug_stepmoved fromgaptomapped, reducing the curated gaps from 14 to 11.
The pass did not establish runtime behavior. createServerSocket, the Lua
compile arm64 speedhack path and the arm64 debugger context still need F0
tests.
The owner was asked to choose the implementation license and chose to remain unlicensed for now. Therefore:
- no Rust code, Lua bridge,
Cargo.tomlor binaries were created; - code contributions remain paused;
- F0 remains blocked until the license decision changes.
The 11 remaining gaps were then given a formal disposition in
Gap deferrals: one F0 runtime experiment
(process_close), seven native-backend dependencies (six pointer-scan tools and
stacktrace), one form-automation design item (ui_open_tool), one snapshot
design item (snapshot_restore) and one macOS out-of-scope item
(trainer_generate). The document records closure criteria, not implementation
claims. The six-tool F0 acceptance tests and evidence requirements are defined
in the F0 test plan; implementation has not started. The
six tools also have JSON Schema 2020-12 input and output contracts in
spec/contracts/f0.yaml, documented in
F0 tool contracts.
Evidence summary
| Claim | Evidence | Label |
|---|---|---|
| The binary is universal | file, lipo -info | Observation |
| The binary is 83,482,352 bytes | stat | Observation |
SHA-256 is c52dbafc…b916de6 | shasum -a 256 | Observation |
| 119,479 FPC symbols | nm -arch arm64 + filter | Observation |
136 Tfrm* classes | strings + filter | Observation |
344 TPF0 resources | strings + count | Observation |
| 585 unique Lua functions | celua.txt + grep/sort | Observation |
| 125,814 exports and 511 imports | REA inspect-macho; non-exhaustive | Observation |
liblua53.dylib requires macOS 13.3 | REA inspect-macho | Observation |
| Signature is Developer ID, hardened runtime | REA inspect-signature | Observation |
libspeedhack.dylib has no arm64 slice | lipo -info | Observation |
debug_attach, debug_detach and debug_step are mapped | celua.txt: debugProcess, detachIfPossible, debug_continueFromBreakpoint | Observation + design |
| 7.7 is not the latest public tag | GitHub API | Observation |
| Full debugging needs SIP/root | Imports, strings and Cheat Engine behavior | Inference |
| arm64 context support is incomplete | Error strings in the binary | Inference |
| A Lua bridge can cover most tools | API surface and design analysis | Inference |
| Effective minimum macOS is 13.3 | Main 10.15 vs liblua 13.3; no runtime test | Inference |
| The bridge will work on macOS 26 | Not tested | Unknown |
Note on REA
REA 6.7.0 was executed as a static CLI/Mach-O pass. It covered the artifact
graph, main and bundled Mach-O files, Info.plist, code signature and dylib
resolution. It did not include Ghidra/Hopper decompilation or runtime
observation. A later pass can still target:
- the macOS-specific units found in symbols;
- runtime behavior of
createServerSocket,createThreadandsynchronize; - the attach and scan flows on arm64.
The static pass is enough to support the design claims recorded here; runtime claims remain F0 work.
Protocol
Target revision
ce-mcp targets MCP 2026-07-28.
The protocol is stateless. There is no initialize handshake, no
notifications/initialized and no Mcp-Session-Id. Every request carries its
protocol version and client capabilities in _meta; clients should also include
their identity. There is no connection-scoped negotiation.
The planned server uses rmcp 3.6 and can also answer 2025-11-25 clients
through its compatibility path.
This page was checked against the official 2026-07-28 versioning, discovery,
tools, caching, pagination and subscriptions pages on 2026-10-21. See the
references at the end.
Discovery
A client may call server/discover before any other request. The server must
implement it.
Illustrative request:
{
"jsonrpc": "2.0",
"id": "discover-1",
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}
Illustrative response:
{
"jsonrpc": "2.0",
"id": "discover-1",
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28", "2025-11-25"],
"capabilities": {
"tools": {}
},
"_meta": {
"io.modelcontextprotocol/serverInfo": {
"name": "ce-mcp",
"version": "0.0.0-design"
}
},
"instructions": "Local Cheat Engine tools. Open a process before reading or writing memory.",
"ttlMs": 3600000,
"cacheScope": "private"
}
}
The instructions field is the right place for the core workflow:
- call
process_list, thenprocess_open; - read or scan with the returned
process_handle; - close handles when finished.
The exact JSON is illustrative until the F0 implementation is tested against the
official schema. The field names come from the 2026-07-28 specification.
Request metadata
Every request carries:
| Key | Required | Purpose |
|---|---|---|
io.modelcontextprotocol/protocolVersion | Yes | Selected protocol revision |
io.modelcontextprotocol/clientInfo | Optional (SHOULD) | Client name and version |
io.modelcontextprotocol/clientCapabilities | Yes | Extensions and features the client supports |
A request missing a required field is malformed and is rejected with
-32602 (invalid params); on HTTP the status is 400 Bad Request. The server must reject a request whose version it
does not support with UnsupportedProtocolVersionError (-32022) and list the
versions it supports, rather than guessing or silently downgrading. On
Streamable HTTP, the version is mirrored in MCP-Protocol-Version; a mismatch
is an HTTP 400 with HeaderMismatch (-32020), not a tool error. See
Transports.
Tools
Listing
tools/list is paginated and cacheable. The result carries ttlMs and
cacheScope.
ttlMs: 3,600,000 for a stable build; lower during development.cacheScope:privateis the conservative default for this local server.cacheScopedescribes who may share a cached response, not how the profile is configured. Usepubliconly when the deployment guarantees an identical tool set for every caller and the response contains no per-caller data.
The active profile is part of the server configuration, not of each request, so the list is stable for the lifetime of a server process.
Calling
A tool call includes the tool name and arguments. The result is either:
- a normal result;
- an error result with
isError: trueand a structured error object; - a task creation result if the tasks extension is active and the operation is long-running.
Every tool is required to have an inputSchema and an outputSchema in its
final contract. Output schemas are important: they let clients validate results
and generate better summaries. The six F0 tools have concrete schemas in
spec/contracts/f0.yaml; the other 75 still need
them. The conventions are in F0 tool contracts.
Naming
- Curated tools use lowercase
snake_caseanddomain_action:process_open,memory_read,scan_start. - Generated Lua tools use the
lua_prefix plus the original function name, preserving its case:lua_readInteger. This is the documented exception; it keeps generated names aligned one-to-one withcelua.txt. - No tool name contains a version number.
- Names are stable within a major version.
State and handles
MCP is stateless; Cheat Engine is not. State is represented by opaque handles.
| Handle | Created by | Required by |
|---|---|---|
process_handle | process_open | Memory, scan, table, debugger and symbol tools |
scan_handle | scan_start | scan_next, scan_results, scan_cancel |
debug_handle | debug_attach | Breakpoint, stepping, register and stack tools |
table_handle | table_new, table_load | Table tools |
A handle is a string with no client-parseable meaning. It may be a random ID, not an address. The backend stores the mapping and validates that the handle is still alive.
ce_handles lists live handles and supports close. Handles expire after a
configurable TTL (default: 30 minutes of inactivity). Expired handles return
CE_HANDLE_EXPIRED.
Tasks
Long operations may use the tasks extension rather than blocking a request.
- The client opts in with
io.modelcontextprotocol/tasksin its capabilities. - The server advertises the extension in
server/discover. - A task result has
resultType: "task"and ataskId, status, TTL and suggested polling interval. - Clients poll with
tasks/get;tasks/updatesupplies input;tasks/cancelrequests cooperative cancellation.
Planned task-producing tools:
scan_startfor large regions or slow scans;pointer_scan_start;pointermap_generate;memory_dumpfor large ranges;trainer_generate, if implemented.
Short operations return resultType: "complete" directly. The server decides
per request; clients must handle both shapes.
Pagination
Any list that can grow without bound is paginated:
scan_results;table_entries;process_listwhen filtered broadly;region_listandmodule_listfor large targets;lua_api_list;tool_searchresults.
Cursors are opaque and expire. A cursor is tied to the query that produced it;
reusing it with different arguments returns CE_INVALID_CURSOR.
Resources
Resources are optional in the first release. A build that does not implement
them must not advertise a resources capability in server/discover. Planned
read-only resources:
| URI | Content |
|---|---|
ce://status | Bridge status and active profile |
ce://process/{handle} | Process summary |
ce://scan/{handle} | Scan summary and progress |
ce://table/{handle} | Table summary |
Resources are read-only snapshots, not a replacement for tools. They carry
ttlMs and cacheScope like other cacheable results.
Subscriptions
Core subscriptions/listen supports these filters:
toolsListChanged;promptsListChanged;resourcesListChanged;resourceSubscriptionsfor specific resource URIs.
Those filters cover list changes and resource updates, not Cheat Engine
runtime events. Process exit, scan progress, breakpoint hits, debugger state
and table changes are not core subscription filters. F0 uses polling
(ce_status, scan_status, debug_status) and task state for those events. A
future vendor extension may define an application-specific filter, but it must
not be presented as core MCP behavior.
Subscriptions are optional. A client that does not subscribe can poll
scan_status, debug_status or ce_status instead. The server must not require
a subscription for correctness.
Errors
Two layers:
- Protocol errors use JSON-RPC error codes for malformed requests, unknown methods, unsupported versions and invalid params.
- Tool errors use a successful JSON-RPC response with
isError: trueand a structured error object.
A tool error is not a transport failure. The client should read the code and decide whether to retry, fix the arguments or ask the user.
See Errors.
Compatibility
2026-07-28is the primary target.2025-11-25is supported throughrmcp’s compatibility path for clients that still useinitialize.- The server must not silently downgrade a request. It reports the versions it supports and lets the client choose.
- Features that depend on the tasks extension are advertised as an extension, not as core protocol.
Not used
The design does not depend on:
- roots;
- sampling;
- the legacy logging utility;
- server-initiated JSON-RPC requests;
- HTTP GET streams or
resources/subscribe; - session IDs.
Request flow
sequenceDiagram
participant C as MCP client
participant S as ce-mcp
participant B as Lua bridge
participant E as Cheat Engine
C->>S: server/discover
S-->>C: versions, capabilities, instructions
C->>S: tools/list (active profile: core)
S-->>C: tools + ttlMs/cacheScope
C->>S: tools/call process_open {pid}
S->>B: call openProcess(pid)
B->>E: Lua call
E-->>B: result
B-->>S: JSON result
S-->>C: {process_handle}
C->>S: tools/call scan_start {process_handle, ...}
S->>B: newMemScan + firstScan
B->>E: scan
E-->>B: progress/results
B-->>S: task or result
S-->>C: {scan_handle, taskId?}
References
- MCP
2026-07-28 - Versioning and compatibility
- Discovery
- Tools
- Caching
- Pagination
- Subscriptions
- stdio transport
- Streamable HTTP transport
- Transports
- Tasks extension
Transports
Summary
| Transport | Status | Default | Use case |
|---|---|---|---|
| stdio | Standard, implemented by rmcp | Yes | One local agent launches the server |
| Streamable HTTP | Standard, implemented by rmcp | Optional | Multi-client, embedded app, debugging |
| In-process worker | rmcp feature | Optional | Future desktop shell |
| Unix domain socket | Custom | Deferred | Lower overhead than loopback TCP |
| WebSocket | Not standard | No | Not supported |
| HTTP+SSE (legacy) | Deprecated | No | Not supported |
stdio
The client launches ce-mcp as a subprocess and exchanges newline-delimited
JSON-RPC over stdin/stdout.
{
"mcpServers": {
"ce-mcp": {
"command": "ce-mcp",
"args": ["--profile", "core"]
}
}
}
Properties:
- no listening port and no network surface;
- the client controls the process lifecycle;
- logs must go to stderr, never stdout;
- one client per process;
- the fastest practical option for a local agent.
The bridge still uses a localhost TCP socket to reach Cheat Engine. That is a separate connection, not the MCP transport.
Streamable HTTP
The server exposes a single MCP endpoint, for example
http://127.0.0.1:7337/mcp. Each message is an HTTP POST. The response is a JSON
object or a request-scoped SSE stream.
{
"mcpServers": {
"ce-mcp": {
"url": "http://127.0.0.1:7337/mcp"
}
}
}
Properties:
- multiple clients can share one server;
- useful for the embedded desktop mode and for inspecting traffic;
- must bind to
127.0.0.1by default; - requires a token or another local authentication mechanism before it is exposed beyond a single-user desktop;
- supports request-scoped SSE for progress, but the design must not require SSE for correctness;
- no session ID; state is in the backend handles.
Required HTTP headers
Every POST carries the protocol metadata twice: in _meta and in mirrored HTTP
headers. The server must validate that they agree.
| Header | Required for | Rule |
|---|---|---|
MCP-Protocol-Version | Every POST | Must match io.modelcontextprotocol/protocolVersion |
Mcp-Method | Every request | Must match the JSON-RPC method |
Mcp-Name | tools/call, resources/read, prompts/get | Must match params.name or params.uri |
Accept | Every POST | Must list application/json and text/event-stream |
A missing or mismatched header is rejected with HTTP 400 Bad Request and
HeaderMismatch (-32020), not with a tool error. Mcp-Name values that are
not header-safe use the specification’s Base64 sentinel encoding. The F0 tests
must cover a non-ASCII name and verify that the selected SDK emits it correctly.
The server does not rely on notifications/cancelled over Streamable HTTP.
Closing the request-scoped SSE stream is the cancellation signal. Older
sessions, Last-Event-ID resumption and GET streams are not part of this
revision.
Security defaults
- Listen address:
127.0.0.1only. - Port: chosen at startup; written to the state file.
- Token: required for non-stdio transports.
- Origin checks: enabled for browser-originated requests.
- Public bind: requires an explicit
--allow-remoteflag and a documented warning. - No CORS wildcard.
In-process worker
rmcp supports an in-process worker transport. It is a good fit for a future
desktop shell that hosts the server and the UI in one process:
- no serialization over a socket;
- direct Rust calls;
- still uses the same tool registry and backend contract.
This transport is not part of the first release.
Unix domain socket
A Unix domain socket would avoid the loopback TCP stack and could use the stdio framing. It is deferred because MCP clients do not universally support custom transports and because TCP is already local and fast enough.
If added, it must be opt-in and use the same authentication and framing rules.
Why not WebSocket?
WebSocket is not a standard MCP transport in 2026-07-28. Adding it would
require a custom client. Streamable HTTP already provides request-scoped SSE for
streaming and works with standard clients.
Performance
The transport is rarely the bottleneck:
- a memory read is dominated by
task_for_pid/Mach VM access and Lua serialization; - a first scan is dominated by the scan engine;
- a debugger wait is dominated by the target.
stdio avoids HTTP parsing and connection management, so it is the default. On loopback, Streamable HTTP adds roughly a sub-millisecond round trip plus HTTP and SSE framing; that is negligible compared with a scan.
Do not choose HTTP for speed. Choose it for multi-client or embedded use.
Backward compatibility
On stdio, a client that supports both modern and legacy servers should send
server/discover first. If the server answers, the client uses the modern
stateless flow. If it does not, the client may fall back to the initialize
handshake.
ce-mcp will advertise both 2026-07-28 and 2025-11-25 during the
compatibility period. F0 must test both protocol versions over stdio; HTTP
compatibility is part of F1.
References
Tool catalog
This is the human-readable catalog of the 81 curated tools. The
machine-readable source of truth is spec/tools/.
Status: every tool is designed; 70 have an identified backend mapping (
mapped) and 11 have no reliable mapping yet (gap). None is implemented. See Coverage.
The server also exposes tool_search as a built-in discovery tool in every
profile. It is not counted in the 81.
The six tools in the F0 spike have machine-readable input and output schemas in
spec/contracts/f0.yaml, explained in
F0 tool contracts. The other tools are catalogued but do not
have contracts yet.
Meta (4)
| Tool | Summary |
|---|---|
ce_info | Server, build, Cheat Engine version and platform information |
ce_status | Bridge state, active profile, open handles and capability summary |
ce_capabilities | Machine-readable feature and coverage matrix |
ce_handles | List, inspect and close backend handles |
Process (7)
| Tool | Summary |
|---|---|
process_list | List processes by PID and name, with an optional filter |
process_open | Open a process by PID or name; returns a process_handle |
process_close | Close a process handle and release its resources |
process_info | PID, name, path, architecture, start time and handle state |
module_list | List loaded modules with base, size and path |
region_list | List memory regions with protection, state and type |
thread_list | List thread IDs for the open process |
Memory (10)
| Tool | Summary |
|---|---|
memory_read | Read a byte range; returns hex or base64 |
memory_write | Write a byte range |
memory_read_value | Read a typed scalar (byte, int, float, double, pointer) |
memory_write_value | Write a typed scalar |
memory_read_string | Read an ASCII, UTF-8 or UTF-16 string |
memory_alloc | Allocate memory in the target process |
memory_free | Free a previous allocation |
memory_protect | Change page protection for a range |
memory_fill | Fill a range with a byte pattern |
memory_dump | Dump a range to a file or return it in chunks |
Scan (8)
| Tool | Summary |
|---|---|
scan_start | First scan: exact, unknown, bigger/smaller, range, string, AOB |
scan_next | Refine results: exact, changed, unchanged, increased, decreased |
scan_cancel | Cancel a running scan or task |
scan_status | Progress, result count and state |
scan_results | Paginated addresses and current values |
scan_refresh | Refresh the values of the current results |
scan_save | Persist a scan session to the server workspace |
scan_load | Restore a scan session |
AOB and symbols (5)
| Tool | Summary |
|---|---|
aob_scan | Array-of-bytes scan with wildcards |
symbol_resolve | Resolve a symbol or CE address expression to an address |
symbol_lookup | Map an address to a module and offset or symbol |
symbol_list | List registered and user-defined symbols |
address_parse | Parse module+offset, pointer and symbol expressions |
Table (10)
| Tool | Summary |
|---|---|
table_new | Create an empty table context |
table_load | Load a .CT or .CETRAINER file into a table context |
table_save | Save a table context to .CT |
table_entries | Paginated address-list entries |
table_add | Add a memory record with address, type and description |
table_update | Update an entry’s description, address, type or script |
table_delete | Delete an entry |
table_freeze | Freeze or unfreeze an entry |
table_set_value | Set an entry’s value |
table_run_script | Activate an entry’s Auto Assembler script |
Pointer scan (6)
| Tool | Summary |
|---|---|
pointer_scan_start | Start a pointer scan; returns a task ID |
pointer_scan_status | Progress, result count and state |
pointer_scan_results | Paginated pointer paths |
pointer_scan_rescan | Rescan with a new target address |
pointer_scan_cancel | Cancel a pointer scan |
pointermap_generate | Generate a pointer map for later scans |
Gap:
celua.txtdoes not expose a direct pointer-scan API. These tools are designed but need a native backend or controlled form automation.
Disassembly and assembly (4)
| Tool | Summary |
|---|---|
disassemble | Disassemble instructions at an address |
assemble | Assemble one or more instructions at an address |
auto_assemble | Run an Auto Assembler script |
code_cave_find | Find code caves in modules and regions |
Debugger (12)
| Tool | Summary |
|---|---|
debug_attach | Attach the debugger; returns a debug_handle |
debug_detach | Detach and release breakpoints |
debug_status | Debugger state, current thread and stop reason |
breakpoint_set | Set a software, hardware or memory breakpoint |
breakpoint_remove | Remove a breakpoint |
breakpoint_list | List breakpoints and hit counts |
debug_continue | Continue execution |
debug_step | Step into, over or out |
registers_get | Read registers for the current thread |
registers_set | Write registers for the current thread |
stacktrace | Return a stack trace with module offsets |
debug_wait | Wait for a breakpoint or debug event with a timeout |
Structures (4)
| Tool | Summary |
|---|---|
structure_new | Create a structure definition |
structure_define | Add fields with offsets, types and names |
structure_read | Read a structure at an address |
structure_list | List definitions in the current table |
Lua (3)
| Tool | Summary |
|---|---|
lua_eval | Evaluate Lua in Cheat Engine; returns a JSON-safe value |
lua_call | Call a documented Lua function by name with typed arguments |
lua_api_list | List documented functions and their migration status |
UI and application (5)
| Tool | Summary |
|---|---|
ui_state | Main-window state and open tools |
ui_open_tool | Open a named Cheat Engine tool or form |
hotkey_list | List registered hotkeys |
hotkey_set | Register or update a hotkey |
speedhack_set | Enable, disable and configure speedhack |
speedhack_set is mapped through speedhack_setSpeed, but the macOS arm64
Lua compile hook path is unverified; the bundled libspeedhack.dylib has no
arm64 slice.
Misc (3)
| Tool | Summary |
|---|---|
trainer_generate | Generate a trainer; Windows/PE-centric, out of scope for macOS |
snapshot_create | Capture a server-side snapshot of a table and selected regions |
snapshot_restore | Restore a snapshot |
Profiles
| Profile | Tools | Contents |
|---|---|---|
core | 32 | The common process → memory → scan → table → Lua loop |
full | 81 | All curated tools |
lua | 589 | 4 meta tools + 585 generated Lua tools |
all | 666 | 81 curated + 585 generated |
See Profiles for the exact core list.
Generated Lua tools
The lua profile exposes one tool per documented Lua function:
lua_readInteger
lua_writeInteger
lua_getAddressList
lua_createServerSocket
Generated tools:
- use the original function name after the
lua_prefix; - accept positional arguments in the documented order;
- return the function’s return values as JSON;
- are marked
generated: truein their metadata; - are not a substitute for curated tools: they have no domain validation, pagination or risk-specific error messages.
The names and status live in spec/lua-api.yaml.
Descriptions are not copied from Cheat Engine; the official document is linked
from the Lua API reference.
What is not in the catalog
- One tool per Cheat Engine dialog.
- DBVM and kernel-mode operations.
- Windows-only trainer internals on macOS.
- Anti-cheat bypass or stealth features.
- A GUI clone.
See Tool migration for the mapping method and Gap deferrals for the remaining 11 tool-level gaps and their closure criteria.
F0 tool contracts
Purpose
The F0 spike exposes six tools:
ce_infoprocess_listprocess_openmemory_readscan_startscan_results
Their machine-readable contracts are in
spec/contracts/f0.yaml. This page explains the
conventions and the parts that are easy to implement inconsistently.
The contracts are designs, not implementation claims. The server generator will
turn them into the tools/list entries: name, description, inputSchema,
outputSchema and annotations. Until F0 passes, no tool is implemented or
tested.
Contract conventions
| Topic | Rule |
|---|---|
| JSON Schema | 2020-12; every object rejects undeclared properties |
| Output | structuredContent must match outputSchema; content is a human-readable fallback |
| Addresses | Lowercase hex strings with 0x, for example 0x100000000 |
| Handles | Opaque strings such as ph_... and sh_...; never parse them |
| PIDs and sizes | JSON integers; sizes and limits reject negative or zero values |
| Memory values | Strings, so an int64 cannot lose precision in JSON |
| Scan values | Decimal strings for numeric types; raw text for string scans |
| Process filters | process_list.filter is a case-insensitive substring match |
| Process names | process_open.name is an exact, case-sensitive match |
| Bytes | Lowercase hex without separators, or standard base64 |
| Pagination | next_cursor is opaque and tied to the query that produced it |
| Errors | isError: true with a structured error object; see Errors |
process_open accepts exactly one of pid or name; the schema uses oneOf to
reject both or neither. name is an exact process name. A name with multiple
matches is an error, not an arbitrary choice.
scan_start supports two comparisons in F0: exact and unknown. The other
Cheat Engine comparisons are deliberately absent until they are tested, because
they imply different value and previous_value semantics. Adding enum values
later is backward-compatible; guessing now is not.
scan_start may return state: "running" with a task_id when the tasks
extension is active. scan_results then reports progress without inventing
partial rows. A short scan may return state: "completed" directly.
Tool summary
| Tool | Input | Output | Read-only |
|---|---|---|---|
ce_info | No arguments | Server, Cheat Engine, bridge, Lua and host versions | Yes |
process_list | filter, limit, cursor | processes, next_cursor | Yes |
process_open | Exactly one of pid, name | process_handle, PID, name, architecture | No |
memory_read | process_handle, address, size, encoding | address, size, encoding, data | Yes |
scan_start | Process handle, value type, comparison, optional value and range | scan_handle, state, count, optional task | No |
scan_results | scan_handle, cursor, limit, include_values | State, value type, rows, cursor, total | Yes |
The annotations in the contract mark only the read-only operations as
readOnlyHint: true. process_open and scan_start change server and target
state, so they are not read-only even though they do not write target memory.
Limits and failure behavior
| Tool | Limit or rule |
|---|---|
process_list | 1–1000 rows per page; an unchanged process list keeps a cursor stable |
process_open | One process at a time, matching Cheat Engine’s opened-process model |
memory_read | 1 byte–1 MiB per call; no silent truncation |
scan_start | 1–1,000,000 retained results; range and alignment are optional |
scan_results | 1–1000 rows per page; include_values: false returns null values |
| Cursors | Invalid or expired cursors return CE_INVALID_CURSOR |
| Handles | Unknown or expired handles return CE_HANDLE_EXPIRED |
| Busy scans | scan_results returns CE_SCAN_BUSY rather than partial garbage |
A read at an unmapped address returns CE_INVALID_ADDRESS. A target that exits
returns CE_PROCESS_CLOSED, and its process and scan handles are invalidated.
The bridge may return CE_TIMEOUT if the operation exceeds its deadline; the
caller must poll the handle or task before retrying.
Why these choices
Addresses and values are strings. JSON numbers cannot represent every 64-bit address or integer exactly, and a single schema that sometimes returns a number and sometimes a string is harder for an agent to use. Strings are stable across languages and transports.
Handles are opaque. A handle is not a PID and not an address. Clients must not construct one, cache it across a server restart or send it to another server. This is what keeps the MCP layer stateless while Cheat Engine remains stateful.
memory_read has a strict size cap. Returning an unbounded byte array over
a local bridge invites memory spikes and truncated results. The cap makes the
limit explicit; memory_dump is the tool for large ranges, and it is outside F0.
scan_start does not hide a long scan behind a blocked request. The
contract allows a completed result or a task. The client must handle both
shapes. F0 may implement the simple completed path first, but the schema already
leaves room for the task extension.
Test obligations
The F0 test plan is the acceptance test. The contract adds these obligations:
- Validate every successful result against its
outputSchema. - Validate that undeclared input properties are rejected.
- Exercise
process_openwithpidonly,nameonly, both and neither. - Exercise
scan_startwithexactandunknown; reject other comparisons. - Verify that
memory_readreturns exactlysizebytes and never truncates. - Verify that
next_cursoris rejected when reused with different arguments. - Verify that
include_values: falsedoes not return stale values. - Verify that handles from a restarted server are rejected.
These tests do not exist yet. They are part of the implementation gate, not a claim about the current repository.
Future tools
The remaining 75 curated tools and the generated Lua tools need their own contracts. They must follow the same conventions: opaque handles, string addresses, bounded pages, structured errors and explicit output schemas. Adding a tool must not change an existing tool’s schema within a major version.
Profiles
Why profiles
The complete surface is large:
- 81 curated tools;
- 585 documented Lua functions;
- 4 meta tools that are always useful.
Sending every schema to a model by default would waste context and increase wrong-tool calls. Profiles make the trade-off explicit.
Definitions
| Profile | Count | Contents | Default |
|---|---|---|---|
core | 32 | Process, memory, scan, AOB/symbols, table and Lua essentials | Yes |
full | 81 | Every curated tool | No |
lua | 589 | 4 meta tools + 585 generated Lua tools | No |
all | 666 | 81 curated + 585 generated | No |
tool_search is a built-in discovery tool available in every profile. It is not
counted in these totals.
core (32)
The default workflow is find → filter → edit → save:
| Group | Tools |
|---|---|
| Meta (4) | ce_info, ce_status, ce_capabilities, ce_handles |
| Process (5) | process_list, process_open, process_close, process_info, module_list |
| Memory (5) | memory_read, memory_write, memory_read_value, memory_write_value, memory_read_string |
| Scan (6) | scan_start, scan_next, scan_cancel, scan_status, scan_results, scan_refresh |
| AOB/symbols (3) | aob_scan, symbol_resolve, address_parse |
| Table (7) | table_new, table_load, table_save, table_entries, table_set_value, table_freeze, table_run_script |
| Lua (2) | lua_eval, lua_api_list |
Not in core: region and thread enumeration, allocation, protection and memory
dumping, scan persistence, raw table editing, pointer scan, disassembly,
debugger, structures, UI and misc tools.
full (81)
All curated tools. Use it when the agent needs the debugger, assembler, structures or pointer scan.
The full list is in Tool catalog and
spec/tools/.
lua (589)
The 4 meta tools plus one generated tool per documented Lua function.
Use it when:
- a client needs the complete documented API;
- a script uses a function that has no curated tool;
- you are testing coverage.
Do not use it as the default. The schemas are numerous, generated tools have weaker validation than curated tools, and many functions are platform-specific.
all (666)
The union of full and the generated Lua tools. It is the literal “every tool”
mode. It is intended for compatibility testing and power users who understand
the context cost.
Selecting a profile
Profiles are selected at server start, not per tool call, so tools/list is
stable and cacheable.
Planned CLI:
ce-mcp --profile core
ce-mcp --profile full --transport stdio
ce-mcp --profile all --transport http --bind 127.0.0.1 --port 7337
Planned environment variable:
CE_MCP_PROFILE=full ce-mcp
Planned MCP client configuration:
{
"mcpServers": {
"ce-mcp": {
"command": "ce-mcp",
"args": ["--profile", "core"]
}
}
}
Behavior outside the profile
tools/listreturns only the active profile plustool_search.tool_searchcan find tools outside the profile and describe them.- Calling a tool outside the profile returns
CE_TOOL_NOT_IN_PROFILE. - The error includes the profile that contains the tool and a remediation such
as “restart with
--profile full”. - The server does not add tools dynamically after startup. Stable lists are required for caching and prompt stability.
Context budget
Approximate guidance, not a hard limit:
| Profile | Tool count | When to use |
|---|---|---|
core | 32 | Most agent sessions |
full | 81 | Debugging, assembly, structures, pointer scan |
lua | 589 | Full API compatibility, script migration |
all | 666 | Testing, exhaustive automation, not normal chat |
The cost is not only the schema tokens. A long tool list also makes selection
harder. Start with core and switch only when the workflow requires it.
Coverage and profiles
Coverage is reported per profile:
corecoverage: the 32 tools and their backend mappings;fullcoverage: the 81 curated tools;luacoverage: the 585 generated functions;allcoverage: the union, with duplicates identified.
A function can be covered by a curated tool and also generated as a Lua tool. This is intentional: the curated tool has a stable, validated contract; the generated tool is the raw API.
References
Errors
Two layers
MCP distinguishes protocol errors from tool execution errors.
Protocol errors
Use JSON-RPC error responses for:
- malformed JSON;
- unknown methods;
- unsupported protocol versions;
- invalid request metadata;
- unknown tools;
- invalid tool arguments that fail schema validation.
These are transport-level failures. The client should not retry without changing the request.
Tool errors
Use a successful JSON-RPC response with isError: true and a structured error
object in structuredContent:
{
"isError": true,
"structuredContent": {
"code": "CE_PROCESS_NOT_FOUND",
"message": "No process matches 'game.exe'.",
"remediation": "Call process_list and retry with a PID.",
"retryable": false,
"details": {
"query": "game.exe"
}
}
}
A tool error means the tool ran and the operation failed. The transport is healthy.
Error object
| Field | Type | Required | Meaning |
|---|---|---|---|
code | string | Yes | Stable machine-readable code |
message | string | Yes | Human-readable summary |
remediation | string | Yes | What the caller can do next |
retryable | boolean | Yes | Whether an identical retry may succeed |
details | object | No | Structured context, never secrets |
cause | string | No | Underlying Cheat Engine or OS message |
Rules:
codeis stable across versions; do not parsemessage.remediationis actionable, not generic.retryableis about an identical retry. A retry with different arguments is a new request.detailsmust not contain the bridge token, absolute user paths or raw target memory beyond what the caller requested.causeis sanitized and truncated.
Codes
| Code | Meaning | Retryable | Typical remediation |
|---|---|---|---|
CE_INVALID_ARGUMENT | Arguments are semantically invalid | No | Fix the argument; see details.field |
CE_UNSUPPORTED_PLATFORM | Tool is not available on this OS/arch | No | Use a supported platform or a different tool |
CE_TOOL_NOT_IN_PROFILE | Tool exists but is outside the active profile | No | Restart with the profile named in details.profile |
CE_BACKEND_UNAVAILABLE | Bridge or Cheat Engine is not reachable | Yes | Start Cheat Engine and load the bridge |
CE_BACKEND_BUSY | Bridge is processing another operation | Yes | Wait and retry; use tasks for long work |
CE_ACCESS_DENIED | Token, permissions or OS access denied | No | Check the token file and macOS permissions |
CE_HANDLE_EXPIRED | Handle is unknown, closed or expired | No | Re-open the process or start a new scan |
CE_PROCESS_NOT_FOUND | No process matches the query | No | Call process_list |
CE_PROCESS_CLOSED | The target exited or was detached | No | Re-open the process |
CE_NOT_ATTACHED | No process is open for this handle | No | Call process_open |
CE_INVALID_ADDRESS | Address is unmapped or malformed | No | Validate with region_list or address_parse |
CE_SCAN_NOT_FOUND | Scan handle does not exist | No | Start a new scan |
CE_SCAN_BUSY | A scan is already running for this handle | Yes | Wait, poll scan_status, or cancel |
CE_SCAN_CANCELLED | Scan was cancelled | No | Start a new scan |
CE_DEBUG_NOT_ATTACHED | No debugger session for this handle | No | Call debug_attach |
CE_BREAKPOINT_NOT_FOUND | Breakpoint ID does not exist | No | Call breakpoint_list |
CE_LUA_ERROR | Lua raised an error | No | Fix the script; see cause |
CE_TIMEOUT | Operation exceeded its deadline | Maybe | Check status before retrying; it may still be running |
CE_INVALID_CURSOR | Pagination cursor is invalid or expired | No | Re-run the original list call |
CE_LIMIT_EXCEEDED | Result or size limit exceeded | No | Narrow the range or use pagination |
CE_INTERNAL | Unexpected server error | Maybe | Report with the request ID |
Retry guidance
retryable: truemeans an identical request may succeed later. Use exponential backoff with jitter (for example 100 ms, 250 ms, 500 ms).CE_TIMEOUTis ambiguous. A scan may still be running. Pollscan_statusor the task before retrying.CE_BACKEND_BUSYresolves when the current operation finishes; do not open a second bridge connection to bypass it.- Never retry
CE_ACCESS_DENIED,CE_INVALID_ARGUMENTorCE_TOOL_NOT_IN_PROFILEwithout changing something. - Tasks are the preferred mechanism for operations that can exceed a client timeout.
Mapping from the bridge
| Bridge condition | Code |
|---|---|
| Connection refused | CE_BACKEND_UNAVAILABLE |
| Missing or bad token | CE_ACCESS_DENIED |
Lua pcall failure | CE_LUA_ERROR |
openProcess returned no process | CE_PROCESS_NOT_FOUND |
| Read at unmapped address | CE_INVALID_ADDRESS |
| Scan thread still active | CE_SCAN_BUSY |
| Socket read timeout | CE_TIMEOUT |
| JSON encode failure | CE_INTERNAL |
Progress and cancellation
- Long operations report progress through tasks or
scan_status, not by emitting unstructured log lines. - Cancellation is cooperative.
scan_cancelandtasks/cancelset a flag; the scan checks it between regions. - A cancelled operation returns
CE_SCAN_CANCELLEDand, if requested, the partial results.
Logging
- stdio: logs go to stderr only.
- HTTP: logs go to stderr or a configured file.
- Audit logs are opt-in and separate from error logs.
- Tokens, raw memory and user paths are redacted by default.
References
Security
Scope
ce-mcp is a local development and research tool. It gives an MCP client the
same power a Cheat Engine user has: read and write another process’s memory,
patch code, run Lua and attach a debugger.
That power is the product. The design does not pretend to sandbox it.
Threat model
| Threat | Impact | Control |
|---|---|---|
| Another local process connects to the bridge | Arbitrary memory access and Lua execution | Localhost bind, per-launch token, 0600 state file |
| Bridge exposed on a public interface | Remote code execution in Cheat Engine’s context | Loopback-only default; explicit --allow-remote with warning |
| Malicious bridge script | Full control of Cheat Engine | Bridge is opt-in; users must review scripts |
| Prompt-injected agent writes to the wrong process | Data corruption or crash | Process handle is explicit; process_info before writes; optional audit |
| Agent reads sensitive memory | Data exposure to the model/provider | Local tool only; user controls the target; no telemetry by default |
| Token leaked in logs or errors | Unauthorized bridge access | Redaction; token never included in tool results |
| Dependency compromise | Code execution in the MCP server | Minimal dependencies, lockfile, dependency review |
| Privilege escalation | Access to protected processes | The server never bypasses SIP, code signing or OS permissions |
Bridge security
The bridge is a Lua script running inside Cheat Engine.
- Bind:
127.0.0.1only, usingcreateServerSocket(port, true). - Port: chosen at startup and written to the state file. No fixed port.
- Token: random per launch, at least 128 bits, required on every request before any Lua is evaluated.
- State file:
~/.ce-mcp/bridge.json, mode0600, contains port, token, PID and protocol version. - Authentication: constant-time comparison where feasible; reject and close on mismatch.
- No unauthenticated eval: the
evalandcalloperations require a valid token.pingmay be unauthenticated but returns no sensitive data. - Limits: maximum request size, maximum response size, execution deadline, maximum concurrent connections.
- Shutdown: a
shutdownrequest closes the listener and removes the state file.
The bridge does not use TLS. Loopback traffic does not leave the host, and the token protects against other local users. A future remote mode would require TLS and a different trust model.
Arbitrary Lua
lua_eval, lua_call and the lua profile execute arbitrary code inside Cheat
Engine. This is intentional.
- There is no Lua sandbox.
- A malicious script can read files, open sockets, modify the target and crash Cheat Engine.
- Only run scripts you trust.
- The MCP server does not automatically run scripts from a
.CTfile or from a model response without an explicit tool call.
If a future release adds a sandbox, it will be a separate backend with a
documented reduced API, not a silent change to lua_eval.
Cheat Engine semantics
Once a process is opened, writes are allowed, matching Cheat Engine. See ADR-0005.
This means:
process_openis the consent boundary;- an agent should call
process_infobefore the first write; - the optional
--safemode can rejectwriteandexecutetools, includinglua_eval; it is not a sandbox and does not make an allowed tool safe; - the optional audit log records calls but does not prevent them.
macOS permissions
Cheat Engine uses task_for_pid, Mach VM APIs and, for debugging, Mach
exceptions or ptrace. macOS may require:
- root or a target signed with
get-task-allow; - disabling SIP for some operations;
- approving the app in System Settings → Privacy & Security;
- Developer Tools permissions for the terminal or client.
ce-mcp does not bypass these requirements. If an operation is denied, the tool
returns CE_ACCESS_DENIED and explains the OS-level remediation. It does not
attempt to disable SIP or escalate privileges.
Data handling
- No telemetry, analytics or cloud calls by default.
- Memory reads are returned to the MCP client; the client and model provider may store them.
- The server does not persist memory dumps unless a tool explicitly writes a file.
- Audit logs are opt-in and redact tokens.
- The bridge token is never included in tool results, logs or error causes.
HTTP mode
If Streamable HTTP is enabled:
- bind to
127.0.0.1by default; - require a token;
- validate the
Originheader for browser clients; - do not enable CORS wildcards;
- do not expose the endpoint through a reverse proxy without authentication;
- prefer stdio when a single local client is enough.
The HTTP server is not a multi-tenant service. It is a local control plane.
Supply chain
- The Rust implementation will use a lockfile and minimal dependencies.
rmcpis the only protocol dependency planned for the first release.- The Lua bridge will avoid vendored third-party Lua modules where possible.
- If
json.luais vendored, its MIT license and hash will be recorded in Third-party notices. - CI will run dependency review and secret scanning.
What is out of scope
- Anti-cheat or game-protection bypass.
- Kernel drivers, DBVM and Windows kernel features.
- Hiding Cheat Engine or the MCP server from other processes.
- Protecting a target from its own user.
- Sandboxing untrusted Lua.
Reporting
Report vulnerabilities privately through GitHub Security Advisories. See SECURITY.md. Do not open a public issue for a security problem.
References
Coverage
Honest status
There is no implementation yet.
| Metric | Value |
|---|---|
| Curated tools designed | 81 |
| Curated tools implemented | 0 |
| Curated tools tested | 0 |
| Documented Lua functions | 585 |
| Lua functions mapped to a curated tool | 0 verified |
| Lua functions implemented as generated tools | 0 |
“Designed” means a contract exists in spec/. It does not mean the tool works.
This page must never report design as coverage.
Curated tools
| Group | Designed | Mapped | Gap | Implemented | Tested |
|---|---|---|---|---|---|
| Meta | 4 | 4 | 0 | 0 | 0 |
| Process | 7 | 6 | 1 | 0 | 0 |
| Memory | 10 | 10 | 0 | 0 | 0 |
| Scan | 8 | 8 | 0 | 0 | 0 |
| AOB/symbols | 5 | 5 | 0 | 0 | 0 |
| Table | 10 | 10 | 0 | 0 | 0 |
| Pointer scan | 6 | 0 | 6 | 0 | 0 |
| Disassembly/assembly | 4 | 4 | 0 | 0 | 0 |
| Debugger | 12 | 11 | 1 | 0 | 0 |
| Structures | 4 | 4 | 0 | 0 | 0 |
| Lua | 3 | 3 | 0 | 0 | 0 |
| UI/application | 5 | 4 | 1 | 0 | 0 |
| Misc | 3 | 1 | 2 | 0 | 0 |
| Total | 81 | 70 | 11 | 0 | 0 |
A “mapped” tool has an identified Lua or native strategy. A “gap” has no reliable mapping yet. Gaps are documented, not hidden.
The 11 gaps
| Tool | Why it is a gap |
|---|---|
process_close | No closeProcess in celua.txt; openProcess(0) behavior is unverified |
pointer_scan_start | No direct Lua pointer-scan API |
pointer_scan_status | Depends on pointer scan |
pointer_scan_results | Depends on pointer scan |
pointer_scan_rescan | Depends on pointer scan |
pointer_scan_cancel | Depends on pointer scan |
pointermap_generate | No direct Lua API; pointer-map callbacks exist, but orchestration is form-driven |
stacktrace | Depends on the debugger backend and symbolication |
ui_open_tool | Form automation is possible but fragile; not designed yet |
snapshot_restore | Restoring memory and table state needs a conflict and safety model |
trainer_generate | Windows/PE-centric; out of scope for macOS |
The disposition and closure criterion for each gap is recorded in Gap deferrals. A gap is not an implementation promise.
Lua API
| Family | Functions | Status on macOS | Notes |
|---|---|---|---|
dbvm_* | 39 | Unsupported on macOS | Windows/DBVM kernel features |
dbk_* | 19 | Unsupported on macOS | Windows kernel features |
debug_* | 22 | Unverified | Some functions are Windows-only; arm64 support is uncertain |
| Other | 505 | Unmapped | Cross-platform or unknown; mapping not started |
| Total | 585 |
The exact names and statuses are in spec/lua-api.yaml.
celua.txt has 585 unique names and 613 signatures because some functions are
overloaded. An initial count of 586 included ModuleLoader(Inheritance: -), a
class heading rather than a function.
The lua profile will generate one tool per documented function. Generated
tools are designed, not implemented. The all profile is the union of the
curated catalog and the generated tools.
Bundled Lua code outside the count
Cheat Engine ships Lua code that is not part of celua.txt:
Contents/Lua/Autorun/: speedhack, Mono/.NET, Java, pseudocode and symbol scripts loaded at startup;Contents/Lua/Extensions/AITools/: an MIT-licensed AI assistant extension;Contents/Lua/Extensions/UETools/: MIT-licensed Unreal Engine inspection tools.
These scripts are not in the 585-function count, are not generated as tools and are not exposed by default. They are shipped application assets, not copied into this repository. Adopting one later would require an explicit tool contract and a license review.
Platform coverage
| Platform | Curated design | Bridge | Native gaps |
|---|---|---|---|
| macOS arm64 | Yes | Planned; first target | Pointer scan, arm64 debugger context, interactive structure dissect, arm64 speedhack path unverified |
| macOS x86_64 | Yes | Planned | Same, plus x86-specific debugger behavior |
| Windows | Yes | Future | DBVM/kernel features excluded |
| Linux | Yes | Future | Bridge needs validation |
No platform is implemented yet.
How coverage will be measured
- Extract function names from
celua.txt. - Compare with
spec/lua-api.yaml. - Fail on missing, duplicate or status-less names.
- Compare
spec/tools/*.yamlwith generated server registration. - Fail on a documented tool that is not registered, or a registered tool that is not documented.
- Run contract tests against a real Cheat Engine 7.7 instance.
- Publish the result here.
A function is only “covered” when:
- a curated tool implements it and has a contract test, or
- a generated tool is registered and tested, or
- it is explicitly excluded with a platform reason.
How to update this page
- Do not edit the counts by hand once the coverage generator exists.
- Until then, update the table when a tool moves from
gaptomapped,implementedortested. - Keep the gaps list current.
- Add a journal entry when a gap is closed or a new one is found.
Related
Cheat Engine Lua API
What it is
Cheat Engine ships a Lua 5.3 runtime and documents its application-specific API
in Contents/Lua/celua.txt.
Observed in the Cheat Engine 7.7 macOS bundle:
| Metric | Value |
|---|---|
| File | /Applications/CheatEngine77.app/Contents/Lua/celua.txt |
| Lines | 4,444 |
| Size | ~240 KB |
| Unique function names | 585 |
| Signatures | 613 |
The difference between names and signatures is overloading. For example,
openProcess accepts a PID or a process name, and loadTable accepts a filename
or a stream.
An initial count of 586 included ModuleLoader(Inheritance: -), a class heading
rather than a function. The corrected function count is 585.
The same document is published in the public source tree: https://github.com/cheat-engine/cheat-engine/blob/master/Cheat%20Engine/bin/celua.txt
How this project uses it
The API is the compatibility target for the Lua bridge.
- Function names are recorded in
spec/lua-api.yaml. - Descriptions are not copied. The official document is the reference.
- Each name has a migration status:
unmapped,curated,generated,excludedorunsupported-on-macos. - The
luaprofile generates one MCP tool per name. - Curated tools map to one or more functions.
This is an interoperability list, not a redistribution of Cheat Engine’s documentation.
Main families
The following is a map of the API, not a full reference. Use celua.txt for
signatures and semantics.
Process and modules
| Function | Purpose |
|---|---|
getProcesslist() | List processes |
openProcess(pid) / openProcess(name) | Open a process |
getOpenedProcessID() | Current PID |
getProcessIDFromProcessName(name) | Resolve a name to a PID |
enumModules() | Enumerate modules |
getThreadlist() | List thread IDs |
There is no documented closeProcess. closeCE() closes Cheat Engine, not the
target. The correct detach behavior is an open question.
Memory
| Function | Purpose |
|---|---|
readBytes(address, count) | Read bytes |
writeBytes(address, bytes) | Write bytes |
readInteger / writeInteger | 32-bit integer |
readQword / writeQword | 64-bit integer |
readFloat / writeFloat | 32-bit float |
readDouble / writeDouble | 64-bit float |
readString / writeString | String |
readPointer / writePointer | Pointer-sized value |
allocateMemory(size, protection) | Allocate in the target |
deAlloc(address) | Free an allocation |
setMemoryProtection(address, size, rights) | Change protection |
enumMemoryRegions() | Enumerate regions |
Scans
| Function | Purpose |
|---|---|
createMemScan(progressbar) | Create a scan object |
memscan:firstScan(...) | First scan |
memscan:nextScan(...) | Next scan |
memscan:waitTillDone() | Wait for completion |
memscan:getResultCount() | Result count |
memscan:getResults(...) | Read results |
The scan object exposes the usual Cheat Engine scan options: value type, rounding, start/end address, protection flags, alignment, hexadecimal input, Unicode and case sensitivity.
Address list and tables
| Function | Purpose |
|---|---|
getAddressList() | Address-list object |
addresslist.createMemoryRecord() | Create a record |
loadTable(filename, merge) | Load .CT / .CETRAINER |
saveTable(filename, protect) | Save a table |
registerSymbol(name, address) | Register a symbol |
getNameFromAddress(address) | Address to symbol/module offset |
The address-list object exposes record properties, freeze state, hotkeys and script activation.
Assembly
| Function | Purpose |
|---|---|
assemble(line, address) | Assemble one instruction |
disassemble(address) | Disassemble one instruction |
getInstructionSize(address) | Instruction length |
autoAssemble(script) | Run an Auto Assembler script |
autoAssembleCheck(script) | Syntax check |
AOBScan(pattern) | Array-of-bytes scan |
Debugger
| Function | Purpose |
|---|---|
debugProcess(interface) | Start the debugger for the open process (attach) |
detachIfPossible() | Detach the debugger |
debug_isDebugging() | Debugger active |
debug_getCurrentDebuggerInterface() | Windows, VEH, kernel, macOS native, gdb |
debug_setBreakpoint(address, ...) | Set a breakpoint |
debug_removeBreakpoint(address) | Remove a breakpoint |
debug_continueFromBreakpoint(method) | Continue, step into or step over |
debug_getContext(extraregs) | Read registers |
debug_setContext(extraregs) | Write registers |
debug_getCurrentContextTable(extraregs) | Context as a table |
The macOS native interface is value 4 in
debug_getCurrentDebuggerInterface(). arm64 context support is not verified.
Structures
| Function | Purpose |
|---|---|
getStructureCount() | Number of global structures |
getStructure(index) / getStructure(name) | Get a structure |
registerStructureDissectOverride(...) | Custom dissect behavior |
getStructureElementsFromName(name) | PDB elements |
Lua, threads and utilities
| Function | Purpose |
|---|---|
createThread(function) | Create a Lua thread |
createThreadNewState(script) | Thread with a separate Lua state |
synchronize(function) | Run on the main thread |
queue(function) | Queue on the main thread |
checkSynchronize(timeout) | Process the queue |
createServerSocket(port, localhostOnly) | Open a TCP listener |
acceptConnection() | Accept a connection |
getMainForm() / getMemoryViewForm() | Form objects |
getLuaEngine() | Lua engine form |
The bridge depends on createServerSocket, acceptConnection, createThread
and synchronize. acceptConnection blocks its calling thread; the bridge must
run it in a Lua thread. LuaPipe provides readBytes, writeBytes, Timeout,
OnTimeout and OnError for the framed JSON payload.
Platform notes
celua.txt is cross-platform, but not every function works everywhere.
dbvm_*anddbk_*target Windows kernel/DBVM features. They are excluded from the macOS bridge.debug_*includes Windows-specific behavior. The macOS native interface is4; arm64 context support is uncertain.trainer_generate-style workflows are Windows/PE-centric and are out of scope for the first macOS release.- File dialogs and form automation may behave differently on macOS.
The migration status per function is in spec/lua-api.yaml, not in this page.
Related
Glossary
Cheat Engine terms
- Address list
- The table of memory records in Cheat Engine. Each record has an address, a value type, a description, an optional script and a freeze state.
- AOB (array of bytes)
- A byte pattern, often with wildcards, used to find code or data that moves between runs.
- Auto Assembler (AA)
- Cheat Engine’s script language for allocating memory, injecting code, registering symbols and enabling/disabling patches.
- Cheat table (
.CT) - A Cheat Engine table file containing address-list records, scripts, symbols and forms.
.CETRAINER- A protected table format used for trainers. Support is Windows-centric and is not a first-release goal.
- Code cave
- Unused space in a module or memory region where injected code can be placed.
- DBVM
- Cheat Engine’s hypervisor-based kernel access layer on Windows. Out of scope for macOS.
- Freeze
- Continuously write a value to keep it from changing.
- Hotkey
- A key combination that triggers a table entry or action.
- MemScan
- The Cheat Engine scan object returned by
createMemScan. It holds the scan type, value type, range and results. - Memory record
- An entry in the address list. It can point to an address, a pointer path or a script.
- Pointer map
- A snapshot of pointers in a process, used to accelerate pointer scans.
- Pointer scan
- A search for a chain of pointers that reaches a target address. Cheat Engine’s implementation is form-driven; the Lua API does not expose a direct scan call.
- Speedhack
- A Cheat Engine feature that changes the perceived speed of a target.
- Structure dissect
- A Cheat Engine view that interprets a memory region as a structure with typed fields.
- Symbol
- A name mapped to an address, such as
game.exe+0x1234or a user-defined symbol. - TCC
- Tiny C Compiler. Cheat Engine bundles it for compiled scripts.
- VEH
- Vectored Exception Handling, a Windows debugger mechanism. Out of scope for macOS.
MCP terms
- Capability
- A feature a client or server supports, advertised during discovery.
- Cursor
- An opaque token for pagination.
- Handle
- An opaque server-side reference to state, such as a process or scan. Handles are used because MCP is stateless.
- MCP
- Model Context Protocol, a JSON-RPC protocol for exposing tools, resources and prompts to AI clients.
server/discover- The
2026-07-28method that returns supported protocol versions, capabilities and server identity. - SSE
- Server-Sent Events. In Streamable HTTP, a request-scoped stream for progress and multi-message responses.
- Stateless
- No session or initialization handshake. Every request carries its own metadata.
- stdio
- Newline-delimited JSON-RPC over a client-launched subprocess’s standard streams.
- Streamable HTTP
- The standard HTTP transport where each message is a POST and the response is JSON or a request-scoped SSE stream.
- Task
- An extension for long-running work. The server returns a task ID; the client
polls
tasks/getand can cancel withtasks/cancel. ttlMs/cacheScope- Cache hints on list and resource results.
ttlMsis a freshness duration;cacheScopeispublicorprivate.
Project terms
- Backend
- The component that executes operations. The first backend is the Lua bridge; a native Rust backend may follow.
- Bridge
ce_bridge.lua, the script loaded into Cheat Engine that exposes a local socket and evaluates requests.- Curated tool
- A typed, documented MCP tool with a stable contract, as opposed to a generated Lua tool.
- Generated tool
- An MCP tool created automatically from a documented Lua function, available
under the
luaprofile. - Profile
- A named set of tools:
core,full,luaorall. - REA
- Reverse Engineering Agent, the tool-assisted analysis workflow used to inspect the Cheat Engine binary. The initial inventory was shell-based; a formal REA pass is pending.
- Safe mode
- An optional mode that rejects write and execute tools. It is not a sandbox and is not the default.
Related
ADR-0001: Adopt an MCP-first architecture
- Status: Accepted
- Date: 2026-10-21
- Supersedes: the full-clone plan
- Superseded by: none
Context
The original goal was a complete Rust clone of Cheat Engine 7.7, including its GUI, scanner, debugger, assembler, Lua runtime and trainer generation.
The target inventory showed the size of that plan:
- an 83,482,352-byte main binary;
- 119,479 FPC-mangled symbols in the arm64 slice;
- 136
Tfrm*classes and 344TPF0resources; - 585 unique documented Lua functions;
- a bundled Lua 5.3 runtime, TCC, speedhack and two tutorial applications.
A faithful clone would take years before it delivered a usable interface. In parallel, Cheat Engine already exposes most of its capability through Lua. The missing piece is a standard interface for agents, not another engine.
Decision
The product is an MCP server, ce-mcp.
- The MCP contract is the stable surface.
- The first backend is a Lua bridge into Cheat Engine 7.7.
- A native Rust backend may replace the bridge later behind the same contract.
- The desktop GUI, full native engine and trainer generation are deferred.
Consequences
Positive
- The MCP design can be validated against a real application quickly.
- Cheat Engine semantics are preserved by construction.
- The documented Lua API provides broad initial coverage.
- The project has a clear, reviewable scope.
- Native work can proceed incrementally without breaking clients.
Negative
- The first backend requires a Cheat Engine installation.
- macOS permissions and SIP constraints still apply.
- Some features have no reliable Lua API and remain gaps.
- The project depends on Cheat Engine’s Lua behavior, including its bugs.
Neutral
- A future native backend is still possible; it is no longer a prerequisite.
- The repository name
ce-mcpreflects the narrowed scope.
Alternatives considered
- Full Rust clone first. Rejected: too large, delays validation, and duplicates a working tool.
- Library-only Rust wrapper. Rejected: does not give agents a standard discovery and invocation surface.
- MCP server that automates the GUI. Rejected: fragile, inaccessible and hard to test.
- MCP server with a native engine from day one. Rejected for the current phase: the contract would be designed against an incomplete engine.
References
ADR-0002: Use stateless MCP with explicit handles
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
MCP 2026-07-28 removes the initialization handshake and sessions. Every
request is self-describing: protocol version, client capabilities and client
information travel in _meta. There is no Mcp-Session-Id and no per-connection
server state.
Cheat Engine is stateful. It has an open process, a current scan, an address list, a debugger session, symbols, hotkeys and global settings. Pretending otherwise would make the tools unreliable, especially with multiple clients.
Decision
The MCP layer is stateless. The backend owns state and exposes it through opaque handles.
| Handle | Created by | State |
|---|---|---|
process_handle | process_open | Open process, including start time to detect PID reuse |
scan_handle | scan_start | Scan type, parameters, results and progress |
debug_handle | debug_attach | Debugger session and breakpoints |
table_handle | table_new / table_load | Address-list/table context |
Rules:
- Handles are opaque strings. Clients must not parse them.
- Every handle has a TTL and a creation timestamp.
ce_handleslists live handles and their state.- Tools that need state require the corresponding handle explicitly.
- Closing a handle releases backend resources. Process exit invalidates the
handle and returns
CE_PROCESS_CLOSED. - The server may keep a default handle for convenience, but it must be visible
in
ce_statusand must not be required. - Long operations return a task ID in addition to the handle.
Consequences
Positive
- Compatible with the stateless MCP revision.
- Multiple clients can share one bridge without invisible session state.
- State is observable and can be cleaned up.
- A server restart does not silently reuse a stale process.
Negative
- Clients must pass handles and manage their lifetime.
- A careless client can leak handles until the TTL expires.
- The backend needs a handle registry, TTL sweeper and invalidation logic.
- Tool signatures are slightly more verbose.
Neutral
- Handles are not security boundaries. The token and localhost binding are.
- The default handle is a convenience, not a protocol feature.
Alternatives considered
- Per-connection sessions. Rejected: MCP
2026-07-28has no session concept, and a stateless HTTP request has no stable connection identity. - PID as the process handle. Rejected: PIDs are reused; a stale PID can point to a different process.
- Singleton process state. Rejected: hides state, breaks multi-client use and makes tests order-dependent.
- Return full state on every call. Rejected: expensive and still does not solve concurrent mutation.
References
ADR-0003: Use stdio by default and Streamable HTTP on localhost
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
MCP 2026-07-28 defines two standard transports:
- stdio, where the client launches the server as a subprocess and exchanges newline-delimited JSON-RPC over stdin/stdout;
- Streamable HTTP, where each message is an HTTP POST to one endpoint and the response is either a JSON object or a request-scoped SSE stream.
The old HTTP+SSE transport is deprecated. WebSocket is not a standard MCP transport. The specification allows custom transports and recommends reusing the stdio framing for reliable bidirectional streams such as Unix domain sockets.
The project has two likely deployment modes:
- a single local agent that launches the server;
- an embedded or desktop mode where several clients share one server.
Decision
- stdio is the default. It has the lowest overhead, no network surface and the simplest lifecycle.
- Streamable HTTP is optional and bound to localhost. It exists for multi-client and embedded use.
- No public bind by default. Binding to a non-loopback address requires an explicit flag and a token.
- No WebSocket or custom external transport. A Unix domain socket may be added later using the stdio framing, but it is not part of the initial contract.
- The in-process worker transport may be used by the future desktop shell; it does not change the wire contract.
Consequences
Positive
- The common case has no HTTP server, port or CORS surface.
- stdio is the fastest practical local path and works with most MCP clients.
- HTTP covers multi-client use without inventing a transport.
- The same tool registry and backend serve both transports.
Negative
- Two transport code paths must be tested.
- HTTP mode needs authentication, origin checks and lifecycle management.
- stdio mode logs to stderr and must never write protocol data there.
- Some clients only support one transport, so documentation must be explicit.
Neutral
- Transport choice does not affect tool schemas.
- The transport is not the performance bottleneck; scans and debugger waits dominate.
Alternatives considered
- HTTP only. Rejected: unnecessary network surface and overhead for the common single-agent case.
- stdio only. Rejected: does not support the embedded multi-client mode.
- WebSocket. Rejected: not a standard MCP transport in this revision.
- gRPC or a custom binary protocol. Rejected: clients would need custom support; MCP already defines the contract.
- Unix domain socket only. Deferred: lower overhead than TCP, but not universally supported by MCP clients.
References
ADR-0004: Expose tools through profiles
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
Cheat Engine documents 585 unique Lua functions. Exposing all of them as individual MCP tools by default would:
- consume a large part of the model’s context with tool schemas;
- slow down tool selection and increase wrong-tool calls;
- make the common workflow harder to discover;
- destabilize prompt caching when the tool list changes.
At the same time, the project’s goal is to expose all tools. Hiding the full API would fail that goal.
Decision
Use four explicit profiles:
| Profile | Contents | Default |
|---|---|---|
core | ~30 curated tools for process, memory, scan, table and Lua | Yes |
full | All ~80 curated tools, including debugger, assembler and structures | No |
lua | One generated tool per documented Lua function (~585) | No |
all | full + lua | No |
Additional rules:
- The server advertises the active profile in
server/discoverandce_capabilities. - The profile is chosen by server configuration, not by a tool call.
tool_searchsearches the full catalog and can describe tools outside the active profile; invoking one outside the profile returnsCE_TOOL_NOT_IN_PROFILE.- Tool names and schemas are stable across profiles; a tool present in
coreis identical infullandall. - Generated Lua tools use a deterministic prefix and are marked as generated in their metadata.
- The
luaprofile is a compatibility surface, not the recommended default.
Consequences
Positive
- The default context stays small and focused.
- Power users can opt into the full curated surface.
- Full Lua compatibility remains available.
- Profiles make coverage and testing measurable.
- Tool lists are deterministic and cacheable.
Negative
- Users must understand profiles and configure the server.
- A tool can be “available” but outside the active profile, which can confuse clients.
- Four profiles multiply the test matrix.
- The generated tools still add a large schema set when enabled.
Neutral
lua_evalis always available incoreandfull, so a user is never completely blocked by a missing curated tool.tool_searchmitigates discoverability without loading every schema.
Alternatives considered
- Expose all 585 tools by default. Rejected: context and selection cost.
- One generic
ce_calltool. Rejected: no typed schemas, poor discoverability and weak validation. - Dynamically add tools after a search. Rejected: tool lists become unstable and incompatible with client-side caching.
- Separate server binaries per profile. Rejected: duplicated deployment and confusing identity.
References
ADR-0005: Preserve Cheat Engine write semantics
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
Many agent tools default to read-only or require per-operation confirmation. Cheat Engine does not. Once a process is opened, Cheat Engine allows reading and writing memory, changing protections, patching code and running scripts. That is the behavior users expect.
The project could add a safety layer, but a different default would:
- break common Cheat Engine workflows;
- make tools behave differently from the application they wrap;
- create a false sense of safety, because
lua_evalcan write anyway; - add friction to every experiment.
Decision
ce-mcp preserves Cheat Engine semantics.
process_openis the consent boundary. After it succeeds, memory writes, protection changes and code patches are allowed.- There is no read-only mode by default.
- Tools declare a risk class (
read,write,execute,debug,ui) for documentation and optional policy. - An opt-in
--safemode may rejectwriteandexecutetools. It is not the default and does not sandbox Lua. - An opt-in audit log records tool calls, arguments and results. It is off by default.
- The project never claims to make Cheat Engine safe. It documents the risks.
Consequences
Positive
- Behavior matches Cheat Engine.
- Existing workflows and scripts transfer directly.
- No surprising failures when an agent tries to edit a value.
- The risk model is honest:
lua_evalis arbitrary execution by design.
Negative
- An agent can corrupt a target process.
- A prompt-injected agent could write to the wrong process.
- Users may expect the tool to protect them and be surprised.
- The optional safe mode can create a false sense of security.
Neutral
- The audit log is an observability feature, not a security boundary.
- Risk classes are metadata; clients may use them for their own approvals.
Alternatives considered
- Read-only by default. Rejected: diverges from Cheat Engine, blocks the main use case and is bypassable through Lua.
- Confirm every write. Rejected: there is no reliable GUI confirmation channel in a headless MCP server; it would break automation.
- No write tools at all. Rejected: fails the product goal.
- Sandbox Lua. Rejected: Cheat Engine’s API is the product; a sandbox would break compatibility and still leave memory writes.
References
ADR-0006: Use a Lua bridge as the first backend
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
The MCP server needs a backend. The options are:
- a native Rust implementation of memory access, scanning, debugging, assembly and Lua;
- a Lua script running inside Cheat Engine, controlled over a local socket;
- automation of Cheat Engine’s GUI forms;
- a plugin or injected library.
The target already contains Lua 5.3, celua.txt documents 585 functions, and
the API includes createServerSocket, acceptConnection, createThread and
synchronize. The binary also contains a lua_server unit, but its behavior
and protocol are undocumented.
Decision
The first backend is a Lua script, ce_bridge.lua, loaded into Cheat Engine
7.7.
Protocol sketch
ce-mcp -> ce_bridge.lua
connect 127.0.0.1:<port>
send 4-byte big-endian length + UTF-8 JSON
receive 4-byte big-endian length + UTF-8 JSON
Request:
{
"id": 1,
"token": "...",
"op": "call",
"name": "readInteger",
"args": ["0x1234"]
}
Response:
{
"id": 1,
"ok": true,
"result": 42
}
The bridge:
- binds to
127.0.0.1only, usingcreateServerSocket(port, true); - writes
{port, token, pid, version}to~/.ce-mcp/bridge.jsonwith mode0600; - requires the token on every request before evaluating Lua;
- runs the accept loop in a
createThreadthread; - uses
synchronizefor GUI-affecting operations; - supports
ping,eval,call,cancelandshutdown; - encodes byte arrays as hex strings and rejects non-JSON-safe values;
- applies best-effort time and size limits.
The port is chosen by the bridge and written to the state file; the MCP server does not scan a fixed port range. The token is random per launch.
The bridge is opt-in. The MCP server never installs or loads it silently.
Consequences
Positive
- Immediate coverage of the documented Lua API.
- Exact Cheat Engine semantics, including edge cases and bugs.
- The bridge is small enough to review and replace.
- The MCP contract can be validated before native work.
- No binary injection or code-signing changes to Cheat Engine.
Negative
- Cheat Engine must be running and the bridge loaded.
- The bridge runs with Cheat Engine’s privileges.
- Blocking Lua calls and GUI synchronization need careful handling.
- The socket protocol is another surface to secure.
- Performance is limited by Lua and JSON serialization.
- A crash in the bridge can affect Cheat Engine.
Neutral
- A native backend can replace individual tools later.
- The bridge protocol is internal and may change before
v1.0. - The built-in
lua_serveris not used; its protocol is undocumented.
Alternatives considered
- Native backend first. Rejected: delays the MCP contract and duplicates a working engine.
- Use the built-in
lua_server. Rejected: undocumented protocol, unclear security model and no guarantee it is enabled on macOS. - GUI automation. Rejected: fragile, slow and inaccessible.
- Inject a native library into Cheat Engine. Rejected: more invasive, code signing and stability risks, no need for the first backend.
- Named pipes only. Deferred: TCP localhost is portable and supported by the Lua socket API; a pipe transport can be added later.
References
ADR-0007: Publish the documentation without a license
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: a future implementation-license ADR
Context
The project wants a public repository now so the design and migration can be reviewed. The implementation license has not been chosen.
Publishing a repository publicly does not grant rights. Without a license, default copyright applies. Calling such a repository “open source” would be incorrect.
The project could:
- choose a permissive license immediately;
- publish privately until the license is chosen;
- publish publicly with an explicit “no license” notice.
Decision
Publish the documentation as a public design preview with no license granted.
LICENSE.mdstates “All rights reserved” and “No license is granted at this time.”README.mdanddocs/legal/license-status.mdrepeat the status.- The repository is not described as open source.
- Code pull requests are paused.
- The implementation license must be chosen before F0 code is merged.
- A future ADR will supersede this one when the license is selected.
The documentation itself is authored for this project. It does not copy Cheat Engine documentation or third-party prose.
Consequences
Positive
- The design can be reviewed now.
- The license decision is not rushed.
- No accidental grant of rights over future code.
- The project can choose a license that fits its dependencies.
Negative
- The repository is source-available, not open source.
- Others cannot legally reuse the documentation without permission.
- GitHub may show an unclear license status.
- Code contributions are blocked, which slows community involvement.
- Some users will ignore the notice.
Neutral
- The maintainer can relicense their own documentation later.
- A future license change cannot retroactively remove rights already granted, but no rights are granted now.
Alternatives considered
- MIT now. Rejected: premature; the implementation may include components with different licensing constraints.
- CC BY 4.0 for documentation and MIT for code. Reasonable, but still a license decision that should be made with the implementation plan.
- Private repository. Rejected: loses early review and the public record of the migration.
- No LICENSE file at all. Rejected: ambiguous; an explicit notice is clearer.
References
ADR-0008: Publish a documentation-only public preview
- Status: Accepted
- Date: 2026-10-21
- Supersedes: none
- Superseded by: none
Context
The design and migration work is substantial and useful on its own. The implementation is not started, and the license is not chosen.
Publishing a repository with placeholder code, an unbuildable Cargo.toml or a
half-working bridge would:
- attract bug reports for code that is not ready;
- create expectations that cannot be met;
- complicate the license decision;
- mix design review with implementation review.
Publishing nothing until the code is ready would lose the opportunity to get feedback on the architecture and tool contract.
Decision
Publish a documentation-only repository now.
- No
Cargo.toml. - No Rust source.
- No Lua bridge code.
- No binaries, installers or release artifacts.
- The tool catalog lives in
spec/as data, not executable code. - The documentation site is built from
docs/with mdBook. - The repository is labelled “design preview” in the README, the book and the changelog.
Code starts in F0, after the implementation license is selected.
Consequences
Positive
- Early review of the architecture and tool contract.
- A clear, citable record of the migration.
- No unbuildable code or false release signals.
- The license decision stays separate from the design.
- Contributors can discuss the design without a code review bottleneck.
Negative
- The repository cannot yet be used.
- Some visitors expect code and leave.
- Documentation can drift from the eventual implementation.
- There is no test suite proving the design works.
Neutral
- The design is explicitly provisional.
- The journal records uncertainty and open questions.
- A future release will add code and update the README.
Alternatives considered
- Publish a code skeleton. Rejected: adds noise and license ambiguity without validating anything.
- Wait for F0. Rejected: loses early feedback and the public migration record.
- Publish the bridge only. Rejected: still requires a license and creates an unsupported partial product.
- Publish as a blog post. Rejected: a repository is easier to update, review and link.
References
License status
Current status
No license is granted. This repository is a public design preview, not an open-source project.
On 2026-10-21 the owner reviewed the implementation-license options and chose to remain unlicensed for now. This is a deliberate gate, not an oversight.
| Item | Status |
|---|---|
| Implementation | Does not exist yet |
| Documentation | Published for viewing |
| License | Not chosen |
| Code contributions | Paused |
| Open source | No |
| Source-available | Yes, for viewing |
| Warranty | None |
Copyright (c) 2026 ce-mcp contributors. All rights reserved.
What you may do
- View the repository on GitHub or in a clone.
- Read the documentation.
- Open an issue to discuss the design.
- Quote short passages with attribution for review or commentary, as permitted by applicable law.
What you may not do
Without prior written permission:
- copy, modify or create derivative works from the documentation;
- redistribute the documentation or a modified version;
- use the documentation to train a model or build a commercial product;
- sublicense or sell the contents;
- use the project name or trademarks in a way that implies endorsement.
These restrictions apply to the documentation and specifications in this repository. They do not apply to Cheat Engine, which is governed by its own terms.
Why no license yet
The license for the implementation is a separate decision from the decision to publish the design.
The project has not chosen it because:
- the implementation does not exist yet;
- the dependency set is not final;
- it is not clear whether any component will need code derived from a third-party project;
- a license chosen now might not fit the first code release.
Publishing the design without a license is deliberate. It lets people review the work without granting rights the project is not ready to grant.
What “source-available” means here
“Source-available” means the source files can be viewed. It does not mean they meet the Open Source Initiative’s definition of open source. The OSI definition requires, among other things, free redistribution and derived works. Those rights are not granted.
GitHub may show a license badge or a “View license” link. LICENSE.md is the
authoritative statement: no license is granted.
Path to open source
Before the first code pull request is merged:
- Choose the implementation license.
- Add the full license text.
- Update
README.md,LICENSE.md,CONTRIBUTING.mdand package metadata. - Confirm dependency license compatibility.
- Record the decision in an ADR that supersedes ADR-0007.
- Enable code scanning and dependency review.
The documentation may be relicensed separately. A documentation license such as CC BY 4.0 and a code license such as MIT or Apache-2.0 are plausible, but no choice has been made.
Contributions
- Issues and design feedback are welcome.
- Code pull requests are paused.
- By submitting a design proposal, you agree that it may be discussed publicly. Do not submit text you do not have the right to share. Because no license is granted yet, the maintainer will ask before incorporating substantial third-party text.
- Do not submit code or documentation copied from Cheat Engine or another project.
See CONTRIBUTING.md.
Third-party material
This repository does not include Cheat Engine binaries, source code, language files, images or documentation. It links to the official project and records factual API names for interoperability.
Other third-party projects are referenced, not vendored. See Third-party notices.
FAQ
Can I use this in my project?
Not without permission. There is no license.
Can I fork it?
GitHub’s terms allow forking within GitHub, but that does not grant a license to use, modify or distribute the contents. Do not rely on a fork as a legal license.
Will it become open source?
The intent is to choose a license before code is published. The specific license is undecided.
Does this affect Cheat Engine?
No. Cheat Engine has its own terms. This repository does not grant or restrict rights to Cheat Engine.
Is this legal advice?
No. Consult a qualified lawyer for your situation.
Related
Trademark
Unofficial project
ce-mcp is an independent, unofficial project.
It is not affiliated with, endorsed by, sponsored by or otherwise connected to Cheat Engine or its authors.
Use of the name
The name “Cheat Engine” is used only to describe interoperability: the project drives Cheat Engine through its Lua API and targets Cheat Engine 7.7. This is a nominative use of a product name. It does not claim ownership of the mark.
The project name ce-mcp is not a Cheat Engine product name and does not imply
that the project is official.
No Cheat Engine assets
This repository does not include:
- Cheat Engine binaries or installers;
- Cheat Engine source code;
- Cheat Engine language files, tutorials, icons or screenshots;
- Cheat Engine documentation text;
- the Cheat Engine logo or other brand assets.
If any such material is found in the repository, it should be reported and removed. See SECURITY.md for private reporting or open a documentation issue for non-sensitive cases.
Third-party names
Other product and project names are the property of their respective owners. They are used only for identification. See Third-party notices.
No endorsement
References to Cheat Engine, MCP, Rust, macOS or other products do not imply endorsement of this project by their owners.
Reporting a concern
If you believe the project uses a trademark incorrectly, open an issue or contact the maintainer listed in MAINTAINERS.md. The project will review the concern and remove or adjust the use if appropriate.
Related
Third-party notices
This repository references third-party projects. It does not vendor them unless stated otherwise. The table is informational and not legal advice.
| Project | Use | License | Link |
|---|---|---|---|
| Cheat Engine | Target application; not distributed | See upstream | https://cheatengine.org/ |
| Model Context Protocol | Protocol specification | See MCP project | https://modelcontextprotocol.io/ |
rmcp (Rust SDK) | Planned MCP implementation dependency | Apache-2.0, with some MIT-licensed contributions | https://github.com/modelcontextprotocol/rust-sdk |
| mdBook | Documentation site generator | MIT | https://github.com/rust-lang/mdBook |
| markdownlint-cli2 | Documentation linting | MIT | https://github.com/DavidAnson/markdownlint-cli2 |
| lychee | Link checking | MIT or Apache-2.0 | https://github.com/lycheeverse/lychee |
| Contributor Covenant | Code of conduct | CC BY 4.0 | https://www.contributor-covenant.org/ |
rxi/json.lua | Planned Lua JSON helper; not vendored yet | MIT | https://github.com/rxi/json.lua |
| GitHub Actions | CI | GitHub terms | https://github.com/features/actions |
Cheat Engine
Cheat Engine is a separate application with its own license and terms. This repository does not distribute it and does not grant any rights to it.
The project records factual API function names from celua.txt for
interoperability. It does not reproduce the documentation’s descriptions. The
official document is linked from
the Lua API reference.
MCP specification
The MCP specification is maintained by the Model Context Protocol project. The project’s licensing is in transition; see the rust-sdk LICENSE and the MCP specification repository.
rmcp
rmcp is the official Rust SDK for MCP. Its LICENSE describes a transition from
the MIT License to Apache-2.0:
- new code and specification contributions are Apache-2.0;
- documentation contributions are CC BY 4.0;
- some earlier contributions remain MIT.
If ce-mcp depends on rmcp, the final implementation license must be
compatible with these terms. This will be checked before F0.
mdBook
The documentation site is built with mdBook, which is MIT-licensed. The repository contains only configuration and Markdown; it does not vendor mdBook.
markdownlint and lychee
CI uses markdownlint-cli2 and lychee as GitHub Actions. They are not part of the shipped software.
Contributor Covenant
The code of conduct links to and adapts the Contributor Covenant 2.1, which is licensed under CC BY 4.0. Attribution is included in CODE_OF_CONDUCT.md.
json.lua
The bridge may vendor rxi/json.lua for JSON encoding inside Cheat Engine. If
it does, the repository will include:
- the MIT license text;
- the upstream commit or version;
- a hash of the vendored file;
- a note in this document.
It is not vendored in the current documentation-only preview.
No Cheat Engine assets
No Cheat Engine binary, source file, language file, tutorial, icon, screenshot or documentation text is included in this repository.
Reporting
If you believe a third-party notice is missing or inaccurate, open an issue or contact the maintainer. See MAINTAINERS.md.