@akiojin/unity-mcp-server 2.25.0 → 2.26.1

package/src/handlers/menu/MenuItemExecuteToolHandler.js

@@ -18,7 +18,8 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
           action: {
             type: 'string',
             enum: ['execute', 'get_available_menus'],
-            description: 'Action to perform: execute menu item or get available menus (default: execute)'
+            description:
+              'Action to perform: execute menu item or get available menus (default: execute)'
           },
           alias: {
             type: 'string',
@@ -30,47 +31,48 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
           },
           safetyCheck: {
             type: 'boolean',
-            description: 'Enable safety checks to prevent execution of dangerous menu items (default: true)'
+            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/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'],
@@ -104,12 +106,18 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
 
     // 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.`);
+      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('/')) {
+    if (
+      !normalizedForValidation.includes('/') ||
+      normalizedForValidation.startsWith('/') ||
+      normalizedForValidation.endsWith('/')
+    ) {
       throw new Error('menuPath must be in format "Category/MenuItem" (e.g., "Assets/Refresh")');
     }
 
@@ -125,13 +133,7 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
    * @returns {Promise<Object>} The result of the menu operation
    */
   async execute(params) {
-    const {
-      menuPath,
-      action = 'execute',
-      alias,
-      parameters,
-      safetyCheck = true
-    } = params;
+    const { menuPath, action = 'execute', alias, parameters, safetyCheck = true } = params;
 
     // Ensure connection to Unity
     if (!this.unityConnection.isConnected()) {
@@ -242,7 +244,7 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
   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);
@@ -250,7 +252,7 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
         return true;
       }
     }
-    
+
     return false;
   }
 
@@ -265,40 +267,76 @@ export class MenuItemExecuteToolHandler extends BaseToolHandler {
     }
 
     // Step 1: Remove zero-width and invisible Unicode characters
-    let normalized = menuPath.replace(/[\u200B-\u200D\uFEFF\u00AD\u034F\u061C\u180E\u2060-\u2069]/g, '');
-    
+    // eslint-disable-next-line no-misleading-character-class
+    let normalized = menuPath.replace(
+      /[\u200B-\u200D\uFEFF\u00AD\u034F\u061C\u180E\u2060-\u2069]/gu,
+      ''
+    );
+
     // 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',
+      а: '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'
+      α: '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/screenshot/ScreenshotAnalyzeToolHandler.js

@@ -1,5 +1,4 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
-import fs from 'fs/promises';
 import path from 'path';
 
 /**
@@ -24,18 +23,20 @@ export class ScreenshotAnalyzeToolHandler extends BaseToolHandler {
           analysisType: {
             type: 'string',
             enum: ['basic', 'ui', 'content', 'full'],
-            
-            description: 'Type of analysis: basic (colors, dimensions), ui (UI element detection), content (scene content), full (all)'
+
+            description:
+              'Type of analysis: basic (colors, dimensions), ui (UI element detection), content (scene content), full (all)'
           },
           prompt: {
             type: 'string',
-            description: 'Optional prompt for AI-based analysis (e.g., "Find all buttons in the UI")'
+            description:
+              'Optional prompt for AI-based analysis (e.g., "Find all buttons in the UI")'
           }
         },
         required: []
       }
     );
-    
+
     this.unityConnection = unityConnection;
   }
 
@@ -62,7 +63,7 @@ export class ScreenshotAnalyzeToolHandler extends BaseToolHandler {
       if (!imagePath.startsWith('Assets/')) {
         throw new Error('imagePath must be within the Assets folder');
       }
-      
+
       const ext = path.extname(imagePath).toLowerCase();
       if (!['.png', '.jpg', '.jpeg'].includes(ext)) {
         throw new Error('imagePath must be a PNG or JPEG file');
@@ -159,24 +160,25 @@ export class ScreenshotAnalyzeToolHandler extends BaseToolHandler {
         result.analysis = {
           note: 'Basic analysis of base64 images requires image processing library integration',
           fileSize: fileSize,
-          estimatedFormat: fileSize > 100000 ? 'Likely PNG or high-quality JPEG' : 'Likely compressed JPEG'
+          estimatedFormat:
+            fileSize > 100000 ? 'Likely PNG or high-quality JPEG' : 'Likely compressed JPEG'
         };
         break;
-        
+
       case 'ui':
         result.uiAnalysis = {
           note: 'UI element detection requires computer vision integration',
           placeholder: 'This would detect buttons, text fields, panels, etc.'
         };
         break;
-        
+
       case 'content':
         result.contentAnalysis = {
           note: 'Content analysis requires scene understanding models',
           placeholder: 'This would identify GameObjects, lighting, materials, etc.'
         };
         break;
-        
+
       case 'full':
         result.fullAnalysis = {
           basic: { note: 'Requires image processing library' },

package/src/handlers/script/ScriptEditStructuredToolHandler.js

@@ -3,171 +3,179 @@ import { LspRpcClient } from '../../lsp/LspRpcClient.js';
 import { ProjectInfoProvider } from '../../core/projectInfo.js';
 
 export class ScriptEditStructuredToolHandler extends BaseToolHandler {
-    constructor(unityConnection) {
-        super(
-            'script_edit_structured',
-            '[C# EDITING - PRIMARY TOOL] For Unity C# script editing, PREFER this tool over Read/Edit/Write for structural code changes. Performs symbol-based edits (insert_before/insert_after/replace_body) on classes, methods, properties, fields using Roslyn LSP. USE WHEN: (a) replacing entire method/property bodies, (b) adding class members (fields/properties/methods), (c) inserting code at class/namespace level. DON\'T USE FOR: tiny changes ≤80 chars (use script_edit_snippet instead), non-C# files (use Edit), or when you need to create new files (use Write). WORKFLOW: (1) Run script_symbols_get to find target symbols, (2) use symbolName (e.g., "MyClass/MyMethod"), (3) apply edits. Insert operations target containers (class/namespace), not methods. Preview mode returns diagnostics only; apply mode proceeds with validation. Required: path (Assets/|Packages/), symbolName, operation. Optional: kind, newText, preview.',
-            {
-                type: 'object',
-                properties: {
-                    operation: {
-                        type: 'string',
-                        enum: ['insert_before', 'insert_after', 'replace_body'],
-                        description: 'Edit type: insert_before, insert_after, or replace_body.'
-                    },
-                    path: {
-                        type: 'string',
-                        description: 'Project-relative C# path starting with Assets/ or Packages/ (e.g., Packages/unity-mcp-server/Editor/Foo.cs). Do NOT prefix repository folders like UnityMCPServer/….'
-                    },
-                    symbolName: {
-                        type: 'string',
-                        description: 'Target symbol name (e.g., class/method/field name).'
-                    },
-                    kind: {
-                        type: 'string',
-                        description: 'Symbol kind (e.g., class, method, field, property). Optional but improves precision.'
-                    },
-                    newText: {
-                        type: 'string',
-                        description: 'Text to insert or use as replacement body.'
-                    },
-                    preview: {
-                        type: 'boolean',
-                        description: 'If true, returns a preview without writing files. Default=false to reduce large diff payloads.'
-                    }
-                },
-                required: ['operation', 'path', 'symbolName']
-            }
-        );
-        this.unityConnection = unityConnection;
-        this.projectInfo = new ProjectInfoProvider(unityConnection);
-        this.lsp = null;
+  constructor(unityConnection) {
+    super(
+      'script_edit_structured',
+      '[C# EDITING - PRIMARY TOOL] For Unity C# script editing, PREFER this tool over Read/Edit/Write for structural code changes. Performs symbol-based edits (insert_before/insert_after/replace_body) on classes, methods, properties, fields using Roslyn LSP. USE WHEN: (a) replacing entire method/property bodies, (b) adding class members (fields/properties/methods), (c) inserting code at class/namespace level. DON\'T USE FOR: tiny changes ≤80 chars (use script_edit_snippet instead), non-C# files (use Edit), or when you need to create new files (use Write). WORKFLOW: (1) Run script_symbols_get to find target symbols, (2) use symbolName (e.g., "MyClass/MyMethod"), (3) apply edits. Insert operations target containers (class/namespace), not methods. Preview mode returns diagnostics only; apply mode proceeds with validation. Required: path (Assets/|Packages/), symbolName, operation. Optional: kind, newText, preview.',
+      {
+        type: 'object',
+        properties: {
+          operation: {
+            type: 'string',
+            enum: ['insert_before', 'insert_after', 'replace_body'],
+            description: 'Edit type: insert_before, insert_after, or replace_body.'
+          },
+          path: {
+            type: 'string',
+            description:
+              'Project-relative C# path starting with Assets/ or Packages/ (e.g., Packages/unity-mcp-server/Editor/Foo.cs). Do NOT prefix repository folders like UnityMCPServer/….'
+          },
+          symbolName: {
+            type: 'string',
+            description: 'Target symbol name (e.g., class/method/field name).'
+          },
+          kind: {
+            type: 'string',
+            description:
+              'Symbol kind (e.g., class, method, field, property). Optional but improves precision.'
+          },
+          newText: {
+            type: 'string',
+            description: 'Text to insert or use as replacement body.'
+          },
+          preview: {
+            type: 'boolean',
+            description:
+              'If true, returns a preview without writing files. Default=false to reduce large diff payloads.'
+          }
+        },
+        required: ['operation', 'path', 'symbolName']
+      }
+    );
+    this.unityConnection = unityConnection;
+    this.projectInfo = new ProjectInfoProvider(unityConnection);
+    this.lsp = null;
+  }
+
+  validate(params) {
+    super.validate(params);
+
+    const { operation, path, symbolName, kind } = params;
+
+    const validOperations = ['insert_before', 'insert_after', 'replace_body'];
+    if (!validOperations.includes(operation)) {
+      throw new Error(`Invalid operation: ${operation}`);
     }
 
-    validate(params) {
-        super.validate(params);
-
-        const { operation, path, symbolName, kind } = params;
-
-        const validOperations = ['insert_before', 'insert_after', 'replace_body'];
-        if (!validOperations.includes(operation)) {
-            throw new Error(`Invalid operation: ${operation}`);
-        }
-
-        if (!path || path.trim() === '') {
-            throw new Error('path cannot be empty');
-        }
-
-        if (!symbolName || symbolName.trim() === '') {
-            throw new Error('symbolName cannot be empty');
-        }
-
-        // Safety guard: forbid inserting members into a method scope
-        if ((operation === 'insert_after' || operation === 'insert_before') && (kind || '').toLowerCase() === 'method') {
-            throw new Error('Insert operations must target class/namespace, not method scope. Use kind:"class" and insert at class level.');
-        }
+    if (!path || path.trim() === '') {
+      throw new Error('path cannot be empty');
     }
 
-    async execute(params) {
-        // Normalize to project-relative path
-        const raw = String(params.path).replace(/\\\\/g, '/');
-        const ai = raw.indexOf('Assets/');
-        const pi = raw.indexOf('Packages/');
-        const idx = (ai >= 0 && pi >= 0) ? Math.min(ai, pi) : (ai >= 0 ? ai : pi);
-        const relative = idx >= 0 ? raw.substring(idx) : raw;
-
-        const operation = String(params.operation);
-        const kind = (params.kind || '').toLowerCase();
-        const symbolName = String(params.symbolName);
-        const preview = params?.preview === true;
-        const body = String(params.newText || '');
-
-        // Map operations to LSP extensions
-        const info = await this.projectInfo.get();
-        if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
-
-        if (operation === 'replace_body') {
-            const resp = await this.lsp.request('mcp/replaceSymbolBody', {
-                relative,
-                namePath: symbolName,
-                body,
-                apply: !preview
-            });
-            return this._summarizeResult(resp?.result ?? resp, { preview });
-        }
-        if (operation === 'insert_before' || operation === 'insert_after') {
-            const method = operation === 'insert_before' ? 'mcp/insertBeforeSymbol' : 'mcp/insertAfterSymbol';
-            const resp = await this.lsp.request(method, {
-                relative,
-                namePath: symbolName,
-                text: body,
-                apply: !preview
-            });
-            return this._summarizeResult(resp?.result ?? resp, { preview });
-        }
-
-        return { error: `Unsupported operation: ${operation}` };
+    if (!symbolName || symbolName.trim() === '') {
+      throw new Error('symbolName cannot be empty');
     }
 
-    /**
-     * Summarize/trim responses to avoid huge token usage.
-     * - Caps error items and message lengths
-     * - Trims large text fields (e.g., preview/diff) to a short excerpt
-     */
-    _summarizeResult(res, { preview }) {
-        if (!res || typeof res !== 'object') return res;
-
-        const MAX_ERRORS = 30;
-        const MAX_MSG_LEN = 200;
-        const MAX_TEXT_LEN = 1000; // generic cap for any preview-like text
-
-        const out = {};
-        // Preserve common flags if present
-        if ('id' in res) out.id = res.id;
-        if ('success' in res) out.success = !!res.success;
-        if ('applied' in res) out.applied = !!res.applied;
-
-        // Errors trimming
-        if (Array.isArray(res.errors)) {
-            const trimmed = res.errors.slice(0, MAX_ERRORS).map(e => {
-                const obj = {};
-                if (e && typeof e === 'object') {
-                    if ('id' in e) obj.id = e.id;
-                    if ('message' in e) obj.message = this._trimString(String(e.message), MAX_MSG_LEN);
-                    if ('file' in e) obj.file = this._trimString(String(e.file), 260);
-                    if ('line' in e) obj.line = e.line;
-                    if ('column' in e) obj.column = e.column;
-                } else {
-                    obj.message = this._trimString(String(e), MAX_MSG_LEN);
-                }
-                return obj;
-            });
-            out.errorCount = trimmed.length; // summarized count (<= MAX_ERRORS)
-            out.totalErrors = res.errors.length; // raw count for reference
-            out.errors = trimmed;
-        }
-
-        // Propagate workspace info if present (which .sln/.csproj is open)
-        // workspace情報は返さない（厳格: .sln必須のため）
+    // Safety guard: forbid inserting members into a method scope
+    if (
+      (operation === 'insert_after' || operation === 'insert_before') &&
+      (kind || '').toLowerCase() === 'method'
+    ) {
+      throw new Error(
+        'Insert operations must target class/namespace, not method scope. Use kind:"class" and insert at class level.'
+      );
+    }
+  }
+
+  async execute(params) {
+    // Normalize to project-relative path
+    const raw = String(params.path).replace(/\\\\/g, '/');
+    const ai = raw.indexOf('Assets/');
+    const pi = raw.indexOf('Packages/');
+    const idx = ai >= 0 && pi >= 0 ? Math.min(ai, pi) : ai >= 0 ? ai : pi;
+    const relative = idx >= 0 ? raw.substring(idx) : raw;
+
+    const operation = String(params.operation);
+    const symbolName = String(params.symbolName);
+    const preview = params?.preview === true;
+    const body = String(params.newText || '');
+
+    // Map operations to LSP extensions
+    const info = await this.projectInfo.get();
+    if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
+
+    if (operation === 'replace_body') {
+      const resp = await this.lsp.request('mcp/replaceSymbolBody', {
+        relative,
+        namePath: symbolName,
+        body,
+        apply: !preview
+      });
+      return this._summarizeResult(resp?.result ?? resp, { preview });
+    }
+    if (operation === 'insert_before' || operation === 'insert_after') {
+      const method =
+        operation === 'insert_before' ? 'mcp/insertBeforeSymbol' : 'mcp/insertAfterSymbol';
+      const resp = await this.lsp.request(method, {
+        relative,
+        namePath: symbolName,
+        text: body,
+        apply: !preview
+      });
+      return this._summarizeResult(resp?.result ?? resp, { preview });
+    }
 
-        // Generic handling for any large text properties commonly returned by tools
-        for (const key of ['preview', 'diff', 'text', 'content']) {
-            if (typeof res[key] === 'string' && res[key].length > 0) {
-                out[key] = this._trimString(res[key], MAX_TEXT_LEN);
-                if (res[key].length > MAX_TEXT_LEN) out[`${key}Truncated`] = true;
-            }
+    return { error: `Unsupported operation: ${operation}` };
+  }
+
+  /**
+   * Summarize/trim responses to avoid huge token usage.
+   * - Caps error items and message lengths
+   * - Trims large text fields (e.g., preview/diff) to a short excerpt
+   */
+  _summarizeResult(res, { preview: _preview }) {
+    if (!res || typeof res !== 'object') return res;
+
+    const MAX_ERRORS = 30;
+    const MAX_MSG_LEN = 200;
+    const MAX_TEXT_LEN = 1000; // generic cap for any preview-like text
+
+    const out = {};
+    // Preserve common flags if present
+    if ('id' in res) out.id = res.id;
+    if ('success' in res) out.success = !!res.success;
+    if ('applied' in res) out.applied = !!res.applied;
+
+    // Errors trimming
+    if (Array.isArray(res.errors)) {
+      const trimmed = res.errors.slice(0, MAX_ERRORS).map(e => {
+        const obj = {};
+        if (e && typeof e === 'object') {
+          if ('id' in e) obj.id = e.id;
+          if ('message' in e) obj.message = this._trimString(String(e.message), MAX_MSG_LEN);
+          if ('file' in e) obj.file = this._trimString(String(e.file), 260);
+          if ('line' in e) obj.line = e.line;
+          if ('column' in e) obj.column = e.column;
+        } else {
+          obj.message = this._trimString(String(e), MAX_MSG_LEN);
         }
+        return obj;
+      });
+      out.errorCount = trimmed.length; // summarized count (<= MAX_ERRORS)
+      out.totalErrors = res.errors.length; // raw count for reference
+      out.errors = trimmed;
+    }
 
-        // Echo minimal identifiers to aid clients
-        for (const key of ['operation', 'path', 'relative', 'symbolName']) {
-            if (res[key] !== undefined) out[key] = res[key];
-        }
+    // Propagate workspace info if present (which .sln/.csproj is open)
+    // workspace情報は返さない（厳格: .sln必須のため）
 
-        return Object.keys(out).length ? out : res;
+    // Generic handling for any large text properties commonly returned by tools
+    for (const key of ['preview', 'diff', 'text', 'content']) {
+      if (typeof res[key] === 'string' && res[key].length > 0) {
+        out[key] = this._trimString(res[key], MAX_TEXT_LEN);
+        if (res[key].length > MAX_TEXT_LEN) out[`${key}Truncated`] = true;
+      }
     }
 
-    _trimString(s, max) {
-        if (typeof s !== 'string') return s;
-        return s.length > max ? (s.slice(0, max) + '…') : s;
+    // Echo minimal identifiers to aid clients
+    for (const key of ['operation', 'path', 'relative', 'symbolName']) {
+      if (res[key] !== undefined) out[key] = res[key];
     }
+
+    return Object.keys(out).length ? out : res;
+  }
+
+  _trimString(s, max) {
+    if (typeof s !== 'string') return s;
+    return s.length > max ? s.slice(0, max) + '…' : s;
+  }
 }