@akiojin/unity-mcp-server 2.14.14

package/src/handlers/component/RemoveComponentToolHandler.js

@@ -0,0 +1,108 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for removing components from GameObjects in Unity
+ */
+export class RemoveComponentToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'remove_component',
+      'Remove a component from a GameObject (scene or prefab mode) by type/index.',
+      {
+        type: 'object',
+        properties: {
+          gameObjectPath: {
+            type: 'string',
+            description: 'Path to the GameObject (e.g., "/Player" or "/Canvas/Button")'
+          },
+          componentType: {
+            type: 'string',
+            description: 'Type of component to remove (e.g., "Rigidbody", "BoxCollider")'
+          },
+          componentIndex: {
+            type: 'number',
+            description: 'Index of component if multiple of same type exist (default: 0)'
+          }
+        },
+        required: ['gameObjectPath', 'componentType']
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params); // Check required fields
+    
+    const { componentIndex } = params;
+
+    // Validate component index if provided
+    if (componentIndex !== undefined && componentIndex < 0) {
+      throw new Error('componentIndex must be non-negative');
+    }
+  }
+
+  /**
+   * Executes the remove component operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of removing the component
+   */
+  async execute(params) {
+    // Ensure connection to Unity
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    // Send command to Unity
+    const response = await this.unityConnection.sendCommand('remove_component', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      removed: response.removed,
+      componentType: response.componentType,
+      message: response.message || 'Component removal completed',
+      ...(response.componentIndex !== undefined && { componentIndex: response.componentIndex })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      removeRigidbody: {
+        description: 'Remove Rigidbody component',
+        params: {
+          gameObjectPath: '/Player',
+          componentType: 'Rigidbody'
+        }
+      },
+      removeSpecificCollider: {
+        description: 'Remove specific collider when multiple exist',
+        params: {
+          gameObjectPath: '/ComplexObject',
+          componentType: 'BoxCollider',
+          componentIndex: 1
+        }
+      },
+      removeLight: {
+        description: 'Remove Light component',
+        params: {
+          gameObjectPath: '/Lighting/OldLight',
+          componentType: 'Light'
+        }
+      }
+    };
+  }
+}

package/src/handlers/console/ClearConsoleToolHandler.js

@@ -0,0 +1,160 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for clearing Unity Editor console logs
+ */
+export class ClearConsoleToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'clear_console',
+      'Clear Console logs (optionally set auto-clear and preserve levels).',
+      {
+        type: 'object',
+        properties: {
+          clearOnPlay: {
+            type: 'boolean',
+            description: 'Clear console when entering play mode. Unity default: false. Set to true for cleaner testing sessions'
+          },
+          clearOnRecompile: {
+            type: 'boolean',
+            description: 'Clear console on script recompilation. Unity default: false. Set to true to focus on current compilation errors'
+          },
+          clearOnBuild: {
+            type: 'boolean',
+            description: 'Clear console when building. Unity default: false. Set to true for clean build logs'
+          },
+          preserveWarnings: {
+            type: 'boolean',
+            description: 'Preserve warning messages when clearing (default: false)'
+          },
+          preserveErrors: {
+            type: 'boolean',
+            description: 'Preserve error messages when clearing (default: false)'
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    const {
+      clearOnPlay,
+      clearOnRecompile,
+      clearOnBuild,
+      preserveWarnings,
+      preserveErrors
+    } = params;
+
+    // Validate boolean parameters
+    if (clearOnPlay !== undefined && typeof clearOnPlay !== 'boolean') {
+      throw new Error('clearOnPlay must be a boolean');
+    }
+
+    if (clearOnRecompile !== undefined && typeof clearOnRecompile !== 'boolean') {
+      throw new Error('clearOnRecompile must be a boolean');
+    }
+
+    if (clearOnBuild !== undefined && typeof clearOnBuild !== 'boolean') {
+      throw new Error('clearOnBuild must be a boolean');
+    }
+
+    if (preserveWarnings !== undefined && typeof preserveWarnings !== 'boolean') {
+      throw new Error('preserveWarnings must be a boolean');
+    }
+
+    if (preserveErrors !== undefined && typeof preserveErrors !== 'boolean') {
+      throw new Error('preserveErrors must be a boolean');
+    }
+
+    // Validate logical consistency
+    const isClearing = clearOnPlay !== false || clearOnRecompile !== false || clearOnBuild !== false;
+    const isPreserving = preserveWarnings === true || preserveErrors === true;
+    
+    if (isPreserving && !isClearing) {
+      throw new Error('Cannot preserve specific log types when not clearing console');
+    }
+  }
+
+  /**
+   * Executes the console clear operation
+   * @param {Object} params - The input parameters
+   * @returns {Promise<Object>} The result of the clear operation
+   */
+  async execute(params) {
+    const {
+      clearOnPlay,
+      clearOnRecompile,
+      clearOnBuild,
+      preserveWarnings,
+      preserveErrors
+    } = params;
+
+    // Ensure connection to Unity
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    // Prepare command parameters
+    const commandParams = {
+      clearOnPlay,
+      clearOnRecompile,
+      clearOnBuild,
+      preserveWarnings,
+      preserveErrors
+    };
+
+    // Send command to Unity
+    const response = await this.unityConnection.sendCommand('clear_console', commandParams);
+
+    // Handle Unity response
+    if (response.success === false) {
+      throw new Error(response.error || 'Failed to clear console');
+    }
+
+    // Build result object
+    const result = {
+      message: response.message || 'Console cleared successfully',
+      timestamp: response.timestamp || new Date().toISOString()
+    };
+
+    // Include optional statistics if available
+    if (response.clearedCount !== undefined) {
+      result.clearedCount = response.clearedCount;
+    }
+    if (response.remainingCount !== undefined) {
+      result.remainingCount = response.remainingCount;
+    }
+    if (response.preservedWarnings !== undefined) {
+      result.preservedWarnings = response.preservedWarnings;
+    }
+    if (response.preservedErrors !== undefined) {
+      result.preservedErrors = response.preservedErrors;
+    }
+    if (response.settingsUpdated !== undefined) {
+      result.settingsUpdated = response.settingsUpdated;
+    }
+
+    // Include settings if they were updated
+    if (response.settingsUpdated) {
+      if (response.clearOnPlay !== undefined) {
+        result.clearOnPlay = response.clearOnPlay;
+      }
+      if (response.clearOnRecompile !== undefined) {
+        result.clearOnRecompile = response.clearOnRecompile;
+      }
+      if (response.clearOnBuild !== undefined) {
+        result.clearOnBuild = response.clearOnBuild;
+      }
+    }
+
+    return result;
+  }
+}

package/src/handlers/console/ReadConsoleToolHandler.js

@@ -0,0 +1,276 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for reading Unity Editor console logs with advanced filtering
+ */
+export class ReadConsoleToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'read_console',
+      'Read Console logs with filters (type/text/time), formatting, sort, and grouping.',
+      {
+        type: 'object',
+        properties: {
+          count: {
+            type: 'number',
+            description: 'Number of logs to retrieve (1-1000, default: 100)',
+            minimum: 1,
+            maximum: 1000
+          },
+          logTypes: {
+            type: 'array',
+            description: 'Filter by log types (default: ["All"])',
+            items: {
+              type: 'string',
+              enum: ['Info', 'Warning', 'Error', 'All']
+            }
+          },
+          filterText: {
+            type: 'string',
+            description: 'Filter logs containing this text (case-insensitive)'
+          },
+          includeStackTrace: {
+            type: 'boolean',
+            description: 'Include stack traces in results. Unity default: false (set to true for debugging)'
+          },
+          format: {
+            type: 'string',
+            description: 'Output format for logs. Unity default: compact. RECOMMENDED: compact for general use, detailed for debugging',
+            enum: ['detailed', 'compact', 'json', 'plain']
+          },
+          sinceTimestamp: {
+            type: 'string',
+            description: 'Only return logs after this timestamp (ISO 8601)'
+          },
+          untilTimestamp: {
+            type: 'string',
+            description: 'Only return logs before this timestamp (ISO 8601)'
+          },
+          sortOrder: {
+            type: 'string',
+            description: 'Sort order for logs (default: newest)',
+            enum: ['newest', 'oldest']
+          },
+          groupBy: {
+            type: 'string',
+            description: 'Group logs by criteria (default: none)',
+            enum: ['none', 'type', 'file', 'time']
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    const {
+      count,
+      logTypes,
+      filterText,
+      includeStackTrace,
+      format,
+      sinceTimestamp,
+      untilTimestamp,
+      sortOrder,
+      groupBy
+    } = params;
+
+    // Validate count
+    if (count !== undefined) {
+      if (typeof count !== 'number' || count < 1 || count > 1000) {
+        throw new Error('count must be between 1 and 1000');
+      }
+    }
+
+    // Validate log types
+    if (logTypes !== undefined) {
+      if (!Array.isArray(logTypes)) {
+        throw new Error('logTypes must be an array');
+      }
+      
+      const validTypes = ['Info', 'Warning', 'Error', 'All'];
+      for (const type of logTypes) {
+        if (!validTypes.includes(type)) {
+          // Invalid types are treated as 'All' later, so just log a warning
+          console.warn(`Invalid log type: ${type}. Will be treated as 'All'.`);
+        }
+      }
+    }
+
+    // Validate timestamps
+    if (sinceTimestamp !== undefined) {
+      if (!this.isValidISO8601(sinceTimestamp)) {
+        throw new Error('sinceTimestamp must be a valid ISO 8601 timestamp');
+      }
+    }
+
+    if (untilTimestamp !== undefined) {
+      if (!this.isValidISO8601(untilTimestamp)) {
+        throw new Error('untilTimestamp must be a valid ISO 8601 timestamp');
+      }
+    }
+
+    // Validate timestamp order
+    if (sinceTimestamp && untilTimestamp) {
+      const since = new Date(sinceTimestamp);
+      const until = new Date(untilTimestamp);
+      if (until <= since) {
+        throw new Error('untilTimestamp must be after sinceTimestamp');
+      }
+    }
+
+    // Validate format
+    if (format !== undefined) {
+      const validFormats = ['detailed', 'compact', 'json', 'plain'];
+      if (!validFormats.includes(format)) {
+        throw new Error(`format must be one of: ${validFormats.join(', ')}`);
+      }
+    }
+
+    // Validate sort order
+    if (sortOrder !== undefined) {
+      const validOrders = ['newest', 'oldest'];
+      if (!validOrders.includes(sortOrder)) {
+        throw new Error(`sortOrder must be one of: ${validOrders.join(', ')}`);
+      }
+    }
+
+    // Validate groupBy
+    if (groupBy !== undefined) {
+      const validGroups = ['none', 'type', 'file', 'time'];
+      if (!validGroups.includes(groupBy)) {
+        throw new Error(`groupBy must be one of: ${validGroups.join(', ')}`);
+      }
+    }
+  }
+
+  /**
+   * Checks if a string is a valid ISO 8601 timestamp
+   * @param {string} timestamp - The timestamp to validate
+   * @returns {boolean} True if valid
+   */
+  isValidISO8601(timestamp) {
+    const regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/;
+    if (!regex.test(timestamp)) {
+      return false;
+    }
+    
+    const date = new Date(timestamp);
+    return !isNaN(date.getTime());
+  }
+
+  /**
+   * Executes the enhanced log reading operation
+   * @param {Object} params - The input parameters
+   * @returns {Promise<Object>} The result of the log reading
+   */
+  async execute(params) {
+    const {
+      count,
+      logTypes,
+      filterText,
+      includeStackTrace,
+      format,
+      sinceTimestamp,
+      untilTimestamp,
+      sortOrder,
+      groupBy
+    } = params;
+
+    // Convert simplified log types to Unity log types
+    let expandedLogTypes = [];
+    
+    if (!logTypes || logTypes.length === 0 || logTypes.includes('All')) {
+      // Default to all types
+      expandedLogTypes = ['Log', 'Warning', 'Error', 'Exception', 'Assert'];
+    } else {
+      // Expand each simplified type to Unity types
+      logTypes.forEach(type => {
+        switch(type) {
+          case 'Info':
+            expandedLogTypes.push('Log');
+            break;
+          case 'Warning':
+            expandedLogTypes.push('Warning');
+            break;
+          case 'Error':
+            // Error includes all error-related types
+            expandedLogTypes.push('Error', 'Exception', 'Assert');
+            break;
+          case 'All':            expandedLogTypes.push('Log', 'Warning', 'Error', 'Exception', 'Assert');
+            break;
+        }
+      });
+      
+      // Remove duplicates
+      expandedLogTypes = [...new Set(expandedLogTypes)];
+    }
+
+    // Ensure connection to Unity
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    // Prepare command parameters
+    const commandParams = {
+      count,
+      logTypes: expandedLogTypes,
+      includeStackTrace,
+      format,
+      sortOrder,
+      groupBy
+    };
+
+    // Add optional parameters
+    if (filterText !== undefined) {
+      commandParams.filterText = filterText;
+    }
+    if (sinceTimestamp !== undefined) {
+      commandParams.sinceTimestamp = sinceTimestamp;
+    }
+    if (untilTimestamp !== undefined) {
+      commandParams.untilTimestamp = untilTimestamp;
+    }
+
+    // Send command to Unity
+    const response = await this.unityConnection.sendCommand('read_console', commandParams);
+
+    // Handle Unity response
+    if (response.success === false) {
+      throw new Error(response.error || 'Failed to read logs');
+    }
+
+    // Build result object
+    const result = {
+      logs: response.logs || [],
+      count: response.count || 0,
+      totalCaptured: response.totalCaptured || 0
+    };
+
+    // Include optional fields if available
+    if (response.filteredCount !== undefined) {
+      result.filteredCount = response.filteredCount;
+    }
+    if (response.statistics !== undefined) {
+      result.statistics = response.statistics;
+    }
+    if (response.groupedLogs !== undefined) {
+      result.groupedLogs = response.groupedLogs;
+    }
+    if (response.format !== undefined) {
+      result.format = response.format;
+    }
+    if (response.groupBy !== undefined) {
+      result.groupBy = response.groupBy;
+    }
+
+    return result;
+  }
+}

package/src/handlers/editor/LayerManagementToolHandler.js

@@ -0,0 +1,160 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handles Unity layer management operations
+ */
+export class LayerManagementToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'manage_layers',
+      'Manage project layers: add/remove/list and convert (by name/index).',
+      {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['add', 'remove', 'get', 'get_by_name', 'get_by_index'],
+            description: 'Operation: add, remove, get, get_by_name, or get_by_index.'
+          },
+          layerName: {
+            type: 'string',
+            description: 'Layer name (required for add/remove/get_by_name). Letters/numbers/space/_ only.'
+          },
+          layerIndex: {
+            type: 'number',
+            minimum: 0,
+            maximum: 31,
+            description: 'Layer index (0-31). Required for get_by_index.'
+          }
+        },
+        required: ['action']
+      }
+    );
+    this.unityConnection = unityConnection;
+    this.RESERVED_LAYERS = ['Default', 'TransparentFX', 'Ignore Raycast', 'Water', 'UI'];
+  }
+
+  /**
+   * Validate the parameters for the layer management operation
+   */
+  validate(params) {
+    const { action, layerName, layerIndex } = params;
+
+    // Check action is provided
+    if (!action) {
+      throw new Error('action is required');
+    }
+
+    // Validate action is one of the allowed values
+    const allowedActions = ['add', 'remove', 'get', 'get_by_name', 'get_by_index'];
+    if (!allowedActions.includes(action)) {
+      throw new Error(`action must be one of: ${allowedActions.join(', ')}`);
+    }
+
+    // Validate based on action
+    switch (action) {
+      case 'add':
+      case 'remove':
+        if (layerName === undefined || layerName === null) {
+          throw new Error(`layerName is required for ${action} action`);
+        }
+        if (layerName === '') {
+          throw new Error('layerName cannot be empty');
+        }
+        if (!this.isValidLayerName(layerName)) {
+          throw new Error('layerName contains invalid characters');
+        }
+        if (action === 'add' && this.RESERVED_LAYERS.includes(layerName)) {
+          throw new Error('layerName is reserved');
+        }
+        break;
+      
+      case 'get_by_name':
+        if (layerName === undefined || layerName === null) {
+          throw new Error('layerName is required for get_by_name action');
+        }
+        break;
+      
+      case 'get_by_index':
+        if (layerIndex === undefined || layerIndex === null) {
+          throw new Error('layerIndex is required for get_by_index action');
+        }
+        if (layerIndex < 0 || layerIndex > 31) {
+          throw new Error('layerIndex must be between 0 and 31');
+        }
+        break;
+    }
+
+    // Call parent validation last
+    super.validate(params);
+  }
+
+  /**
+   * Check if layer name contains only valid characters
+   */
+  isValidLayerName(layerName) {
+    // Layer names should only contain letters, numbers, spaces, and underscores
+    const validPattern = /^[a-zA-Z0-9\s_]+$/;
+    return validPattern.test(layerName);
+  }
+
+  /**
+   * Execute the layer management command
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    const result = await this.unityConnection.sendCommand('manage_layers', params);
+    
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    
+    return result;
+  }
+
+  /**
+   * Get examples of how to use this tool
+   */
+  getExamples() {
+    return {
+      getLayers: {
+        description: 'Get all layers with indices',
+        params: {
+          action: 'get'
+        }
+      },
+      addLayer: {
+        description: 'Add a new layer',
+        params: {
+          action: 'add',
+          layerName: 'Enemy'
+        }
+      },
+      removeLayer: {
+        description: 'Remove an existing layer',
+        params: {
+          action: 'remove',
+          layerName: 'Enemy'
+        }
+      },
+      getLayerByName: {
+        description: 'Get layer index by name',
+        params: {
+          action: 'get_by_name',
+          layerName: 'Player'
+        }
+      },
+      getLayerByIndex: {
+        description: 'Get layer name by index',
+        params: {
+          action: 'get_by_index',
+          layerIndex: 8
+        }
+      }
+    };
+  }
+}