@createlex/createlexgenai 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# @createlex/createlexgenai
+
+CLI tool for integrating AI-powered tools with Unreal Engine. Works as an MCP server for AI CLI tools (Claude Code, Codex CLI, Gemini CLI, etc.) or as a standalone command-line interface.
+
+**71+ tools** for spawning actors, creating Blueprints, managing materials, UI widgets, physics, project architecture, and more — all without requiring a custom UE plugin.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @createlex/createlexgenai
+
+# Authenticate
+createlex login
+
+# Check everything is working
+createlex status
+
+# Set up your AI tool
+createlex setup claude-code
+```
+
+## Requirements
+
+- **Node.js 18+**
+- **Unreal Engine 5.x** with at least one backend enabled (see below)
+- **Python 3.10+** (for MCP serve mode)
+- **CreateLex account** with active subscription
+
+## Setup Guide (No Plugin Required)
+
+### Step 1: Install the CLI
+
+```bash
+npm install -g @createlex/createlexgenai
+```
+
+Or run without installing:
+
+```bash
+npx @createlex/createlexgenai --version
+```
+
+### Step 2: Authenticate
+
+```bash
+createlex login
+```
+
+This opens your browser to sign in. Your token is saved to `~/.createlex/auth.json`.
+
+Verify:
+
+```bash
+createlex status
+```
+
+### Step 3: Enable UE Built-in Backends
+
+You need **at least one** of these enabled in your Unreal project. Both are built into UE — no custom plugin required.
+
+#### Option A: Web Remote Control (Recommended)
+
+1. Open your UE project
+2. Go to **Edit > Plugins**
+3. Search for **"Web Remote Control"** and enable it
+4. Restart the editor
+5. Go to **Edit > Project Settings > Plugins > Remote Control**
+6. Check **"Enable Remote Control Web Server"**
+7. Set port to **30010** (default)
+8. Ensure **"Enable HTTP Server"** is checked
+
+#### Option B: Python Remote Execution
+
+1. Open your UE project
+2. Go to **Edit > Plugins**
+3. Search for **"Python Editor Script Plugin"** and enable it
+4. Restart the editor
+5. Go to **Edit > Project Settings > Plugins > Python**
+6. Check **"Enable Remote Execution"**
+7. Multicast group: `239.0.0.1`, port: `6766` (defaults)
+
+> **Tip:** Enable both for maximum reliability. If one backend is unavailable, the CLI automatically falls back to the other.
+
+### Step 4: Verify Connection
+
+```bash
+createlex connect
+```
+
+Expected output (without plugin):
+
+```
+Plugin (TCP 9878): Not connected
+Web Remote Control (HTTP 30010): Connected
+Remote Execution (UDP 6766): Available
+```
+
+### Step 5: Configure Your AI Tool / IDE
+
+#### Automatic Setup
+
+```bash
+# Set up a specific IDE
+createlex setup <ide>
+
+# Set up all detected IDEs at once
+createlex setup --all
+```
+
+#### Supported IDEs
+
+| IDE | Command | Config Location |
+|---|---|---|
+| Claude Code | `createlex setup claude-code` | CLI command (manual) |
+| Cursor | `createlex setup cursor` | `~/.cursor/mcp.json` |
+| Windsurf | `createlex setup windsurf` | `~/.codeium/windsurf/mcp_config.json` |
+| Claude Desktop | `createlex setup claude-desktop` | `%APPDATA%/Claude/claude_desktop_config.json` |
+| VS Code | `createlex setup vscode` | `.vscode/settings.json` |
+| Antigravity | `createlex setup antigravity` | `~/.gemini/antigravity/mcp_config.json` |
+| Gemini CLI | `createlex setup gemini-cli` | `~/.gemini/settings.json` |
+| Kiro | `createlex setup kiro` | `~/.kiro/settings/mcp.json` |
+| Trae | `createlex setup trae` | `%APPDATA%/Trae/User/mcp.json` |
+| Augment | `createlex setup augment` | `~/.augment/mcp.json` |
+| Codex | `createlex setup codex` | `~/.codex/config.toml` |
+
+#### Manual IDE Configuration
+
+All IDEs use the same MCP server command:
+
+```
+npx @createlex/createlexgenai serve
+```
+
+**Claude Code:**
+```bash
+claude mcp add createlex-unreal -- npx @createlex/createlexgenai serve
+```
+
+**Codex CLI** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.createlex-unreal]
+command = "npx"
+args = ["@createlex/createlexgenai", "serve"]
+```
+
+**JSON-based IDEs** (Cursor, Windsurf, Claude Desktop, etc.):
+```json
+{
+  "mcpServers": {
+    "createlex-unreal": {
+      "command": "npx",
+      "args": ["@createlex/createlexgenai", "serve"]
+    }
+  }
+}
+```
+
+### Step 6: Start Using It
+
+Once configured, your AI tool has access to all 71+ Unreal Engine tools. Try:
+
+- *"Spawn a cube at the origin"*
+- *"Create a Blueprint called BP_Enemy based on Character"*
+- *"List all actors in the scene"*
+- *"Create a medieval town"*
+
+## CLI Commands
+
+```bash
+# MCP server mode (for AI CLI tools)
+createlex serve                    # stdio MCP server
+createlex serve --port 38080       # TCP MCP server
+
+# Direct tool execution
+createlex exec <tool> [--key value ...]
+createlex exec get_all_scene_objects
+createlex exec spawn_object --actor-class StaticMeshActor --location "0,0,0"
+createlex exec execute_python_script --script "print('Hello from UE!')"
+
+# List available tools
+createlex tools                    # Formatted list
+createlex tools --json             # JSON output
+
+# Auth
+createlex login                    # Browser auth flow
+createlex logout                   # Clear credentials
+
+# Status & connection
+createlex status                   # Auth + subscription + UE connection info
+createlex connect                  # Test UE connection, show setup tips
+
+# Configuration
+createlex config list              # Show all settings
+createlex config get unrealPort    # Get a specific value
+createlex config set unrealPort 9879
+createlex config reset             # Reset to defaults
+
+# IDE setup
+createlex setup                    # List supported IDEs
+createlex setup claude-code        # Set up specific IDE
+createlex setup --all              # Set up all detected IDEs
+```
+
+## How Connection Fallback Works
+
+When a tool is executed, the CLI tries backends in this order:
+
+1. **CreatelexGenAI Plugin** (TCP port 9878) — Fastest, direct JSON. Used if the plugin is installed.
+2. **Web Remote Control** (HTTP port 30010) — Translates commands to Python, executes via UE's built-in HTTP API.
+3. **Python Remote Execution** (UDP port 6766) — Translates commands to Python, executes via UE's multicast remote execution protocol.
+
+All 71 tools work through all backends. The `ue_native_handler.py` module translates every command into standalone Python that runs inside UE's interpreter.
+
+## Available Tools (71+)
+
+| Category | Tools |
+|---|---|
+| **General** | `get_all_scene_objects`, `execute_python_script`, `execute_unreal_command` |
+| **Script** | `execute_python_script`, `run_automation_test` |
+| **Actors** | `spawn_object`, `delete_actor`, `find_actors_by_name`, `set_actor_transform`, `set_actor_property`, `get_actor_properties`, `duplicate_actor`, `rename_actor`, `set_actor_mobility`, `set_actor_physics` |
+| **Blueprint** | `create_blueprint`, `spawn_blueprint`, `compile_blueprint`, `add_component_to_blueprint`, `set_blueprint_variable`, `get_blueprint_details` |
+| **Blueprint Nodes** | `add_node`, `connect_nodes`, `add_variable`, `add_function`, `add_event`, `set_pin_value`, `get_blueprint_graph` |
+| **Materials** | `create_material`, `apply_material_to_actor`, `set_material_parameter`, `create_material_instance` |
+| **Mesh** | `set_static_mesh`, `create_procedural_mesh`, `merge_meshes` |
+| **Physics** | `simulate_physics`, `add_physics_constraint`, `set_collision_profile`, `add_force`, `set_physics_material` |
+| **UI/Widgets** | `create_widget`, `modify_widget`, `bind_widget_event`, `add_widget_animation`, `create_widget_component` |
+| **UI Slicing** | `upload_ui_image`, `slice_ui_image`, `generate_ui_from_slices` |
+| **Project** | `create_project_folder`, `get_files_in_folder`, `import_asset`, `create_level`, `set_level_settings` |
+| **Architecture** | `create_town`, `construct_house`, `construct_building`, `create_road`, `create_landscape`, `place_foliage`, `create_water_body`, `create_sky_atmosphere`, `create_lighting_scenario`, `create_marketplace`, `create_wall`, `create_floor` |
+
+## Configuration
+
+Settings are stored in `~/.createlex/config.json`:
+
+| Key | Default | Description |
+|---|---|---|
+| `unrealPort` | `9878` | CreatelexGenAI plugin TCP port |
+| `mcpPort` | `38080` | MCP TCP server port (for `serve --port`) |
+| `apiBaseUrl` | `https://api.createlex.com/api` | CreateLex API endpoint |
+| `webBaseUrl` | `https://createlex.com` | CreateLex web app URL |
+| `debug` | `false` | Enable debug logging |
+
+## Troubleshooting
+
+### "No backends connected to Unreal Engine"
+- Make sure UE is running with your project open
+- Enable Web Remote Control or Python Remote Execution (see Step 3)
+- Run `createlex connect` for detailed diagnostics
+
+### "Authentication: Not logged in"
+```bash
+createlex login
+```
+
+### "Subscription: Inactive"
+- Visit [createlex.com](https://createlex.com) to check your subscription status
+- Run `createlex status` to see the specific error
+
+### Web Remote Control not responding
+- Check **Edit > Project Settings > Plugins > Remote Control** in UE
+- Ensure "Enable Remote Control Web Server" is checked
+- Verify port 30010 is not blocked by firewall
+
+### Python Remote Execution not available
+- Check **Edit > Project Settings > Plugins > Python** in UE
+- Ensure "Enable Remote Execution" is checked
+- Verify UDP port 6766 is not blocked
+
+## License
+
+Proprietary. Requires an active CreateLex subscription.

package/bin/createlex.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../src/cli');
+run(process.argv);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@createlex/createlexgenai",
+  "version": "1.0.0",
+  "description": "CLI tool and MCP server for CreatelexGenAI — Unreal Engine AI integration",
+  "bin": {
+    "createlex": "./bin/createlex.js"
+  },
+  "main": "src/cli.js",
+  "scripts": {
+    "start": "node bin/createlex.js",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "createlex",
+    "unreal-engine",
+    "mcp",
+    "ai",
+    "cli",
+    "generative-ai",
+    "game-development"
+  ],
+  "author": "CreateLex LLC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "open": "^8.4.2",
+    "ora": "^5.4.1"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "python/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CreatelexLLC/createlexgenai"
+  },
+  "homepage": "https://createlex.com"
+}

package/python/activity_tracker.py

@@ -0,0 +1,280 @@
+"""
+MCP Activity Tracker - Logs tool usage to the CreateLex backend
+
+This module tracks MCP tool calls and sends usage data to the backend
+for analytics and monitoring. All logging is non-blocking to avoid
+impacting tool execution performance.
+"""
+
+import os
+import json
+import time
+import threading
+import queue
+from datetime import datetime
+from typing import Optional, Dict, Any
+import logging
+
+logger = logging.getLogger('mcp_activity_tracker')
+
+# Configuration
+ACTIVITY_API_ENDPOINT = os.environ.get('CREATELEX_API_URL', 'https://api.createlex.com') + '/api/mcp/activity'
+BATCH_SIZE = 10  # Send activities in batches
+FLUSH_INTERVAL = 30  # Flush every 30 seconds even if batch isn't full
+MAX_QUEUE_SIZE = 100  # Maximum pending activities before dropping
+
+class MCPActivityTracker:
+    """
+    Asynchronous activity tracker for MCP tool calls.
+    
+    Collects tool usage data and sends it to the backend in batches
+    to minimize network overhead and avoid blocking tool execution.
+    """
+    
+    def __init__(self):
+        self._activity_queue = queue.Queue(maxsize=MAX_QUEUE_SIZE)
+        self._worker_thread = None
+        self._shutdown = False
+        self._session_id = self._generate_session_id()
+        self._session_start = datetime.utcnow().isoformat()
+        self._tool_call_count = 0
+        
+        # User info from environment (set by VSCode extension)
+        self._user_id = os.environ.get('CREATELEX_USER_ID')
+        self._user_email = os.environ.get('CREATELEX_USER_EMAIL') or os.environ.get('USER_EMAIL')
+        self._device_id = os.environ.get('CREATELEX_DEVICE_ID')
+        self._auth_token = os.environ.get('CREATELEX_AUTH_TOKEN')
+        
+        # Start background worker
+        self._start_worker()
+        
+        logger.info(f"Activity tracker initialized - Session: {self._session_id[:8]}...")
+        
+    def _generate_session_id(self) -> str:
+        """Generate a unique session ID"""
+        import hashlib
+        import uuid
+        return hashlib.sha256(f"{uuid.uuid4()}-{time.time()}".encode()).hexdigest()[:32]
+    
+    def _start_worker(self):
+        """Start the background worker thread"""
+        if self._worker_thread is None or not self._worker_thread.is_alive():
+            self._worker_thread = threading.Thread(target=self._worker_loop, daemon=True)
+            self._worker_thread.start()
+            logger.info("Activity tracker worker started")
+    
+    def _worker_loop(self):
+        """Background worker that sends batched activities"""
+        batch = []
+        last_flush = time.time()
+        
+        while not self._shutdown:
+            try:
+                # Try to get an activity from the queue (with timeout)
+                try:
+                    activity = self._activity_queue.get(timeout=1.0)
+                    batch.append(activity)
+                except queue.Empty:
+                    pass
+                
+                # Check if we should flush the batch
+                should_flush = (
+                    len(batch) >= BATCH_SIZE or
+                    (len(batch) > 0 and time.time() - last_flush >= FLUSH_INTERVAL)
+                )
+                
+                if should_flush:
+                    self._send_batch(batch)
+                    batch = []
+                    last_flush = time.time()
+                    
+            except Exception as e:
+                logger.error(f"Activity worker error: {e}")
+                time.sleep(1)  # Back off on error
+        
+        # Final flush on shutdown
+        if batch:
+            self._send_batch(batch)
+    
+    def _send_batch(self, batch: list):
+        """Send a batch of activities to the backend"""
+        if not batch:
+            return
+            
+        try:
+            import requests
+            
+            payload = {
+                'session_id': self._session_id,
+                'user_id': self._user_id,
+                'user_email': self._user_email,
+                'device_id': self._device_id,
+                'activities': batch,
+                'timestamp': datetime.utcnow().isoformat()
+            }
+            
+            headers = {
+                'Content-Type': 'application/json'
+            }
+            
+            # Add auth token if available
+            if self._auth_token:
+                headers['Authorization'] = f'Bearer {self._auth_token}'
+            
+            response = requests.post(
+                ACTIVITY_API_ENDPOINT,
+                json=payload,
+                headers=headers,
+                timeout=5  # Short timeout to avoid blocking
+            )
+            
+            if response.status_code == 200:
+                logger.debug(f"Sent {len(batch)} activities to backend")
+            else:
+                logger.warning(f"Failed to send activities: {response.status_code}")
+                
+        except requests.RequestException as e:
+            logger.warning(f"Network error sending activities: {e}")
+        except Exception as e:
+            logger.error(f"Error sending activities: {e}")
+    
+    def track_tool_call(
+        self,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        success: bool,
+        duration_ms: float,
+        error: Optional[str] = None,
+        result_summary: Optional[str] = None
+    ):
+        """
+        Track a tool call.
+        
+        Args:
+            tool_name: Name of the MCP tool called
+            arguments: Arguments passed to the tool (sanitized)
+            success: Whether the tool call succeeded
+            duration_ms: Execution time in milliseconds
+            error: Error message if failed
+            result_summary: Brief summary of the result (for analytics)
+        """
+        self._tool_call_count += 1
+        
+        activity = {
+            'type': 'mcp_tool_call',
+            'tool_name': tool_name,
+            'success': success,
+            'duration_ms': duration_ms,
+            'timestamp': datetime.utcnow().isoformat(),
+            'call_number': self._tool_call_count,
+            # Sanitize arguments - remove potentially sensitive data
+            'argument_keys': list(arguments.keys()) if arguments else [],
+            'argument_count': len(arguments) if arguments else 0
+        }
+        
+        if error:
+            activity['error'] = str(error)[:200]  # Truncate long errors
+            
+        if result_summary:
+            activity['result_summary'] = result_summary[:100]
+        
+        try:
+            self._activity_queue.put_nowait(activity)
+        except queue.Full:
+            logger.warning("Activity queue full, dropping oldest entry")
+            try:
+                self._activity_queue.get_nowait()
+                self._activity_queue.put_nowait(activity)
+            except:
+                pass
+    
+    def track_session_event(self, event_type: str, details: Optional[Dict] = None):
+        """
+        Track a session event (startup, shutdown, error, etc.)
+        
+        Args:
+            event_type: Type of event ('session_start', 'session_end', 'error', etc.)
+            details: Additional event details
+        """
+        activity = {
+            'type': 'session_event',
+            'event_type': event_type,
+            'timestamp': datetime.utcnow().isoformat(),
+            'details': details or {}
+        }
+        
+        try:
+            self._activity_queue.put_nowait(activity)
+        except queue.Full:
+            pass
+    
+    def get_session_stats(self) -> Dict:
+        """Get current session statistics"""
+        return {
+            'session_id': self._session_id,
+            'session_start': self._session_start,
+            'tool_call_count': self._tool_call_count,
+            'user_id': self._user_id,
+            'device_id': self._device_id,
+            'pending_activities': self._activity_queue.qsize()
+        }
+    
+    def shutdown(self):
+        """Graceful shutdown - flush pending activities"""
+        logger.info("Activity tracker shutting down...")
+        self._shutdown = True
+        
+        # Track session end
+        self.track_session_event('session_end', {
+            'total_tool_calls': self._tool_call_count
+        })
+        
+        # Wait for worker to finish (with timeout)
+        if self._worker_thread and self._worker_thread.is_alive():
+            self._worker_thread.join(timeout=5)
+
+
+# Global tracker instance
+_tracker: Optional[MCPActivityTracker] = None
+
+def get_tracker() -> MCPActivityTracker:
+    """Get or create the global activity tracker"""
+    global _tracker
+    if _tracker is None:
+        _tracker = MCPActivityTracker()
+        _tracker.track_session_event('session_start', {
+            'platform': os.environ.get('MCP_PLATFORM', 'unknown'),
+            'version': os.environ.get('MCP_VERSION', 'unknown')
+        })
+    return _tracker
+
+def track_tool_call(
+    tool_name: str,
+    arguments: Dict[str, Any],
+    success: bool,
+    duration_ms: float,
+    error: Optional[str] = None,
+    result_summary: Optional[str] = None
+):
+    """Convenience function to track a tool call"""
+    try:
+        tracker = get_tracker()
+        tracker.track_tool_call(
+            tool_name=tool_name,
+            arguments=arguments,
+            success=success,
+            duration_ms=duration_ms,
+            error=error,
+            result_summary=result_summary
+        )
+    except Exception as e:
+        # Never let tracking errors affect main functionality
+        logger.error(f"Failed to track tool call: {e}")
+
+def shutdown_tracker():
+    """Shutdown the global tracker"""
+    global _tracker
+    if _tracker:
+        _tracker.shutdown()
+        _tracker = None
+