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

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

Status at a glance

AreaStatus
Target inventoryComplete for the shipped Cheat Engine 7.7 macOS bundle
MCP protocol researchComplete for 2026-07-28
Tool catalogDesigned; no implementation
Lua bridgeDesigned; not implemented
MCP serverDesigned; not implemented
Documentation siteThis book
LicenseTBD; 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:

  1. Curated tools for the common workflows: process selection, memory access, scans, the address list, symbols, the debugger, assembly and structures.
  2. A Lua escape hatch for the full documented API.
  3. 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 .CT files;
  • 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:

  1. MCP server — protocol handling, tool discovery, validation, pagination, tasks and transport.
  2. Tool registry — the machine-readable catalog and the dispatch layer.
  3. Backend contract — a trait that abstracts Cheat Engine operations.
  4. 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 initialize handshake 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 ttlMs and cacheScope so clients can cache tool and resource lists.
  • Subscriptions. subscriptions/listen can 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.yaml defines core, full, lua and all.
  • spec/tools/*.yaml defines the curated tools.
  • spec/lua-api.yaml lists 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 synchronize for 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:

HandleCreated byMeaning
process_handleprocess_openAn open process, including its start time to avoid PID reuse
scan_handlescan_startA scan session and its result set
debug_handledebug_attachAn active debugger session
table_handletable_new / table_loadAn 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:

ProfilePurpose
coreDefault agent workflow
fullAll curated tools
luaGenerated tools for the documented Lua API
allfull + 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, remediation and retryable.
  • 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

DateMilestone
2026-10-21Inspected the Cheat Engine 7.7 macOS bundle and measured its surface
2026-10-21Researched the public Cheat Engine source landscape
2026-10-21Researched MCP 2026-07-28 and the Rust SDK
2026-10-21Narrowed the scope from a full clone to an MCP server
2026-10-21Chose a Lua bridge as the first backend
2026-10-21Defined profiles, stateless handles and the tool catalog
2026-10-21Ran a formal REA CLI/Mach-O, plist and signature pass
2026-10-21Mapped three debugger controls and formally deferred the remaining 11 gaps
2026-10-21Defined the F0 bridge and MCP acceptance test plan
2026-10-21Defined JSON Schema contracts for the six F0 tools
2026-10-21Published a documentation-only public preview
TBDF0: bridge and MCP spike
TBDImplementation license selected before code contributions

How to read these documents

DocumentQuestion it answers
01-target-inventory.mdWhat exactly is the Cheat Engine 7.7 build we are targeting?
02-source-landscape.mdWhat public source exists, and what can we rely on?
03-mcp-research.mdWhich MCP revision and transports should we target?
04-decisions.mdWhat did we decide, when, and why?
05-backend-strategy.mdWhy a Lua bridge first, and how does a native backend fit?
06-tool-migration.mdHow do Cheat Engine capabilities become MCP tools?
07-open-source.mdWhat does the project need before it is open source?
08-gap-deferrals.mdWhy are the remaining 11 tools gaps, and what would close them?
09-f0-test-plan.mdHow will the six-tool F0 spike be accepted?
journal/2026-10-21.mdWhat 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:

  1. Capability migration: turning Cheat Engine’s operations into stable MCP tools.
  2. 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:

  1. add a dated journal entry under journal/;
  2. update 04-decisions.md;
  3. add or supersede an ADR if the decision is architectural;
  4. update 06-tool-migration.md if the tool catalog changes;
  5. 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

FieldValue
Application/Applications/CheatEngine77.app
Bundle nameCheat Engine 7.7
Bundle identifierorg.cheatengine.cheatengine
Version7.7 (CFBundleShortVersionString)
ExecutableContents/MacOS/cheatengine
ArchitecturesUniversal: x86_64 and arm64
Main executable minimum macOS10.15 (LC_BUILD_VERSION, SDK 10.15)
Bundled Lua minimum macOS13.3 (LC_BUILD_VERSION, SDK 13.3)
Info.plist minimumNo LSMinimumSystemVersion key
Bundle size~104 MB
Main binary size83,482,352 bytes
Main binary SHA-256c52dbafcf101cea70c5fc3ccf3c8df704a55cc414b8480b717152a502b916de6
Lua libraryContents/MacOS/liblua53.dylib, 597,904 bytes
Lua library SHA-2562bade6b1645cbff550f5bd1499cd759cdfb211e2b82d1142748637eb9b647885
Code signatureDeveloper ID Application: Eric Heijnen (3W4HR5987G)
Signature timestamp2026-05-29 09:43:47
Hardened runtimeYes
EntitlementsNone 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

PathNotes
Contents/MacOS/cheatengineMain application
Contents/MacOS/liblua53.dylibLua 5.3 runtime
Contents/MacOS/libspeedhack.dylibSpeedhack library; only i386 and x86_64, no arm64
Contents/MacOS/libtcc-64.dylibTiny C Compiler; universal x86_64/arm64
Contents/MacOS/libtcc-arm64.dylibTiny C Compiler; universal x86_64/arm64
Contents/MacOS/tcclib/TCC runtime headers and license files
Contents/MacOS/tutorial-aarch64.apparm64 tutorial target
Contents/MacOS/tutorial-x86_64.appx86_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.dylibUniversal 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

BinaryArchitecturesMinimum macOSNotes
cheatenginex86_64, arm6410.15SDK 10.15; LD 1167.5; UUID 205C584C-1289-347E-847C-323C73662D42
liblua53.dylibx86_64, arm6413.3SDK 13.3; LD 857.1; one dependency (libSystem)
libspeedhack.dylibi386, x86_6410.5 (x86_64 slice)No arm64 slice
libtcc-64.dylibx86_64, arm6411.0SDK 13.3
libtcc-arm64.dylibx86_64, arm6411.0SDK 13.3
libMonoDataCollectorMac.dylibx86_64, arm6411.0SDK 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

MetricValueHow measured
Total symbol lines (arm64 slice)126,325nm -arch arm64
FPC-mangled symbols ($$_)119,479nm + filter
Mach-O export records125,814 returned; non-exhaustiveREA inspect-macho
Mach-O import records511 returned; non-exhaustiveREA inspect-macho
Unit-like prefixes10,393Symbol prefixes; includes LCL/RTL
Tfrm* classes136strings + filter
TPF0 form resources344strings count
Documented Lua functions585 unique, 613 signaturescelua.txt
celua.txt size4,444 lines, ~240 KBwc, 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 unique dbk_* 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:

UnitRelevance
macexceptiondebuggerinterfaceMach exception-based debugger
maccreateremotethreadRemote thread creation
macjitwriterJIT/code writing
macummUser-mode memory manager UI
macPipePipe transport
coresymbolicationSymbolication via CoreSymbolication
machotkeysGlobal hotkeys
speedhack2Speedhack implementation
lua_serverBuilt-in Lua server
tcclibTCC 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?"
  • AuthorizationCreate
  • already root / not root yet
  • task_for_pid
  • mach_vm_read / mach_vm_write / mach_vm_protect
  • thread_get_state / thread_set_state
  • ptrace

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 createServerSocket and createThread behave as required in the bridge on macOS 26.
  • Whether the 13.3 minimum of liblua53.dylib prevents 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.dylib has no arm64 slice.
  • The exact loading order, permissions and enablement of Lua/Autorun and Lua/Extensions when 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:

FieldValue
Default branchmaster
Latest release tag7.5 (2023-02-23)
Latest commit on master2025-04-19
Files in the tree2,498 blobs
Pascal sources529 .pas
Lazarus forms164 .lfm
Program files20 .lpr
Lua files52 .lua
Root license fileNot 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

  1. Do not copy source code into this repository. The project has no license for the implementation yet, and the upstream licensing status is unclear.
  2. Do not copy documentation prose. Link to the official document and write original summaries.
  3. 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.
  4. Prefer the shipped binary for behavior. If the binary and the 7.5 source disagree, the binary wins.
  5. 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:

  1. Artifact and Mach-O inventory with the built-in REA tools.
  2. Targeted native analysis of macOS-specific units: macexceptiondebuggerinterface, maccreateremotethread, macjitwriter, macumm, speedhack2 and lua_server.
  3. Runtime observation of the bridge-relevant flows, once a test target and code-signing setup exist.
  4. 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.

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 initialize handshake, notifications/initialized and Mcp-Session-Id are removed.
  • Per-request metadata. Protocol version and client capabilities travel in _meta on 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 and resources/subscribe/unsubscribe. Clients opt in to notification categories.
  • Tasks extension. Long-running work is a separate extension with tasks/get, tasks/update and tasks/cancel. The old blocking tasks/result pattern is gone.
  • Caching hints. List and resource results carry ttlMs and cacheScope.
  • Multi-round-trip requests. Servers return InputRequiredResult with embedded requests instead of initiating separate server-to-client requests.
  • resultType. Every result is complete, input_required or, 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:

Transports

The standard bindings are:

  1. stdio — newline-delimited JSON-RPC over the standard streams of a client-launched subprocess.
  2. 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.

TransportLocal latencyClientsNotes
stdioLowestOne per processNo HTTP overhead; best for a local agent
Streamable HTTP~sub-millisecond on loopback, plus HTTP/SSE overheadManyBest for the embedded app and multi-client
In-process workerNo network serializationOneBest for UI ↔ server inside one process
HTTP over Unix socketLower than TCPMany localOptional; 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-28 support with compatibility for 2025-11-25 and earlier;
  • server/discover and 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_open returns a process_handle;
  • scan_start returns a scan_handle and possibly a task ID;
  • debug_attach returns a debug_handle;
  • table_new/table_load return a table_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-25 compatibility path F0 must prove. The current target is the stdio path; HTTP compatibility can wait for F1. rmcp provides 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/.

IDDateDecisionRationaleStatus
D12026-10-21Make MCP the product, not an afterthoughtCheat Engine already exposes a large Lua API; an MCP server delivers value without reimplementing the GUIAccepted, ADR-0001
D22026-10-21Scope the current project to the MCP serverA full Rust clone is a multi-year effort and would delay validation of the MCP designAccepted, ADR-0001
D32026-10-21Use a Lua bridge as the first backendImmediate coverage of the documented API and exact Cheat Engine semanticsAccepted, ADR-0006
D42026-10-21Preserve Cheat Engine write semanticsOnce a process is open, Cheat Engine allows writes; adding a different default would break compatibilityAccepted, ADR-0005
D52026-10-21Use core, full, lua and all tool profilesHundreds of tools in every context would hurt discovery and selectionAccepted, ADR-0004
D62026-10-21Default to stdio; offer Streamable HTTP on localhoststdio is the lowest-overhead local transport; HTTP is needed for multi-client and embedded modeAccepted, ADR-0003
D72026-10-21Use stateless MCP with explicit handlesMCP 2026-07-28 has no sessions; state belongs in the backendAccepted, ADR-0002
D82026-10-21Publish a documentation-only public preview nowMakes the design reviewable and the migration reusable without publishing unfinished codeAccepted, ADR-0008
D92026-10-21Write repository documentation in EnglishStandard for open-source reach and contributionsAccepted
D102026-10-21Do not choose a license yetThe code license decision can wait until implementation; the repository is explicitly marked as a public previewAccepted, ADR-0007
D112026-10-21Use REA CLI + Mach-O inventory first; add Ghidra only if neededThe public source covers most of the architecture; REA should target macOS-specific deltasAccepted, pending execution
D122026-10-21Keep .CT and Cheat Engine Lua compatibilityExisting tables and scripts are the main ecosystem; a clean format would lose that valueAccepted
D132026-10-21Defer the egui desktop GUIThe MCP server and bridge must be validated first; the GUI is a separate client of the same engineSuperseded by D2 for the current scope
D142026-10-21Name the public repository ce-mcpShort, neutral and not implying affiliation with Cheat EngineAccepted

Decisions that were considered and deferred

TopicWhy it is deferred
Full Rust engineRequires reimplementing memory access, scanning, debugger, assembler and the Lua API before the MCP contract is validated
In-app desktop UIA GUI is a large surface and not needed to prove the MCP design
Pointer scanNo obvious Lua API; needs either form automation or a native implementation
Windows/Linux bridgeThe first target is macOS 7.7; the contract should stabilize first
.CETRAINER and trainer generationDepends on a working table and script layer
Multi-agent HTTP serverF1/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-25 clients.

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.1 only;
  • writes {port, token, pid} to a user-only file;
  • authenticates before evaluating any code;
  • accepts ping, eval, call, cancel and shutdown;
  • runs the accept loop in a Lua thread;
  • uses synchronize when 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.dylib declares 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.dylib contains only i386 and x86_64 slices. The Lua SpeedhackV3Mac.lua path uses compile and 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;
  • .CT load/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_pid and 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;
  • .CT parsing 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_UNAVAILABLE or CE_UNSUPPORTED_PLATFORM, not a silent no-op.
  • Coverage is reported per backend, not hidden.

Failure handling

FailureBehavior
Cheat Engine not runningCE_BACKEND_UNAVAILABLE with remediation
Bridge script not loadedCE_BACKEND_UNAVAILABLE with setup instructions
Token mismatchCE_ACCESS_DENIED; no Lua evaluation
Process exitedCE_PROCESS_CLOSED; handles invalidated
Scan cancelledCE_SCAN_CANCELLED; partial results retained if requested
Lua errorCE_LUA_ERROR with the original message and traceback if available
TimeoutCE_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:

  1. a curated MCP tool for the operation, or
  2. a generated tool for the documented Lua function, or
  3. 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

  1. Inventory. Extract the documented Lua function names and the visible Cheat Engine domains.
  2. Domain model. Group capabilities into process, memory, scan, table, symbols, pointer scan, assembly, debugger, structures, Lua, UI and misc.
  3. Curated design. Define the tools an agent should see by default. Each tool gets a stable name, typed parameters and a backend mapping.
  4. Mapping. For every Lua function, record whether it is covered by a curated tool, will be generated as its own tool, or is excluded.
  5. 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.

GroupCountTools
Meta4ce_info, ce_status, ce_capabilities, ce_handles
Process7process_list, process_open, process_close, process_info, module_list, region_list, thread_list
Memory10memory_read, memory_write, memory_read_value, memory_write_value, memory_read_string, memory_alloc, memory_free, memory_protect, memory_fill, memory_dump
Scan8scan_start, scan_next, scan_cancel, scan_status, scan_results, scan_refresh, scan_save, scan_load
AOB/Symbols5aob_scan, symbol_resolve, symbol_lookup, symbol_list, address_parse
Table10table_new, table_load, table_save, table_entries, table_add, table_update, table_delete, table_freeze, table_set_value, table_run_script
Pointer scan6pointer_scan_start, pointer_scan_status, pointer_scan_results, pointer_scan_rescan, pointer_scan_cancel, pointermap_generate
Disassembly/Assembly4disassemble, assemble, auto_assemble, code_cave_find
Debugger12debug_attach, debug_detach, debug_status, breakpoint_set, breakpoint_remove, breakpoint_list, debug_continue, debug_step, registers_get, registers_set, stacktrace, debug_wait
Structures4structure_new, structure_define, structure_read, structure_list
Lua3lua_eval, lua_call, lua_api_list
UI/App5ui_state, ui_open_tool, hotkey_list, hotkey_set, speedhack_set
Misc3trainer_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:

LevelMeaning
curatedThe function is behind a curated MCP tool with a stable contract
generatedThe function gets its own tool under the lua profile
excludedThe 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:

  1. Documented automation. The 585 Lua functions in celua.txt. These are covered by curated tools, generated tools, or an explicit exclusion.
  2. Operations with no Lua entry point. Pointer scan, parts of structure dissect, trainer generation and some UI flows. These are listed as gap or excluded, not silently omitted.
  3. 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

StatusMeaning
designedTool contract exists in spec/; no implementation
mappedBackend mapping is identified; not tested
implementedBackend call works in a development build
testedContract tests and an end-to-end test pass
unsupportedNot available on the platform or backend
gapNo 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

PlatformCurated toolsLua bridgeNotes
macOSDesignedPlannedFirst target; arm64 is the primary test host
WindowsDesignedFutureNamed pipes or localhost TCP; DBVM/kernel features remain out of scope
LinuxDesignedFutureThe 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 gapReasonCandidate solution
Pointer scanNo direct Lua API found in celua.txt; the UI forms orchestrate itNative backend or controlled form automation
Structure dissect UIThe structure_* tools cover definitions and reads; the interactive window is form-drivenUse structure_*; UI parity is out of scope
arm64 debugger contextThe binary contains explicit aarch64 context error pathsNative Mach exception backend
Code cave scannerNo single documented API; code_cave_find composes region and byte scansPlanned composed tool
Trainer generationWindows/PE-centricOut of scope for macOS; revisit later
DBVM and kernel featuresWindows-only by designExcluded

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:

  1. parse the documented function names from a local Cheat Engine installation or a checked-in names file;
  2. compare them with spec/lua-api.yaml;
  3. fail if a name is missing, duplicated or has no status;
  4. compare spec/tools/*.yaml with the generated server registration;
  5. fail if a tool is documented but not registered, or vice versa;
  6. publish docs/reference/coverage.md as a generated report.

The coverage report must distinguish designed, implemented and tested. A design document is not coverage.

Adding a tool

  1. Add the definition to the right spec/tools/*.yaml file.
  2. Assign a profile, platforms, backend and risk class.
  3. Add the Cheat Engine Lua mapping or mark it gap.
  4. Update spec/lua-api.yaml if a documented function becomes covered.
  5. Run the generator and the coverage check.
  6. 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:

  1. Publish the design now. This is allowed, with an explicit “no license” notice.
  2. 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.toml and package metadata.
  • Update CONTRIBUTING.md with 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 NOTICE file 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.
  • markdownlint for structure and consistency.
  • Link checking for external references.
  • No generated code or copied documentation in the site.

Release plan

ReleaseContentsGate
v0.0.0-docsDesign previewThis document set is complete and reviewed
v0.1.0-alphaBridge + MCP spikeLicense chosen; F0 acceptance criteria met
v0.2.0-alphaCore profileF1 acceptance criteria met
v1.0.0Stable contractF4 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-mcp name.
  • 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

DispositionCountTools
Deferred to an F0 runtime experiment1process_close
Deferred to the native backend7six pointer-scan tools, stacktrace
Deferred pending form-automation design1ui_open_tool
Deferred pending snapshot design1snapshot_restore
Out of scope for the macOS release1trainer_generate
Total11

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:

  1. open the target and record getOpenedProcessID();
  2. call openProcess(0);
  3. verify the PID, process handle and dependent handles;
  4. verify that memory and scan operations fail with the documented error;
  5. 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:

  1. is guarded by an exact Cheat Engine version;
  2. has a cancellation path;
  3. returns structured results rather than screen text;
  4. 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

OptionWhy it was rejected
Assume openProcess(0) closes the targetUndocumented and destructive
Automate the pointer-scan and tracer forms in F0Fragile, hard to cancel, hard to test
Return a synthetic stack trace from registersWould invent frames and symbols
Call closeCE() for process_closeCloses Cheat Engine, not the target process
Treat snapshot_create as proof that restore worksCreate 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_info
  • process_list
  • process_open
  • memory_read
  • scan_start
  • scan_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

ItemRequirement
LicenseAn explicit implementation license has been chosen
Cheat Engine7.7 from /Applications/CheatEngine77.app
HostmacOS 26 on arm64 for the primary run
TargetA disposable, self-signed test process with known values
SIPRecord the host state; do not disable it for the first run
PermissionsRecord whether the target is debuggable without elevation
RepositoryNo 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.lua without modifying the application bundle.
  • Confirm the bridge version, Cheat Engine version and Lua version in ce_info.
  • Confirm ~/.ce-mcp/bridge.json is 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, then tools/list, then one read.
  • Legacy stdio: perform the 2025-11-25 initialize handshake, then tools/list and one read. Record whether the same tool schemas are returned.
  • Send an unsupported version and verify -32022 with 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, not 0.0.0.0 or ::.
  • 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.Timeout and createServerSocket; 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

ToolTestPass condition
ce_infoCall with no argumentsReturns server, Cheat Engine, Lua, OS and architecture versions
ce_infoCall with no target openStill succeeds; no process-dependent fields are invented
process_listList all processesReturns bounded results with PID and name
process_listFilter by exact and partial nameFilter is case-insensitive where documented; no duplicate PIDs
process_listPaginateCursor is stable for an unchanged process list; invalid cursor is rejected
process_openOpen the test target by PIDReturns a process handle and correct PID
process_openOpen by name with one matchReturns the same target
process_openOpen an invalid PID or nameReturns CE_PROCESS_NOT_FOUND; no handle is leaked
process_openOpen a protected processReturns a structured permission error; does not bypass SIP
memory_readRead a known integer, float and stringBytes match the target before and after the call
memory_readRead an unmapped addressReturns CE_INVALID_ADDRESS; connection remains usable
memory_readRequest more than the size limitReturns CE_LIMIT_EXCEEDED; no partial silent truncation
memory_readRead after the target exitsReturns CE_PROCESS_CLOSED or the documented equivalent
scan_startScan for a known 4-byte integerReturns a scan handle and task state
scan_startScan for a known float and stringEach value type follows its documented comparison and alignment
scan_startScan with an invalid rangeReturns CE_INVALID_ARGUMENT
scan_startCancel a running scanReturns CE_SCAN_CANCELLED and releases the scan thread
scan_resultsRead results from a completed scanReturns bounded, paginated results with addresses and values
scan_resultsRead results from an unknown handleReturns CE_SCAN_NOT_FOUND
scan_resultsRead before the scan completesReturns CE_SCAN_BUSY or a progress object, not partial garbage
scan_resultsPaginate to the endLast page has no duplicate or skipped addresses

Handle tests

  • A process_handle from process_open is required by memory_read and scan_start.
  • A scan_handle from scan_start is required by scan_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:

  1. the commit and bridge version;
  2. the macOS version, architecture and SIP state;
  3. the Cheat Engine version and binary SHA-256;
  4. the test target identity and how it was built;
  5. the exact request and response, with secrets redacted;
  6. pass, fail or blocked, with the observed error;
  7. timing for scan start, scan completion and a 1 MiB read;
  8. 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/Autorun differ 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

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.

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:

  1. call process_list, then process_open;
  2. read or scan with the returned process_handle;
  3. 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:

KeyRequiredPurpose
io.modelcontextprotocol/protocolVersionYesSelected protocol revision
io.modelcontextprotocol/clientInfoOptional (SHOULD)Client name and version
io.modelcontextprotocol/clientCapabilitiesYesExtensions 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: private is the conservative default for this local server. cacheScope describes who may share a cached response, not how the profile is configured. Use public only 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: true and 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_case and domain_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 with celua.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.

HandleCreated byRequired by
process_handleprocess_openMemory, scan, table, debugger and symbol tools
scan_handlescan_startscan_next, scan_results, scan_cancel
debug_handledebug_attachBreakpoint, stepping, register and stack tools
table_handletable_new, table_loadTable 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/tasks in its capabilities.
  • The server advertises the extension in server/discover.
  • A task result has resultType: "task" and a taskId, status, TTL and suggested polling interval.
  • Clients poll with tasks/get; tasks/update supplies input; tasks/cancel requests cooperative cancellation.

Planned task-producing tools:

  • scan_start for large regions or slow scans;
  • pointer_scan_start;
  • pointermap_generate;
  • memory_dump for 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_list when filtered broadly;
  • region_list and module_list for large targets;
  • lua_api_list;
  • tool_search results.

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:

URIContent
ce://statusBridge 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;
  • resourceSubscriptions for 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:

  1. Protocol errors use JSON-RPC error codes for malformed requests, unknown methods, unsupported versions and invalid params.
  2. Tool errors use a successful JSON-RPC response with isError: true and 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-28 is the primary target.
  • 2025-11-25 is supported through rmcp’s compatibility path for clients that still use initialize.
  • 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

Transports

Summary

TransportStatusDefaultUse case
stdioStandard, implemented by rmcpYesOne local agent launches the server
Streamable HTTPStandard, implemented by rmcpOptionalMulti-client, embedded app, debugging
In-process workerrmcp featureOptionalFuture desktop shell
Unix domain socketCustomDeferredLower overhead than loopback TCP
WebSocketNot standardNoNot supported
HTTP+SSE (legacy)DeprecatedNoNot 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.1 by 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.

HeaderRequired forRule
MCP-Protocol-VersionEvery POSTMust match io.modelcontextprotocol/protocolVersion
Mcp-MethodEvery requestMust match the JSON-RPC method
Mcp-Nametools/call, resources/read, prompts/getMust match params.name or params.uri
AcceptEvery POSTMust 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.1 only.
  • 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-remote flag 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)

ToolSummary
ce_infoServer, build, Cheat Engine version and platform information
ce_statusBridge state, active profile, open handles and capability summary
ce_capabilitiesMachine-readable feature and coverage matrix
ce_handlesList, inspect and close backend handles

Process (7)

ToolSummary
process_listList processes by PID and name, with an optional filter
process_openOpen a process by PID or name; returns a process_handle
process_closeClose a process handle and release its resources
process_infoPID, name, path, architecture, start time and handle state
module_listList loaded modules with base, size and path
region_listList memory regions with protection, state and type
thread_listList thread IDs for the open process

Memory (10)

ToolSummary
memory_readRead a byte range; returns hex or base64
memory_writeWrite a byte range
memory_read_valueRead a typed scalar (byte, int, float, double, pointer)
memory_write_valueWrite a typed scalar
memory_read_stringRead an ASCII, UTF-8 or UTF-16 string
memory_allocAllocate memory in the target process
memory_freeFree a previous allocation
memory_protectChange page protection for a range
memory_fillFill a range with a byte pattern
memory_dumpDump a range to a file or return it in chunks

Scan (8)

ToolSummary
scan_startFirst scan: exact, unknown, bigger/smaller, range, string, AOB
scan_nextRefine results: exact, changed, unchanged, increased, decreased
scan_cancelCancel a running scan or task
scan_statusProgress, result count and state
scan_resultsPaginated addresses and current values
scan_refreshRefresh the values of the current results
scan_savePersist a scan session to the server workspace
scan_loadRestore a scan session

AOB and symbols (5)

ToolSummary
aob_scanArray-of-bytes scan with wildcards
symbol_resolveResolve a symbol or CE address expression to an address
symbol_lookupMap an address to a module and offset or symbol
symbol_listList registered and user-defined symbols
address_parseParse module+offset, pointer and symbol expressions

Table (10)

ToolSummary
table_newCreate an empty table context
table_loadLoad a .CT or .CETRAINER file into a table context
table_saveSave a table context to .CT
table_entriesPaginated address-list entries
table_addAdd a memory record with address, type and description
table_updateUpdate an entry’s description, address, type or script
table_deleteDelete an entry
table_freezeFreeze or unfreeze an entry
table_set_valueSet an entry’s value
table_run_scriptActivate an entry’s Auto Assembler script

Pointer scan (6)

ToolSummary
pointer_scan_startStart a pointer scan; returns a task ID
pointer_scan_statusProgress, result count and state
pointer_scan_resultsPaginated pointer paths
pointer_scan_rescanRescan with a new target address
pointer_scan_cancelCancel a pointer scan
pointermap_generateGenerate a pointer map for later scans

Gap: celua.txt does not expose a direct pointer-scan API. These tools are designed but need a native backend or controlled form automation.

Disassembly and assembly (4)

ToolSummary
disassembleDisassemble instructions at an address
assembleAssemble one or more instructions at an address
auto_assembleRun an Auto Assembler script
code_cave_findFind code caves in modules and regions

Debugger (12)

ToolSummary
debug_attachAttach the debugger; returns a debug_handle
debug_detachDetach and release breakpoints
debug_statusDebugger state, current thread and stop reason
breakpoint_setSet a software, hardware or memory breakpoint
breakpoint_removeRemove a breakpoint
breakpoint_listList breakpoints and hit counts
debug_continueContinue execution
debug_stepStep into, over or out
registers_getRead registers for the current thread
registers_setWrite registers for the current thread
stacktraceReturn a stack trace with module offsets
debug_waitWait for a breakpoint or debug event with a timeout

Structures (4)

ToolSummary
structure_newCreate a structure definition
structure_defineAdd fields with offsets, types and names
structure_readRead a structure at an address
structure_listList definitions in the current table

Lua (3)

ToolSummary
lua_evalEvaluate Lua in Cheat Engine; returns a JSON-safe value
lua_callCall a documented Lua function by name with typed arguments
lua_api_listList documented functions and their migration status

UI and application (5)

ToolSummary
ui_stateMain-window state and open tools
ui_open_toolOpen a named Cheat Engine tool or form
hotkey_listList registered hotkeys
hotkey_setRegister or update a hotkey
speedhack_setEnable, 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)

ToolSummary
trainer_generateGenerate a trainer; Windows/PE-centric, out of scope for macOS
snapshot_createCapture a server-side snapshot of a table and selected regions
snapshot_restoreRestore a snapshot

Profiles

ProfileToolsContents
core32The common process → memory → scan → table → Lua loop
full81All curated tools
lua5894 meta tools + 585 generated Lua tools
all66681 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: true in 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_info
  • process_list
  • process_open
  • memory_read
  • scan_start
  • scan_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

TopicRule
JSON Schema2020-12; every object rejects undeclared properties
OutputstructuredContent must match outputSchema; content is a human-readable fallback
AddressesLowercase hex strings with 0x, for example 0x100000000
HandlesOpaque strings such as ph_... and sh_...; never parse them
PIDs and sizesJSON integers; sizes and limits reject negative or zero values
Memory valuesStrings, so an int64 cannot lose precision in JSON
Scan valuesDecimal strings for numeric types; raw text for string scans
Process filtersprocess_list.filter is a case-insensitive substring match
Process namesprocess_open.name is an exact, case-sensitive match
BytesLowercase hex without separators, or standard base64
Paginationnext_cursor is opaque and tied to the query that produced it
ErrorsisError: 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

ToolInputOutputRead-only
ce_infoNo argumentsServer, Cheat Engine, bridge, Lua and host versionsYes
process_listfilter, limit, cursorprocesses, next_cursorYes
process_openExactly one of pid, nameprocess_handle, PID, name, architectureNo
memory_readprocess_handle, address, size, encodingaddress, size, encoding, dataYes
scan_startProcess handle, value type, comparison, optional value and rangescan_handle, state, count, optional taskNo
scan_resultsscan_handle, cursor, limit, include_valuesState, value type, rows, cursor, totalYes

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

ToolLimit or rule
process_list1–1000 rows per page; an unchanged process list keeps a cursor stable
process_openOne process at a time, matching Cheat Engine’s opened-process model
memory_read1 byte–1 MiB per call; no silent truncation
scan_start1–1,000,000 retained results; range and alignment are optional
scan_results1–1000 rows per page; include_values: false returns null values
CursorsInvalid or expired cursors return CE_INVALID_CURSOR
HandlesUnknown or expired handles return CE_HANDLE_EXPIRED
Busy scansscan_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:

  1. Validate every successful result against its outputSchema.
  2. Validate that undeclared input properties are rejected.
  3. Exercise process_open with pid only, name only, both and neither.
  4. Exercise scan_start with exact and unknown; reject other comparisons.
  5. Verify that memory_read returns exactly size bytes and never truncates.
  6. Verify that next_cursor is rejected when reused with different arguments.
  7. Verify that include_values: false does not return stale values.
  8. 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

ProfileCountContentsDefault
core32Process, memory, scan, AOB/symbols, table and Lua essentialsYes
full81Every curated toolNo
lua5894 meta tools + 585 generated Lua toolsNo
all66681 curated + 585 generatedNo

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:

GroupTools
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/list returns only the active profile plus tool_search.
  • tool_search can 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:

ProfileTool countWhen to use
core32Most agent sessions
full81Debugging, assembly, structures, pointer scan
lua589Full API compatibility, script migration
all666Testing, 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:

  • core coverage: the 32 tools and their backend mappings;
  • full coverage: the 81 curated tools;
  • lua coverage: the 585 generated functions;
  • all coverage: 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

FieldTypeRequiredMeaning
codestringYesStable machine-readable code
messagestringYesHuman-readable summary
remediationstringYesWhat the caller can do next
retryablebooleanYesWhether an identical retry may succeed
detailsobjectNoStructured context, never secrets
causestringNoUnderlying Cheat Engine or OS message

Rules:

  • code is stable across versions; do not parse message.
  • remediation is actionable, not generic.
  • retryable is about an identical retry. A retry with different arguments is a new request.
  • details must not contain the bridge token, absolute user paths or raw target memory beyond what the caller requested.
  • cause is sanitized and truncated.

Codes

CodeMeaningRetryableTypical remediation
CE_INVALID_ARGUMENTArguments are semantically invalidNoFix the argument; see details.field
CE_UNSUPPORTED_PLATFORMTool is not available on this OS/archNoUse a supported platform or a different tool
CE_TOOL_NOT_IN_PROFILETool exists but is outside the active profileNoRestart with the profile named in details.profile
CE_BACKEND_UNAVAILABLEBridge or Cheat Engine is not reachableYesStart Cheat Engine and load the bridge
CE_BACKEND_BUSYBridge is processing another operationYesWait and retry; use tasks for long work
CE_ACCESS_DENIEDToken, permissions or OS access deniedNoCheck the token file and macOS permissions
CE_HANDLE_EXPIREDHandle is unknown, closed or expiredNoRe-open the process or start a new scan
CE_PROCESS_NOT_FOUNDNo process matches the queryNoCall process_list
CE_PROCESS_CLOSEDThe target exited or was detachedNoRe-open the process
CE_NOT_ATTACHEDNo process is open for this handleNoCall process_open
CE_INVALID_ADDRESSAddress is unmapped or malformedNoValidate with region_list or address_parse
CE_SCAN_NOT_FOUNDScan handle does not existNoStart a new scan
CE_SCAN_BUSYA scan is already running for this handleYesWait, poll scan_status, or cancel
CE_SCAN_CANCELLEDScan was cancelledNoStart a new scan
CE_DEBUG_NOT_ATTACHEDNo debugger session for this handleNoCall debug_attach
CE_BREAKPOINT_NOT_FOUNDBreakpoint ID does not existNoCall breakpoint_list
CE_LUA_ERRORLua raised an errorNoFix the script; see cause
CE_TIMEOUTOperation exceeded its deadlineMaybeCheck status before retrying; it may still be running
CE_INVALID_CURSORPagination cursor is invalid or expiredNoRe-run the original list call
CE_LIMIT_EXCEEDEDResult or size limit exceededNoNarrow the range or use pagination
CE_INTERNALUnexpected server errorMaybeReport with the request ID

Retry guidance

  • retryable: true means an identical request may succeed later. Use exponential backoff with jitter (for example 100 ms, 250 ms, 500 ms).
  • CE_TIMEOUT is ambiguous. A scan may still be running. Poll scan_status or the task before retrying.
  • CE_BACKEND_BUSY resolves when the current operation finishes; do not open a second bridge connection to bypass it.
  • Never retry CE_ACCESS_DENIED, CE_INVALID_ARGUMENT or CE_TOOL_NOT_IN_PROFILE without changing something.
  • Tasks are the preferred mechanism for operations that can exceed a client timeout.

Mapping from the bridge

Bridge conditionCode
Connection refusedCE_BACKEND_UNAVAILABLE
Missing or bad tokenCE_ACCESS_DENIED
Lua pcall failureCE_LUA_ERROR
openProcess returned no processCE_PROCESS_NOT_FOUND
Read at unmapped addressCE_INVALID_ADDRESS
Scan thread still activeCE_SCAN_BUSY
Socket read timeoutCE_TIMEOUT
JSON encode failureCE_INTERNAL

Progress and cancellation

  • Long operations report progress through tasks or scan_status, not by emitting unstructured log lines.
  • Cancellation is cooperative. scan_cancel and tasks/cancel set a flag; the scan checks it between regions.
  • A cancelled operation returns CE_SCAN_CANCELLED and, 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

ThreatImpactControl
Another local process connects to the bridgeArbitrary memory access and Lua executionLocalhost bind, per-launch token, 0600 state file
Bridge exposed on a public interfaceRemote code execution in Cheat Engine’s contextLoopback-only default; explicit --allow-remote with warning
Malicious bridge scriptFull control of Cheat EngineBridge is opt-in; users must review scripts
Prompt-injected agent writes to the wrong processData corruption or crashProcess handle is explicit; process_info before writes; optional audit
Agent reads sensitive memoryData exposure to the model/providerLocal tool only; user controls the target; no telemetry by default
Token leaked in logs or errorsUnauthorized bridge accessRedaction; token never included in tool results
Dependency compromiseCode execution in the MCP serverMinimal dependencies, lockfile, dependency review
Privilege escalationAccess to protected processesThe 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.1 only, using createServerSocket(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, mode 0600, contains port, token, PID and protocol version.
  • Authentication: constant-time comparison where feasible; reject and close on mismatch.
  • No unauthenticated eval: the eval and call operations require a valid token. ping may be unauthenticated but returns no sensitive data.
  • Limits: maximum request size, maximum response size, execution deadline, maximum concurrent connections.
  • Shutdown: a shutdown request 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 .CT file 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_open is the consent boundary;
  • an agent should call process_info before the first write;
  • the optional --safe mode can reject write and execute tools, including lua_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.1 by default;
  • require a token;
  • validate the Origin header 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.
  • rmcp is the only protocol dependency planned for the first release.
  • The Lua bridge will avoid vendored third-party Lua modules where possible.
  • If json.lua is 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.

MetricValue
Curated tools designed81
Curated tools implemented0
Curated tools tested0
Documented Lua functions585
Lua functions mapped to a curated tool0 verified
Lua functions implemented as generated tools0

“Designed” means a contract exists in spec/. It does not mean the tool works. This page must never report design as coverage.

Curated tools

GroupDesignedMappedGapImplementedTested
Meta44000
Process76100
Memory1010000
Scan88000
AOB/symbols55000
Table1010000
Pointer scan60600
Disassembly/assembly44000
Debugger1211100
Structures44000
Lua33000
UI/application54100
Misc31200
Total81701100

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

ToolWhy it is a gap
process_closeNo closeProcess in celua.txt; openProcess(0) behavior is unverified
pointer_scan_startNo direct Lua pointer-scan API
pointer_scan_statusDepends on pointer scan
pointer_scan_resultsDepends on pointer scan
pointer_scan_rescanDepends on pointer scan
pointer_scan_cancelDepends on pointer scan
pointermap_generateNo direct Lua API; pointer-map callbacks exist, but orchestration is form-driven
stacktraceDepends on the debugger backend and symbolication
ui_open_toolForm automation is possible but fragile; not designed yet
snapshot_restoreRestoring memory and table state needs a conflict and safety model
trainer_generateWindows/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

FamilyFunctionsStatus on macOSNotes
dbvm_*39Unsupported on macOSWindows/DBVM kernel features
dbk_*19Unsupported on macOSWindows kernel features
debug_*22UnverifiedSome functions are Windows-only; arm64 support is uncertain
Other505UnmappedCross-platform or unknown; mapping not started
Total585

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

PlatformCurated designBridgeNative gaps
macOS arm64YesPlanned; first targetPointer scan, arm64 debugger context, interactive structure dissect, arm64 speedhack path unverified
macOS x86_64YesPlannedSame, plus x86-specific debugger behavior
WindowsYesFutureDBVM/kernel features excluded
LinuxYesFutureBridge needs validation

No platform is implemented yet.

How coverage will be measured

  1. Extract function names from celua.txt.
  2. Compare with spec/lua-api.yaml.
  3. Fail on missing, duplicate or status-less names.
  4. Compare spec/tools/*.yaml with generated server registration.
  5. Fail on a documented tool that is not registered, or a registered tool that is not documented.
  6. Run contract tests against a real Cheat Engine 7.7 instance.
  7. 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 gap to mapped, implemented or tested.
  • Keep the gaps list current.
  • Add a journal entry when a gap is closed or a new one is found.

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:

MetricValue
File/Applications/CheatEngine77.app/Contents/Lua/celua.txt
Lines4,444
Size~240 KB
Unique function names585
Signatures613

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, excluded or unsupported-on-macos.
  • The lua profile 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

FunctionPurpose
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

FunctionPurpose
readBytes(address, count)Read bytes
writeBytes(address, bytes)Write bytes
readInteger / writeInteger32-bit integer
readQword / writeQword64-bit integer
readFloat / writeFloat32-bit float
readDouble / writeDouble64-bit float
readString / writeStringString
readPointer / writePointerPointer-sized value
allocateMemory(size, protection)Allocate in the target
deAlloc(address)Free an allocation
setMemoryProtection(address, size, rights)Change protection
enumMemoryRegions()Enumerate regions

Scans

FunctionPurpose
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

FunctionPurpose
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

FunctionPurpose
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

FunctionPurpose
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

FunctionPurpose
getStructureCount()Number of global structures
getStructure(index) / getStructure(name)Get a structure
registerStructureDissectOverride(...)Custom dissect behavior
getStructureElementsFromName(name)PDB elements

Lua, threads and utilities

FunctionPurpose
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_* and dbk_* target Windows kernel/DBVM features. They are excluded from the macOS bridge.
  • debug_* includes Windows-specific behavior. The macOS native interface is 4; 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.

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+0x1234 or 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-28 method 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/get and can cancel with tasks/cancel.
ttlMs / cacheScope
Cache hints on list and resource results. ttlMs is a freshness duration; cacheScope is public or private.

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 lua profile.
Profile
A named set of tools: core, full, lua or all.
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.

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 344 TPF0 resources;
  • 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-mcp reflects the narrowed scope.

Alternatives considered

  1. Full Rust clone first. Rejected: too large, delays validation, and duplicates a working tool.
  2. Library-only Rust wrapper. Rejected: does not give agents a standard discovery and invocation surface.
  3. MCP server that automates the GUI. Rejected: fragile, inaccessible and hard to test.
  4. 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.

HandleCreated byState
process_handleprocess_openOpen process, including start time to detect PID reuse
scan_handlescan_startScan type, parameters, results and progress
debug_handledebug_attachDebugger session and breakpoints
table_handletable_new / table_loadAddress-list/table context

Rules:

  • Handles are opaque strings. Clients must not parse them.
  • Every handle has a TTL and a creation timestamp.
  • ce_handles lists 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_status and 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

  1. Per-connection sessions. Rejected: MCP 2026-07-28 has no session concept, and a stateless HTTP request has no stable connection identity.
  2. PID as the process handle. Rejected: PIDs are reused; a stale PID can point to a different process.
  3. Singleton process state. Rejected: hides state, breaks multi-client use and makes tests order-dependent.
  4. 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:

  1. a single local agent that launches the server;
  2. 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

  1. HTTP only. Rejected: unnecessary network surface and overhead for the common single-agent case.
  2. stdio only. Rejected: does not support the embedded multi-client mode.
  3. WebSocket. Rejected: not a standard MCP transport in this revision.
  4. gRPC or a custom binary protocol. Rejected: clients would need custom support; MCP already defines the contract.
  5. 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:

ProfileContentsDefault
core~30 curated tools for process, memory, scan, table and LuaYes
fullAll ~80 curated tools, including debugger, assembler and structuresNo
luaOne generated tool per documented Lua function (~585)No
allfull + luaNo

Additional rules:

  • The server advertises the active profile in server/discover and ce_capabilities.
  • The profile is chosen by server configuration, not by a tool call.
  • tool_search searches the full catalog and can describe tools outside the active profile; invoking one outside the profile returns CE_TOOL_NOT_IN_PROFILE.
  • Tool names and schemas are stable across profiles; a tool present in core is identical in full and all.
  • Generated Lua tools use a deterministic prefix and are marked as generated in their metadata.
  • The lua profile 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_eval is always available in core and full, so a user is never completely blocked by a missing curated tool.
  • tool_search mitigates discoverability without loading every schema.

Alternatives considered

  1. Expose all 585 tools by default. Rejected: context and selection cost.
  2. One generic ce_call tool. Rejected: no typed schemas, poor discoverability and weak validation.
  3. Dynamically add tools after a search. Rejected: tool lists become unstable and incompatible with client-side caching.
  4. 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_eval can write anyway;
  • add friction to every experiment.

Decision

ce-mcp preserves Cheat Engine semantics.

  • process_open is 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 --safe mode may reject write and execute tools. 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_eval is 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

  1. Read-only by default. Rejected: diverges from Cheat Engine, blocks the main use case and is bypassable through Lua.
  2. Confirm every write. Rejected: there is no reliable GUI confirmation channel in a headless MCP server; it would break automation.
  3. No write tools at all. Rejected: fails the product goal.
  4. 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:

  1. a native Rust implementation of memory access, scanning, debugging, assembly and Lua;
  2. a Lua script running inside Cheat Engine, controlled over a local socket;
  3. automation of Cheat Engine’s GUI forms;
  4. 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.1 only, using createServerSocket(port, true);
  • writes {port, token, pid, version} to ~/.ce-mcp/bridge.json with mode 0600;
  • requires the token on every request before evaluating Lua;
  • runs the accept loop in a createThread thread;
  • uses synchronize for GUI-affecting operations;
  • supports ping, eval, call, cancel and shutdown;
  • 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_server is not used; its protocol is undocumented.

Alternatives considered

  1. Native backend first. Rejected: delays the MCP contract and duplicates a working engine.
  2. Use the built-in lua_server. Rejected: undocumented protocol, unclear security model and no guarantee it is enabled on macOS.
  3. GUI automation. Rejected: fragile, slow and inaccessible.
  4. Inject a native library into Cheat Engine. Rejected: more invasive, code signing and stability risks, no need for the first backend.
  5. 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:

  1. choose a permissive license immediately;
  2. publish privately until the license is chosen;
  3. publish publicly with an explicit “no license” notice.

Decision

Publish the documentation as a public design preview with no license granted.

  • LICENSE.md states “All rights reserved” and “No license is granted at this time.”
  • README.md and docs/legal/license-status.md repeat 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

  1. MIT now. Rejected: premature; the implementation may include components with different licensing constraints.
  2. CC BY 4.0 for documentation and MIT for code. Reasonable, but still a license decision that should be made with the implementation plan.
  3. Private repository. Rejected: loses early review and the public record of the migration.
  4. 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

  1. Publish a code skeleton. Rejected: adds noise and license ambiguity without validating anything.
  2. Wait for F0. Rejected: loses early feedback and the public migration record.
  3. Publish the bridge only. Rejected: still requires a license and creates an unsupported partial product.
  4. 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.

ItemStatus
ImplementationDoes not exist yet
DocumentationPublished for viewing
LicenseNot chosen
Code contributionsPaused
Open sourceNo
Source-availableYes, for viewing
WarrantyNone

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:

  1. Choose the implementation license.
  2. Add the full license text.
  3. Update README.md, LICENSE.md, CONTRIBUTING.md and package metadata.
  4. Confirm dependency license compatibility.
  5. Record the decision in an ADR that supersedes ADR-0007.
  6. 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.

No. Consult a qualified lawyer for your situation.

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.

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.

ProjectUseLicenseLink
Cheat EngineTarget application; not distributedSee upstreamhttps://cheatengine.org/
Model Context ProtocolProtocol specificationSee MCP projecthttps://modelcontextprotocol.io/
rmcp (Rust SDK)Planned MCP implementation dependencyApache-2.0, with some MIT-licensed contributionshttps://github.com/modelcontextprotocol/rust-sdk
mdBookDocumentation site generatorMIThttps://github.com/rust-lang/mdBook
markdownlint-cli2Documentation lintingMIThttps://github.com/DavidAnson/markdownlint-cli2
lycheeLink checkingMIT or Apache-2.0https://github.com/lycheeverse/lychee
Contributor CovenantCode of conductCC BY 4.0https://www.contributor-covenant.org/
rxi/json.luaPlanned Lua JSON helper; not vendored yetMIThttps://github.com/rxi/json.lua
GitHub ActionsCIGitHub termshttps://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.