@akiojin/unity-mcp-server 2.14.14

package/src/handlers/base/BaseToolHandler.js

@@ -0,0 +1,133 @@
+/**
+ * Base class for all tool handlers
+ * Provides common functionality for validation, execution, and error handling
+ */
+import { logger } from '../../core/config.js';
+
+export class BaseToolHandler {
+  constructor(name, description, inputSchema = {}) {
+    this.name = name;
+    this.description = description;
+    this.inputSchema = inputSchema;
+  }
+
+  /**
+   * Validates the input parameters against the schema
+   * Override this method for custom validation
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    // Basic validation - check required fields from schema
+    if (this.inputSchema.required) {
+      for (const field of this.inputSchema.required) {
+        if (params[field] === undefined || params[field] === null) {
+          throw new Error(`Missing required parameter: ${field}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Executes the tool logic
+   * Must be implemented by subclasses
+   * @param {object} params - Validated input parameters
+   * @returns {Promise<object>} Tool result
+   */
+  async execute(params) {
+    throw new Error('execute() must be implemented by subclass');
+  }
+
+  /**
+   * Main handler method that orchestrates validation and execution
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Standardized response
+   */
+  async handle(params = {}) {
+    logger.debug(`[Handler ${this.name}] Starting handle() with params:`, params);
+    
+    try {
+      // Validate parameters
+      logger.debug(`[Handler ${this.name}] Validating parameters...`);
+      this.validate(params);
+      logger.debug(`[Handler ${this.name}] Validation passed`);
+      
+      // Execute tool logic
+      logger.debug(`[Handler ${this.name}] Executing tool logic...`);
+      const startTime = Date.now();
+      const result = await this.execute(params);
+      const duration = Date.now() - startTime;
+      logger.info(`[Handler ${this.name}] Execution completed in ${duration}ms`);
+      
+      // Return success response in new format
+      return {
+        status: 'success',
+        result
+      };
+    } catch (error) {
+      logger.error(`[Handler ${this.name}] Error occurred: ${error.message}`);
+      if (error.stack) {
+        logger.debug(`[Handler ${this.name}] Error stack: ${error.stack}`);
+      }
+      
+      // Return error response in new format
+      return {
+        status: 'error',
+        error: error.message,
+        code: error.code || 'TOOL_ERROR',
+        details: {
+          tool: this.name,
+          params: this.summarizeParams(params),
+          stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
+        }
+      };
+    }
+  }
+
+  /**
+   * Summarizes parameters for error reporting
+   * @param {object} params - Parameters to summarize
+   * @returns {string} Summary string
+   */
+  summarizeParams(params) {
+    if (!params || typeof params !== 'object') {
+      return 'No parameters';
+    }
+
+    const entries = Object.entries(params);
+    if (entries.length === 0) {
+      return 'Empty parameters';
+    }
+
+    return entries
+      .map(([key, value]) => {
+        let valueStr = '';
+        if (value === null) {
+          valueStr = 'null';
+        } else if (value === undefined) {
+          valueStr = 'undefined';
+        } else if (typeof value === 'string') {
+          // Truncate long strings
+          valueStr = value.length > 50 ? `"${value.substring(0, 47)}..."` : `"${value}"`;
+        } else if (typeof value === 'object') {
+          valueStr = Array.isArray(value) ? `[Array(${value.length})]` : '[Object]';
+        } else {
+          valueStr = String(value);
+        }
+        return `${key}: ${valueStr}`;
+      })
+      .join(', ');
+  }
+
+  /**
+   * Returns the tool definition for MCP
+   * @returns {object} Tool definition
+   */
+  getDefinition() {
+    return {
+      name: this.name,
+      description: this.description,
+      inputSchema: this.inputSchema
+    };
+  }
+}

package/src/handlers/compilation/GetCompilationStateToolHandler.js

@@ -0,0 +1,90 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for getting Unity compilation state and errors
+ */
+export class GetCompilationStateToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_compilation_state',
+      'Get current Unity compilation state, errors, and warnings with enhanced detection',
+      {
+        type: 'object',
+        properties: {
+          includeMessages: {
+            type: 'boolean',
+            description: 'Include detailed compilation messages. Unity default: false. Set to true for debugging compilation issues'
+          },
+          maxMessages: {
+            type: 'number',
+            description: 'Maximum number of messages to return (default: 50)'
+          }
+        }
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the get compilation state operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The compilation state and messages
+   */
+  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('get_compilation_state', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      success: response.success,
+      isCompiling: response.isCompiling,
+      isUpdating: response.isUpdating,
+      isMonitoring: response.isMonitoring,
+      lastCompilationTime: response.lastCompilationTime,
+      messageCount: response.messageCount,
+      errorCount: response.errorCount,
+      warningCount: response.warningCount,
+      ...(response.messages !== undefined && { messages: response.messages })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      getBasicState: {
+        description: 'Get compilation state without detailed messages',
+        params: {
+          includeMessages: false
+        }
+      },
+      getFullState: {
+        description: 'Get compilation state with all error details',
+        params: {
+          includeMessages: true,
+          maxMessages: 100
+        }
+      },
+      getRecentErrors: {
+        description: 'Get recent compilation errors only',
+        params: {
+          includeMessages: true,
+          maxMessages: 10
+        }
+      }
+    };
+  }
+}

package/src/handlers/component/AddComponentToolHandler.js

@@ -0,0 +1,126 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for adding components to GameObjects in Unity
+ */
+export class AddComponentToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'add_component',
+      'Add a component to a GameObject (scene or prefab mode) with optional initial properties.',
+      {
+        type: 'object',
+        properties: {
+          gameObjectPath: {
+            type: 'string',
+            description: 'Scene path to the GameObject (e.g., "/Player" or "/Canvas/Button").'
+          },
+          componentType: {
+            type: 'string',
+            description: 'Type of component to add (e.g., "Rigidbody", "BoxCollider", "Light")'
+          },
+          properties: {
+            type: 'object',
+            description: 'Initial property values to set on the new component.',
+            additionalProperties: true
+          }
+        },
+        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 { gameObjectPath, componentType } = params;
+
+    if (!gameObjectPath || gameObjectPath.trim() === '') {
+      throw new Error('gameObjectPath cannot be empty');
+    }
+
+    if (!componentType || componentType.trim() === '') {
+      throw new Error('componentType cannot be empty');
+    }
+  }
+
+  /**
+   * Executes the add component operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of adding 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('add_component', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return success result
+    return {
+      componentType: response.componentType,
+      gameObjectPath: response.gameObjectPath,
+      message: response.message || 'Component added successfully',
+      ...(response.properties && { appliedProperties: response.properties })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      addRigidbody: {
+        description: 'Add Rigidbody with custom properties',
+        params: {
+          gameObjectPath: '/Player',
+          componentType: 'Rigidbody',
+          properties: {
+            mass: 2.0,
+            drag: 0.5,
+            useGravity: true,
+            isKinematic: false
+          }
+        }
+      },
+      addCollider: {
+        description: 'Add BoxCollider to GameObject',
+        params: {
+          gameObjectPath: '/Player/Hitbox',
+          componentType: 'BoxCollider',
+          properties: {
+            isTrigger: true,
+            size: { x: 1, y: 2, z: 1 }
+          }
+        }
+      },
+      addLight: {
+        description: 'Add Light component',
+        params: {
+          gameObjectPath: '/Lighting/MainLight',
+          componentType: 'Light',
+          properties: {
+            type: 'Directional',
+            intensity: 1.5,
+            color: { r: 1, g: 0.95, b: 0.8, a: 1 }
+          }
+        }
+      }
+    };
+  }
+}

package/src/handlers/component/GetComponentTypesToolHandler.js

@@ -0,0 +1,100 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for discovering available component types in Unity
+ */
+export class GetComponentTypesToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_component_types',
+      'Get available component types in Unity',
+      {
+        type: 'object',
+        properties: {
+          category: {
+            type: 'string',
+            description: 'Filter by category (e.g., "Physics", "Rendering", "UI")'
+          },
+          search: {
+            type: 'string',
+            description: 'Search for component types by name'
+          },
+          onlyAddable: {
+            type: 'boolean',
+            description: 'Return only components that can be added to GameObjects (default: false)'
+          }
+        }
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the get component types operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The list of available component types
+   */
+  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('get_component_types', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      componentTypes: response.componentTypes || [],
+      totalCount: response.totalCount || 0,
+      categories: response.categories || [],
+      ...(response.searchTerm !== undefined && { searchTerm: response.searchTerm }),
+      ...(response.onlyAddable !== undefined && { onlyAddable: response.onlyAddable })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      getAllTypes: {
+        description: 'Get all available component types',
+        params: {}
+      },
+      getPhysicsComponents: {
+        description: 'Get only physics-related components',
+        params: {
+          category: 'Physics'
+        }
+      },
+      searchColliders: {
+        description: 'Search for collider components',
+        params: {
+          search: 'collider'
+        }
+      },
+      getAddableComponents: {
+        description: 'Get only components that can be added',
+        params: {
+          onlyAddable: true
+        }
+      },
+      searchPhysicsAddable: {
+        description: 'Search for addable physics components',
+        params: {
+          category: 'Physics',
+          onlyAddable: true,
+          search: 'body'
+        }
+      }
+    };
+  }
+}

package/src/handlers/component/ListComponentsToolHandler.js

@@ -0,0 +1,85 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for listing components on GameObjects in Unity
+ */
+export class ListComponentsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'list_components',
+      'List all components on a GameObject in Unity (works in both scene and prefab mode)',
+      {
+        type: 'object',
+        properties: {
+          gameObjectPath: {
+            type: 'string',
+            description: 'Path to the GameObject (e.g., "/Player" or "/Canvas/Button")'
+          },
+          includeInherited: {
+            type: 'boolean',
+            description: 'Include inherited base component types (default: false)'
+          }
+        },
+        required: ['gameObjectPath']
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the list components operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The list of components
+   */
+  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('list_components', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      gameObjectPath: response.gameObjectPath,
+      components: response.components || [],
+      componentCount: response.componentCount || 0,
+      ...(response.includesInherited !== undefined && { includesInherited: response.includesInherited })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      listBasicComponents: {
+        description: 'List all components on a GameObject',
+        params: {
+          gameObjectPath: '/Player'
+        }
+      },
+      listWithInherited: {
+        description: 'List components including inherited types',
+        params: {
+          gameObjectPath: '/Player',
+          includeInherited: true
+        }
+      },
+      listUIComponents: {
+        description: 'List components on a UI element',
+        params: {
+          gameObjectPath: '/Canvas/Button'
+        }
+      }
+    };
+  }
+}

package/src/handlers/component/ModifyComponentToolHandler.js

@@ -0,0 +1,143 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for modifying component properties on GameObjects in Unity
+ */
+export class ModifyComponentToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'modify_component',
+      'Modify properties of a component on a GameObject in Unity (works in both scene and prefab mode)',
+      {
+        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 modify (e.g., "Rigidbody", "Light")'
+          },
+          componentIndex: {
+            type: 'number',
+            description: 'Index of component if multiple of same type exist (default: 0)'
+          },
+          properties: {
+            type: 'object',
+            description: 'Properties to modify with their new values',
+            additionalProperties: true
+          }
+        },
+        required: ['gameObjectPath', 'componentType', 'properties']
+      }
+    );
+    
+    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 { properties } = params;
+
+    // Validate properties is not empty
+    if (!properties || Object.keys(properties).length === 0) {
+      throw new Error('properties cannot be empty');
+    }
+  }
+
+  /**
+   * Executes the modify component operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of modifying 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('modify_component', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      componentType: response.componentType,
+      modifiedProperties: response.modifiedProperties || [],
+      message: response.message || 'Component properties updated',
+      ...(response.componentIndex !== undefined && { componentIndex: response.componentIndex })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      modifyRigidbody: {
+        description: 'Modify Rigidbody properties',
+        params: {
+          gameObjectPath: '/Player',
+          componentType: 'Rigidbody',
+          properties: {
+            mass: 5.0,
+            drag: 0.5,
+            angularDrag: 0.05,
+            useGravity: true,
+            isKinematic: false
+          }
+        }
+      },
+      modifyLight: {
+        description: 'Modify Light component settings',
+        params: {
+          gameObjectPath: '/Lighting/MainLight',
+          componentType: 'Light',
+          properties: {
+            intensity: 2.0,
+            color: { r: 1, g: 0.95, b: 0.8, a: 1 },
+            range: 50,
+            type: 'Point'
+          }
+        }
+      },
+      modifyNestedProperties: {
+        description: 'Modify nested properties using dot notation',
+        params: {
+          gameObjectPath: '/Player',
+          componentType: 'Rigidbody',
+          properties: {
+            'constraints.freezePositionX': true,
+            'constraints.freezePositionY': false,
+            'constraints.freezeRotationZ': true
+          }
+        }
+      },
+      modifyCamera: {
+        description: 'Modify Camera settings',
+        params: {
+          gameObjectPath: '/MainCamera',
+          componentType: 'Camera',
+          properties: {
+            fieldOfView: 75,
+            nearClipPlane: 0.1,
+            farClipPlane: 1000,
+            depth: -1
+          }
+        }
+      }
+    };
+  }
+}