cheatengine 5.8.13 → 5.8.15

package/src/base.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// -*- coding: utf-8 -*-
+/**
+ * Cheat Engine MCP Server - Named pipe bridge to Cheat Engine
+ * JavaScript/Node.js version
+ */
+
+const net = require('net');
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+// ============ Configuration ============
+const Config = {
+  PIPE_NAME: `\\\\.\\pipe\\${process.env.CE_MCP_PIPE_NAME || 'ce_mcp_bridge'}`,
+  AUTH_TOKEN: process.env.CE_MCP_AUTH_TOKEN || null,
+  MAX_RETRIES: 3,
+  CHUNK_SIZE: 1024 * 1024,
+  MAX_RESPONSE_SIZE: 10 * 1024 * 1024,
+  DEBUG: process.env.DEBUG === '1' || false,
+};
+
+// ============ Timeout Error ============
+class TimeoutError extends Error {
+  constructor(toolName, params, elapsedTime, timeout) {
+    super(`Tool '${toolName}' timed out after ${elapsedTime.toFixed(2)}s (timeout: ${timeout}s)`);
+    this.toolName = toolName;
+    this.params = params;
+    this.elapsedTime = elapsedTime;
+    this.timeout = timeout;
+  }
+}
+
+// ============ Logger ============
+class Logger {
+  static log(msg, level = 'INFO') {
+    if (level === 'DEBUG' && !Config.DEBUG) return;
+    process.stderr.write(`[CheatEngine-MCP-${level}] ${msg}\n`);
+  }
+
+  static info(msg) {
+    Logger.log(msg, 'INFO');
+  }
+
+  static debug(msg) {
+    Logger.log(msg, 'DEBUG');
+  }
+
+  static error(msg) {
+    Logger.log(msg, 'ERROR');
+  }
+}
+
+const log = Logger;
+
+// ============ Connection Health Monitoring ============
+class ConnectionHealth {
+  constructor() {
+    this.lastSuccessTime = 0.0;
+    this.connectionAttempts = 0;
+    this.consecutiveErrors = 0;
+    this.totalErrors = 0;
+    this.lastError = null;
+    this.isConnected = false;
+  }
+}
+
+class HealthMonitor {
+  constructor(errorThreshold = 5) {
+    this.health = new ConnectionHealth();
+    this.errorThreshold = errorThreshold;
+  }
+
+  recordSuccess() {
+    this.health.lastSuccessTime = Date.now() / 1000;
+    this.health.consecutiveErrors = 0;
+    this.health.isConnected = true;
+  }
+
+  recordError(error) {
+    this.health.consecutiveErrors++;
+    this.health.totalErrors++;
+    this.health.lastError = error;
+    this.health.isConnected = false;
+    return this.health.consecutiveErrors >= this.errorThreshold;
+  }
+
+  recordConnectionAttempt() {
+    this.health.connectionAttempts++;
+  }
+
+  getMetrics() {
+    return {
+      last_success_time: this.health.lastSuccessTime,
+      connection_attempts: this.health.connectionAttempts,
+      consecutive_errors: this.health.consecutiveErrors,
+      total_errors: this.health.totalErrors,
+      last_error: this.health.lastError,
+      is_connected: this.health.isConnected,
+    };
+  }
+
+  reset() {
+    this.health = new ConnectionHealth();
+  }
+}
+
+// ============ Timeout Manager ============
+class TimeoutManager {
+  static DEFAULT_TIMEOUT = 30;
+
+  static TOOL_TIMEOUTS = {
+    ce_find_pointer_path: 60,
+    ce_break_and_trace: 60,
+    ce_find_what_accesses: 30,
+    ce_find_what_writes: 30,
+    ce_aob_scan: 30,
+    ce_value_scan: 30,
+    ce_scan_new: 30,
+    ce_scan_next: 30,
+    ce_build_cfg: 45,
+    ce_symbolic_trace: 45,
+    ce_call_function: 30,
+  };
+
+  constructor(defaultTimeout = null, toolTimeouts = null) {
+    this.defaultTimeout = defaultTimeout !== null ? defaultTimeout : TimeoutManager.DEFAULT_TIMEOUT;
+    this.toolTimeouts = { ...TimeoutManager.TOOL_TIMEOUTS };
+    if (toolTimeouts) {
+      Object.assign(this.toolTimeouts, toolTimeouts);
+    }
+  }
+
+  getTimeout(toolName) {
+    return this.toolTimeouts[toolName] || this.defaultTimeout;
+  }
+
+  setTimeout(toolName, timeout) {
+    this.toolTimeouts[toolName] = timeout;
+  }
+
+  getAllTimeouts() {
+    return {
+      default_timeout: this.defaultTimeout,
+      tool_timeouts: { ...this.toolTimeouts },
+    };
+  }
+}
+
+// ============ Metrics Collector ============
+class ToolMetrics {
+  constructor() {
+    this.callCount = 0;
+    this.totalTime = 0.0;
+    this.errorCount = 0;
+    this.lastCallTime = 0.0;
+  }
+}
+
+class MetricsCollector {
+  constructor() {
+    this.toolMetrics = new Map();
+    this.startTime = Date.now() / 1000;
+  }
+
+  recordCall(toolName, duration, isError = false) {
+    if (!this.toolMetrics.has(toolName)) {
+      this.toolMetrics.set(toolName, new ToolMetrics());
+    }
+
+    const metrics = this.toolMetrics.get(toolName);
+    metrics.callCount++;
+    metrics.totalTime += duration;
+    metrics.lastCallTime = Date.now() / 1000;
+    if (isError) {
+      metrics.errorCount++;
+    }
+  }
+
+  getToolMetrics(toolName) {
+    const metrics = this.toolMetrics.get(toolName);
+    if (!metrics) return null;
+
+    return {
+      calls: metrics.callCount,
+      total_time: metrics.totalTime,
+      avg_time: metrics.callCount > 0 ? metrics.totalTime / metrics.callCount : 0,
+      errors: metrics.errorCount,
+      error_rate: metrics.callCount > 0 ? metrics.errorCount / metrics.callCount : 0,
+      last_call_time: metrics.lastCallTime,
+    };
+  }
+
+  getSummary() {
+    let totalCalls = 0;
+    let totalErrors = 0;
+    const tools = {};
+
+    for (const [name, metrics] of this.toolMetrics) {
+      totalCalls += metrics.callCount;
+      totalErrors += metrics.errorCount;
+      tools[name] = {
+        calls: metrics.callCount,
+        avg_time: metrics.callCount > 0 ? metrics.totalTime / metrics.callCount : 0,
+        errors: metrics.errorCount,
+        error_rate: metrics.callCount > 0 ? metrics.errorCount / metrics.callCount : 0,
+      };
+    }
+
+    return {
+      uptime: Date.now() / 1000 - this.startTime,
+      total_calls: totalCalls,
+      total_errors: totalErrors,
+      error_rate: totalCalls > 0 ? totalErrors / totalCalls : 0,
+      tools,
+    };
+  }
+
+  reset() {
+    this.toolMetrics.clear();
+    this.startTime = Date.now() / 1000;
+  }
+}
+
+module.exports = {
+  Config,
+  TimeoutError,
+  ConnectionHealth,
+  HealthMonitor,
+  TimeoutManager,
+  ToolMetrics,
+  MetricsCollector,
+  Logger,
+  log,
+};

package/src/pipe-client.js

@@ -0,0 +1,316 @@
+/**
+ * Windows Named Pipe Client for Cheat Engine MCP Bridge
+ * Uses Node.js net module to connect to Windows named pipes
+ */
+
+const net = require('net');
+const { EventEmitter } = require('events');
+const { Config, HealthMonitor, Logger, log } = require('./base');
+
+// Windows error codes
+const ERROR_FILE_NOT_FOUND = 2;
+const ERROR_PIPE_BUSY = 231;
+const ERROR_ACCESS_DENIED = 5;
+const ERROR_BROKEN_PIPE = 109;
+const ERROR_PIPE_NOT_CONNECTED = 233;
+
+class PipeClient extends EventEmitter {
+  constructor(pipeName = Config.PIPE_NAME, errorThreshold = 5) {
+    super();
+    this.pipeName = pipeName;
+    this.socket = null;
+    this.healthMonitor = new HealthMonitor(errorThreshold);
+    this.reconnectTimer = null;
+    this.stopReconnectFlag = false;
+    this.connected = false;
+    this.connectionAttempts = 0;
+    this.lastError = null;
+    this.lastConnectErrorCode = null;
+    this.lastSuccessTime = 0;
+    this.responseBuffer = Buffer.alloc(0);
+    this.pendingResponse = null;
+  }
+
+  isValid() {
+    return this.socket !== null && this.connected && !this.socket.destroyed;
+  }
+
+  async _tryConnectOnce() {
+    return new Promise((resolve) => {
+      try {
+        const socket = net.createConnection(this.pipeName, () => {
+          this.socket = socket;
+          this.connected = true;
+          this.lastError = null;
+          this.lastConnectErrorCode = null;
+          this.lastSuccessTime = Date.now() / 1000;
+          log.info('Connected to Cheat Engine Pipe');
+          this.healthMonitor.recordSuccess();
+          resolve(true);
+        });
+
+        socket.on('error', (err) => {
+          this.lastConnectErrorCode = err.code;
+          this.lastError = err.message;
+          
+          // Handle specific error codes
+          if (err.code === 'ENOENT') {
+            this.lastConnectErrorCode = ERROR_FILE_NOT_FOUND;
+          } else if (err.code === 'EACCES') {
+            this.lastConnectErrorCode = ERROR_ACCESS_DENIED;
+          } else if (err.message && err.message.includes('EBUSY')) {
+            this.lastConnectErrorCode = ERROR_PIPE_BUSY;
+          }
+          
+          resolve(false);
+        });
+
+        socket.on('close', () => {
+          this.connected = false;
+          if (this.socket) {
+            this.socket = null;
+          }
+        });
+
+        socket.on('data', (data) => {
+          this._handleData(data);
+        });
+
+      } catch (err) {
+        this.lastError = err.message;
+        resolve(false);
+      }
+    });
+  }
+
+  _handleData(data) {
+    this.responseBuffer = Buffer.concat([this.responseBuffer, data]);
+    
+    // Try to parse response
+    if (this.pendingResponse && this.responseBuffer.length >= 4) {
+      const respLen = this.responseBuffer.readUInt32LE(0);
+      
+      if (respLen === 0 || respLen > Config.MAX_RESPONSE_SIZE) {
+        this.pendingResponse.reject(new Error(`Invalid response size: ${respLen}`));
+        this.pendingResponse = null;
+        this.responseBuffer = Buffer.alloc(0);
+        return;
+      }
+
+      if (this.responseBuffer.length >= 4 + respLen) {
+        const respData = this.responseBuffer.slice(4, 4 + respLen);
+        this.responseBuffer = this.responseBuffer.slice(4 + respLen);
+        
+        try {
+          const decoded = this._decodeResponse(respData);
+          const result = JSON.parse(decoded);
+          this.pendingResponse.resolve(result);
+        } catch (err) {
+          this.pendingResponse.reject(err);
+        }
+        this.pendingResponse = null;
+      }
+    }
+  }
+
+  _decodeResponse(data) {
+    // Try multiple encodings
+    const encodings = ['utf-8', 'latin1'];
+    for (const encoding of encodings) {
+      try {
+        return data.toString(encoding);
+      } catch (err) {
+        continue;
+      }
+    }
+    return data.toString('utf-8');
+  }
+
+  async _reconnectLoop() {
+    let backoff = 0.5;
+    const maxBackoff = 10.0;
+
+    while (!this.stopReconnectFlag) {
+      if (!this.isValid()) {
+        this.connectionAttempts++;
+        this.healthMonitor.recordConnectionAttempt();
+
+        if (await this._tryConnectOnce()) {
+          backoff = 0.5;
+        } else {
+          backoff = Math.min(backoff * 1.5, maxBackoff);
+        }
+      } else {
+        backoff = 0.5;
+      }
+
+      await this._sleep(backoff * 1000);
+    }
+  }
+
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  startBackgroundReconnect() {
+    if (this.reconnectTimer) return;
+    this.stopReconnectFlag = false;
+    this._reconnectLoop();
+  }
+
+  async connect(force = false, timeout = 3000) {
+    if (!force && this.isValid()) {
+      return true;
+    }
+
+    // Try immediate connection
+    this.connectionAttempts++;
+    this.healthMonitor.recordConnectionAttempt();
+    if (await this._tryConnectOnce()) {
+      return true;
+    }
+
+    // Start background reconnect and wait
+    this.startBackgroundReconnect();
+    
+    // Wait for connection with timeout
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      if (this.isValid()) return true;
+      await this._sleep(100);
+    }
+    return false;
+  }
+
+  _close() {
+    this.connected = false;
+    if (this.socket) {
+      try {
+        this.socket.destroy();
+      } catch (err) {
+        // Ignore
+      }
+      this.socket = null;
+    }
+  }
+
+  _getConnectionErrorMessage(winerrorCode, attempt) {
+    const messages = {
+      [ERROR_FILE_NOT_FOUND]: (
+        "Cheat Engine MCP Bridge not running. " +
+        "Load 'ce_mcp_bridge.lua' in CE (Table -> Show Cheat Table Lua Script -> Execute)"
+      ),
+      [ERROR_PIPE_BUSY]: "Pipe busy - another client may be connected",
+      [ERROR_ACCESS_DENIED]: "Access denied - try running as administrator",
+      [ERROR_BROKEN_PIPE]: "Connection lost - restart bridge script in CE",
+    };
+    
+    const baseMsg = messages[winerrorCode] || `Connection failed (error ${winerrorCode})`;
+    return `${baseMsg} [attempt ${attempt}/${Config.MAX_RETRIES}]`;
+  }
+
+  async _doSendReceive(data) {
+    // Add authentication token if configured
+    if (Config.AUTH_TOKEN) {
+      data = { ...data, auth_token: Config.AUTH_TOKEN };
+    }
+
+    for (let retry = 0; retry < Config.MAX_RETRIES; retry++) {
+      const connected = await this.connect(retry > 0);
+      if (!connected) {
+        if (this.lastConnectErrorCode) {
+          return {
+            error: this._getConnectionErrorMessage(this.lastConnectErrorCode, retry + 1)
+          };
+        }
+        return {
+          error: `Cannot connect to CE (attempt ${retry + 1}/${Config.MAX_RETRIES})`
+        };
+      }
+
+      try {
+        const jsonStr = JSON.stringify(data);
+        const jsonBytes = Buffer.from(jsonStr, 'utf-8');
+        const lenBuffer = Buffer.alloc(4);
+        lenBuffer.writeUInt32LE(jsonBytes.length, 0);
+
+        // Send request
+        this.socket.write(lenBuffer);
+        this.socket.write(jsonBytes);
+
+        // Wait for response
+        const result = await this._waitForResponse();
+        this.lastSuccessTime = Date.now() / 1000;
+        this.healthMonitor.recordSuccess();
+        return result;
+
+      } catch (err) {
+        log.debug(`Pipe error (attempt ${retry + 1}): ${err.message}`);
+        this.healthMonitor.recordError(err.message);
+        this._close();
+        await this._sleep(100 * (retry + 1));
+      }
+    }
+
+    return { error: this.lastError || "Connection failed after retries" };
+  }
+
+  _waitForResponse() {
+    return new Promise((resolve, reject) => {
+      this.pendingResponse = { resolve, reject };
+      this.responseBuffer = Buffer.alloc(0);
+    });
+  }
+
+  async sendReceive(data, timeout = 30000, toolName = null) {
+    const timeoutSeconds = timeout / 1000.0;
+    const startTime = Date.now();
+
+    // Create timeout promise
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        const elapsedTime = (Date.now() - startTime) / 1000;
+        const errorMsg = `Tool execution timed out after ${elapsedTime.toFixed(2)}s (timeout: ${timeoutSeconds}s)`;
+        log.error(`Timeout: tool=${toolName || 'unknown'}, params=${JSON.stringify(data.params || {})}, elapsed=${elapsedTime.toFixed(2)}s`);
+        this.healthMonitor.recordError(errorMsg);
+        reject(new TimeoutError(toolName || data.command || 'unknown', data.params || {}, elapsedTime, timeoutSeconds));
+      }, timeout);
+    });
+
+    try {
+      const result = await Promise.race([
+        this._doSendReceive(data),
+        timeoutPromise
+      ]);
+      return result;
+    } catch (err) {
+      if (err instanceof TimeoutError) {
+        return {
+          error: err.message,
+          timeout_info: {
+            tool_name: toolName || data.command || 'unknown',
+            params: data.params || {},
+            elapsed_time: err.elapsedTime,
+            timeout_seconds: err.timeout,
+          },
+        };
+      }
+      return { error: err.message };
+    }
+  }
+
+  getHealthMetrics() {
+    return this.healthMonitor.getMetrics();
+  }
+
+  stop() {
+    this.stopReconnectFlag = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this._close();
+  }
+}
+
+module.exports = { PipeClient };