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.