@akiojin/unity-mcp-server 2.14.14

package/src/handlers/asset/CreatePrefabToolHandler.js

@@ -0,0 +1,78 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class CreatePrefabToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'create_prefab',
+            'Create a prefab from a GameObject path or create an empty prefab at a target asset path.',
+            {
+                type: 'object',
+                properties: {
+                    gameObjectPath: {
+                        type: 'string',
+                        description: 'Scene path to convert (e.g., "/Root/Player"). Mutually exclusive with createFromTemplate.'
+                    },
+                    prefabPath: {
+                        type: 'string',
+                        description: 'Asset path for the prefab. Must start with Assets/ and end with .prefab.'
+                    },
+                    createFromTemplate: {
+                        type: 'boolean',
+                        description: 'If true, create an empty prefab (no source GameObject) (default: false).'
+                    },
+                    overwrite: {
+                        type: 'boolean',
+                        description: 'If true, overwrite existing prefab at the destination path (default: false).'
+                    }
+                },
+                required: ['prefabPath']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Call parent validation for required fields
+        super.validate(params);
+
+        const { prefabPath, gameObjectPath, createFromTemplate } = params;
+
+        // Validate prefabPath format
+        if (!prefabPath.startsWith('Assets/') || !prefabPath.endsWith('.prefab')) {
+            throw new Error('prefabPath must start with Assets/ and end with .prefab');
+        }
+
+        // Validate gameObjectPath when provided
+        if (gameObjectPath !== undefined && gameObjectPath === '') {
+            throw new Error('gameObjectPath cannot be empty when provided');
+        }
+
+        // Validate mutually exclusive options
+        if (gameObjectPath && createFromTemplate) {
+            throw new Error('Cannot specify both gameObjectPath and createFromTemplate');
+        }
+    }
+
+    async execute(params) {
+        const {
+            gameObjectPath,
+            prefabPath,
+            createFromTemplate = false,
+            overwrite = false
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('create_prefab', {
+            gameObjectPath,
+            prefabPath,
+            createFromTemplate,
+            overwrite
+        });
+
+        return result;
+    }
+}

package/src/handlers/asset/ExitPrefabModeToolHandler.js

@@ -0,0 +1,83 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for exiting Unity's prefab mode
+ */
+export class ExitPrefabModeToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'exit_prefab_mode',
+      'Exit prefab mode and return to the main scene',
+      {
+        type: 'object',
+        properties: {
+          saveChanges: {
+            type: 'boolean',
+            description: 'Save changes before exiting (default: true)'
+          }
+        }
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the exit prefab mode operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of exiting prefab mode
+   */
+  async execute(params) {
+    // Ensure connection to Unity
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    // Default saveChanges to true
+    const executeParams = {
+      saveChanges: params.saveChanges !== undefined ? params.saveChanges : true
+    };
+
+    // Send command to Unity
+    const response = await this.unityConnection.sendCommand('exit_prefab_mode', executeParams);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      success: response.success,
+      wasInPrefabMode: response.wasInPrefabMode,
+      message: response.message || 'Exited prefab mode',
+      ...(response.changesSaved !== undefined && { changesSaved: response.changesSaved }),
+      ...(response.prefabPath !== undefined && { prefabPath: response.prefabPath })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      exitAndSave: {
+        description: 'Exit prefab mode and save changes',
+        params: {
+          saveChanges: true
+        }
+      },
+      exitWithoutSave: {
+        description: 'Exit prefab mode without saving changes',
+        params: {
+          saveChanges: false
+        }
+      },
+      exitDefault: {
+        description: 'Exit prefab mode (saves by default)',
+        params: {}
+      }
+    };
+  }
+}

package/src/handlers/asset/InstantiatePrefabToolHandler.js

@@ -0,0 +1,133 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class InstantiatePrefabToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'instantiate_prefab',
+            'Instantiate a prefab in the scene with optional transform, parent, and name override.',
+            {
+                type: 'object',
+                properties: {
+                    prefabPath: {
+                        type: 'string',
+                        description: 'Asset path to the prefab. Must start with Assets/ and end with .prefab.'
+                    },
+                    position: {
+                        type: 'object',
+                        properties: {
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            z: { type: 'number' }
+                        },
+                        description: 'World position for the instance (requires x,y,z).'
+                    },
+                    rotation: {
+                        type: 'object',
+                        properties: {
+                            x: { type: 'number' },
+                            y: { type: 'number' },
+                            z: { type: 'number' }
+                        },
+                        description: 'Euler rotation for the instance (x,y,z).'
+                    },
+                    parent: {
+                        type: 'string',
+                        description: 'Parent GameObject scene path (optional).'
+                    },
+                    name: {
+                        type: 'string',
+                        description: 'Override name for the instantiated object.'
+                    }
+                },
+                required: ['prefabPath']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Call parent validation for required fields
+        super.validate(params);
+
+        const { prefabPath, parent, position, rotation } = params;
+
+        // Validate prefabPath format
+        if (!prefabPath.startsWith('Assets/') || !prefabPath.endsWith('.prefab')) {
+            throw new Error('prefabPath must start with Assets/ and end with .prefab');
+        }
+
+        // Validate parent when provided
+        if (parent !== undefined && parent === '') {
+            throw new Error('parent cannot be empty when provided');
+        }
+
+        // Validate position object when provided
+        if (position !== undefined) {
+            if (typeof position !== 'object' || position === null) {
+                throw new Error('position must be an object');
+            }
+            
+            // Check individual properties first for better error messages
+            if ('x' in position && typeof position.x !== 'number') {
+                throw new Error('position.x must be a number');
+            }
+            if ('y' in position && typeof position.y !== 'number') {
+                throw new Error('position.y must be a number');
+            }
+            if ('z' in position && typeof position.z !== 'number') {
+                throw new Error('position.z must be a number');
+            }
+            
+            // Then check for missing properties
+            if (!('x' in position) || !('y' in position) || !('z' in position)) {
+                throw new Error('position must have x, y, and z properties');
+            }
+        }
+
+        // Validate rotation object when provided
+        if (rotation !== undefined) {
+            if (typeof rotation !== 'object' || rotation === null) {
+                throw new Error('rotation must be an object');
+            }
+            
+            if (!('x' in rotation) || !('y' in rotation) || !('z' in rotation)) {
+                throw new Error('rotation must have x, y, and z properties');
+            }
+
+            if (typeof rotation.x !== 'number') {
+                throw new Error('rotation.x must be a number');
+            }
+            if (typeof rotation.y !== 'number') {
+                throw new Error('rotation.y must be a number');
+            }
+            if (typeof rotation.z !== 'number') {
+                throw new Error('rotation.z must be a number');
+            }
+        }
+    }
+
+    async execute(params) {
+        const {
+            prefabPath,
+            position,
+            rotation,
+            parent,
+            name
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('instantiate_prefab', {
+            prefabPath,
+            position,
+            rotation,
+            parent,
+            name
+        });
+
+        return result;
+    }
+}

package/src/handlers/asset/ModifyMaterialToolHandler.js

@@ -0,0 +1,76 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ModifyMaterialToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'modify_material',
+            'Modify a material by updating property values and/or changing the shader.',
+            {
+                type: 'object',
+                properties: {
+                    materialPath: {
+                        type: 'string',
+                        description: 'Asset path to the material. Must start with Assets/ and end with .mat.'
+                    },
+                    properties: {
+                        type: 'object',
+                        description: 'Property updates (e.g., {"_Color":[1,0,0,1], "_Metallic":0.5}).'
+                    },
+                    shader: {
+                        type: 'string',
+                        description: 'Optional: change the shader (e.g., Standard, Unlit/Color).'
+                    }
+                },
+                required: ['materialPath', 'properties']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Call parent validation for required fields
+        super.validate(params);
+
+        const { materialPath, properties, shader } = params;
+
+        // Validate materialPath format
+        if (!materialPath.startsWith('Assets/') || !materialPath.endsWith('.mat')) {
+            throw new Error('materialPath must start with Assets/ and end with .mat');
+        }
+
+        // Validate properties
+        if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
+            throw new Error('properties must be an object');
+        }
+
+        if (Object.keys(properties).length === 0) {
+            throw new Error('properties cannot be empty');
+        }
+
+        // Validate shader when provided
+        if (shader !== undefined && shader === '') {
+            throw new Error('shader cannot be empty when provided');
+        }
+    }
+
+    async execute(params) {
+        const {
+            materialPath,
+            properties,
+            shader
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('modify_material', {
+            materialPath,
+            properties,
+            shader
+        });
+
+        return result;
+    }
+}

package/src/handlers/asset/ModifyPrefabToolHandler.js

@@ -0,0 +1,72 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ModifyPrefabToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'modify_prefab',
+            'Modify an existing prefab by applying property changes (optionally to instances).',
+            {
+                type: 'object',
+                properties: {
+                    prefabPath: {
+                        type: 'string',
+                        description: 'Asset path to the prefab. Must start with Assets/ and end with .prefab.'
+                    },
+                    modifications: {
+                        type: 'object',
+                        description: 'Key/value object of properties to modify on the prefab.'
+                    },
+                    applyToInstances: {
+                        type: 'boolean',
+                        description: 'If true, also apply to existing scene instances (default: true).'
+                    }
+                },
+                required: ['prefabPath', 'modifications']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Call parent validation for required fields
+        super.validate(params);
+
+        const { prefabPath, modifications } = params;
+
+        // Validate prefabPath format
+        if (!prefabPath.startsWith('Assets/') || !prefabPath.endsWith('.prefab')) {
+            throw new Error('prefabPath must start with Assets/ and end with .prefab');
+        }
+
+        // Validate modifications is object
+        if (typeof modifications !== 'object' || modifications === null || Array.isArray(modifications)) {
+            throw new Error('modifications must be an object');
+        }
+
+        // Validate modifications is not empty
+        if (Object.keys(modifications).length === 0) {
+            throw new Error('modifications cannot be empty');
+        }
+    }
+
+    async execute(params) {
+        const {
+            prefabPath,
+            modifications,
+            applyToInstances = true
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('modify_prefab', {
+            prefabPath,
+            modifications,
+            applyToInstances
+        });
+
+        return result;
+    }
+}

package/src/handlers/asset/OpenPrefabToolHandler.js

@@ -0,0 +1,121 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for opening prefabs in Unity's prefab mode
+ */
+export class OpenPrefabToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'open_prefab',
+      'Open a prefab asset in prefab mode for editing. Once in prefab mode, use component tools (list_components, add_component, etc.) to inspect and modify components.',
+      {
+        type: 'object',
+        properties: {
+          prefabPath: {
+            type: 'string',
+            description: 'Asset path to the prefab (must start with Assets/ and end with .prefab)'
+          },
+          focusObject: {
+            type: 'string',
+            description: 'Optional path to object within prefab to focus on (relative to prefab root)'
+          },
+          isolateObject: {
+            type: 'boolean',
+            description: 'Isolate the focused object in the hierarchy (default: false)'
+          }
+        },
+        required: ['prefabPath']
+      }
+    );
+    
+    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 { prefabPath } = params;
+
+    // Validate prefabPath is not empty
+    if (!prefabPath || prefabPath.trim() === '') {
+      throw new Error('prefabPath cannot be empty');
+    }
+
+    // Validate prefabPath format
+    if (!prefabPath.startsWith('Assets/') || !prefabPath.endsWith('.prefab')) {
+      throw new Error('prefabPath must start with Assets/ and end with .prefab');
+    }
+  }
+
+  /**
+   * Executes the open prefab operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of opening the prefab
+   */
+  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('open_prefab', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      success: response.success,
+      prefabPath: response.prefabPath,
+      isInPrefabMode: response.isInPrefabMode,
+      prefabContentsRoot: response.prefabContentsRoot,
+      message: response.message || 'Prefab opened',
+      ...(response.focusedObject !== undefined && { focusedObject: response.focusedObject }),
+      ...(response.wasAlreadyOpen !== undefined && { wasAlreadyOpen: response.wasAlreadyOpen })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      openSimple: {
+        description: 'Open a prefab for editing',
+        params: {
+          prefabPath: 'Assets/Prefabs/PlayerCharacter.prefab'
+        }
+      },
+      openWithFocus: {
+        description: 'Open prefab and focus on specific object',
+        params: {
+          prefabPath: 'Assets/Prefabs/UI/MainMenu.prefab',
+          focusObject: '/Canvas/Buttons/StartButton'
+        }
+      },
+      openWithIsolation: {
+        description: 'Open prefab and isolate specific object',
+        params: {
+          prefabPath: 'Assets/Prefabs/Enemies/Boss.prefab',
+          focusObject: '/Armature/Hips/Spine',
+          isolateObject: true
+        }
+      },
+      openForComponentWork: {
+        description: 'Open prefab for component inspection and modification (use with component tools like list_components, add_component, etc.)',
+        params: {
+          prefabPath: 'Assets/Prefabs/Weapons/Sword.prefab'
+        }
+      }
+    };
+  }
+}

package/src/handlers/asset/SavePrefabToolHandler.js

@@ -0,0 +1,106 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for saving prefab changes in Unity
+ */
+export class SavePrefabToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'save_prefab',
+      'Save current prefab changes in prefab mode or save a GameObject as prefab override',
+      {
+        type: 'object',
+        properties: {
+          gameObjectPath: {
+            type: 'string',
+            description: 'Path to GameObject to save as prefab override (optional - if not provided, saves current prefab in prefab mode)'
+          },
+          includeChildren: {
+            type: 'boolean',
+            description: 'Include child object overrides when saving (default: true)'
+          }
+        }
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    const { gameObjectPath } = params;
+
+    // If gameObjectPath is provided, ensure it's not empty
+    if (gameObjectPath !== undefined && gameObjectPath.trim() === '') {
+      throw new Error('gameObjectPath cannot be empty when provided');
+    }
+  }
+
+  /**
+   * Executes the save prefab operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The result of saving the prefab
+   */
+  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('save_prefab', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return result
+    return {
+      success: response.success,
+      message: response.message || 'Prefab saved',
+      ...(response.savedInPrefabMode !== undefined && { savedInPrefabMode: response.savedInPrefabMode }),
+      ...(response.prefabPath !== undefined && { prefabPath: response.prefabPath }),
+      ...(response.gameObjectPath !== undefined && { gameObjectPath: response.gameObjectPath }),
+      ...(response.overridesApplied !== undefined && { overridesApplied: response.overridesApplied }),
+      ...(response.includedChildren !== undefined && { includedChildren: response.includedChildren })
+    };
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      saveInPrefabMode: {
+        description: 'Save changes while in prefab mode',
+        params: {}
+      },
+      savePrefabInstance: {
+        description: 'Save GameObject prefab instance overrides',
+        params: {
+          gameObjectPath: '/Player'
+        }
+      },
+      saveWithChildren: {
+        description: 'Save prefab instance including all child overrides',
+        params: {
+          gameObjectPath: '/UI/MainMenu',
+          includeChildren: true
+        }
+      },
+      saveWithoutChildren: {
+        description: 'Save only the root GameObject overrides',
+        params: {
+          gameObjectPath: '/Enemies/Boss',
+          includeChildren: false
+        }
+      }
+    };
+  }
+}