Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

ItemValue
HostmacOS 26.6.2, Apple M4 Pro, arm64
Target/Applications/CheatEngine77.app
Cheat Engine version7.7
Tools usedfile, lipo, nm, strings, otool, vtool, codesign, shasum, REA 6.7.0 CLI, GitHub API, MCP specification
REAFormal CLI/Mach-O, plist and signature pass completed; no Ghidra/Hopper
Files modifiedNone 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 344 TPF0 form 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_64 and arm64;
  • main executable minimum macOS 10.15;
  • liblua53.dylib minimum macOS 13.3; Info.plist has no minimum key;
  • code-signed with the hardened-runtime flag;
  • no entitlements observed;
  • liblua53.dylib and libspeedhack.dylib;
  • libtcc-64.dylib, libtcc-arm64.dylib and libMonoDataCollectorMac.dylib;
  • libspeedhack.dylib has no arm64 slice;
  • tutorial-aarch64.app and tutorial-x86_64.app;
  • 49 language files;
  • Contents/Lua/celua.txt with 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;
  • master last pushed 2025-04-19;
  • 529 .pas and 164 .lfm files;
  • 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 initialize and no session header;
  • server/discover advertises versions and capabilities;
  • stdio and Streamable HTTP are the standard transports;
  • WebSocket is not standard;
  • subscriptions/listen replaces 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:

  1. MCP-first. The product is the MCP server, not a clone.
  2. Scope. Current work is the MCP server and its bridge. The native engine and GUI are deferred.
  3. Bridge first. A Lua bridge gives immediate coverage and exact Cheat Engine semantics.
  4. Cheat Engine semantics. Writes are allowed after opening a process. The project does not invent a read-only default.
  5. Profiles. core, full, lua and all, to keep tool discovery manageable.
  6. Stateless MCP. Explicit handles for process, scan, debugger and table state.
  7. stdio + localhost HTTP. stdio by default; HTTP for multi-client and embedded mode.
  8. Docs-only public preview now. Publish the design and migration before the code.
  9. No license yet. The repository is explicitly marked as a public preview, not open source.
  10. English documentation. The conversation may be Spanish, but the repository is English for reach.
  11. 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 .CT implementation;
  • 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:

  1. Does createServerSocket work reliably in Cheat Engine 7.7 on macOS 26?
  2. Does the bridge accept loop coexist with synchronize without freezing the GUI?
  3. Which debug_* functions work on arm64?
  4. Is openProcess(0) the correct way to close a process?
  5. Can pointer scan be driven without a native implementation?
  6. What is the exact behavior of Lua/Autorun and Lua/Extensions in a signed app bundle?
  7. Which MCP clients support 2026-07-28 today, and which need the 2025-11-25 compatibility path?
  8. What license will the implementation use? Answered 2026-10-21: no license for now; code remains paused.

9. Next actions

  1. Publish this documentation as the ce-mcp public preview. Done; see section 10.
  2. Review every external link and factual claim. Done with markdownlint, lychee and mdBook in CI.
  3. Choose the implementation license before F0 code. Blocked: the owner chose to remain unlicensed for now.
  4. Build the bridge and a six-tool MCP spike. Blocked by the license gate.
  5. Test against a self-signed target with SIP enabled.
  6. 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 main branch.
  • 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.toml or 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.dylib declares 13.3; if the dylib loads, 13.3 is the effective floor;
  • libspeedhack.dylib has i386 and x86_64 slices only, while libtcc-64.dylib, libtcc-arm64.dylib and libMonoDataCollectorMac.dylib are 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.txt documents a blocking createServerSocket and a LuaPipe with readBytes/writeBytes, supporting the bridge design;
  • the bundle ships AITools and UETools Lua 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() and debug_continueFromBreakpoint(co_stepinto/co_stepover) calls; debug_attach, debug_detach and debug_step moved from gap to mapped, 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.toml or 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

ClaimEvidenceLabel
The binary is universalfile, lipo -infoObservation
The binary is 83,482,352 bytesstatObservation
SHA-256 is c52dbafc…b916de6shasum -a 256Observation
119,479 FPC symbolsnm -arch arm64 + filterObservation
136 Tfrm* classesstrings + filterObservation
344 TPF0 resourcesstrings + countObservation
585 unique Lua functionscelua.txt + grep/sortObservation
125,814 exports and 511 importsREA inspect-macho; non-exhaustiveObservation
liblua53.dylib requires macOS 13.3REA inspect-machoObservation
Signature is Developer ID, hardened runtimeREA inspect-signatureObservation
libspeedhack.dylib has no arm64 slicelipo -infoObservation
debug_attach, debug_detach and debug_step are mappedcelua.txt: debugProcess, detachIfPossible, debug_continueFromBreakpointObservation + design
7.7 is not the latest public tagGitHub APIObservation
Full debugging needs SIP/rootImports, strings and Cheat Engine behaviorInference
arm64 context support is incompleteError strings in the binaryInference
A Lua bridge can cover most toolsAPI surface and design analysisInference
Effective minimum macOS is 13.3Main 10.15 vs liblua 13.3; no runtime testInference
The bridge will work on macOS 26Not testedUnknown

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, createThread and synchronize;
  • the attach and scan flows on arm64.

The static pass is enough to support the design claims recorded here; runtime claims remain F0 work.