@akiojin/unity-mcp-server 2.14.14

package/src/handlers/script/ScriptSymbolFindToolHandler.js

@@ -0,0 +1,117 @@
+import path from 'path';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { CodeIndex } from '../../core/codeIndex.js';
+import { LspRpcClient } from '../../lsp/LspRpcClient.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+
+export class ScriptSymbolFindToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_symbol_find',
+            'Find symbol definitions by name (class/method/field/property) using the bundled C# LSP. Guidance: prefer narrowing by kind and set exact=true when possible; use scope=assets|packages to avoid large outputs. Use results (container, namespace) to construct container namePath like Outer/Nested/Member for subsequent edit tools.',
+            {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Symbol name to search (exact or fuzzy based on "exact").'
+                    },
+                    kind: {
+                        type: 'string',
+                        description: 'Optional: narrow by symbol kind (class, method, field, property).'
+                    },
+                    scope: {
+                        type: 'string',
+                        enum: ['assets', 'packages', 'embedded', 'all'],
+                        description: 'Search scope: assets (Assets/), packages (Packages/), embedded, or all (default: all).'
+                    },
+                    exact: {
+                        type: 'boolean',
+                        description: 'If true, match name exactly; otherwise allows partial matches (default: false).'
+                    }
+                },
+                required: ['name']
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.index = new CodeIndex(unityConnection);
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+        this.lsp = null;
+    }
+
+    validate(params) {
+        super.validate(params);
+
+        const { name } = params;
+
+        if (!name || name.trim() === '') {
+            throw new Error('name cannot be empty');
+        }
+    }
+
+    async execute(params) {
+        const { name, kind, scope = 'assets', exact = false } = params;
+        // Prefer persistent index if available
+        let results = [];
+        if (await this.index.isReady()) {
+            const rows = await this.index.querySymbols({ name, kind, scope, exact });
+            results = rows.map(r => ({
+                path: r.path,
+                symbol: {
+                    name: r.name,
+                    kind: r.kind,
+                    namespace: r.ns,
+                    container: r.container,
+                    startLine: r.line,
+                    startColumn: r.column,
+                    endLine: r.line,
+                    endColumn: r.column
+                }
+            }));
+        } else {
+            const info = await this.projectInfo.get();
+            if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
+            const resp = await this.lsp.request('workspace/symbol', { query: String(name) });
+            const arr = resp?.result || [];
+            results = arr.map(s => ({
+                path: (s.location?.uri || '').replace('file://',''),
+                symbol: {
+                    name: s.name,
+                    kind: this.mapKind(s.kind),
+                    namespace: null,
+                    container: null,
+                    startLine: (s.location?.range?.start?.line ?? 0) + 1,
+                    startColumn: (s.location?.range?.start?.character ?? 0) + 1,
+                    endLine: (s.location?.range?.end?.line ?? 0) + 1,
+                    endColumn: (s.location?.range?.end?.character ?? 0) + 1,
+                }
+            }));
+        }
+        // Optional post-filtering: scope and exact name
+        if (scope && scope !== 'all') {
+            results = results.filter(x => {
+                const p = (x.path || '').replace(/\\\\/g, '/');
+                switch (scope) {
+                    case 'assets': return p.startsWith('Assets/');
+                    case 'packages': return p.startsWith('Packages/') || p.startsWith('Library/PackageCache/');
+                    case 'embedded': return p.startsWith('Packages/');                }
+            });
+        }
+        if (exact) {
+            const target = String(name);
+            results = results.filter(x => x.symbol && x.symbol.name === target);
+        }
+        return { success: true, results, total: results.length };
+    }
+
+    mapKind(k) {
+        switch(k){
+            case 5: return 'class';
+            case 23: return 'struct';
+            case 11: return 'interface';
+            case 10: return 'enum';
+            case 6: return 'method';
+            case 7: return 'property';
+            case 8: return 'field';        }
+    }
+}

package/src/handlers/script/ScriptSymbolsGetToolHandler.js

@@ -0,0 +1,96 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+
+export class ScriptSymbolsGetToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            'script_symbols_get',
+            'FIRST STEP: Identify symbols (classes, methods, fields, properties) with spans before any edit. Path must start with Assets/ or Packages/. Use this to scope changes to a single symbol and avoid line-based edits. Returns line/column positions and container names (helpful to build container namePath like Outer/Nested/Member).',
+            {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'Project-relative .cs path under Assets/ or Packages/ (e.g., Packages/unity-mcp-server/Editor/Foo.cs). Do NOT prefix repository folders (e.g., UnityMCPServer/…).'
+                    }
+                },
+                required: ['path']
+            }
+        );
+        this.unityConnection = unityConnection;
+        this.projectInfo = new ProjectInfoProvider(unityConnection);
+    }
+
+    validate(params) {
+        super.validate(params);
+
+        const { path } = params;
+
+        if (!path || path.trim() === '') {
+            throw new Error('path cannot be empty');
+        }
+
+        // Check for .cs extension
+        if (!path.endsWith('.cs')) {
+            throw new Error('Only .cs files are supported');
+        }
+    }
+
+    async execute(params) {
+        // Normalize to project-relative path (strip repo-root prefixes if provided)
+        const rawPath = String(params.path || '').replace(/\\/g, '/');
+        const ai = rawPath.indexOf('Assets/');
+        const pi = rawPath.indexOf('Packages/');
+        const cut = (ai >= 0 && pi >= 0) ? Math.min(ai, pi) : (ai >= 0 ? ai : pi);
+        const relPath = cut >= 0 ? rawPath.substring(cut) : rawPath;
+
+        try {
+            const info = await this.projectInfo.get();
+            if (!relPath.startsWith('Assets/') && !relPath.startsWith('Packages/')) {
+                return { error: 'Path must be under Assets/ or Packages/' };
+            }
+            const abs = path.join(info.projectRoot, relPath);
+            const st = await fs.stat(abs).catch(() => null);
+            if (!st || !st.isFile()) return { error: 'File not found', path: relPath };
+            const { LspRpcClient } = await import('../../lsp/LspRpcClient.js');
+            const lsp = new LspRpcClient(info.projectRoot);
+            const uri = 'file://' + abs.replace(/\\\\/g, '/');
+            const res = await lsp.request('textDocument/documentSymbol', { textDocument: { uri } });
+            const docSymbols = res?.result ?? res ?? [];
+            const list = [];
+            const visit = (s, container) => {
+                const start = s.range?.start || s.selectionRange?.start || {};
+                list.push({
+                    name: s.name || '',
+                    kind: this.mapKind(s.kind),
+                    container: container || null,
+                    namespace: null,
+                    startLine: (start.line ?? 0) + 1,
+                    startColumn: (start.character ?? 0) + 1,
+                    endLine: (start.line ?? 0) + 1,
+                    endColumn: (start.character ?? 0) + 1
+                });
+                if (Array.isArray(s.children)) for (const c of s.children) visit(c, s.name || container);
+            };
+            if (Array.isArray(docSymbols)) for (const s of docSymbols) visit(s, null);
+            return { success: true, path: relPath, symbols: list };
+        } catch (e) {
+            return { error: e.message || 'Failed to get symbols' };
+        }
+    }
+
+    mapKind(k) {
+        switch (k) {
+            case 5: return 'class';
+            case 23: return 'struct';
+            case 11: return 'interface';
+            case 10: return 'enum';
+            case 6: return 'method';
+            case 7: return 'property';
+            case 8: return 'field';
+            default: return undefined;
+        }
+    }
+}

package/src/handlers/settings/GetProjectSettingsToolHandler.js

@@ -0,0 +1,161 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for retrieving Unity project settings
+ */
+export class GetProjectSettingsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_project_settings',
+      'Get project settings by category via include flags (player/graphics/quality/physics/etc.).',
+      {
+        type: 'object',
+        properties: {
+          includePlayer: {
+            type: 'boolean',
+            description: 'Include player settings (company/product name, version, etc.) (default: true).'
+          },
+          includeGraphics: {
+            type: 'boolean',
+            description: 'Include graphics settings (color space, render pipeline, etc.) (default: false).'
+          },
+          includeQuality: {
+            type: 'boolean',
+            description: 'Include quality settings (levels, anti-aliasing, shadows, etc.) (default: false).'
+          },
+          includePhysics: {
+            type: 'boolean',
+            description: 'Include 3D physics settings (gravity, solver iterations, etc.) (default: false).'
+          },
+          includePhysics2D: {
+            type: 'boolean',
+            description: 'Include 2D physics settings (default: false).'
+          },
+          includeAudio: {
+            type: 'boolean',
+            description: 'Include audio settings (speaker mode, DSP buffer, volume, etc.) (default: false).'
+          },
+          includeTime: {
+            type: 'boolean',
+            description: 'Include time settings (fixed timestep, time scale, etc.) (default: false).'
+          },
+          includeInputManager: {
+            type: 'boolean',
+            description: 'Include input manager settings (legacy input system) (default: false).'
+          },
+          includeEditor: {
+            type: 'boolean',
+            description: 'Include editor settings (Unity Remote, serialization mode, etc.) (default: false).'
+          },
+          includeBuild: {
+            type: 'boolean',
+            description: 'Include build settings (scenes in build, build target, etc.) (default: false).'
+          },
+          includeTags: {
+            type: 'boolean',
+            description: 'Include tags, layers, and sorting layers (default: false).'
+          }
+        },
+        required: []
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    // All parameters are optional booleans with defaults, no special validation needed
+    const booleanParams = [
+      'includePlayer', 'includeGraphics', 'includeQuality',
+      'includePhysics', 'includePhysics2D', 'includeAudio',
+      'includeTime', 'includeInputManager', 'includeEditor',
+      'includeBuild', 'includeTags'
+    ];
+
+    for (const param of booleanParams) {
+      if (params[param] !== undefined && typeof params[param] !== 'boolean') {
+        throw new Error(`${param} must be a boolean value`);
+      }
+    }
+  }
+
+  /**
+   * Executes the get project settings operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The project settings
+   */
+  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('get_project_settings', params);
+
+    // Handle Unity response
+    if (response.error) {
+      throw new Error(response.error);
+    }
+
+    // Return the settings object
+    return response;
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      getBasicSettings: {
+        description: 'Get basic player settings only (default)',
+        params: {}
+      },
+      getGraphicsAndQuality: {
+        description: 'Get graphics and quality settings',
+        params: {
+          includeGraphics: true,
+          includeQuality: true
+        }
+      },
+      getPhysicsSettings: {
+        description: 'Get all physics-related settings',
+        params: {
+          includePhysics: true,
+          includePhysics2D: true,
+          includeTime: true
+        }
+      },
+      getEditorSettings: {
+        description: 'Get editor and build configuration',
+        params: {
+          includeEditor: true,
+          includeBuild: true,
+          includeTags: true
+        }
+      },
+      getAllSettings: {
+        description: 'Get all available settings',
+        params: {
+          includePlayer: true,
+          includeGraphics: true,
+          includeQuality: true,
+          includePhysics: true,
+          includePhysics2D: true,
+          includeAudio: true,
+          includeTime: true,
+          includeInputManager: true,
+          includeEditor: true,
+          includeBuild: true,
+          includeTags: true
+        }
+      }
+    };
+  }
+}

package/src/handlers/settings/UpdateProjectSettingsToolHandler.js

@@ -0,0 +1,272 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for updating Unity project settings with safety confirmation
+ */
+export class UpdateProjectSettingsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'update_project_settings',
+      'Update project settings by category with a confirmation safety flag.',
+      {
+        type: 'object',
+        properties: {
+          confirmChanges: {
+            type: 'boolean',
+            description: 'Safety flag: must be true to apply changes (prevents accidental edits).'
+          },
+          player: {
+            type: 'object',
+            description: 'Player settings (company/product name, bundle version, windowing).',
+            properties: {
+              companyName: { type: 'string', description: 'Company name' },
+              productName: { type: 'string', description: 'Product name' },
+              version: { type: 'string', description: 'Bundle version' },
+              defaultScreenWidth: { type: 'number', description: 'Default screen width' },
+              defaultScreenHeight: { type: 'number', description: 'Default screen height' },
+              runInBackground: { type: 'boolean', description: 'Allow running in background' }
+            }
+          },
+          graphics: {
+            type: 'object',
+            description: 'Graphics settings (color space, render pipeline, etc.).',
+            properties: {
+              colorSpace: {
+                type: 'string',
+                enum: ['Gamma', 'Linear'],
+                description: 'Color space (requires Unity restart)'
+              }
+            }
+          },
+          physics: {
+            type: 'object',
+            description: '3D physics settings (gravity, solver iterations, thresholds).',
+            properties: {
+              gravity: {
+                type: 'object',
+                properties: {
+                  x: { type: 'number' },
+                  y: { type: 'number' },
+                  z: { type: 'number' }
+                }
+              },
+              defaultSolverIterations: { type: 'number' },
+              defaultSolverVelocityIterations: { type: 'number' },
+              bounceThreshold: { type: 'number' },
+              sleepThreshold: { type: 'number' },
+              defaultContactOffset: { type: 'number' }
+            }
+          },
+          physics2D: {
+            type: 'object',
+            description: '2D physics settings (gravity, iterations, thresholds).',
+            properties: {
+              gravity: {
+                type: 'object',
+                properties: {
+                  x: { type: 'number' },
+                  y: { type: 'number' }
+                }
+              },
+              velocityIterations: { type: 'number' },
+              positionIterations: { type: 'number' },
+              velocityThreshold: { type: 'number' }
+            }
+          },
+          audio: {
+            type: 'object',
+            description: 'Audio settings (global volume).',
+            properties: {
+              globalVolume: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                description: 'Global volume (0-1)'
+              }
+            }
+          },
+          time: {
+            type: 'object',
+            description: 'Time settings (fixed timestep, time scale).',
+            properties: {
+              fixedDeltaTime: { type: 'number', description: 'Fixed timestep' },
+              timeScale: { type: 'number', minimum: 0, description: 'Time scale (0 = paused)' },
+              maximumDeltaTime: { type: 'number', description: 'Maximum allowed timestep' }
+            }
+          },
+          quality: {
+            type: 'object',
+            description: 'Quality settings (levels, vSync, AA, shadows).',
+            properties: {
+              currentLevel: { type: 'string', description: 'Quality level name' },
+              vSyncCount: {
+                type: 'number',
+                minimum: 0,
+                maximum: 4,
+                description: 'VSync count (0=off, 1=every VBlank, 2=every second VBlank)'
+              },
+              antiAliasing: {
+                type: 'number',
+                enum: [0, 2, 4, 8],
+                description: 'Anti-aliasing samples'
+              },
+              shadowDistance: { type: 'number', minimum: 0, description: 'Shadow rendering distance' }
+            }
+          }
+        },
+        required: ['confirmChanges']
+      }
+    );
+    
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {Object} params - The input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    // Require explicit confirmation
+    if (!params.confirmChanges) {
+      throw new Error('confirmChanges must be set to true to update settings. This is a safety measure to prevent accidental changes.');
+    }
+
+    // Check that at least one settings category is provided
+    const settingsCategories = ['player', 'graphics', 'physics', 'physics2D', 'audio', 'time', 'quality'];
+    const hasSettings = settingsCategories.some(cat => params[cat] !== undefined);
+    
+    if (!hasSettings) {
+      throw new Error('At least one settings category must be provided to update');
+    }
+
+    // Validate specific settings
+    if (params.audio?.globalVolume !== undefined) {
+      const volume = params.audio.globalVolume;
+      if (typeof volume !== 'number' || volume < 0 || volume > 1) {
+        throw new Error('globalVolume must be a number between 0 and 1');
+      }
+    }
+
+    if (params.quality?.vSyncCount !== undefined) {
+      const vSync = params.quality.vSyncCount;
+      if (!Number.isInteger(vSync) || vSync < 0 || vSync > 4) {
+        throw new Error('vSyncCount must be an integer between 0 and 4');
+      }
+    }
+
+    if (params.quality?.antiAliasing !== undefined) {
+      const aa = params.quality.antiAliasing;
+      if (![0, 2, 4, 8].includes(aa)) {
+        throw new Error('antiAliasing must be 0, 2, 4, or 8');
+      }
+    }
+
+    if (params.graphics?.colorSpace !== undefined) {
+      const colorSpace = params.graphics.colorSpace;
+      if (!['Gamma', 'Linear'].includes(colorSpace)) {
+        throw new Error('colorSpace must be either "Gamma" or "Linear"');
+      }
+    }
+
+    if (params.time?.timeScale !== undefined) {
+      const timeScale = params.time.timeScale;
+      if (typeof timeScale !== 'number' || timeScale < 0) {
+        throw new Error('timeScale must be a non-negative number');
+      }
+    }
+  }
+
+  /**
+   * Executes the update project settings operation
+   * @param {Object} params - The validated input parameters
+   * @returns {Promise<Object>} The update results
+   */
+  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('update_project_settings', params);
+
+    // Handle Unity response
+    if (response.error) {
+      // Check for specific error codes
+      if (response.code === 'CONFIRMATION_REQUIRED') {
+        throw new Error('Settings update requires confirmation. Set confirmChanges to true.');
+      }
+      throw new Error(response.error);
+    }
+
+    // Return the update results
+    return response;
+  }
+
+  /**
+   * Gets example usage for this tool
+   * @returns {Object} Example usage scenarios
+   */
+  getExamples() {
+    return {
+      updatePlayerSettings: {
+        description: 'Update player settings like company and product name',
+        params: {
+          confirmChanges: true,
+          player: {
+            companyName: 'My Company',
+            productName: 'My Game',
+            version: '1.0.0'
+          }
+        }
+      },
+      updatePhysicsSettings: {
+        description: 'Update physics settings like gravity',
+        params: {
+          confirmChanges: true,
+          physics: {
+            gravity: { x: 0, y: -9.81, z: 0 },
+            defaultSolverIterations: 10
+          }
+        }
+      },
+      updateQualitySettings: {
+        description: 'Update quality settings',
+        params: {
+          confirmChanges: true,
+          quality: {
+            vSyncCount: 1,
+            antiAliasing: 4,
+            shadowDistance: 150
+          }
+        }
+      },
+      updateMultipleCategories: {
+        description: 'Update multiple settings categories at once',
+        params: {
+          confirmChanges: true,
+          player: {
+            version: '2.0.0'
+          },
+          audio: {
+            globalVolume: 0.8
+          },
+          time: {
+            timeScale: 1.0,
+            fixedDeltaTime: 0.02
+          }
+        }
+      },
+      safetyCheckExample: {
+        description: 'Example showing safety check (will fail)',
+        params: {
+          confirmChanges: false,  // This will trigger safety check
+          player: {
+            productName: 'Accidental Change'
+          }
+        }
+      }
+    };
+  }
+}

package/src/handlers/system/GetCommandStatsToolHandler.js

@@ -0,0 +1,25 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class GetCommandStatsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_command_stats',
+      'Retrieve aggregated counts and recent Unity command types to audit traffic.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  async execute(params) {
+    if (!this.unityConnection.isConnected()) {
+      await this.unityConnection.connect();
+    }
+    const result = await this.unityConnection.sendCommand('get_command_stats', {});
+    return result;
+  }
+}
+