cheatengine 5.8.13 → 5.8.15

package/src/tool-registry.js

@@ -0,0 +1,887 @@
+/**
+ * Tool Registry for MCP Tools
+ * Defines all 60+ tools available in the Cheat Engine MCP Bridge
+ */
+
+const ToolCategory = {
+  SYSTEM: 'system',
+  MEMORY: 'memory',
+  SCANNING: 'scanning',
+  SYMBOLS: 'symbols',
+  DEBUG: 'debug',
+  ANALYSIS: 'analysis',
+};
+
+class ToolParam {
+  constructor(name, type, description = '', required = false, defaultValue = null, enumValues = null) {
+    this.name = name;
+    this.type = type;
+    this.description = description;
+    this.required = required;
+    this.default = defaultValue;
+    this.enum = enumValues || [];
+  }
+}
+
+class Tool {
+  constructor(name, description, luaCommand, category, params = []) {
+    this.name = name;
+    this.description = description;
+    this.luaCommand = luaCommand;
+    this.category = category;
+    this.params = params;
+  }
+
+  toMCPSchema() {
+    const properties = {};
+    const required = [];
+
+    for (const p of this.params) {
+      const prop = { type: p.type };
+      if (p.description) prop.description = p.description;
+      if (p.default !== null) prop.default = p.default;
+      if (p.enum && p.enum.length > 0) prop.enum = p.enum;
+      properties[p.name] = prop;
+
+      if (p.required) {
+        required.push(p.name);
+      }
+    }
+
+    return {
+      name: this.name,
+      description: this.description,
+      inputSchema: {
+        type: 'object',
+        properties,
+        required,
+      },
+    };
+  }
+}
+
+class ToolRegistry {
+  constructor() {
+    this.tools = new Map();
+    this.ADDR_PARAM = new ToolParam(
+      'address',
+      'string',
+      "Address expression (e.g. 'game.exe+123' or '0x123456')",
+      true
+    );
+    this._registerAllTools();
+  }
+
+  _registerAllTools() {
+    this._registerSystemTools();
+    this._registerMemoryTools();
+    this._registerScanningTools();
+    this._registerSymbolTools();
+    this._registerDebugTools();
+    this._registerAnalysisTools();
+  }
+
+  _register(tool) {
+    this.tools.set(tool.name, tool);
+  }
+
+  _registerSystemTools() {
+    this._register(new Tool(
+      'ce_ping',
+      'Test connection to Cheat Engine and get bridge status. ' +
+      'If connection fails, automatically returns diagnostic info with troubleshooting suggestions. ' +
+      'Returns connection health metrics (last_success_time, connection_attempts, consecutive_errors, total_errors, is_connected) ' +
+      'and server metrics (uptime, total_calls, error_rate, per-tool statistics).',
+      'ping',
+      ToolCategory.SYSTEM
+    ));
+
+    this._register(new Tool(
+      'ce_get_process_info',
+      '[INIT] Get current attached process info and refresh symbols. CALL THIS FIRST in any session. ' +
+      'Returns: {name, pid, is64bit, ce_version, debugger: {active, interfaceName, canBreak}, ' +
+      'last_symbol_refresh (timestamp), symbol_refresh_count, module_count}. ' +
+      'Also triggers symbol handler refresh to ensure symbols are up-to-date after module loading.',
+      'get_process_info',
+      ToolCategory.SYSTEM
+    ));
+
+    this._register(new Tool(
+      'ce_execute_lua',
+      'Execute raw Lua code in CE',
+      'execute_lua',
+      ToolCategory.SYSTEM,
+      [new ToolParam('code', 'string', 'Lua code to execute', true)]
+    ));
+
+    this._register(new Tool(
+      'ce_get_selected_address',
+      'Get the currently selected address in CE Memory View/Disassembler',
+      'get_selected_address',
+      ToolCategory.SYSTEM
+    ));
+
+    this._register(new Tool(
+      'ce_get_logs',
+      'Get log entries from the Cheat Engine MCP Bridge Lua side. ' +
+      'Returns: {entries: [{timestamp, level, category, message, data}], count}. ' +
+      'Useful for debugging and monitoring bridge operations.',
+      'get_logs',
+      ToolCategory.SYSTEM,
+      [
+        new ToolParam('count', 'integer', 'Maximum number of log entries to return (default: 100)', false, 100),
+        new ToolParam('min_level', 'integer', 'Minimum log level to include: 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR (default: 1)', false, 1),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_list_processes',
+      'List running processes. Use before ce_attach_process to find available targets. ' +
+      'Returns: {count, processes: [{pid, name}]}.',
+      'list_processes',
+      ToolCategory.SYSTEM,
+      [
+        new ToolParam('filter', 'string', 'Filter processes by name (case-insensitive substring match)'),
+        new ToolParam('max_results', 'integer', 'Maximum results to return (default: 100)', false, 100),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_attach_process',
+      'Attach to a process by PID or name. Clears caches and scan sessions after attaching. ' +
+      'Returns: {success, pid, name, is64bit}.',
+      'attach_process',
+      ToolCategory.SYSTEM,
+      [new ToolParam('target', 'string', "Process ID (number) or process name (e.g. 'game.exe')", true)]
+    ));
+
+    this._register(new Tool(
+      'ce_auto_assemble',
+      'Execute an Auto Assembler script. Supports enable/disable scripts, code injection, etc. ' +
+      'Returns: {success, target_self}.',
+      'auto_assemble',
+      ToolCategory.SYSTEM,
+      [
+        new ToolParam('script', 'string', 'Auto Assembler script content', true),
+        new ToolParam('target_self', 'boolean', 'Target CE process itself (for internal scripts)', false, false),
+      ]
+    ));
+  }
+
+  _registerMemoryTools() {
+    const memTypes = ['byte', 'word', 'dword', 'qword', 'float', 'double', 'string', 'bytes'];
+
+    this._register(new Tool(
+      'ce_read_memory',
+      'Read a single memory value. Returns: {address, type, value}. ' +
+      'For reading multiple addresses, use ce_read_memory_batch instead for better performance.',
+      'read_memory',
+      ToolCategory.MEMORY,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('type', 'string', 'Value type', true, null, memTypes),
+        new ToolParam('size', 'integer', 'Size for string/bytes', false, 100),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_read_memory_batch',
+      '[PERFORMANCE] Read multiple memory addresses in ONE request. ' +
+      'ALWAYS prefer this over multiple ce_read_memory calls for better performance. ' +
+      'Example: [{"address": "game.exe+100", "type": "dword", "id": "hp"}, {"address": "game.exe+104", "type": "float", "id": "mp"}]. ' +
+      'Returns: {results: [{id, address, type, value, error?}]}.',
+      'read_memory_batch',
+      ToolCategory.MEMORY,
+      [new ToolParam('requests', 'array', 'Array of {address, type, id?, size?} objects', true)]
+    ));
+
+    this._register(new Tool(
+      'ce_write_memory',
+      'Write memory value. Returns: {success: true, address, bytes_written}.',
+      'write_memory',
+      ToolCategory.MEMORY,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('type', 'string', 'Value type', true, null, memTypes),
+        new ToolParam('value', 'string', 'Value to write (number, string, or byte array)', true),
+      ]
+    ));
+  }
+
+  _registerScanningTools() {
+    this._register(new Tool(
+      'ce_aob_scan',
+      "Scan for byte pattern (AOB/signature) in memory. Supports ?? wildcards for variable bytes. " +
+      "USE WHEN: Finding code by signature, locating functions, making version-independent scripts. " +
+      "NOT FOR: Finding data values (use ce_scan_new or ce_value_scan). " +
+      "Returns: {count, results: [addresses]}.",
+      'aob_scan',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('aob_string', 'string', "e.g. '48 89 5C 24 ?? 48 83 EC 20'", true),
+        new ToolParam('module', 'string', "Limit scan to specific module for better performance (e.g. 'game.exe', 'UnityPlayer.dll')"),
+        new ToolParam('protection', 'string', 'Flags like -C+X', false, '-C+X'),
+        new ToolParam('start', 'string', 'Start address (optional, use module instead for better performance)'),
+        new ToolParam('stop', 'string', 'Stop address (optional)'),
+        new ToolParam('max_results', 'integer', 'Maximum results', false, 100),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_value_scan',
+      '[MANUAL POINTER TRACING - STEP 2] Scan memory for a specific value. ' +
+      'USE WHEN: After ce_find_what_accesses returns a register value, search for that value to find pointer storage. ' +
+      "Example: RBX=0x12345678 accessed your address -> scan for 0x12345678 (qword) -> find where pointer is stored. " +
+      "NOT FOR: Finding game values like health/gold (use ce_scan_new for value hunting). " +
+      'Returns: {count, results: [{address, symbol, isStatic}], value_searched, type, module}. ' +
+      'TIP: isStatic=true means the address is in a module (potential static base found!).',
+      'value_scan',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('value', 'string', "Value to search for (e.g. '0x255D5E758' or '12345')", true),
+        new ToolParam('type', 'string', 'Value type', true, null, ['byte', 'word', 'dword', 'qword', 'float', 'double', 'string']),
+        new ToolParam('module', 'string', "Limit scan to specific module (e.g. 'game.exe')"),
+        new ToolParam('protection', 'string', 'Memory protection flags (default: \'+W-C\' for writable memory)', false, '+W-C'),
+        new ToolParam('start', 'string', 'Start address (optional)'),
+        new ToolParam('stop', 'string', 'Stop address (optional)'),
+        new ToolParam('max_results', 'integer', 'Maximum results', false, 100),
+        new ToolParam('is_hex', 'boolean', 'Treat value as hexadecimal (auto-detected if omitted)'),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_scan_new',
+      '[VALUE HUNTING] Start scan session to find unknown addresses by observing value changes. ' +
+      "USE WHEN: You don't know the address but can observe changes (health 100->95). " +
+      "WORKFLOW: ce_scan_new -> change value in game -> ce_scan_next('decreased') -> repeat until few results. " +
+      'NOT FOR: Pointer tracing (use ce_value_scan). NOT FOR: Code patterns (use ce_aob_scan). ' +
+      'Returns: {session_id, count}. Use ce_scan_next to filter, ce_scan_results to get addresses.',
+      'scan_new',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('value', 'string', "Value to search for (e.g. '100' or '0x64')", true),
+        new ToolParam('type', 'string', 'Value type', true, null, ['byte', 'word', 'dword', 'qword', 'float', 'double', 'string']),
+        new ToolParam('module', 'string', "Limit scan to specific module (e.g. 'game.exe')"),
+        new ToolParam('protection', 'string', 'Memory protection flags', false, '+W-C'),
+        new ToolParam('start', 'string', 'Start address (optional)'),
+        new ToolParam('stop', 'string', 'Stop address (optional)'),
+        new ToolParam('is_hex', 'boolean', 'Treat value as hexadecimal (auto-detected if omitted)'),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_scan_next',
+      'Continue scanning (filter) an existing session. Supports various scan types. ' +
+      'Returns: {session_id, count, scan_number, scan_type}.',
+      'scan_next',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('session_id', 'string', 'Session ID from ce_scan_new', true),
+        new ToolParam('value', 'string', 'Value to search for', true),
+        new ToolParam('scan_type', 'string', 'Scan type for filtering', false, 'exact', 
+          ['exact', 'increased', 'decreased', 'changed', 'unchanged', 'increased_by', 'decreased_by', 'bigger_than', 'smaller_than', 'between']),
+        new ToolParam('value2', 'string', "Second value for 'between' scan type"),
+        new ToolParam('is_hex', 'boolean', 'Treat value as hexadecimal'),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_scan_results',
+      'Get paginated results from a scan session. ' +
+      'Returns: {session_id, total_count, start_index, returned_count, has_more, results: [{index, address, symbol, value, isStatic}]}.',
+      'scan_results',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('session_id', 'string', 'Session ID from ce_scan_new', true),
+        new ToolParam('start_index', 'integer', 'Starting index for pagination', false, 0),
+        new ToolParam('limit', 'integer', 'Maximum results to return (max 1000)', false, 100),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_scan_close',
+      'Close a scan session and release resources. ' +
+      'Returns: {session_id, closed, active_sessions}.',
+      'scan_close',
+      ToolCategory.SCANNING,
+      [new ToolParam('session_id', 'string', 'Session ID to close', true)]
+    ));
+
+    this._register(new Tool(
+      'ce_scan_list',
+      'List all active scan sessions. ' +
+      'Returns: {active_sessions, max_sessions, sessions: [{session_id, count, scan_count, value_type, ...}]}.',
+      'scan_list',
+      ToolCategory.SCANNING
+    ));
+
+    this._register(new Tool(
+      'ce_enum_modules',
+      'List all loaded modules (DLLs). Returns: {count, modules: [{name, base, size}]}.',
+      'enum_modules',
+      ToolCategory.SCANNING
+    ));
+
+    this._register(new Tool(
+      'ce_get_address_list',
+      'Get all records from Cheat Table (address list)',
+      'get_address_list',
+      ToolCategory.SCANNING,
+      [new ToolParam('include_script', 'boolean', 'Include script content for AA script entries', false, false)]
+    ));
+
+    this._register(new Tool(
+      'ce_add_address_record',
+      'Add a new record to Cheat Table',
+      'add_address_record',
+      ToolCategory.SCANNING,
+      [
+        new ToolParam('description', 'string', 'Record description/name', true),
+        new ToolParam('address', 'string', 'Address expression', true),
+        new ToolParam('value_type', 'string', 'Value type', false, 'dword', 
+          ['byte', 'word', 'dword', 'qword', 'float', 'double', 'string', 'bytes', 'script']),
+        new ToolParam('script', 'string', 'AA script content (only for script type)'),
+      ]
+    ));
+  }
+
+  _registerSymbolTools() {
+    this._register(new Tool(
+      'ce_get_address',
+      "Resolve expression to address. Returns: {expression, address}. " +
+      "Supports: 'game.exe+0x1234', '[[base]+10]+20', symbol names.",
+      'get_address',
+      ToolCategory.SYMBOLS,
+      [new ToolParam('expression', 'string', 'Address expression to resolve', true)]
+    ));
+
+    this._register(new Tool(
+      'ce_get_symbol',
+      '[SYMBOL LOOKUP] Get symbol name, RTTI class info, and module details for an address. ' +
+      'USE WHEN: Identifying what code/data an address belongs to, checking if address is in a module. ' +
+      'Returns: {address, symbol, hasSymbol, rttiClassName, hasRTTI, inModule, inSystemModule, ' +
+      'moduleInfo: {name, base, size, offset, is64bit, path}}. ' +
+      "TIP: inModule=true with symbol containing '.exe+' or '.dll+' indicates a static address.",
+      'get_symbol',
+      ToolCategory.SYMBOLS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('include_module', 'boolean', 'Include module name in symbol', false, true),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_get_region_info',
+      'Get memory region info (base, size, protection)',
+      'get_region_info',
+      ToolCategory.SYMBOLS,
+      [this.ADDR_PARAM]
+    ));
+
+    this._register(new Tool(
+      'ce_auto_guess',
+      'Guess the value type at an address (byte/word/dword/qword/float/double/string/pointer). ' +
+      'USE WHEN: Analyzing unknown memory, determining how to read a value. ' +
+      'Returns: {type_id, type_name, value}. Useful for structure field analysis.',
+      'auto_guess',
+      ToolCategory.SYMBOLS,
+      [this.ADDR_PARAM]
+    ));
+
+    this._register(new Tool(
+      'ce_resolve_pointer',
+      '[VERIFICATION] Resolve a KNOWN pointer chain to get final address and optionally read value. ' +
+      'USE WHEN: You already have base+offsets and want to verify the chain works or read the value. ' +
+      'Returns CE notation like \'[[game.exe+123]+10]+20\' for easy copy to CE. ' +
+      'NOT FOR: Discovering pointer paths (use ce_find_pointer_path for discovery). ' +
+      'Returns: {base, offsets, final_address, ceNotation, chain: [{level, address, value, symbol}]}.',
+      'resolve_pointer',
+      ToolCategory.SYMBOLS,
+      [
+        new ToolParam('base', 'string', 'Base address or symbol', true),
+        new ToolParam('offsets', 'array', 'Array of offsets, e.g. [0x100, 0x20, 0x8]', true),
+        new ToolParam('read_value', 'boolean', 'Read value at final address', false, false),
+        new ToolParam('value_type', 'string', 'Value type to read if read_value=true', false, 'dword',
+          ['byte', 'word', 'dword', 'qword', 'float', 'double', 'pointer']),
+      ]
+    ));
+  }
+
+  _registerDebugTools() {
+    this._register(new Tool(
+      'ce_disassemble',
+      'Basic disassembly - get raw instructions at an address. ' +
+      'USE WHEN: You just need to see assembly code (opcodes, bytes). ' +
+      'FOR DEEPER ANALYSIS: Use ce_analyze_code (extracts calls/jumps) or ce_build_cfg (function-level CFG). ' +
+      'Returns: {instructions: [{address, opcode, bytes, size}], nextAddress}.',
+      'disassemble',
+      ToolCategory.DEBUG,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('count', 'integer', 'Number of instructions', false, 10),
+        new ToolParam('direction', 'string', 'Disassembly direction: forward (default) or backward using getPreviousOpcode', false, 'forward', ['forward', 'backward']),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_get_instruction_info',
+      'Get detailed instruction info. Returns: {address, opcode, parameters, bytes, size, isCall, isJump, isRet, isConditionalJump, readsMemory, writesMemory}.',
+      'get_instruction_info',
+      ToolCategory.DEBUG,
+      [this.ADDR_PARAM]
+    ));
+
+    this._register(new Tool(
+      'ce_set_breakpoint',
+      'Set a hardware breakpoint. Returns: {success, address, type}. Use ce_remove_breakpoint to remove.',
+      'set_breakpoint',
+      ToolCategory.DEBUG,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('type', 'string', 'Breakpoint type', false, 'execute', ['execute', 'write', 'access']),
+        new ToolParam('size', 'integer', 'Size in bytes for write/access breakpoints', false, 1),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_remove_breakpoint',
+      'Remove a debug breakpoint',
+      'remove_breakpoint',
+      ToolCategory.DEBUG,
+      [this.ADDR_PARAM]
+    ));
+
+    this._register(new Tool(
+      'ce_get_breakpoints',
+      'List all active breakpoints',
+      'get_breakpoints',
+      ToolCategory.DEBUG
+    ));
+
+    this._register(new Tool(
+      'ce_break_and_get_regs',
+      '[SINGLE CAPTURE] Set breakpoint and capture registers ONCE when hit. ' +
+      'USE WHEN: You need register values at ONE specific point (function args, pointer values). ' +
+      'Returns all registers + call stack at breakpoint hit. ' +
+      'FOR MULTI-STEP: Use ce_break_and_trace to trace execution flow. ' +
+      'Returns: {triggered, registers: {rax-r15, rip, rflags}, callStack, returnAddress}.',
+      'break_and_get_regs',
+      ToolCategory.DEBUG,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('timeout', 'integer', 'Timeout in ms', false, 5000),
+        new ToolParam('stack_depth', 'integer', 'Number of stack entries to read', false, 16),
+        new ToolParam('include_xmm', 'boolean', 'Include XMM registers (SSE/AVX) for floating point analysis', false, false),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_break_and_trace',
+      '[EXECUTION TRACE] Trace code execution step-by-step from breakpoint. Most powerful debugging tool. ' +
+      'USE WHEN: Understanding algorithm logic, following data transformations, debugging execution flow. ' +
+      'Captures FULL register state at EACH instruction. ' +
+      'FOR SINGLE SNAPSHOT: Use ce_break_and_get_regs instead. ' +
+      "Returns: {steps, stop_reason, trace: [{step, address, instruction, registers}]}. " +
+      "Stop reasons: 'ret', 'end_address', 'max_steps', 'timeout'.",
+      'break_and_trace',
+      ToolCategory.DEBUG,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('max_steps', 'integer', 'Maximum instructions to trace', false, 100),
+        new ToolParam('timeout', 'integer', 'Timeout in ms', false, 10000),
+        new ToolParam('stop_on_ret', 'boolean', 'Stop tracing when ret is encountered', false, true),
+        new ToolParam('trace_into_call', 'boolean', 'Trace into call instructions (step into vs step over)', false, false),
+        new ToolParam('end_address', 'string', 'Stop tracing when this address is reached'),
+        new ToolParam('initial_regs', 'object', 
+          'Set register values at first hit. ' +
+          'Example: {"rcx": "0x12345", "rdx": 100}'),
+      ]
+    ));
+  }
+
+  _registerAnalysisTools() {
+    // Analysis tools - first batch
+    this._register(new Tool(
+      'ce_find_what_accesses',
+      '[MANUAL POINTER TRACING - STEP 1] Find code that reads/writes an address (like CE\'s F5 key). ' +
+      'This tool monitors for 10 seconds - user must trigger memory access during this time. ' +
+      'USE WHEN: ce_find_pointer_path failed and you need manual pointer tracing. ' +
+      'Returns register values (e.g., RBX=0x12345678) showing what pointer was used to access the address. ' +
+      'WORKFLOW: Take register value -> ce_value_scan to find where that pointer is stored -> repeat until static base.',
+      'find_what_accesses',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('user_prompted', 'boolean', 
+          "REQUIRED: Set true ONLY after you told user 'I will monitor for 10 seconds, please change the value in game NOW'. " +
+          'You must prompt user BEFORE calling.', true),
+        new ToolParam('size', 'integer', 'Size to monitor (1/2/4/8 bytes)', false, 4),
+        new ToolParam('duration_ms', 'integer', 'Monitoring duration in milliseconds (default 10000 = 10 seconds)', false, 10000),
+        new ToolParam('max_records', 'integer', 'Maximum hit records before stopping', false, 1000),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_find_what_writes',
+      'Find code that WRITES to an address (like CE\'s F6 key). Monitors writes only, ignores reads. ' +
+      'This tool monitors for 10 seconds - user must trigger memory write during this time. ' +
+      'USE WHEN: Finding what MODIFIES a value (e.g., what decreases player health). ' +
+      'USE ce_find_what_accesses instead if you need both reads and writes for pointer tracing.',
+      'find_what_writes',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('user_prompted', 'boolean', 
+          "REQUIRED: Set true ONLY after you told user 'I will monitor for 10 seconds, please trigger a write in game NOW'. " +
+          'You must prompt user BEFORE calling.', true),
+        new ToolParam('size', 'integer', 'Size to monitor (1/2/4/8 bytes)', false, 4),
+        new ToolParam('duration_ms', 'integer', 'Monitoring duration in milliseconds (default 10000 = 10 seconds)', false, 10000),
+        new ToolParam('max_records', 'integer', 'Maximum hit records before stopping', false, 1000),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_analyze_code',
+      'Static analysis of code block - disassembly PLUS extracted calls, jumps, memory references. ' +
+      'USE WHEN: Understanding what a code section does without execution. ' +
+      'Returns call targets, jump destinations, memory access patterns. ' +
+      'FOR FUNCTION-LEVEL: Use ce_build_cfg. FOR DYNAMIC ANALYSIS: Use ce_break_and_trace. ' +
+      'Returns: {instructions, calls, jumps, memory_refs}.',
+      'analyze_code',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('count', 'integer', 'Number of instructions to analyze', false, 20),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_build_cfg',
+      'Build Control Flow Graph for an entire function. ' +
+      'USE WHEN: Analyzing function structure, finding loops, understanding complex branching. ' +
+      'Returns basic blocks, edges, loop detection, cyclomatic complexity. ' +
+      'TIP: Use ce_find_function_boundaries first if you don\'t know function start address. ' +
+      'Returns: {entry, blocks: [{id, start, end, successors, predecessors, isLoopHeader}], edges, loops, complexity}.',
+      'build_cfg',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('max_instructions', 'integer', 'Maximum instructions to analyze (default 500)', false, 500),
+        new ToolParam('max_blocks', 'integer', 'Maximum basic blocks (default 100)', false, 100),
+        new ToolParam('detect_loops', 'boolean', 'Detect and annotate loop structures', false, true),
+        new ToolParam('include_disasm', 'boolean', 'Include disassembly in each block', false, true),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_detect_patterns',
+      '[PATTERN RECOGNITION] Detect common code patterns in a function. ' +
+      'USE WHEN: Quick function classification, finding crypto code, detecting anti-debug, locating string usage. ' +
+      'Detects: switch_tables (jump tables), virtual_calls (vtable calls), string_refs (string literals), ' +
+      'crypto_constants (MD5/SHA/TEA/Blowfish magic numbers), anti_debug (IsDebuggerPresent/rdtsc), ' +
+      'comparisons (cmp/test), memory_patterns (struct field access). ' +
+      'Returns: {patterns: {switch_tables, virtual_calls, string_refs, crypto_constants, anti_debug, comparisons, memory_patterns}, ' +
+      'summary: {has_switch, has_virtual_calls, has_strings, has_crypto, has_anti_debug, unique_offsets}}.',
+      'detect_patterns',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('max_instructions', 'integer', 'Maximum instructions to scan', false, 200),
+        new ToolParam('patterns', 'array', 'Specific patterns to detect (omit for all)'),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_compare_functions',
+      'Compare two functions for similarity. Returns matching blocks, differing instructions, ' +
+      'and similarity score. Useful for patch analysis and finding similar code.',
+      'compare_functions',
+      ToolCategory.ANALYSIS,
+      [
+        new ToolParam('address1', 'string', 'First function address', true),
+        new ToolParam('address2', 'string', 'Second function address', true),
+        new ToolParam('max_instructions', 'integer', 'Max instructions per function', false, 200),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_trace_dataflow',
+      "Trace how a SINGLE register's value flows through code. " +
+      "USE WHEN: 'Where does RAX get its value?' or 'Where is RCX used after this?'. " +
+      'Tracks ONE register only. FOR CROSS-REGISTER: Use ce_program_slice which follows data across mov/xchg. ' +
+      'Returns: {definitions: [where value comes from], uses: [where value goes]}.',
+      'trace_dataflow',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('register', 'string', "Register to trace (e.g. 'rax', 'rcx')", true),
+        new ToolParam('max_instructions', 'integer', 'Max instructions to analyze', false, 100),
+        new ToolParam('direction', 'string', "Trace direction: 'forward' (uses) or 'backward' (definitions)", false, 'both', ['forward', 'backward', 'both']),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_program_slice',
+      '[ADVANCED] Compute program slice - find ALL instructions affecting a value (backward) or affected by it (forward). ' +
+      "USE WHEN: Understanding 'how is this value computed' across multiple registers and memory operations. " +
+      'Unlike ce_trace_dataflow, follows data through register transfers (mov rax,rbx). ' +
+      'Essential for complex algorithm reverse engineering. ' +
+      'Returns: {slice_instructions, dependencies}.',
+      'program_slice',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('criterion', 'string', "Slicing criterion: register name (e.g. 'rax') or memory pattern (e.g. '[rbx+10]')", true),
+        new ToolParam('direction', 'string', "Slice direction: 'backward' (what affects this) or 'forward' (what this affects)", false, 'backward', ['backward', 'forward']),
+        new ToolParam('max_instructions', 'integer', 'Max instructions to analyze', false, 200),
+        new ToolParam('follow_calls', 'boolean', 'Follow into called functions (increases depth but slower)', false, false),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_analyze_struct_access',
+      'Infer structure fields by scanning memory values at an address. ' +
+      'USE WHEN: Analyzing object/struct layout, finding field offsets. ' +
+      'Scans memory range and guesses field types. ' +
+      'FOR DYNAMIC ANALYSIS: Use ce_trace_struct_access to see what code accesses the struct.',
+      'analyze_struct_access',
+      ToolCategory.ANALYSIS,
+      [
+        new ToolParam('base_address', 'string', this.ADDR_PARAM.description, true),
+        new ToolParam('scan_range', 'integer', 'Range to scan in bytes', false, 512),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_trace_struct_access',
+      'Dynamic trace: Monitor what code accesses a memory region. ' +
+      'USE WHEN: Finding which code reads/writes struct fields, understanding object usage patterns. ' +
+      'FOR STATIC ANALYSIS: Use ce_analyze_struct_access to infer field types from values.',
+      'trace_struct_access',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('size', 'integer', 'Size to monitor', false, 4),
+        new ToolParam('mode', 'string', 'Trace mode', false, 'read_write', ['read_write', 'write']),
+        new ToolParam('duration_ms', 'integer', 'Duration in milliseconds', false, 1000),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_cleanup',
+      'Force remove ALL breakpoints and traces set by MCP tools. ' +
+      'USE WHEN: Game frozen due to stuck breakpoint, cleaning up after analysis, resetting debug state. ' +
+      'Safe to call anytime - cleans up zombie resources.',
+      'cleanup_breakpoints',
+      ToolCategory.ANALYSIS
+    ));
+
+    this._register(new Tool(
+      'ce_find_pointer_path',
+      '[RECOMMENDED FIRST] Automatically find static pointer path to a dynamic address. ' +
+      'This tool monitors memory access internally for ~10 seconds per level - user must trigger access during this time. ' +
+      'USE WHEN: You have a dynamic address and need a stable pointer chain (base+offsets). ' +
+      'Returns: {success, base_address, offsets, ce_pointer_notation, steps, suggestions}. ' +
+      "Strategies: 'hybrid' (recommended), 'f5', 'value_scan'. " +
+      'NOT FOR: Addresses already static (module+offset format).',
+      'find_pointer_path',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('user_prompted', 'boolean', 
+          "REQUIRED: Set true ONLY after you told user 'I will trace pointers, please interact with the value in game NOW (change it, take damage, use feature)'. " +
+          'You must prompt user BEFORE calling.', true),
+        new ToolParam('max_depth', 'integer', 'Maximum pointer chain depth (1-10)', false, 7),
+        new ToolParam('duration_ms', 'integer', 'Monitoring duration per level in ms (default 10000)', false, 10000),
+        new ToolParam('max_results', 'integer', 'Maximum candidate pointers to evaluate per level', false, 10),
+        new ToolParam('strategy', 'string', 
+          "Search strategy: 'hybrid' (recommended, F5 + value_scan + region-based scoring), 'f5' (pure F5 method), 'value_scan' (pure pointer search)", 
+          false, 'hybrid', ['hybrid', 'f5', 'value_scan']),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_find_references',
+      'Find all code locations referencing an address. Returns: {address, count, references: [{address, instruction}]}.',
+      'find_references',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('limit', 'integer', 'Maximum results to return', false, 50),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_find_call_references',
+      'Find all CALL instructions targeting a function (who calls this function). ' +
+      'USE WHEN: Understanding function usage, finding entry points, tracing call hierarchy. ' +
+      'Auto-detects module from target address for better performance. ' +
+      'Returns: {count, callers: [{address, instruction, symbol}]}.',
+      'find_call_references',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('module', 'string', "Limit scan to specific module (e.g. 'game.exe'). If omitted, auto-detects from target address."),
+        new ToolParam('limit', 'integer', 'Maximum results to return', false, 100),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_find_function_boundaries',
+      'Find function start/end by prologue/epilogue patterns. ' +
+      "USE WHEN: You have an address inside a function and need to find where the function starts/ends. " +
+      'WORKFLOW: Use this first, then ce_build_cfg for full function analysis. ' +
+      'Returns: {function_start, function_end, size}.',
+      'find_function_boundaries',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('max_search', 'integer', 'Maximum bytes to search for boundaries', false, 4096),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_checksum_memory',
+      'Calculate MD5 hash of a memory region. Useful for detecting code modifications.',
+      'checksum_memory',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('size', 'integer', 'Number of bytes to hash', false, 256),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_generate_signature',
+      'Generate unique AOB signature for code at an address. ' +
+      'USE WHEN: Creating version-independent scripts, documenting code locations for future game updates. ' +
+      'WORKFLOW: Generate signature here -> after game update, use ce_aob_scan to relocate. ' +
+      'Returns: {address, signature, mask, unique}.',
+      'generate_signature',
+      ToolCategory.ANALYSIS,
+      [this.ADDR_PARAM]
+    ));
+
+    this._registerHookTools();
+    this._registerEmulationTools();
+  }
+
+  _registerHookTools() {
+    this._register(new Tool(
+      'ce_hook_function',
+      '[NON-BLOCKING] Hook a function to intercept calls and capture arguments automatically. ' +
+      'USE WHEN: Monitoring function calls without stopping execution (e.g., logging all damage events). ' +
+      'Captures first 4 args: x64 uses RCX/RDX/R8/R9, x32 uses stack. ' +
+      'WORKFLOW: ce_hook_function -> let game run -> ce_get_hook_log to retrieve captured data. ' +
+      'FOR SINGLE CAPTURE: Use ce_break_and_get_regs instead.',
+      'hook_function',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('name', 'string', 'Hook identifier name', true),
+        new ToolParam('capture_args', 'integer', 'Number of arguments to capture (0-4, default 4)', false, 4),
+        new ToolParam('capture_return', 'boolean', 'Reserved for future use (not implemented)', false, true),
+        new ToolParam('max_records', 'integer', 'Fixed at 64 (circular buffer)', false, 64),
+        new ToolParam('calling_convention', 'string', 'Calling convention hint', false, 'auto', ['auto', 'fastcall', 'stdcall', 'cdecl']),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_unhook_function',
+      'Remove a function hook by name and restore original code. ' +
+      'Call this when finished analyzing to clean up resources and free memory.',
+      'unhook_function',
+      ToolCategory.ANALYSIS,
+      [new ToolParam('name', 'string', 'Hook identifier name', true)]
+    ));
+
+    this._register(new Tool(
+      'ce_list_hooks',
+      'List all active function hooks with their status and call counts. ' +
+      'Use to check which hooks are currently installed before adding new ones.',
+      'list_hooks',
+      ToolCategory.ANALYSIS
+    ));
+
+    this._register(new Tool(
+      'ce_get_hook_log',
+      'Get captured function call arguments. Returns entries with args[1-4] containing: ' +
+      'x64: RCX(this/arg1), RDX(arg2), R8(arg3), R9(arg4); ' +
+      'x32: stack params [esp+10/14/18/1C]. ' +
+      'Values are hex addresses/integers. total_calls shows how many times function was called.',
+      'get_hook_log',
+      ToolCategory.ANALYSIS,
+      [
+        new ToolParam('name', 'string', 'Hook identifier name', true),
+        new ToolParam('clear', 'boolean', 'Clear log after reading', false, false),
+        new ToolParam('limit', 'integer', 'Max records to return (1-64, default 50)', false, 50),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_clear_hook_log',
+      'Clear the call log and reset total_calls counter for a hook. ' +
+      'Use when: 1) Starting fresh measurement, 2) Log buffer full (64 entries max), ' +
+      '3) Want to count calls from a specific point. Omit name to clear all hooks.',
+      'clear_hook_log',
+      ToolCategory.ANALYSIS,
+      [new ToolParam('name', 'string', 'Hook name (omit to clear all)')]
+    ));
+  }
+
+  _registerEmulationTools() {
+    this._register(new Tool(
+      'ce_call_function',
+      '[DANGEROUS] Call a function in target process - EXECUTES REAL CODE! ' +
+      'USE WHEN: Testing function behavior, calling game functions programmatically. ' +
+      'Uses x64 fastcall (RCX, RDX, R8, R9). May crash game if used incorrectly. ' +
+      'Returns: {success, return_value, return_type}.',
+      'call_function',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('args', 'array', 'Function arguments (up to 4 for fastcall). Can be integers or address expressions.', false, []),
+        new ToolParam('timeout', 'integer', 'Timeout in milliseconds', false, 5000),
+        new ToolParam('return_type', 'string', 'How to interpret return value', false, 'qword', 
+          ['byte', 'word', 'dword', 'qword', 'float', 'double', 'pointer']),
+      ]
+    ));
+
+    this._register(new Tool(
+      'ce_symbolic_trace',
+      '[NO EXECUTION] Lightweight symbolic execution - interprets instructions WITHOUT running them. ' +
+      'USE WHEN: Understanding code logic safely, analyzing potentially dangerous code, static algorithm analysis. ' +
+      "Produces readable expressions like 'rax = ((arg0 + 5) << 2)'. " +
+      'Supports: mov, movzx, movsxd, lea, add, sub, xor, and, or, shl, shr, imul, cmp, test, cmovxx. ' +
+      'FOR ACTUAL EXECUTION: Use ce_break_and_trace instead. ' +
+      'Returns: {trace: [{address, instruction, effects}], final_state: {reg: expression}, stop_reason}.',
+      'symbolic_trace',
+      ToolCategory.ANALYSIS,
+      [
+        this.ADDR_PARAM,
+        new ToolParam('count', 'integer', 'Number of instructions to trace', false, 30),
+        new ToolParam('initial_state', 'object', 
+          'Initial register values as symbols or concrete values. ' +
+          'Example: {"rcx": "this_ptr", "rdx": "arg1", "r8": 0}'),
+        new ToolParam('stop_on_call', 'boolean', 'Stop tracing when encountering a call instruction', false, true),
+        new ToolParam('stop_on_ret', 'boolean', 'Stop tracing when encountering a ret instruction', false, true),
+        new ToolParam('simplify', 'boolean', 'Simplify expressions (e.g., x^x=0, x+0=x)', false, true),
+      ]
+    ));
+  }
+
+  getTool(name) {
+    return this.tools.get(name) || null;
+  }
+
+  getAllSchemas() {
+    return Array.from(this.tools.values()).map(tool => tool.toMCPSchema());
+  }
+
+  getLuaCommand(toolName) {
+    const tool = this.tools.get(toolName);
+    return tool ? tool.luaCommand : null;
+  }
+}
+
+module.exports = { ToolRegistry, ToolCategory, Tool, ToolParam };