@akiojin/unity-mcp-server 2.14.14

package/src/handlers/menu/ExecuteMenuItemToolHandler.js

@@ -0,0 +1,304 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for executing Unity Editor menu items
+ */
+export class ExecuteMenuItemToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'execute_menu_item',
+      'Execute a Unity menu item or list available menus (with safety checks).',
+      {
+        type: 'object',
+        properties: {
+          menuPath: {
+            type: 'string',
+            description: 'Unity menu path (e.g., "Assets/Refresh", "Window/General/Console")'
+          },
+          action: {
+            type: 'string',
+            enum: ['execute', 'get_available_menus'],
+            description: 'Action to perform: execute menu item or get available menus (default: execute)'
+          },
+          alias: {
+            type: 'string',
+            description: 'Menu alias for common operations (e.g., "refresh", "console")'
+          },
+          parameters: {
+            type: 'object',
+            description: 'Additional parameters for menu execution (if supported)'
+          },
+          safetyCheck: {
+            type: 'boolean',
+            description: 'Enable safety checks to prevent execution of dangerous menu items (default: true)'
+          }
+        },
+        required: ['menuPath']
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+    
+    // Define blacklisted menu items for safety
+    // Includes dialog-opening menus that cause MCP hanging
+    this.blacklistedMenus = new Set([
+      // Application control
+      'File/Quit',
+      
+      // Dialog-opening file operations (cause MCP hanging)
+      'File/Open Scene',
+      'File/New Scene', 
+      'File/Save Scene As...',
+      'File/Build Settings...',
+      'File/Build And Run',
+      
+      // Dialog-opening asset operations (cause MCP hanging)
+      'Assets/Import New Asset...',
+      'Assets/Import Package/Custom Package...',
+      'Assets/Export Package...',
+      'Assets/Delete',
+      
+      // Dialog-opening preferences and settings (cause MCP hanging)
+      'Edit/Preferences...',
+      'Edit/Project Settings...',
+      
+      // Dialog-opening window operations (may cause issues)
+      'Window/Package Manager',
+      'Window/Asset Store',
+      
+      // Scene view operations that may require focus (potential hanging)
+      'GameObject/Align With View',
+      'GameObject/Align View to Selected'
+    ]);
+    
+    // Common menu aliases
+    this.menuAliases = new Map([
+      ['refresh', 'Assets/Refresh'],
+      ['console', 'Window/General/Console'],
+      ['inspector', 'Window/General/Inspector'],
+      ['hierarchy', 'Window/General/Hierarchy'],
+      ['project', 'Window/General/Project'],
+      ['scene', 'Window/General/Scene'],
+      ['game', 'Window/General/Game'],
+      ['animation', 'Window/Animation/Animation'],
+      ['animator', 'Window/Animation/Animator']
+    ]);
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    const { menuPath, action, safetyCheck = true } = params;
+
+    // menuPath is required
+    if (!menuPath) {
+      throw new Error('menuPath is required');
+    }
+
+    if (typeof menuPath !== 'string' || menuPath.trim() === '') {
+      throw new Error('menuPath cannot be empty');
+    }
+
+    // Safety check for blacklisted items with security normalization (BEFORE format validation)
+    if (safetyCheck && this.isMenuPathBlacklisted(menuPath)) {
+      throw new Error(`Menu item is blacklisted for safety: ${menuPath}. Use safetyCheck: false to override.`);
+    }
+
+    // Validate menu path format (should contain at least one slash) - after normalization for security
+    const normalizedForValidation = this.normalizeMenuPath(menuPath);
+    if (!normalizedForValidation.includes('/') || normalizedForValidation.startsWith('/') || normalizedForValidation.endsWith('/')) {
+      throw new Error('menuPath must be in format "Category/MenuItem" (e.g., "Assets/Refresh")');
+    }
+
+    // Validate action if provided
+    if (action && !['execute', 'get_available_menus'].includes(action)) {
+      throw new Error('action must be one of: execute, get_available_menus');
+    }
+  }
+
+  /**
+   * Executes the menu item operation
+   * @param {Object} params - The input parameters
+   * @returns {Promise<Object>} The result of the menu operation
+   */
+  async execute(params) {
+    const {
+      menuPath,
+      action = 'execute',
+      alias,
+      parameters,
+      safetyCheck = true
+    } = params;
+
+    // Ensure connection to Unity
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    // Resolve alias if provided
+    let resolvedMenuPath = menuPath;
+    if (alias && this.menuAliases.has(alias)) {
+      resolvedMenuPath = this.menuAliases.get(alias);
+    }
+
+    // Prepare command parameters
+    const commandParams = {
+      action,
+      menuPath: resolvedMenuPath,
+      safetyCheck
+    };
+
+    // Add optional parameters
+    if (alias) {
+      commandParams.alias = alias;
+    }
+    if (parameters) {
+      commandParams.parameters = parameters;
+    }
+
+    // Send command to Unity
+    const response = await this.unityConnection.sendCommand('execute_menu_item', commandParams);
+
+    // Handle Unity response
+    if (response.success === false) {
+      throw new Error(response.error || 'Failed to execute menu operation');
+    }
+
+    // Build result object based on action
+    if (action === 'get_available_menus') {
+      return {
+        availableMenus: response.availableMenus || [],
+        totalMenus: response.totalMenus,
+        filteredCount: response.filteredCount,
+        message: response.message || 'Available menus retrieved successfully'
+      };
+    } else {
+      // Execute action
+      const result = {
+        menuPath: response.menuPath || resolvedMenuPath,
+        message: response.message || 'Menu item executed successfully'
+      };
+
+      // Include optional metadata if available
+      if (response.executed !== undefined) {
+        result.executed = response.executed;
+      }
+      if (response.executionTime !== undefined) {
+        result.executionTime = response.executionTime;
+      }
+      if (response.menuExists !== undefined) {
+        result.menuExists = response.menuExists;
+      }
+      if (response.alias) {
+        result.alias = response.alias;
+      }
+
+      return result;
+    }
+  }
+
+  /**
+   * Gets a list of common menu aliases
+   * @returns {Object} Map of aliases to menu paths
+   */
+  getMenuAliases() {
+    return Object.fromEntries(this.menuAliases);
+  }
+
+  /**
+   * Gets a list of blacklisted menu items
+   * @returns {Array} List of blacklisted menu paths
+   */
+  getBlacklistedMenus() {
+    return Array.from(this.blacklistedMenus);
+  }
+
+  /**
+   * Adds a custom menu alias
+   * @param {string} alias - The alias name
+   * @param {string} menuPath - The Unity menu path
+   */
+  addMenuAlias(alias, menuPath) {
+    this.menuAliases.set(alias, menuPath);
+  }
+
+  /**
+   * Adds a menu item to the blacklist
+   * @param {string} menuPath - The Unity menu path to blacklist
+   */
+  addToBlacklist(menuPath) {
+    this.blacklistedMenus.add(menuPath);
+  }
+
+  /**
+   * Securely checks if a menu path is blacklisted using normalized comparison
+   * Prevents bypass attacks using case changes, whitespace, Unicode, etc.
+   * @param {string} menuPath - The menu path to check
+   * @returns {boolean} True if the path is blacklisted
+   */
+  isMenuPathBlacklisted(menuPath) {
+    // Normalize the input path to prevent bypass attacks
+    const normalizedPath = this.normalizeMenuPath(menuPath);
+    
+    // Check against normalized blacklist entries
+    for (const blacklistedItem of this.blacklistedMenus) {
+      const normalizedBlacklistItem = this.normalizeMenuPath(blacklistedItem);
+      if (normalizedPath === normalizedBlacklistItem) {
+        return true;
+      }
+    }
+    
+    return false;
+  }
+
+  /**
+   * Normalizes a menu path to prevent security bypass attacks
+   * @param {string} menuPath - The raw menu path
+   * @returns {string} The normalized path
+   */
+  normalizeMenuPath(menuPath) {
+    if (!menuPath || typeof menuPath !== 'string') {
+      return '';
+    }
+
+    // Step 1: Remove zero-width and invisible Unicode characters
+    let normalized = menuPath.replace(/[\u200B-\u200D\uFEFF\u00AD\u034F\u061C\u180E\u2060-\u2069]/g, '');
+    
+    // Step 2: Normalize Unicode to canonical form (handles homograph attacks)
+    normalized = normalized.normalize('NFC');
+    
+    // Step 3: Convert to lowercase for case-insensitive comparison
+    normalized = normalized.toLowerCase();
+    
+    // Step 4: Trim whitespace and remove all internal whitespace (security bypass prevention)
+    normalized = normalized.trim().replace(/\s+/g, '');
+    
+    // Step 5: Normalize path separators (convert backslashes to forward slashes)
+    normalized = normalized.replace(/\\/g, '/');
+    
+    // Step 6: Remove duplicate path separators
+    normalized = normalized.replace(/\/+/g, '/');
+    
+    // Step 7: Handle common homograph substitutions for ASCII characters
+    const homographMap = {
+      // Cyrillic lookalikes
+      'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c', 'х': 'x', 'у': 'y',
+      'і': 'i', 'ј': 'j', 'ѕ': 's', 'һ': 'h', 'ց': 'q', 'ԁ': 'd', 'ɡ': 'g',
+      // Greek lookalikes
+      'α': 'a', 'β': 'b', 'γ': 'g', 'δ': 'd', 'ε': 'e', 'ζ': 'z', 'η': 'h',
+      'θ': 'o', 'ι': 'i', 'κ': 'k', 'λ': 'l', 'μ': 'm', 'ν': 'n', 'ξ': 'x',
+      'ο': 'o', 'π': 'p', 'ρ': 'p', 'σ': 's', 'τ': 't', 'υ': 'u', 'φ': 'f',
+      'χ': 'x', 'ψ': 'y', 'ω': 'w'
+    };
+    
+    // Replace homographs
+    for (const [homograph, ascii] of Object.entries(homographMap)) {
+      normalized = normalized.replace(new RegExp(homograph, 'g'), ascii);
+    }
+    
+    return normalized;
+  }
+}

package/src/handlers/package/PackageManagerToolHandler.js

@@ -0,0 +1,248 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Package Manager Tool Handler for Unity MCP
+ * Handles Unity Package Manager operations including search, install, and management
+ */
+
+export default class PackageManagerToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'package_manager',
+      'Manage Unity packages - search, install, remove, and list packages',
+      {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['search', 'list', 'install', 'remove', 'info', 'recommend'],
+            description: 'The package operation to perform'
+          },
+          keyword: {
+            type: 'string',
+            description: 'Search keyword (for search action)'
+          },
+          packageId: {
+            type: 'string',
+            description: 'Package ID to install (e.g., com.unity.textmeshpro)'
+          },
+          packageName: {
+            type: 'string',
+            description: 'Package name to remove or get info'
+          },
+          version: {
+            type: 'string',
+            description: 'Specific version to install (optional)'
+          },
+          category: {
+            type: 'string',
+            enum: ['essential', 'rendering', 'tools', 'networking', 'mobile'],
+            description: 'Category for recommendations'
+          },
+          includeBuiltIn: {
+            type: 'boolean',
+            description: 'Include built-in packages in list (default: false)'
+          },
+          limit: {
+            type: 'number',
+            description: 'Maximum number of search results (default: 20)'
+          }
+        },
+        required: ['action']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  validate(params) {
+    const { action, keyword, packageId, packageName } = params || {};
+
+    if (!action) {
+      throw new Error('action is required');
+    }
+
+    const valid = ['search', 'list', 'install', 'remove', 'info', 'recommend'];
+    if (!valid.includes(action)) {
+      throw new Error(`Invalid action: ${action}. Must be one of: ${valid.join(', ')}`);
+    }
+
+    switch (action) {
+      case 'search':
+        if (!keyword) throw new Error('Search keyword is required for search action');
+        break;
+      case 'install':
+        if (!packageId) throw new Error('Package ID is required for install action');
+        break;
+      case 'remove':
+      case 'info':
+        if (!packageName) throw new Error('Package name is required for this action');
+        break;
+    }
+  }
+
+  async execute(params) {
+    const { action, ...parameters } = params;
+
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+
+    const result = await this.unityConnection.sendCommand('package_manager', {
+      action,
+      ...parameters
+    });
+
+    return this.formatResponse(action, result);
+  }
+
+  formatResponse(action, result) {
+    if (result && result.error) {
+      return {
+        success: false,
+        error: result.error
+      };
+    }
+
+    switch (action) {
+      case 'search':
+        return {
+          success: result.success,
+          action: 'search',
+          keyword: result.keyword,
+          totalCount: result.totalCount || 0,
+          packages: (result.packages || []).map(pkg => ({
+            packageId: pkg.packageId,
+            name: pkg.name,
+            displayName: pkg.displayName,
+            description: this.truncateDescription(pkg.description),
+            version: pkg.version,
+            category: pkg.category
+          })),
+          message: result.message || `Found ${result.totalCount || 0} packages`
+        };
+
+      case 'list':
+        return {
+          success: result.success,
+          action: 'list',
+          totalCount: result.totalCount || 0,
+          packages: (result.packages || []).map(pkg => ({
+            packageId: pkg.packageId,
+            name: pkg.name,
+            displayName: pkg.displayName,
+            version: pkg.version,
+            source: pkg.source,
+            isDirectDependency: pkg.isDirectDependency
+          })),
+          message: result.message || `Listed ${result.totalCount || 0} installed packages`
+        };
+
+      case 'install':
+        return {
+          success: result.success,
+          action: 'install',
+          packageId: result.packageId,
+          name: result.name,
+          displayName: result.displayName,
+          version: result.version,
+          message: result.message || `Successfully installed ${result.displayName || result.name}`
+        };
+
+      case 'remove':
+        return {
+          success: result.success,
+          action: 'remove',
+          packageName: result.packageName,
+          message: result.message || `Successfully removed ${result.packageName}`
+        };
+
+      case 'info':
+        if (result.package) {
+          return {
+            success: result.success,
+            action: 'info',
+            package: {
+              ...result.package,
+              description: this.truncateDescription(result.package.description)
+            },
+            message: `Package information for ${result.package.displayName || result.package.name}`
+          };
+        }
+        return result;
+
+      case 'recommend':
+        return {
+          success: result.success,
+          action: 'recommend',
+          category: result.category,
+          categories: result.categories,
+          packages: result.packages,
+          allPackages: result.allPackages,
+          message: result.message || 'Package recommendations retrieved'
+        };    }
+  }
+
+  truncateDescription(description) {
+    if (!description) return '';
+    const maxLength = 150;
+    if (description.length <= maxLength) return description;
+    return description.substring(0, maxLength) + '...';
+  }
+
+  static getExamples() {
+    return [
+      {
+        description: 'Search for packages',
+        input: {
+          action: 'search',
+          keyword: 'timeline',
+          limit: 10
+        }
+      },
+      {
+        description: 'Install a package',
+        input: {
+          action: 'install',
+          packageId: 'com.unity.textmeshpro'
+        }
+      },
+      {
+        description: 'Install a specific version',
+        input: {
+          action: 'install',
+          packageId: 'com.unity.timeline',
+          version: '1.7.1'
+        }
+      },
+      {
+        description: 'List installed packages',
+        input: {
+          action: 'list',
+          includeBuiltIn: false
+        }
+      },
+      {
+        description: 'Remove a package',
+        input: {
+          action: 'remove',
+          packageName: 'com.unity.timeline'
+        }
+      },
+      {
+        description: 'Get package info',
+        input: {
+          action: 'info',
+          packageName: 'com.unity.textmeshpro'
+        }
+      },
+      {
+        description: 'Get recommended packages',
+        input: {
+          action: 'recommend',
+          category: 'essential'
+        }
+      }
+    ];
+  }
+}