cheatengine 5.8.14 → 5.8.16

package/bin/cheatengine

@@ -1,89 +1,45 @@
 #!/usr/bin/env node
 /**
- * Cheat Engine MCP Server - NPX wrapper
- * 调用Python运行ce_mcp_server.py
+ * Cheat Engine MCP Server - CLI Entry Point
+ * Works with: npm install -g, npx, and local installs
  */
 
-const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
-// 调试模式
+// Debug mode
 const DEBUG = process.env.DEBUG === '1';
 function log(...args) {
   if (DEBUG) console.error('[cheatengine]', ...args);
 }
 
-log('Starting cheatengine wrapper...');
+log('Starting cheatengine MCP server...');
 
-// 找到包根目录（兼容 npx/npm install 各种情况）
-function findPackageRoot() {
-  // 方法1: 通过 package.json 定位
-  try {
-    const pkgPath = require.resolve('cheatengine/package.json');
-    return path.dirname(pkgPath);
-  } catch (e) {
-    // 方法2: 通过当前文件相对路径
-    return path.join(__dirname, '..');
-  }
-}
-
-const packageRoot = findPackageRoot();
+// Get package root directory (__dirname is bin/ in the package)
+const packageRoot = path.join(__dirname, '..');
 log('Package root:', packageRoot);
 
-const pythonScript = path.join(packageRoot, 'ce_mcp_server.py');
-log('Python script path:', pythonScript);
+const serverScript = path.join(packageRoot, 'ce_mcp_server.js');
+log('Server script:', serverScript);
 
-// 验证Python脚本存在
-if (!fs.existsSync(pythonScript)) {
-  console.error('[cheatengine] 错误: 找不到 ce_mcp_server.py');
-  console.error('查找路径:', pythonScript);
-  console.error('包根目录:', packageRoot);
+// Verify script exists
+if (!fs.existsSync(serverScript)) {
+  console.error('[cheatengine] Error: Cannot find ce_mcp_server.js');
+  console.error('Expected at:', serverScript);
   process.exit(1);
 }
 
-// 检测Python命令 - Windows上尝试多个选项
-let pythonCmd = 'python';
-if (process.platform === 'win32') {
-  // Windows: 尝试 python, python3, py
-  for (const cmd of ['python', 'python3', 'py']) {
-    try {
-      execSync(`${cmd} --version`, { stdio: 'ignore' });
-      pythonCmd = cmd;
-      log('Found Python:', cmd);
-      break;
-    } catch (e) {
-      // 尝试下一个
-    }
-  }
+// Ensure stdin/stdout are in proper mode for MCP
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(false);
 }
 
-log('Using Python command:', pythonCmd);
-
-const proc = spawn(pythonCmd, [pythonScript], {
-  stdio: ['pipe', 'pipe', 'pipe'],
-  windowsHide: true
-});
-
-log('Python process spawned, PID:', proc.pid);
-
-// 透传stdin/stdout/stderr
-process.stdin.pipe(proc.stdin);
-proc.stdout.pipe(process.stdout);
-proc.stderr.pipe(process.stderr);
-
-proc.on('exit', (code, signal) => {
-  log('Python process exited, code:', code, 'signal:', signal);
-  process.exit(code ?? 0);
-});
-
-proc.on('error', (err) => {
-  console.error('[cheatengine] 启动失败:', err.message);
-  console.error('请确保已安装Python和pywin32: pip install pywin32');
+// Run the server
+log('Loading MCP server...');
+try {
+  require(serverScript);
+} catch (err) {
+  console.error('[cheatengine] Failed to start:', err.message);
+  console.error(err.stack);
   process.exit(1);
-});
-
-// 如果3秒内没有退出，说明启动成功
-setTimeout(() => {
-  log('Python process still running after 3s');
-}, 3000);
+}

package/ce_mcp_server.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+// -*- coding: utf-8 -*-
+/**
+ * Cheat Engine MCP Server - Main Server Implementation
+ * JavaScript/Node.js version
+ */
+
+const { Config, TimeoutManager, MetricsCollector, log } = require('./src/base');
+const { PipeClient } = require('./src/pipe-client');
+const { ToolRegistry } = require('./src/tool-registry');
+
+// ============ MCP Server ============
+class CEMCPServer {
+  constructor() {
+    this.pipeClient = new PipeClient();
+    this.pipeClient.startBackgroundReconnect();
+    this.toolRegistry = new ToolRegistry();
+    this.timeoutManager = new TimeoutManager();
+    this.metricsCollector = new MetricsCollector();
+    this.requestCount = 0;
+  }
+
+  async _diagnoseConnection() {
+    const checks = [];
+    const suggestions = [];
+    let allPassed = true;
+
+    // Check 1: Pipe existence
+    let pipeExists = false;
+    try {
+      const fs = require('fs');
+      // Try to check if pipe exists (Windows specific)
+      const testClient = new PipeClient();
+      const connected = await testClient.connect(false, 1000);
+      if (connected) {
+        pipeExists = true;
+        testClient.stop();
+        checks.push({
+          name: 'pipe_exists',
+          passed: true,
+          message: `Pipe '${Config.PIPE_NAME}' available`,
+        });
+      } else {
+        throw new Error('Connection failed');
+      }
+    } catch (err) {
+      allPassed = false;
+      checks.push({
+        name: 'pipe_exists',
+        passed: false,
+        message: 'Pipe not found - CE bridge not running',
+      });
+      suggestions.push(
+        '1. Open Cheat Engine',
+        "2. Table -> Show Cheat Table Lua Script",
+        '3. Paste ce_mcp_bridge.lua content and Execute',
+        "4. Look for '[CheatEngine-MCP] Bridge started' message"
+      );
+    }
+
+    // Check 2: CE process
+    try {
+      const { execSync } = require('child_process');
+      const result = execSync('tasklist /FI "IMAGENAME eq cheatengine*" /FO CSV /NH', { 
+        encoding: 'utf-8',
+        timeout: 5000 
+      });
+      const ceRunning = result.toLowerCase().includes('cheatengine');
+      if (ceRunning) {
+        checks.push({
+          name: 'ce_process',
+          passed: true,
+          message: 'Cheat Engine is running',
+        });
+      } else {
+        allPassed = false;
+        checks.push({
+          name: 'ce_process',
+          passed: false,
+          message: 'Cheat Engine not found',
+        });
+        suggestions.unshift('Start Cheat Engine first!');
+      }
+    } catch (err) {
+      checks.push({
+        name: 'ce_process',
+        passed: null,
+        message: `Could not check: ${err.message}`,
+      });
+    }
+
+    // Check 3: Custom pipe name
+    const customPipe = process.env.CE_MCP_PIPE_NAME;
+    if (customPipe) {
+      checks.push({
+        name: 'custom_pipe',
+        passed: null,
+        message: `Using custom pipe: ${customPipe}`,
+      });
+      suggestions.push(`Ensure CE Lua also uses pipe name: ${customPipe}`);
+    }
+
+    return {
+      status: (allPassed && pipeExists) ? 'ok' : 'failed',
+      pipe_name: Config.PIPE_NAME,
+      checks,
+      suggestions: suggestions.length > 0 ? suggestions : ['Connection should work - try again'],
+    };
+  }
+
+  async executeTool(name, args) {
+    const luaCmd = this.toolRegistry.getLuaCommand(name);
+    if (!luaCmd) {
+      return { error: `Unknown tool: ${name}` };
+    }
+
+    const timeoutSeconds = this.timeoutManager.getTimeout(name);
+    const timeoutMs = timeoutSeconds * 1000;
+    const startTime = Date.now();
+
+    const response = await this.pipeClient.sendReceive(
+      { command: luaCmd, params: args },
+      timeoutMs,
+      name
+    );
+
+    const duration = (Date.now() - startTime) / 1000;
+    const isError = response.error !== undefined;
+    this.metricsCollector.recordCall(name, duration, isError);
+
+    if (isError) {
+      // For ce_ping, return diagnostic info on connection failure
+      if (name === 'ce_ping') {
+        const diag = await this._diagnoseConnection();
+        return { error: response.error, diagnostic: diag };
+      }
+      if (response.timeout_info) {
+        return {
+          error: response.error,
+          timeout_info: response.timeout_info,
+        };
+      }
+      return { error: response.error };
+    }
+
+    const result = response.result || response;
+
+    // Attach health and server metrics to ce_ping response
+    if (name === 'ce_ping') {
+      const healthMetrics = this.pipeClient.getHealthMetrics();
+      const serverMetrics = this.metricsCollector.getSummary();
+      if (typeof result === 'object' && result !== null) {
+        result.connection_health = healthMetrics;
+        result.server_metrics = serverMetrics;
+      } else {
+        return {
+          result,
+          connection_health: healthMetrics,
+          server_metrics: serverMetrics,
+        };
+      }
+    }
+
+    return result;
+  }
+
+  handleRequest(req) {
+    const method = req.method || '';
+    const reqId = req.id;
+    const params = req.params || {};
+
+    if (method === 'initialize') {
+      return this._handleInitialize(reqId);
+    } else if (method === 'notifications/initialized') {
+      return null;
+    } else if (method === 'tools/list') {
+      return this._handleToolsList(reqId);
+    } else if (method === 'tools/call') {
+      return this._handleToolsCall(reqId, params);
+    } else {
+      return this._errorResponse(reqId, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  _handleInitialize(reqId) {
+    return {
+      jsonrpc: '2.0',
+      id: reqId,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'cheatengine-mcp-bridge', version: '5.8.14' },
+        instructions: (
+          '# Cheat Engine MCP - AI Usage Guide\n\n' +
+          '## Tool Selection Decision Tree\n\n' +
+          '### Q: Do I know the address?\n' +
+          '- NO, but can observe value changes -> ce_scan_new workflow (value hunting)\n' +
+          '- YES, need stable pointer -> ce_find_pointer_path (auto) or manual F5+value_scan\n' +
+          '- YES, want to read/write -> ce_read_memory / ce_write_memory\n\n' +
+          '### Q: What am I searching for?\n' +
+          '- Game values (health, gold) -> ce_scan_new (NOT ce_value_scan!)\n' +
+          '- Code signatures -> ce_aob_scan (supports ?? wildcards)\n' +
+          '- Pointer storage locations -> ce_value_scan (after getting register value from F5)\n\n' +
+          '### Q: How to analyze code?\n' +
+          '- View execution flow -> ce_break_and_trace (dynamic, real execution)\n' +
+          '- Safely understand algorithm -> ce_symbolic_trace (static, no execution)\n' +
+          '- Function structure -> ce_build_cfg + ce_detect_patterns\n\n' +
+          '## Workflow Templates\n\n' +
+          '### 1. Value Hunting (find unknown address)\n' +
+          "1. ce_attach_process(target='game.exe')\n" +
+          "2. ce_scan_new(value='100', type='dword') -> returns session_id\n" +
+          '3. [Take damage in game, health becomes 95]\n' +
+          "4. ce_scan_next(session_id, value='95', scan_type='exact') -> count decreases\n" +
+          '5. Repeat steps 3-4 until count < 10\n' +
+          '6. ce_scan_results(session_id) -> get candidate addresses\n' +
+          "7. ce_read_memory(address, type='dword') -> verify correct address\n" +
+          '8. ce_scan_close(session_id) -> release resources (max 5 concurrent!)\n\n' +
+          '### 2. Pointer Tracing (make address stable)\n' +
+          "Method A (auto, try first): ce_find_pointer_path(address='0x12345678')\n" +
+          'Method B (manual, if A fails):\n' +
+          "1. ce_find_what_accesses(address='0x12345678', duration_ms=10000)\n" +
+          '2. Get register value from result (e.g., RBX=0x255D5E758)\n' +
+          "3. ce_value_scan(value='0x255D5E758', type='qword')\n" +
+          '4. Find result with isStatic=true -> that\'s your base pointer!\n\n' +
+          '### 3. Function Monitoring (non-blocking)\n' +
+          "1. ce_hook_function(address='game.exe+12345', name='damageHook')\n" +
+          '2. [Let game run, trigger events]\n' +
+          "3. ce_get_hook_log(name='damageHook') -> captured args (x64: RCX,RDX,R8,R9)\n" +
+          "4. ce_unhook_function(name='damageHook') -> cleanup when done\n\n" +
+          '## Tool Comparison (Correct vs Wrong)\n' +
+          '| Purpose | Correct | Wrong |\n' +
+          '| Find game values | ce_scan_new | ce_value_scan |\n' +
+          '| Find code signature | ce_aob_scan | ce_scan_new |\n' +
+          '| Batch read memory | ce_read_memory_batch | multiple ce_read_memory |\n' +
+          '| Monitor function | ce_hook_function | ce_break_and_get_regs |\n\n' +
+          '## System Limits\n' +
+          '- Scan sessions: max 5 (auto-expire after 5 min inactivity)\n' +
+          '- Hardware breakpoints: max 4 (shared by F5/F6/trace)\n' +
+          '- Hook buffer: 64 records (circular, oldest overwritten when full)\n' +
+          '- Pointer depth: max 10 levels\n' +
+          '- Message size: 10MB per request/response\n\n' +
+          '## Common Errors\n' +
+          "- 'Process not attached' -> call ce_attach_process first\n" +
+          "- 'Too many scan sessions' -> ce_scan_list() then ce_scan_close()\n" +
+          "- 'Hardware breakpoint limit' -> ce_cleanup() to clear all\n" +
+          "- 'Hook name already exists' -> ce_unhook_function(name) first"
+        ),
+      },
+    };
+  }
+
+  _handleToolsList(reqId) {
+    return {
+      jsonrpc: '2.0',
+      id: reqId,
+      result: { tools: this.toolRegistry.getAllSchemas() },
+    };
+  }
+
+  async _handleToolsCall(reqId, params) {
+    const toolName = params.name || '';
+    const toolArgs = params.arguments || {};
+
+    try {
+      const result = await this.executeTool(toolName, toolArgs);
+
+      // Check if error: has error field, success=false, and no partial results
+      let isError = false;
+      if (typeof result === 'object' && result !== null && result.error) {
+        const hasPartialResult = ['chain', 'path', 'partialCENotation', 'finalAddress'].some(k => k in result);
+        isError = result.success === false && !hasPartialResult;
+      }
+
+      const text = isError
+        ? `Error: ${result.error}`
+        : JSON.stringify(result, null, 2);
+
+      return {
+        jsonrpc: '2.0',
+        id: reqId,
+        result: {
+          content: [{ type: 'text', text }],
+          isError: isError,
+        },
+      };
+    } catch (err) {
+      return this._errorResponse(reqId, -32603, err.message);
+    }
+  }
+
+  _errorResponse(reqId, code, message) {
+    return {
+      jsonrpc: '2.0',
+      id: reqId,
+      error: { code, message },
+    };
+  }
+
+  async run() {
+    log.info('Cheat Engine MCP Bridge Started. Waiting for input...');
+    log.info(`Node.js version: ${process.version}`);
+
+    // Use raw stdin/stdout for MCP protocol - no readline to avoid buffering issues
+    process.stdin.setEncoding('utf8');
+    
+    let buffer = '';
+    
+    process.stdin.on('data', async (chunk) => {
+      buffer += chunk;
+      
+      // Process complete lines
+      let lines = buffer.split('\n');
+      buffer = lines.pop(); // Keep incomplete line in buffer
+      
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        
+        this.requestCount++;
+        
+        try {
+          const request = JSON.parse(line);
+          const response = this.handleRequest(request);
+          
+          if (response) {
+            // Handle async tool calls
+            if (response instanceof Promise) {
+              const result = await response;
+              process.stdout.write(JSON.stringify(result) + '\n');
+            } else {
+              process.stdout.write(JSON.stringify(response) + '\n');
+            }
+          }
+        } catch (err) {
+          if (err instanceof SyntaxError) {
+            log.error(`Failed to decode JSON: ${err.message}`);
+          } else {
+            log.error(`Critical Error (request #${this.requestCount}): ${err.stack}`);
+          }
+        }
+      }
+    });
+
+    process.stdin.on('end', () => {
+      log.info('Received end of input');
+      this.pipeClient.stop();
+      log.info(`Server Stopped (processed ${this.requestCount} requests)`);
+      process.exit(0);
+    });
+
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+      log.info('Received interrupt signal');
+      this.pipeClient.stop();
+      log.info(`Server Stopped (processed ${this.requestCount} requests)`);
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', () => {
+      log.info('Received terminate signal');
+      this.pipeClient.stop();
+      log.info(`Server Stopped (processed ${this.requestCount} requests)`);
+      process.exit(0);
+    });
+  }
+}
+
+// ============ Entry Point ============
+function main() {
+  const server = new CEMCPServer();
+  server.run();
+}
+
+main();

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "cheatengine",
-  "version": "5.8.14",
+  "version": "5.8.16",
   "description": "Cheat Engine MCP Server - AI-assisted reverse engineering bridge",
-  "main": "bin/cheatengine",
+  "main": "ce_mcp_server.js",
   "bin": {
     "cheatengine": "bin/cheatengine"
   },
   "scripts": {
-    "start": "node bin/cheatengine"
+    "start": "node ce_mcp_server.js",
+    "test": "node ce_mcp_server.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
   },
   "keywords": [
     "mcp",
@@ -19,12 +23,10 @@
   ],
   "author": "",
   "license": "MIT",
-  "engines": {
-    "node": ">=14.0.0"
-  },
   "files": [
     "bin/",
-    "ce_mcp_server.py",
+    "src/",
+    "ce_mcp_server.js",
     "README.md",
     "README_CN.md"
   ]