ce-mcp-server 5.8.4

package/README.md

@@ -0,0 +1,444 @@
+English | [中文](README_CN.md)
+
+# CE MCP v5.8.4 - AI-Assisted Reverse Engineering
+
+MCP bridge enabling AI assistants to directly control Cheat Engine for game hacking and reverse engineering.
+
+## Architecture
+
+```
+AI <--MCP/JSON-RPC--> ce_mcp_server.py <--Named Pipe--> ce_mcp_bridge.lua (CE)
+                           ↑
+                  Background auto-reconnect
+```
+
+## Installation
+
+1. **Install Dependencies**: `pip install pywin32`
+
+2. **Load in CE** (choose one):
+   - **Auto-load**: Copy `ce_mcp_bridge.lua` to CE's `autorun` folder (e.g. `D:\Cheat Engine\autorun\`)
+   - **Manual**: Press `Ctrl+Alt+L`, execute:
+     ```lua
+     dofile([[D:\path\to\ce_mcp_bridge.lua]])
+     ```
+
+3. **Configure MCP** (`.kiro/settings/mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "cheat-engine": {
+         "command": "python",
+         "args": ["D:/path/to/ce_mcp/ce_mcp_server.py"]
+       }
+     }
+   }
+   ```
+
+## Connection Features
+
+- **Auto-reconnect**: MCP Server automatically reconnects when CE restarts
+- **Background retry**: Connection attempts run in background with exponential backoff
+- **Diagnostic on failure**: `ce_ping` returns detailed diagnostic info when connection fails
+- **Thread-safe**: All pipe operations are protected by locks
+
+## Security Features
+
+### Authentication Token
+
+Optional authentication layer for pipe communication. When enabled, all requests must include a valid token.
+
+**Setup:**
+1. Set the same environment variable on both sides:
+   ```bash
+   # Windows CMD
+   set CE_MCP_AUTH_TOKEN=your_secret_token_here
+   
+   # PowerShell
+   $env:CE_MCP_AUTH_TOKEN = "your_secret_token_here"
+   ```
+
+2. Start CE and load the bridge
+3. Start the MCP server
+
+If tokens don't match, requests will be rejected with "Authentication failed" error.
+
+### Custom Pipe Name
+
+For anti-detection, you can customize the pipe name:
+```bash
+set CE_MCP_PIPE_NAME=my_custom_pipe_name
+```
+
+### Hook Name Validation
+
+Hook names are validated to prevent AA script injection:
+- Must start with letter or underscore
+- Can only contain alphanumeric characters and underscores
+- Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`
+
+Invalid names like `"my hook"` or `"hook;inject"` will be rejected.
+
+---
+
+## Tool Reference
+
+### System & Connection
+
+#### `ce_ping`
+Test connection to CE bridge. **Returns diagnostic info with troubleshooting suggestions on failure.**
+
+#### `ce_get_process_info`
+Get attached process info and refresh symbol handler. Also clears address cache.
+
+#### `ce_attach_process(target)`
+Attach to a process by PID or name. Clears caches and scan sessions after attaching.
+
+**Parameters:**
+- `target` (string, required): Process ID (number) or process name (e.g. `"game.exe"`)
+
+#### `ce_auto_assemble(script, target_self?)`
+Execute an Auto Assembler script. Supports enable/disable scripts, code injection, etc.
+
+**Parameters:**
+- `script` (string, required): Auto Assembler script content
+- `target_self` (boolean, optional): Target CE process itself (default: false)
+
+#### `ce_execute_lua(code)`
+Execute arbitrary Lua code in CE.
+
+**Parameters:**
+- `code` (string, required): Lua code to execute
+
+---
+
+### Memory Read/Write
+
+#### `ce_read_memory(address, type, size?)`
+Read a single memory value.
+
+**Parameters:**
+- `address` (string, required): Address expression (e.g. `"game.exe+0x1234"`, `"0x140001000"`)
+- `type` (string, required): `byte`, `word`, `dword`, `qword`, `float`, `double`, `string`, `bytes`
+- `size` (integer, optional): Size for string/bytes type (default: 100)
+
+#### `ce_read_memory_batch(requests)`
+Read multiple addresses in one call. **Always prefer this over multiple ce_read_memory calls.**
+
+**Parameters:**
+- `requests` (array, required): Array of `{address, type, id?, size?}`
+
+#### `ce_write_memory(address, type, value)`
+Write a value to memory.
+
+**Parameters:**
+- `address` (string, required): Address expression
+- `type` (string, required): Value type
+- `value` (string, required): Value to write
+
+---
+
+### Scanning & Search
+
+#### `ce_aob_scan(aob_string, module?, protection?, max_results?)`
+Scan memory for Array of Bytes pattern. Supports `??` wildcards.
+
+**Parameters:**
+- `aob_string` (string, required): Pattern like `"48 89 5C 24 ?? 48 83 EC 20"`
+- `module` (string, optional): Limit scan to module (e.g. `"game.exe"`)
+- `protection` (string, optional): Memory protection flags (default: `"-C+X"`)
+- `max_results` (integer, optional): Maximum results (default: 100)
+
+#### `ce_value_scan(value, type, module?, protection?)`
+Scan for a specific value. Useful for pointer tracing. **One-shot scan - for iterative scanning use Scan Sessions.**
+
+**Parameters:**
+- `value` (string, required): Value to search (e.g. `"0x255D5E758"` or `"12345"`)
+- `type` (string, required): `byte`, `word`, `dword`, `qword`, `float`, `double`, `string`
+- `module` (string, optional): Limit to module
+- `protection` (string, optional): Default `"+W-C"` for writable memory
+
+---
+
+### Scan Sessions
+
+Implements CE's core "First Scan → Next Scan" workflow with session management. Sessions auto-expire after 5 minutes of inactivity.
+
+#### `ce_scan_new(value, type, module?, protection?)`
+Start a new scan session.
+
+#### `ce_scan_next(session_id, value, scan_type?, value2?)`
+Continue scanning (filter) an existing session.
+
+**scan_type options:**
+- `exact` - Exact value match
+- `increased` / `decreased` - Value increased/decreased
+- `changed` / `unchanged` - Value changed/unchanged
+- `bigger_than` / `smaller_than` - Greater/less than
+- `between` - Between value and value2
+
+#### `ce_scan_results(session_id, start_index?, limit?)`
+Get paginated results from a scan session.
+
+#### `ce_scan_close(session_id)`
+Close a scan session and release resources.
+
+#### `ce_scan_list`
+List all active scan sessions.
+
+#### `ce_enum_modules`
+List all loaded modules (DLLs).
+
+---
+
+### Symbols & Addresses
+
+#### `ce_get_address(expression)`
+Resolve address expression to numeric address.
+
+**Parameters:**
+- `expression` (string, required): e.g. `"game.exe+0x1234"`, `"[[game.exe+100]+20]+8"`
+
+#### `ce_get_symbol(address, include_module?)`
+Get symbol name from address, with RTTI class info.
+
+#### `ce_resolve_pointer(base, offsets, read_value?, value_type?)`
+Resolve multi-level pointer chain with CE notation support.
+
+**Parameters:**
+- `base` (string, required): Base address or symbol (e.g. `"game.exe+1234"`)
+- `offsets` (array, required): Array of offsets, e.g. `[0x100, 0x20, 0x8]`
+- `read_value` (boolean, optional): Read value at final address (default: false)
+- `value_type` (string, optional): Value type (default: "dword")
+
+**Returns:** Includes `ceNotation` (CE-compatible pointer notation) that can be directly used in CE address list.
+
+#### `ce_auto_guess(address)`
+Guess the value type at an address.
+
+---
+
+### Disassembly & Code Analysis
+
+#### `ce_disassemble(address, count?, direction?)`
+Disassemble instructions.
+
+**Parameters:**
+- `address` (string, required): Start address
+- `count` (integer, optional): Number of instructions (default: 10)
+- `direction` (string, optional): `"forward"` or `"backward"` (default: forward)
+
+#### `ce_get_instruction_info(address)`
+Get detailed info about a single instruction.
+
+#### `ce_analyze_code(address, count?)`
+Static analysis of code block (calls, jumps, refs).
+
+---
+
+### Debugging & Breakpoints
+
+#### `ce_set_breakpoint(address, type?, size?)`
+Set a hardware breakpoint.
+
+**Parameters:**
+- `address` (string, required): Address expression
+- `type` (string, optional): `"execute"`, `"write"`, `"access"` (default: execute)
+- `size` (integer, optional): Size for write/access breakpoints (default: 1)
+
+#### `ce_break_and_get_regs(address, timeout?, include_xmm?, stack_depth?)`
+Set breakpoint and capture registers when hit. Also returns call stack.
+
+#### `ce_break_and_trace(address, max_steps?, timeout?, stop_on_ret?, trace_into_call?, end_address?, initial_regs?)`
+**Multi-step execution trace.** Most powerful debugging tool - traces code execution step by step, capturing full register state at each instruction.
+
+**Parameters:**
+- `address` (string, required): Start address (breakpoint location)
+- `max_steps` (integer, optional): Maximum instructions to trace (default: 100)
+- `timeout` (integer, optional): Timeout in ms (default: 10000)
+- `stop_on_ret` (boolean, optional): Stop when `ret` is encountered (default: true)
+- `trace_into_call` (boolean, optional): Step into calls vs step over (default: false)
+- `end_address` (string, optional): Stop when this address is reached
+- `initial_regs` (object, optional): Set register values at first hit
+
+**Stop reasons:** `"ret"`, `"end_address"`, `"max_steps"`, `"timeout"`
+
+#### `ce_cleanup`
+Remove all breakpoints and traces. Use when game freezes.
+
+---
+
+### Analysis Tools
+
+#### `ce_find_what_accesses(address, size?, duration_ms?, max_records?)`
+Find what code accesses this address (like CE's F5 feature). Monitors reads and writes.
+
+#### `ce_find_what_writes(address, size?, duration_ms?, max_records?)`
+Find what writes to this address (like CE's F6 feature). Monitors only writes.
+
+#### `ce_find_pointer_path(address, max_depth?, strategy?)`
+**Automatic pointer chain tracing.** Finds static base address for dynamic addresses.
+
+**Parameters:**
+- `address` (string, required): Dynamic address to trace
+- `max_depth` (integer, optional): Max pointer depth 1-10 (default: 7)
+- `strategy` (string, optional): `"hybrid"`, `"f5"`, `"value_scan"` (default: hybrid)
+
+#### `ce_find_references(address, limit?)`
+Find all code locations that reference a specific address.
+
+#### `ce_find_call_references(address, module?, limit?)`
+Find all CALL instructions that target a specific function.
+
+#### `ce_find_function_boundaries(address, max_search?)`
+Detect function start and end by analyzing prologue/epilogue patterns.
+
+#### `ce_generate_signature(address)`
+Generate unique AOB signature for an address. Useful for game updates.
+
+---
+
+### Advanced Analysis
+
+#### `ce_build_cfg(address, max_blocks?, max_instructions?, detect_loops?)`
+Build Control Flow Graph for a function.
+
+#### `ce_detect_patterns(address, max_instructions?, patterns?)`
+Detect common code patterns: switch tables, virtual calls, string refs, crypto constants.
+
+#### `ce_compare_functions(address1, address2, max_instructions?)`
+Compare two functions for similarity.
+
+#### `ce_trace_dataflow(address, register, direction?, max_instructions?)`
+Trace data flow for a register within a function.
+
+#### `ce_program_slice(address, criterion, direction?, max_instructions?)`
+Compute program slice - find all instructions affecting or affected by a variable.
+
+---
+
+### Code Emulation
+
+#### `ce_symbolic_trace(address, count?, initial_state?, stop_on_call?, stop_on_ret?)`
+Lightweight symbolic execution. Interprets instruction semantics without executing.
+
+**Parameters:**
+- `address` (string, required): Start address
+- `count` (integer, optional): Instructions to trace (default: 30)
+- `initial_state` (object, optional): Initial register symbols, e.g. `{"rcx": "this_ptr", "rdx": "arg1"}`
+
+#### `ce_call_function(address, args?, return_type?, timeout?)`
+Call a function in the target process. **WARNING: Executes real code!**
+
+---
+
+### Function Hooking
+
+#### `ce_hook_function(address, name, capture_args?, calling_convention?)`
+Hook a function to intercept calls and capture arguments.
+
+**Parameters:**
+- `address` (string, required): Function address
+- `name` (string, required): Hook identifier
+- `capture_args` (integer, optional): Number of args to capture 0-4 (default: 4)
+- `calling_convention` (string, optional): `"auto"`, `"fastcall"`, `"stdcall"`, `"cdecl"`
+
+#### `ce_get_hook_log(name, limit?, clear?)`
+Get captured function call arguments.
+
+#### `ce_unhook_function(name)`
+Remove a function hook.
+
+#### `ce_list_hooks`
+List all active hooks.
+
+---
+
+### Cheat Table
+
+#### `ce_get_address_list(include_script?)`
+Get all records from Cheat Table.
+
+#### `ce_add_address_record(description, address, value_type?, script?)`
+Add a new record to Cheat Table.
+
+---
+
+## Recommended Workflows
+
+### Pointer Tracing
+```python
+# Automatic (preferred)
+result = ce_find_pointer_path(address="0x255D5E758")
+# Returns: base_address, offsets, ce_pointer_notation
+
+# Manual (if automatic fails)
+# 1. Find what accesses the address
+accesses = ce_find_what_accesses(address="0x255D5E758")
+# 2. Get register value (e.g., rcx = 0x255D5E658)
+# 3. Search for pointer storing that value
+pointers = ce_value_scan(value="0x255D5E658", type="qword")
+# 4. Repeat until finding game.exe+offset
+```
+
+### Function Analysis
+```python
+# 1. Find function boundaries
+bounds = ce_find_function_boundaries(address="0x14587EDB0")
+
+# 2. Trace execution
+trace = ce_break_and_trace(address="0x14587EDB0", max_steps=100)
+
+# 3. Generate signature for updates
+sig = ce_generate_signature(address="0x14587EDB0")
+```
+
+### Reverse Engineering Unknown Code
+```python
+# 1. Disassemble
+code = ce_disassemble(address="0x14587EDB0", count=20)
+
+# 2. Symbolic trace to understand logic
+symbolic = ce_symbolic_trace(address="0x14587EDB0", initial_state={"rcx": "this"})
+
+# 3. Build CFG for complex functions
+cfg = ce_build_cfg(address="0x14587EDB0")
+
+# 4. Detect patterns
+patterns = ce_detect_patterns(address="0x14587EDB0")
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Connection failed | Use `ce_ping` - it returns diagnostic info with specific suggestions |
+| CE restarted | MCP Server auto-reconnects, just reload the Lua script in CE |
+| Pipe error | Run `CE_MCP.stop()` then `CE_MCP.start()` in CE |
+| Permission denied | Run CE as administrator |
+| Game frozen | Use `ce_cleanup()` to remove all breakpoints |
+| Breakpoint not triggering | Ensure code path is executed in game |
+
+## Status Check
+
+```lua
+CE_MCP.stats()  -- Check bridge status in CE
+reloadMcpBridge()  -- Reload bridge after code changes
+```
+
+## Version History
+
+- **v5.8.4**: Connection improvements - Background auto-reconnect thread; Auto-reconnect when CE restarts; `ce_ping` returns diagnostic info on failure; Thread-safe pipe operations
+- **v5.8.3**: Improved tool descriptions for better AI recognition
+- **v5.8.1**: Security improvements - Added optional authentication token; Added hook name validation
+- **v5.8.0**: Added Scan Sessions, `ce_attach_process`, `ce_auto_assemble`
+- **v5.0**: Added `ce_break_and_trace` with multi-step tracing
+- **v4.2**: Added CFG, pattern detection, dataflow analysis
+- **v4.0**: Added function hooking, symbolic trace
+- **v3.0**: Added pointer path finding, structure analysis
+
+## References
+
+- [CE Wiki](https://wiki.cheatengine.org/)