@createlex/createlexgenai 1.0.0

package/src/cli.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+
+function run(argv) {
+  const program = new Command();
+
+  program
+    .name('createlex')
+    .description('CreatelexGenAI CLI — Unreal Engine AI integration')
+    .version(pkg.version);
+
+  // MCP server mode
+  program
+    .command('serve')
+    .description('Start MCP server (stdio mode for AI CLI tools)')
+    .option('--port <port>', 'Run in TCP mode on specified port')
+    .option('--debug', 'Enable debug logging')
+    .action((opts) => {
+      const { serve } = require('./commands/serve');
+      serve(opts);
+    });
+
+  // Direct tool execution
+  program
+    .command('exec <tool>')
+    .description('Execute a tool directly against Unreal Engine')
+    .option('--port <port>', 'UE socket port', '9878')
+    .option('--backend <backend>', 'Connection backend: plugin, web-remote, remote-exec (auto-detects if omitted)')
+    .allowUnknownOption(true)
+    .action((tool, opts, cmd) => {
+      const { exec } = require('./commands/exec');
+      // Collect extra args as tool arguments
+      const extraArgs = cmd.args.slice(1);
+      exec(tool, extraArgs, opts);
+    });
+
+  // List available tools
+  program
+    .command('tools')
+    .description('List all available MCP tools')
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
+      const { tools } = require('./commands/tools');
+      tools(opts);
+    });
+
+  // Auth commands
+  program
+    .command('login')
+    .description('Authenticate with CreateLex')
+    .action(() => {
+      const { login } = require('./commands/login');
+      login();
+    });
+
+  program
+    .command('logout')
+    .description('Clear stored credentials')
+    .action(() => {
+      const { logout } = require('./commands/logout');
+      logout();
+    });
+
+  // Status & connection
+  program
+    .command('status')
+    .description('Show connection and subscription status')
+    .action(() => {
+      const { status } = require('./commands/status');
+      status();
+    });
+
+  program
+    .command('connect')
+    .description('Test connection to Unreal Engine')
+    .option('--port <port>', 'UE socket port', '9878')
+    .action((opts) => {
+      const { connect } = require('./commands/connect');
+      connect(opts);
+    });
+
+  // Configuration
+  program
+    .command('config')
+    .description('Manage configuration')
+    .argument('<action>', 'Action: get, set, list, reset')
+    .argument('[key]', 'Config key')
+    .argument('[value]', 'Config value')
+    .action((action, key, value) => {
+      const { config } = require('./commands/config');
+      config(action, key, value);
+    });
+
+  // IDE setup
+  program
+    .command('setup [ide]')
+    .description('Auto-configure MCP for an IDE (e.g., claude-code, cursor, windsurf)')
+    .option('--all', 'Configure all detected IDEs')
+    .action((ide, opts) => {
+      const { setup } = require('./commands/setup');
+      setup(ide, opts);
+    });
+
+  program.parse(argv);
+}
+
+module.exports = { run };

package/src/commands/config.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const log = require('../utils/logger');
+const configStore = require('../core/config-store');
+
+function config(action, key, value) {
+  switch (action) {
+    case 'list': {
+      const all = configStore.list();
+      log.header('Configuration');
+      for (const [k, v] of Object.entries(all)) {
+        log.keyValue(k, v);
+      }
+      break;
+    }
+
+    case 'get': {
+      if (!key) {
+        log.error('Usage: createlex config get <key>');
+        process.exit(1);
+      }
+      const val = configStore.get(key);
+      if (val === undefined) {
+        log.error(`Unknown config key: ${key}`);
+        process.exit(1);
+      }
+      console.log(val);
+      break;
+    }
+
+    case 'set': {
+      if (!key || value === undefined) {
+        log.error('Usage: createlex config set <key> <value>');
+        process.exit(1);
+      }
+      const updated = configStore.set(key, value);
+      log.success(`Set ${key} = ${updated[key]}`);
+      break;
+    }
+
+    case 'reset': {
+      const defaults = configStore.reset();
+      log.success('Configuration reset to defaults');
+      for (const [k, v] of Object.entries(defaults)) {
+        log.keyValue(k, v);
+      }
+      break;
+    }
+
+    default:
+      log.error(`Unknown action: ${action}. Use: get, set, list, reset`);
+      process.exit(1);
+  }
+}
+
+module.exports = { config };

package/src/commands/connect.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const log = require('../utils/logger');
+const chalk = require('chalk');
+const { detectBackends, BACKEND } = require('../core/unreal-connection');
+
+async function connect(opts = {}) {
+  const pluginPort = parseInt(opts.port, 10) || 9878;
+
+  log.header('Unreal Engine Connection Test');
+  log.info('Scanning all connection backends...');
+  log.blank();
+
+  const backends = await detectBackends({ pluginPort });
+
+  let anyConnected = false;
+
+  // 1. CreatelexGenAI Plugin (TCP 9878)
+  const plugin = backends[BACKEND.PLUGIN];
+  if (plugin.connected) {
+    log.success(`${plugin.name}: Connected (port ${pluginPort})`);
+    log.keyValue('    Features', 'Full 71+ tools, MCP server, direct exec');
+    anyConnected = true;
+  } else {
+    log.warn(`${plugin.name}: Not available`);
+    log.keyValue('    Requires', 'CreatelexGenAI plugin enabled in UE');
+    log.keyValue('    Port', pluginPort);
+  }
+
+  log.blank();
+
+  // 2. Web Remote Control (HTTP 30010)
+  const webRemote = backends[BACKEND.WEB_REMOTE];
+  if (webRemote.connected) {
+    log.success(`${webRemote.name}: Connected (port ${webRemote.port || 30010})`);
+    if (webRemote.verified) {
+      log.keyValue('    Features', 'Call UFunctions, get/set properties, console commands, Python exec');
+    } else {
+      log.keyValue('    Status', chalk.yellow('Server responds but function calls unverified'));
+    }
+    anyConnected = true;
+  } else {
+    log.warn(`${webRemote.name}: Not available`);
+    log.keyValue('    Requires', 'Web Remote Control plugin in UE (built-in)');
+    log.keyValue('    Enable', 'Edit > Plugins > "Web Remote Control" + run WebControl.StartServer');
+  }
+
+  log.blank();
+
+  // 3. Python Remote Execution (UDP 6766)
+  const remoteExec = backends[BACKEND.REMOTE_EXEC];
+  if (remoteExec.connected) {
+    log.success(`${remoteExec.name}: Available`);
+    if (remoteExec.nodes && remoteExec.nodes.length > 0) {
+      for (const node of remoteExec.nodes) {
+        log.keyValue('    Node', `${node.machine} (${node.engine_version})`);
+      }
+    }
+    log.keyValue('    Features', 'Execute Python scripts inside UE editor');
+    anyConnected = true;
+  } else {
+    log.warn(`${remoteExec.name}: Not available`);
+    log.keyValue('    Requires', 'Python Editor Script Plugin + "Allow Python Remote Execution" in Project Settings');
+  }
+
+  log.blank();
+
+  if (anyConnected) {
+    log.success('Unreal Engine is reachable!');
+
+    if (!plugin.connected && (webRemote.connected || remoteExec.connected)) {
+      log.blank();
+      log.info(chalk.yellow('Note: Without the CreatelexGenAI plugin, only a subset of tools are available.'));
+      log.info('Available without plugin:');
+      log.info('  - execute_python_script');
+      log.info('  - execute_unreal_command');
+      log.info('  - get_all_scene_objects');
+      log.info('  - spawn_object (basic)');
+      log.blank();
+      log.info('For full 71+ tools, enable the CreatelexGenAI plugin.');
+    }
+  } else {
+    log.error('No Unreal Engine connection found.');
+    log.blank();
+    log.info('To connect, you need at least one of:');
+    log.blank();
+    log.info(chalk.bold('  Option 1: CreatelexGenAI Plugin') + ' (recommended — full features)');
+    log.info('    Enable the plugin in your UE project');
+    log.blank();
+    log.info(chalk.bold('  Option 2: Web Remote Control') + ' (built-in UE plugin)');
+    log.info('    Edit > Plugins > "Web Remote Control" > Enable');
+    log.info('    Then run: WebControl.StartServer in console');
+    log.blank();
+    log.info(chalk.bold('  Option 3: Python Remote Execution') + ' (built-in UE plugin)');
+    log.info('    Edit > Plugins > "Python Editor Script Plugin" > Enable');
+    log.info('    Project Settings > Python > "Allow Python Remote Execution" > Check');
+  }
+}
+
+module.exports = { connect };

package/src/commands/exec.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const log = require('../utils/logger');
+const authManager = require('../core/auth-manager');
+const { executeWithBackend, autoSelectBackend, BACKEND } = require('../core/unreal-connection');
+
+async function exec(tool, extraArgs, opts = {}) {
+  // Auth check
+  const token = authManager.getToken();
+  if (!token) {
+    log.error('Not authenticated. Run `createlex login` first.');
+    process.exit(1);
+  }
+
+  const validation = authManager.validateTokenFormat(token);
+  if (!validation.valid) {
+    log.error('Token expired or invalid. Run `createlex login`.');
+    process.exit(1);
+  }
+
+  // Parse extra args into a params object
+  // Supports: --key value, --key=value, --flag (boolean true)
+  const params = {};
+  for (let i = 0; i < extraArgs.length; i++) {
+    const arg = extraArgs[i];
+    if (arg.startsWith('--')) {
+      const eqIndex = arg.indexOf('=');
+      if (eqIndex !== -1) {
+        const key = arg.slice(2, eqIndex).replace(/-/g, '_');
+        params[key] = arg.slice(eqIndex + 1);
+      } else {
+        const key = arg.slice(2).replace(/-/g, '_');
+        const next = extraArgs[i + 1];
+        if (next && !next.startsWith('--')) {
+          params[key] = next;
+          i++;
+        } else {
+          params[key] = true;
+        }
+      }
+    }
+  }
+
+  const port = parseInt(opts.port, 10) || 9878;
+
+  // Determine backend
+  let backendId = opts.backend || null;
+
+  if (!backendId) {
+    // Auto-detect best backend
+    const selected = await autoSelectBackend({ pluginPort: port });
+    if (!selected.backend) {
+      log.error('No Unreal Engine connection available. Run `createlex connect` to diagnose.');
+      process.exit(1);
+    }
+    backendId = selected.backend;
+    log.info(`Using backend: ${selected.info.name}`);
+  }
+
+  log.info(`Executing tool: ${tool}`);
+  if (Object.keys(params).length > 0) {
+    log.debug(`Parameters: ${JSON.stringify(params)}`);
+  }
+
+  try {
+    const result = await executeWithBackend(tool, params, {
+      port,
+      backend: backendId
+    });
+
+    // Format output based on backend response format
+    if (backendId === BACKEND.PLUGIN) {
+      formatPluginResult(result);
+    } else if (backendId === BACKEND.REMOTE_EXEC) {
+      formatRemoteExecResult(result);
+    } else if (backendId === BACKEND.WEB_REMOTE) {
+      formatWebRemoteResult(result);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+}
+
+function formatPluginResult(result) {
+  if (result.error) {
+    log.error(`Tool error: ${result.error.message || JSON.stringify(result.error)}`);
+    process.exit(1);
+  }
+
+  if (result.result) {
+    const content = result.result.content || result.result;
+    if (Array.isArray(content)) {
+      for (const item of content) {
+        if (item.type === 'text') {
+          console.log(item.text);
+        } else {
+          console.log(JSON.stringify(item, null, 2));
+        }
+      }
+    } else if (typeof content === 'object') {
+      console.log(JSON.stringify(content, null, 2));
+    } else {
+      console.log(content);
+    }
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+function formatRemoteExecResult(result) {
+  if (!result.success) {
+    log.error('Execution failed');
+    if (result.outputLog) {
+      for (const entry of result.outputLog) {
+        if (entry.type === 'error' || entry.type === 'warning') {
+          log.warn(entry.message);
+        }
+      }
+    }
+    process.exit(1);
+  }
+
+  // Print output
+  if (result.output) {
+    console.log(result.output);
+  }
+  if (result.result !== null && result.result !== undefined) {
+    console.log(typeof result.result === 'string' ? result.result : JSON.stringify(result.result, null, 2));
+  }
+  if (result.outputLog && result.outputLog.length > 0) {
+    for (const entry of result.outputLog) {
+      console.log(`[${entry.type}] ${entry.message}`);
+    }
+  }
+}
+
+function formatWebRemoteResult(result) {
+  if (typeof result === 'object') {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result);
+  }
+}
+
+module.exports = { exec };

package/src/commands/login.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const http = require('http');
+const crypto = require('crypto');
+const log = require('../utils/logger');
+const authManager = require('../core/auth-manager');
+const configStore = require('../core/config-store');
+
+async function login() {
+  const existing = authManager.getToken();
+  if (existing) {
+    const validation = authManager.validateTokenFormat(existing);
+    if (validation.valid) {
+      log.info('Already logged in. Use `createlex logout` first to re-authenticate.');
+      return;
+    }
+    log.warn('Existing token is expired or invalid. Starting fresh login...');
+  }
+
+  const state = crypto.randomBytes(16).toString('hex');
+  const webBaseUrl = configStore.get('webBaseUrl') || 'https://createlex.com';
+
+  // Start a temporary local server to receive the auth callback
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+
+    if (url.pathname === '/callback') {
+      const token = url.searchParams.get('token');
+      const returnedState = url.searchParams.get('state');
+
+      if (returnedState !== state) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Authentication failed: state mismatch</h2></body></html>');
+        return;
+      }
+
+      if (!token) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h2>Authentication failed: no token received</h2></body></html>');
+        return;
+      }
+
+      const validation = authManager.validateTokenFormat(token);
+      if (!validation.valid) {
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(`<html><body><h2>Authentication failed: ${validation.reason}</h2></body></html>`);
+        return;
+      }
+
+      // Store the token
+      authManager.setToken(token, {
+        email: validation.payload?.email,
+        userId: validation.payload?.sub || validation.payload?.userId
+      });
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end('<html><body><h2>Authentication successful!</h2><p>You can close this window and return to the terminal.</p></body></html>');
+
+      log.blank();
+      log.success('Login successful!');
+
+      if (validation.payload?.email) {
+        log.keyValue('Email', validation.payload.email);
+      }
+
+      server.close();
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+
+  // Find an available port
+  await new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', () => resolve());
+    server.on('error', reject);
+  });
+
+  const port = server.address().port;
+  const callbackUrl = encodeURIComponent(`http://localhost:${port}/callback`);
+  const authUrl = `${webBaseUrl}/auth/cli?callback=${callbackUrl}&state=${state}`;
+
+  log.header('CreateLex Login');
+  log.info('Opening browser for authentication...');
+  log.blank();
+  log.info(`If the browser doesn't open, visit:`);
+  log.info(authUrl);
+  log.blank();
+
+  try {
+    const open = require('open');
+    await open(authUrl);
+  } catch {
+    log.warn('Could not open browser automatically. Please visit the URL above.');
+  }
+
+  log.info('Waiting for authentication...');
+
+  // Timeout after 5 minutes
+  const timeout = setTimeout(() => {
+    log.error('Authentication timed out after 5 minutes.');
+    server.close();
+    process.exit(1);
+  }, 5 * 60 * 1000);
+
+  server.on('close', () => {
+    clearTimeout(timeout);
+  });
+}
+
+module.exports = { login };

package/src/commands/logout.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const log = require('../utils/logger');
+const authManager = require('../core/auth-manager');
+
+function logout() {
+  const existing = authManager.getToken();
+  if (!existing) {
+    log.info('Not currently logged in.');
+    return;
+  }
+
+  authManager.clearAuth();
+  log.success('Logged out. Credentials cleared.');
+}
+
+module.exports = { logout };