@akiojin/unity-mcp-server 2.14.14

package/src/handlers/system/PingToolHandler.js

@@ -0,0 +1,53 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for the ping tool
+ * Tests connection to Unity Editor
+ */
+export class PingToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'ping',
+      'Test connection to Unity Editor',
+      {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description: 'Optional message to echo back'
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the ping command
+   * @param {object} params - Input parameters
+   * @returns {Promise<object>} Ping result
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send ping command with optional message
+    const result = await this.unityConnection.sendCommand('ping', {
+      message: params.message || 'ping'
+    });
+    
+    // Format the result for the response
+    return {
+      message: result.message,
+      echo: result.echo || params.message || 'ping',
+      timestamp: result.timestamp || new Date().toISOString(),
+      unityVersion: result.unityVersion,
+      version: result._version || result.version,
+      editorState: result._editorState || result.editorState
+    };
+  }
+}

package/src/handlers/system/RefreshAssetsToolHandler.js

@@ -0,0 +1,45 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for the refresh_assets tool
+ * Triggers Unity to refresh assets and potentially recompile
+ */
+export class RefreshAssetsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'refresh_assets',
+      'Refresh assets and check compilation status.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the refresh_assets command
+   * @param {object} params - Input parameters (none required)
+   * @returns {Promise<object>} Refresh result
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    
+    // Send refresh_assets command
+    const result = await this.unityConnection.sendCommand('refresh_assets', {});
+    
+    return {
+      message: result.message,
+      isCompiling: result.isCompiling,
+      timestamp: result.timestamp,
+      note: result.isCompiling 
+        ? 'Unity is compiling. New commands will be available after compilation completes.'
+        : 'Asset refresh complete. Unity is not currently compiling.'
+    };
+  }
+}

package/src/handlers/ui/ClickUIElementToolHandler.js

@@ -0,0 +1,110 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ClickUIElementToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'click_ui_element',
+            'Simulate clicking on UI elements',
+            {
+                type: 'object',
+                properties: {
+                    elementPath: {
+                        type: 'string',
+                        description: 'Full hierarchy path to the UI element'
+                    },
+                    clickType: {
+                        type: 'string',
+                        enum: ['left', 'right', 'middle'],
+                        
+                        description: 'Type of click (left, right, middle)'
+                    },
+                    holdDuration: {
+                        type: 'number',
+                        
+                        minimum: 0,
+                        maximum: 10000,
+                        description: 'Duration to hold click in milliseconds'
+                    },
+                    position: {
+                        type: 'object',
+                        properties: {
+                            x: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'X position within element (0-1)'
+                            },
+                            y: {
+                                type: 'number',
+                                minimum: 0,
+                                maximum: 1,
+                                description: 'Y position within element (0-1)'
+                            }
+                        },
+                        description: 'Specific position within element to click'
+                    }
+                },
+                required: ['elementPath']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Call parent validation for required fields
+        super.validate(params);
+
+        // Validate clickType enum
+        if (params.clickType && !['left', 'right', 'middle'].includes(params.clickType)) {
+            throw new Error('clickType must be one of: left, right, middle');
+        }
+
+        // Validate holdDuration range
+        if (params.holdDuration !== undefined) {
+            const duration = params.holdDuration;
+            if (typeof duration !== 'number' || duration < 0 || duration > 10000) {
+                throw new Error('holdDuration must be between 0 and 10000 milliseconds');
+            }
+        }
+
+        // Validate position object
+        if (params.position) {
+            const pos = params.position;
+            if (pos.x !== undefined && typeof pos.x !== 'number') {
+                throw new Error('position.x must be a number');
+            }
+            if (pos.y !== undefined && typeof pos.y !== 'number') {
+                throw new Error('position.y must be a number');
+            }
+            if (pos.x !== undefined && (pos.x < 0 || pos.x > 1)) {
+                throw new Error('position.x must be between 0 and 1');
+            }
+            if (pos.y !== undefined && (pos.y < 0 || pos.y > 1)) {
+                throw new Error('position.y must be between 0 and 1');
+            }
+        }
+    }
+
+    async execute(params) {
+        const {
+            elementPath,
+            clickType = 'left',
+            holdDuration = 0,
+            position
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('click_ui_element', {
+            elementPath,
+            clickType,
+            holdDuration,
+            position
+        });
+
+        return result;
+    }
+}

package/src/handlers/ui/FindUIElementsToolHandler.js

@@ -0,0 +1,63 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class FindUIElementsToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'find_ui_elements',
+            'Find UI elements by component type, tag, or name pattern.',
+            {
+                type: 'object',
+                properties: {
+                    elementType: {
+                        type: 'string',
+                        description: 'UI component type (e.g., Button, Toggle, Slider).'
+                    },
+                    tagFilter: {
+                        type: 'string',
+                        description: 'Filter by GameObject tag.'
+                    },
+                    namePattern: {
+                        type: 'string',
+                        description: 'Search by name substring or regex.'
+                    },
+                    includeInactive: {
+                        type: 'boolean',
+                        description: 'If true, include inactive UI elements.'
+                    },
+                    canvasFilter: {
+                        type: 'string',
+                        description: 'Filter by parent Canvas name.'
+                    }
+                },
+                required: []
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    async execute(params = {}) {
+        const {
+            elementType,
+            tagFilter,
+            namePattern,
+            includeInactive = false,
+            canvasFilter
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('find_ui_elements', {
+            elementType,
+            tagFilter,
+            namePattern,
+            includeInactive,
+            canvasFilter
+        });
+
+        // Return the result for the BaseToolHandler to format
+        return result;
+    }
+}

package/src/handlers/ui/GetUIElementStateToolHandler.js

@@ -0,0 +1,50 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class GetUIElementStateToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'get_ui_element_state',
+            'Get detailed state information about UI elements',
+            {
+                type: 'object',
+                properties: {
+                    elementPath: {
+                        type: 'string',
+                        description: 'Full hierarchy path to the UI element'
+                    },
+                    includeChildren: {
+                        type: 'boolean',
+                        description: 'Include child element states (default: false)'
+                    },
+                    includeInteractableInfo: {
+                        type: 'boolean',
+                        description: 'Include interaction capabilities (default: true)'
+                    }
+                },
+                required: ['elementPath']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    async execute(params) {
+        const {
+            elementPath,
+            includeChildren = false,
+            includeInteractableInfo = true
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('get_ui_element_state', {
+            elementPath,
+            includeChildren,
+            includeInteractableInfo
+        });
+
+        return result;
+    }
+}

package/src/handlers/ui/SetUIElementValueToolHandler.js

@@ -0,0 +1,49 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class SetUIElementValueToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'set_ui_element_value',
+            'Set values for UI input elements',
+            {
+                type: 'object',
+                properties: {
+                    elementPath: {
+                        type: 'string',
+                        description: 'Full hierarchy path to the UI element'
+                    },
+                    value: {
+                        description: 'New value to set (type depends on element type)'
+                    },
+                    triggerEvents: {
+                        type: 'boolean',
+                        description: 'Whether to trigger associated events (default: true)'
+                    }
+                },
+                required: ['elementPath', 'value']
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    async execute(params) {
+        const {
+            elementPath,
+            value,
+            triggerEvents = true
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        const result = await this.unityConnection.sendCommand('set_ui_element_value', {
+            elementPath,
+            value,
+            triggerEvents
+        });
+
+        return result;
+    }
+}

package/src/handlers/ui/SimulateUIInputToolHandler.js

@@ -0,0 +1,156 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class SimulateUIInputToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'simulate_ui_input',
+            'Simulate complex UI interactions and input sequences',
+            {
+                type: 'object',
+                properties: {
+                    // Option 1: Simple single input
+                    elementPath: {
+                        type: 'string',
+                        description: 'Target UI element path (for simple input)'
+                    },
+                    inputType: {
+                        type: 'string',
+                        enum: ['click', 'doubleclick', 'rightclick', 'hover', 'focus', 'type'],
+                        description: 'Type of input to simulate (for simple input)'
+                    },
+                    inputData: {
+                        type: 'string',
+                        description: 'Data for input (e.g., text to type)'
+                    },
+                    // Option 2: Complex sequence
+                    inputSequence: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                type: {
+                                    type: 'string',
+                                    description: 'Action type (click, setvalue)'
+                                },
+                                params: {
+                                    type: 'object',
+                                    description: 'Parameters for the action'
+                                }
+                            },
+                            required: ['type', 'params']
+                        },
+                        description: 'Array of input actions to perform (for complex input)'
+                    },
+                    waitBetween: {
+                        type: 'number',
+                        
+                        minimum: 0,
+                        maximum: 10000,
+                        description: 'Delay between actions in milliseconds'
+                    },
+                    validateState: {
+                        type: 'boolean',
+                        description: 'Validate UI state between actions (default: true)'
+                    }
+                }
+            }
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    validate(params) {
+        // Check if using simple mode or complex mode
+        const hasSimpleParams = params.elementPath && params.inputType;
+        const hasComplexParams = params.inputSequence;
+
+        if (!hasSimpleParams && !hasComplexParams) {
+            throw new Error('Either (elementPath + inputType) or inputSequence is required');
+        }
+
+        if (hasSimpleParams && hasComplexParams) {
+            throw new Error('Cannot use both simple and complex input modes simultaneously');
+        }
+
+        // Validate simple mode
+        if (hasSimpleParams) {
+            if (!params.elementPath || typeof params.elementPath !== 'string') {
+                throw new Error('elementPath must be a non-empty string');
+            }
+
+            const validInputTypes = ['click', 'doubleclick', 'rightclick', 'hover', 'focus', 'type'];
+            if (!validInputTypes.includes(params.inputType)) {
+                throw new Error(`inputType must be one of: ${validInputTypes.join(', ')}`);
+            }
+
+            if (params.inputType === 'type' && !params.inputData) {
+                throw new Error('inputData is required when inputType is "type"');
+            }
+        }
+
+        // Validate complex mode
+        if (hasComplexParams) {
+            if (!Array.isArray(params.inputSequence)) {
+                throw new Error('inputSequence must be an array');
+            }
+
+            if (params.inputSequence.length === 0) {
+                throw new Error('inputSequence must contain at least one action');
+            }
+
+            // Validate each action
+            for (const action of params.inputSequence) {
+                if (!action.type || !action.params) {
+                    throw new Error('Each action must have type and params');
+                }
+            }
+        }
+
+        // Validate waitBetween range
+        if (params.waitBetween !== undefined) {
+            const wait = params.waitBetween;
+            if (typeof wait !== 'number' || wait < 0 || wait > 10000) {
+                throw new Error('waitBetween must be between 0 and 10000 milliseconds');
+            }
+        }
+    }
+
+    async execute(params) {
+        const {
+            elementPath,
+            inputType,
+            inputData,
+            inputSequence,
+            waitBetween = 100,
+            validateState = true
+        } = params;
+
+        // Ensure connected
+        if (!this.unityConnection.isConnected()) {
+            await this.unityConnection.connect();
+        }
+
+        let actualInputSequence;
+
+        // Handle simple mode - convert to sequence format
+        if (elementPath && inputType) {
+            actualInputSequence = [{
+                type: inputType,
+                params: {
+                    elementPath,
+                    inputData: inputData || null
+                }
+            }];
+        } else {
+            // Use provided sequence
+            actualInputSequence = inputSequence;
+        }
+
+        const result = await this.unityConnection.sendCommand('simulate_ui_input', {
+            inputSequence: actualInputSequence,
+            waitBetween,
+            validateState
+        });
+
+        return result;
+    }
+}

package/src/handlers/video/CaptureVideoForToolHandler.js

@@ -0,0 +1,96 @@
+/**
+ * Handler for recording video for a fixed duration (auto-stop).
+ * Orchestrates start→wait→stop via Unity MCP commands.
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class CaptureVideoForToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'capture_video_for',
+      'Record video for a fixed duration (auto-stop). Optionally enters Play Mode first.',
+      {
+        type: 'object',
+        properties: {
+          captureMode: { type: 'string', enum: ['game'], description: 'Capture source. Currently only "game" supported.' },
+          width: { type: 'number', description: 'Output width (0 = default 1280)' },
+          height: { type: 'number', description: 'Output height (0 = default 720)' },
+          fps: { type: 'number', description: 'Frames per second (default 30)' },
+          durationSec: { type: 'number', description: 'Duration to record in seconds' },
+          play: { type: 'boolean', description: 'Enter Play Mode before recording (default true if not already playing)' }
+        },
+        required: ['durationSec']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params) {
+    const startTime = Date.now();
+    let enteredPlay = false;
+    try {
+      // Optionally enter Play Mode (default true if not already playing)
+      let needPlay = !!params.play;
+      if (params.play === undefined) {
+        try {
+          const s0 = await this.unityConnection.sendCommand('get_editor_state', {});
+          needPlay = !(s0 && s0.isPlaying);
+        } catch { needPlay = true; }
+      }
+      if (needPlay) {
+        await this.unityConnection.sendCommand('play_game', {});
+        for (let i = 0; i < 60; i++) {
+          const s = await this.unityConnection.sendCommand('get_editor_state', {});
+          if (s && s.isPlaying) { enteredPlay = true; break; }
+          await sleep(250);
+        }
+      }
+
+      // Start with auto-stop
+      const { WORKSPACE_ROOT } = await import('../../core/config.js');
+      const startResp = await this.unityConnection.sendCommand('capture_video_start', {
+        captureMode: params.captureMode || 'game',
+        width: params.width ?? 1280,
+        height: params.height ?? 720,
+        fps: params.fps ?? 30,
+        maxDurationSec: params.durationSec,
+        workspaceRoot: WORKSPACE_ROOT
+      });
+      if (startResp && startResp.error) {
+        return { error: startResp.error, code: startResp.code || 'UNITY_ERROR' };
+      }
+
+      // Wait until stopped (status reports isRecording=false)
+      const deadline = Date.now() + Math.max(0, Math.floor((params.durationSec || 0) * 1000)) + 1500; // small buffer
+      let lastStatus = null;
+      while (Date.now() < deadline) {
+        lastStatus = await this.unityConnection.sendCommand('capture_video_status', {});
+        if (lastStatus && lastStatus.isRecording === false) break;
+        await sleep(250);
+      }
+
+      // Safety stop if still recording after deadline
+      if (lastStatus && lastStatus.isRecording) {
+        await this.unityConnection.sendCommand('capture_video_stop', {});
+      }
+
+      // Final stop result
+      const stopResp = await this.unityConnection.sendCommand('capture_video_stop', {});
+      const elapsedMs = Date.now() - startTime;
+      return {
+        ...stopResp,
+        requestedDurationSec: params.durationSec,
+        elapsedMs,
+        message: 'Video recorded for requested duration and stopped'
+      };
+    } catch (e) {
+      return { error: e.message, code: 'CLIENT_ERROR' };
+    } finally {
+      // If we entered play, attempt to leave play (best-effort)
+      try { if (enteredPlay) await this.unityConnection.sendCommand('stop_game', {}); } catch {}
+    }
+  }
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/src/handlers/video/CaptureVideoStartToolHandler.js

@@ -0,0 +1,38 @@
+/**
+ * Handler for starting video capture in Unity Editor (via MCP)
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class CaptureVideoStartToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'capture_video_start',
+      'Start video recording (Game view). Requires com.unity.recorder.',
+      {
+        type: 'object',
+        properties: {
+          captureMode: { type: 'string', enum: ['game'], description: 'Capture source. Currently only "game" supported.' },
+          width: { type: 'number', description: 'Output width (0 = auto/default)' },
+          height: { type: 'number', description: 'Output height (0 = auto/default)' },
+          fps: { type: 'number', description: 'Frames per second (e.g., 30)' },
+          maxDurationSec: { type: 'number', description: 'Auto stop after N seconds (0 = unlimited)' }
+        }
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params, context) {
+    const { WORKSPACE_ROOT } = await import('../../core/config.js');
+    const { outputPath, ...rest } = params || {};
+    const response = await this.unityConnection.sendCommand('capture_video_start', { ...rest, workspaceRoot: WORKSPACE_ROOT });
+    if (response.error) {
+      return { error: response.error, code: response.code || 'UNITY_ERROR' };
+    }
+    return {
+      ...response,
+      message: response.message || 'Video recording started'
+    };
+  }
+}