@akiojin/unity-mcp-server 2.14.14

package/src/handlers/gameobject/DeleteGameObjectToolHandler.js

@@ -0,0 +1,101 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for the delete_gameobject tool
+ * Deletes GameObjects from the Unity scene
+ */
+export class DeleteGameObjectToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'delete_gameobject',
+      'Delete GameObject(s) by path or paths (optionally include children).',
+      {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Path to a single GameObject to delete'
+          },
+          paths: {
+            type: 'array',
+            description: 'Array of paths to multiple GameObjects to delete',
+            items: {
+              type: 'string'
+            }
+          },
+          includeChildren: {
+            type: 'boolean',
+            description: 'Whether to delete children (default: true)'
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params);
+    
+    // Either path or paths must be provided
+    if (!params.path && (!params.paths || params.paths.length === 0)) {
+      throw new Error('Either "path" or "paths" parameter must be provided');
+    }
+    
+    // Validate paths array if provided
+    if (params.paths) {
+      if (!Array.isArray(params.paths)) {
+        throw new Error('paths must be an array of strings');
+      }
+      
+      for (const path of params.paths) {
+        if (typeof path !== 'string') {
+          throw new Error('All paths must be strings');
+        }
+      }
+    }
+  }
+
+  /**
+   * Executes the delete_gameobject command
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Deletion result
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send delete_gameobject command
+    const result = await this.unityConnection.sendCommand('delete_gameobject', params);
+    
+    // Check for errors from Unity
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    
+    // Add summary
+    if (result.deletedCount !== undefined) {
+      if (result.deletedCount === 0) {
+        result.summary = 'No GameObjects were deleted';
+      } else if (result.deletedCount === 1) {
+        result.summary = `Deleted 1 GameObject: ${result.deleted[0]}`;
+      } else {
+        result.summary = `Deleted ${result.deletedCount} GameObjects`;
+      }
+      
+      if (result.notFoundCount > 0) {
+        result.summary += ` (${result.notFoundCount} not found)`;
+      }
+    }
+    
+    return result;
+  }
+}

package/src/handlers/gameobject/FindGameObjectToolHandler.js

@@ -0,0 +1,119 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for the find_gameobject tool
+ * Finds GameObjects in Unity scene by various criteria
+ */
+export class FindGameObjectToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'find_gameobject',
+      'Find GameObjects by name, tag, or layer with optional exact matching.',
+      {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'Name to search for'
+          },
+          tag: {
+            type: 'string',
+            description: 'Tag to search for'
+          },
+          layer: {
+            type: 'number',
+            description: 'Layer index to search for (0-31)',
+            minimum: 0,
+            maximum: 31
+          },
+          exactMatch: {
+            type: 'boolean',
+            description: 'Whether to match name exactly (default: false)'
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params);
+    
+    // At least one search criteria must be provided
+    if (!params.name && !params.tag && params.layer === undefined) {
+      throw new Error('At least one search criteria (name, tag, or layer) must be provided');
+    }
+    
+    // Validate layer
+    if (params.layer !== undefined) {
+      const layer = Number(params.layer);
+      if (isNaN(layer) || layer < 0 || layer > 31) {
+        throw new Error('layer must be a number between 0 and 31');
+      }
+    }
+  }
+
+  /**
+   * Executes the find_gameobject command
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Found GameObjects
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send find_gameobject command
+    const result = await this.unityConnection.sendCommand('find_gameobject', params);
+    
+    // Check for errors from Unity
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    
+    // Add summary information
+    if (result.objects && Array.isArray(result.objects)) {
+      result.summary = this.generateSummary(result.objects, params);
+    }
+    
+    return result;
+  }
+
+  /**
+   * Generates a summary of the search results
+   * @param {Array} objects - Found GameObjects
+   * @param {object} searchParams - Search parameters used
+   * @returns {string} Summary text
+   */
+  generateSummary(objects, searchParams) {
+    const parts = [];
+    
+    if (searchParams.name) {
+      parts.push(`name${searchParams.exactMatch === false ? ' containing' : ''} "${searchParams.name}"`);
+    }
+    if (searchParams.tag) {
+      parts.push(`tag "${searchParams.tag}"`);
+    }
+    if (searchParams.layer !== undefined) {
+      parts.push(`layer ${searchParams.layer}`);
+    }
+    
+    const criteria = parts.join(', ');
+    
+    if (objects.length === 0) {
+      return `No GameObjects found matching ${criteria}`;
+    } else if (objects.length === 1) {
+      return `Found 1 GameObject matching ${criteria}: ${objects[0].name}`;
+    } else {
+      return `Found ${objects.length} GameObjects matching ${criteria}`;
+    }
+  }
+}

package/src/handlers/gameobject/GetHierarchyToolHandler.js

@@ -0,0 +1,132 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for the get_hierarchy tool
+ * Gets the Unity scene hierarchy
+ */
+export class GetHierarchyToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_hierarchy',
+      'Get scene hierarchy. For large scenes, prefer nameOnly=true. With nameOnly, use maxObjects ~100–500; when requesting details, keep maxObjects ~10–50 to conserve tokens. Only enable includeComponents/includeTransform when necessary.',
+      {
+        type: 'object',
+        properties: {
+          rootPath: {
+            type: 'string',
+            description: 'Path to GameObject whose children will be the root of the returned hierarchy (e.g., "/Team_0" returns Team_0\'s children). If not specified, returns scene root objects.'
+          },
+          includeInactive: {
+            type: 'boolean',
+            description: 'Include inactive GameObjects (default: true)'
+          },
+          maxDepth: {
+            type: 'number',
+            description: 'Maximum depth to traverse from the root. 0=immediate children only (default), 1=children+grandchildren, 2=children+grandchildren+great-grandchildren, etc. (-1 for unlimited)',
+            minimum: -1
+          },
+          includeComponents: {
+            type: 'boolean',
+            description: 'Include component information (default: false). WARNING: Significantly increases response size - use with small maxObjects values.'
+          },
+          includeTransform: {
+            type: 'boolean',
+            description: 'Include transform information (default: false). WARNING: Increases response size - use with small maxObjects values.'
+          },
+          includeTags: {
+            type: 'boolean',
+            description: 'Include tag information (default: false)'
+          },
+          includeLayers: {
+            type: 'boolean',
+            description: 'Include layer information (default: false)'
+          },
+          nameOnly: {
+            type: 'boolean',
+            description: 'Return only names and paths for minimal data size (default: false). RECOMMENDED for large hierarchies to reduce token usage.'
+          },
+          maxObjects: {
+            type: 'number',
+            description: 'Maximum number of objects to include in response. Unity default: 100 (-1 for unlimited). RECOMMENDED: 10-50 for detailed info, 100-500 for nameOnly mode to avoid MCP token limits',
+            minimum: -1
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params);
+    
+    // Validate maxDepth
+    if (params.maxDepth !== undefined) {
+      const depth = Number(params.maxDepth);
+      if (isNaN(depth) || depth < -1) {
+        throw new Error('maxDepth must be -1 or a positive number');
+      }
+    }
+    
+    // Validate maxObjects
+    if (params.maxObjects !== undefined) {
+      const maxObjects = Number(params.maxObjects);
+      if (isNaN(maxObjects) || maxObjects < -1) {
+        throw new Error('maxObjects must be -1 or a positive number');
+      }
+    }
+  }
+
+  /**
+   * Executes the get_hierarchy command
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Scene hierarchy
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send get_hierarchy command
+    const result = await this.unityConnection.sendCommand('get_hierarchy', params);
+    
+    // Check for errors from Unity
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    
+    // Add helpful summary
+    if (result.hierarchy) {
+      result.totalObjects = this.countObjects(result.hierarchy);
+      result.summary = `Scene "${result.sceneName}" contains ${result.totalObjects} GameObject${result.totalObjects !== 1 ? 's' : ''} (${result.objectCount} at root level)`;
+    }
+    
+    return result;
+  }
+
+  /**
+   * Counts total objects in hierarchy recursively
+   * @param {Array} hierarchy - Hierarchy array
+   * @returns {number} Total object count
+   */
+  countObjects(hierarchy) {
+    let count = 0;
+    
+    for (const node of hierarchy) {
+      count++; // Count this node
+      
+      if (node.children && Array.isArray(node.children)) {
+        count += this.countObjects(node.children);
+      }
+    }
+    
+    return count;
+  }
+}

package/src/handlers/gameobject/ModifyGameObjectToolHandler.js

@@ -0,0 +1,128 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { validateVector3, validateLayer, validateGameObjectPath } from '../../utils/validators.js';
+
+/**
+ * Handler for the modify_gameobject tool
+ * Modifies properties of existing GameObjects
+ */
+export class ModifyGameObjectToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'modify_gameobject',
+      'Modify GameObject properties (transform/name/parent/active/tag/layer).',
+      {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Path to the GameObject to modify (required)'
+          },
+          name: {
+            type: 'string',
+            description: 'New name for the GameObject'
+          },
+          position: {
+            type: 'object',
+            description: 'New world position',
+            properties: {
+              x: { type: 'number' },
+              y: { type: 'number' },
+              z: { type: 'number' }
+            }
+          },
+          rotation: {
+            type: 'object',
+            description: 'New rotation in Euler angles',
+            properties: {
+              x: { type: 'number' },
+              y: { type: 'number' },
+              z: { type: 'number' }
+            }
+          },
+          scale: {
+            type: 'object',
+            description: 'New local scale',
+            properties: {
+              x: { type: 'number' },
+              y: { type: 'number' },
+              z: { type: 'number' }
+            }
+          },
+          active: {
+            type: 'boolean',
+            description: 'Set active state'
+          },
+          parentPath: {
+            type: ['string', 'null'],
+            description: 'Path to new parent GameObject (null to unparent)'
+          },
+          tag: {
+            type: 'string',
+            description: 'New tag'
+          },
+          layer: {
+            type: 'number',
+            description: 'New layer index (0-31)',
+            minimum: 0,
+            maximum: 31
+          }
+        },
+        required: ['path']
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params);
+    
+    // Path is required
+    validateGameObjectPath(params.path);
+    
+    // At least one modification must be specified
+    const modifiableProps = ['name', 'position', 'rotation', 'scale', 'active', 'parentPath', 'tag', 'layer'];
+    const hasModification = modifiableProps.some(prop => params.hasOwnProperty(prop));
+    
+    if (!hasModification) {
+      throw new Error('At least one property to modify must be specified');
+    }
+    
+    // Validate vector3 properties
+    if (params.position) validateVector3(params.position, 'position');
+    if (params.rotation) validateVector3(params.rotation, 'rotation');
+    if (params.scale) validateVector3(params.scale, 'scale');
+    
+    // Validate layer
+    if (params.layer !== undefined) {
+      validateLayer(Number(params.layer));
+    }
+  }
+
+  /**
+   * Executes the modify_gameobject command
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Modified GameObject info
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send modify_gameobject command
+    const result = await this.unityConnection.sendCommand('modify_gameobject', params);
+    
+    // Check for errors from Unity
+    if (result.error) {
+      throw new Error(result.error);
+    }
+    
+    return result;
+  }
+}