@akiojin/unity-mcp-server 2.16.0 → 2.25.0

package/src/handlers/script/ScriptEditSnippetToolHandler.js

@@ -0,0 +1,272 @@
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { LspRpcClient } from '../../lsp/LspRpcClient.js';
+
+const MAX_INSTRUCTIONS = 10;
+const MAX_DIFF_CHARS = 80;
+const PREVIEW_MAX = 1000;
+
+const normalizeSlashes = (p) => p.replace(/\\/g, '/');
+
+export class ScriptEditSnippetToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'script_edit_snippet',
+      '[C# EDITING - PRECISION TOOL] For Unity C# scripts, use for tiny surgical edits (≤80 chars per change). Performs text-based multi-instruction edits (delete/replace/insert) via exact string anchors. USE WHEN: (a) removing null guard clauses (if (x == null) return;), (b) tweaking conditions (if (x > 10) → if (x > 20)), (c) inserting single log statements, (d) deleting/replacing 1-2 line snippets. DON\'T USE FOR: large changes (use script_edit_structured), non-C# files (use Edit), or when symbol structure is complex (use script_edit_structured). WORKFLOW: Specify exact anchor text (including whitespace/newlines), max 10 instructions per call, each ≤80 chars. Anchor must match exactly once in file. Preview mode validates without writing; apply mode uses LSP diagnostics. Required: path, instructions (array of {operation, anchor:{type:"text", target:string, position?:"before"|"after"}, newText?}).',
+      {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Project-relative C# path starting with Assets/ or Packages/ (e.g., Assets/Scripts/Foo.cs).'
+          },
+          preview: {
+            type: 'boolean',
+            description: 'If true, run validation and return preview text without writing to disk. Default=false.'
+          },
+          instructions: {
+            type: 'array',
+            minItems: 1,
+            maxItems: MAX_INSTRUCTIONS,
+            description: 'Ordered list of snippet edits to apply (≤10).',
+            items: {
+              type: 'object',
+              properties: {
+                operation: {
+                  type: 'string',
+                  enum: ['delete', 'replace', 'insert'],
+                  description: 'Edit type.'
+                },
+                anchor: {
+                  type: 'object',
+                  description: 'Positioning info. Currently supports type=text with exact target snippet.',
+                  properties: {
+                    type: { type: 'string', enum: ['text'], default: 'text' },
+                    target: { type: 'string', description: 'Exact snippet to locate (including whitespace).' },
+                    position: {
+                      type: 'string',
+                      enum: ['before', 'after'],
+                      description: 'For insert operations, whether to insert before or after the anchor text (default=after).'
+                    }
+                  },
+                  required: ['type', 'target']
+                },
+                newText: {
+                  type: 'string',
+                  description: 'Replacement or insertion text. Required for replace/insert.'
+                }
+              },
+              required: ['operation', 'anchor']
+            }
+          }
+        },
+        required: ['path', 'instructions']
+      }
+    );
+    this.projectInfo = new ProjectInfoProvider(unityConnection);
+    this.lsp = null;
+  }
+
+  validate(params) {
+    super.validate(params);
+    const { path: filePath, instructions } = params;
+    if (!filePath || String(filePath).trim() === '') {
+      throw new Error('path cannot be empty');
+    }
+    if (!Array.isArray(instructions) || instructions.length === 0) {
+      throw new Error('instructions must be a non-empty array');
+    }
+    if (instructions.length > MAX_INSTRUCTIONS) {
+      throw new Error(`instruction limit exceeded (max ${MAX_INSTRUCTIONS})`);
+    }
+    for (let i = 0; i < instructions.length; i++) {
+      const instr = instructions[i] ?? {};
+      const op = instr.operation;
+      if (!['delete', 'replace', 'insert'].includes(op)) {
+        throw new Error(`Unsupported operation at instructions[${i}]: ${op}`);
+      }
+      const anchor = instr.anchor || {};
+      if ((anchor.type || 'text') !== 'text') {
+        throw new Error(`Unsupported anchor.type at instructions[${i}]: ${anchor.type}`);
+      }
+      const target = anchor.target;
+      if (!target || typeof target !== 'string') {
+        throw new Error(`anchor.target must be a non-empty string at instructions[${i}]`);
+      }
+      if ((op === 'replace' || op === 'insert') && (instr.newText ?? '') === '') {
+        throw new Error(`newText is required for ${op} operation at instructions[${i}]`);
+      }
+    }
+  }
+
+  async execute(params) {
+    const info = await this.projectInfo.get();
+    const { relative, absolute } = this.#resolvePaths(info, params.path);
+    const preview = params.preview === true;
+    const instructions = params.instructions;
+
+    let original;
+    try {
+      original = await fs.readFile(absolute, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') {
+        throw new Error(`file not found: ${relative}`);
+      }
+      throw e;
+    }
+
+    let working = original;
+    const results = [];
+    for (let i = 0; i < instructions.length; i++) {
+      const instr = instructions[i];
+      const { updatedText, result } = this.#applyInstruction(working, instr, i);
+      working = updatedText;
+      results.push(result);
+    }
+
+    if (working === original) {
+      return this.#buildResponse({ preview, results, original, updated: working });
+    }
+
+    const diagnostics = await this.#validateWithLsp(info, relative, working);
+    const hasErrors = diagnostics.some(d => this.#severityIsError(d.severity));
+    if (hasErrors) {
+      const first = diagnostics.find(d => this.#severityIsError(d.severity));
+      const msg = first?.message || 'syntax error';
+      throw new Error(`syntax_error: ${msg}`);
+    }
+
+    if (!preview) {
+      await fs.writeFile(absolute, working, 'utf8');
+    }
+
+    return this.#buildResponse({ preview, results, original, updated: working, diagnostics });
+  }
+
+  #resolvePaths(info, rawPath) {
+    const normalized = normalizeSlashes(String(rawPath));
+    const idxAssets = normalized.indexOf('Assets/');
+    const idxPackages = normalized.indexOf('Packages/');
+    const idx = (idxAssets >= 0 && idxPackages >= 0)
+      ? Math.min(idxAssets, idxPackages)
+      : (idxAssets >= 0 ? idxAssets : idxPackages);
+    const relative = idx >= 0 ? normalized.substring(idx) : normalized;
+
+    if (!relative.startsWith('Assets/') && !relative.startsWith('Packages/')) {
+      throw new Error('path must start with Assets/ or Packages/');
+    }
+
+    const projectRoot = info.projectRoot;
+    const absolute = path.join(projectRoot, relative.replace(/\//g, path.sep));
+    return { relative, absolute };
+  }
+
+  #applyInstruction(text, instruction, index) {
+    const anchor = instruction.anchor;
+    const target = anchor.target;
+    const occurrences = [];
+    let pos = text.indexOf(target);
+    while (pos !== -1) {
+      occurrences.push(pos);
+      pos = text.indexOf(target, pos + 1);
+    }
+    if (occurrences.length === 0) {
+      throw new Error(`anchor_not_found: instructions[${index}]`);
+    }
+    if (occurrences.length > 1) {
+      throw new Error(`anchor_not_unique: instructions[${index}] matches ${occurrences.length} locations`);
+    }
+    const start = occurrences[0];
+    const end = start + target.length;
+
+    let replacement = '';
+    if (instruction.operation === 'delete') {
+      replacement = '';
+    } else if (instruction.operation === 'replace') {
+      replacement = instruction.newText;
+    } else if (instruction.operation === 'insert') {
+      const position = (instruction.anchor.position || 'after').toLowerCase();
+      if (position === 'before') {
+        return this.#replaceRange(text, start, start, instruction.newText, target, index);
+      }
+      if (position !== 'after') {
+        throw new Error(`Unsupported anchor.position "${instruction.anchor.position}" at instructions[${index}]`);
+      }
+      return this.#replaceRange(text, end, end, instruction.newText, target, index);
+    }
+    return this.#replaceRange(text, start, end, replacement, target, index);
+  }
+
+  #replaceRange(text, start, end, newText, anchorTarget, index) {
+    const before = text.slice(0, start);
+    const current = text.slice(start, end);
+    const after = text.slice(end);
+    const replacement = newText ?? '';
+    const diffMagnitude = Math.max(current.length, replacement.length);
+    if (diffMagnitude > MAX_DIFF_CHARS) {
+      throw new Error(`diff exceeds ${MAX_DIFF_CHARS} characters at instructions[${index}]`);
+    }
+    const updated = before + replacement + after;
+    return {
+      updatedText: updated,
+      result: {
+        index,
+        status: 'applied',
+        reason: 'anchor_matched',
+        beforeSnippet: this.#clipSnippet(current.length ? current : anchorTarget),
+        afterSnippet: this.#clipSnippet(replacement),
+        charactersChanged: diffMagnitude
+      }
+    };
+  }
+
+  async #validateWithLsp(info, relative, updatedText) {
+    if (!this.lsp) {
+      this.lsp = new LspRpcClient(info.projectRoot);
+    }
+    return await this.lsp.validateText(relative, updatedText);
+  }
+
+  #buildResponse({ preview, results, original, updated, diagnostics = [] }) {
+    const out = {
+      success: true,
+      applied: !preview,
+      results,
+      diagnostics,
+      beforeHash: this.#hash(original),
+      afterHash: this.#hash(updated)
+    };
+    if (preview) {
+      out.preview = this.#clipPreview(updated);
+    }
+    return out;
+  }
+
+  #clipPreview(text) {
+    if (typeof text !== 'string') return '';
+    if (text.length <= PREVIEW_MAX) return text;
+    return text.slice(0, PREVIEW_MAX) + '…';
+  }
+
+  #clipSnippet(s) {
+    if (!s) return '';
+    return s.length > 120 ? (s.slice(0, 117) + '…') : s;
+  }
+
+  #hash(content) {
+    return crypto.createHash('sha256').update(content ?? '', 'utf8').digest('hex');
+  }
+
+  #severityIsError(severity) {
+    if (severity === null || severity === undefined) return false;
+    if (typeof severity === 'number') {
+      // 1 = Error in LSP DiagnosticSeverity enum
+      return severity === 1;
+    }
+    const s = String(severity).toLowerCase();
+    return s === 'error' || s === '2';
+  }
+}

package/src/handlers/script/ScriptEditStructuredToolHandler.js

@@ -6,7 +6,7 @@ export class ScriptEditStructuredToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
             'script_edit_structured',
-            'PRIORITY: Use this for ALL code changes. Perform structured edits (insert_before/insert_after/replace_body) on a known symbol. Required params: path (file under Assets/ or Packages/), symbolName (prefer container path e.g. MyType/Nested/Foo). Guidance: (1) Locate targets with script_symbols_get first, (2) insert_* must target a class/namespace (never a method), (3) replace_body must be a self-contained body including braces, (4) preview is for diagnostics only — apply proceeds even if diagnostics exist; errors are returned. LLM summary limits: errors≤30 (message≤200 chars, file≤260), large text (preview/diff/text/content)≤1000 chars with Truncated flag.',
+            '[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: {

package/src/handlers/settings/{GetProjectSettingsToolHandler.js → SettingsGetToolHandler.js}

@@ -3,10 +3,10 @@ import { BaseToolHandler } from '../base/BaseToolHandler.js';
 /**
  * Handler for retrieving Unity project settings
  */
-export class GetProjectSettingsToolHandler extends BaseToolHandler {
+export class SettingsGetToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'get_project_settings',
+      'settings_get',
       'Get project settings by category via include flags (player/graphics/quality/physics/etc.).',
       {
         type: 'object',

package/src/handlers/settings/{UpdateProjectSettingsToolHandler.js → SettingsUpdateToolHandler.js}

@@ -3,10 +3,10 @@ import { BaseToolHandler } from '../base/BaseToolHandler.js';
 /**
  * Handler for updating Unity project settings with safety confirmation
  */
-export class UpdateProjectSettingsToolHandler extends BaseToolHandler {
+export class SettingsUpdateToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'update_project_settings',
+      'settings_update',
       'Update project settings by category with a confirmation safety flag.',
       {
         type: 'object',

package/src/handlers/system/{GetCommandStatsToolHandler.js → SystemGetCommandStatsToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class GetCommandStatsToolHandler extends BaseToolHandler {
+export class SystemGetCommandStatsToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'get_command_stats',
+      'system_get_command_stats',
       'Retrieve aggregated counts and recent Unity command types to audit traffic.',
       {
         type: 'object',
@@ -22,4 +22,3 @@ export class GetCommandStatsToolHandler extends BaseToolHandler {
     return result;
   }
 }
-

package/src/handlers/system/{PingToolHandler.js → SystemPingToolHandler.js}

@@ -1,13 +1,13 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
 /**
- * Handler for the ping tool
+ * Handler for the system_ping tool
  * Tests connection to Unity Editor
  */
-export class PingToolHandler extends BaseToolHandler {
+export class SystemPingToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'ping',
+      'system_ping',
       'Test connection to Unity Editor',
       {
         type: 'object',

package/src/handlers/system/{RefreshAssetsToolHandler.js → SystemRefreshAssetsToolHandler.js}

@@ -1,13 +1,13 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
 /**
- * Handler for the refresh_assets tool
+ * Handler for the system_refresh_assets tool
  * Triggers Unity to refresh assets and potentially recompile
  */
-export class RefreshAssetsToolHandler extends BaseToolHandler {
+export class SystemRefreshAssetsToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'refresh_assets',
+      'system_refresh_assets',
       'Refresh assets and check compilation status.',
       {
         type: 'object',

package/src/handlers/test/{GetTestStatusToolHandler.js → TestGetStatusToolHandler.js}

@@ -4,10 +4,10 @@ import { BaseToolHandler } from '../base/BaseToolHandler.js';
  * Handler for getting Unity test execution status
  * Works with non-blocking test execution from RunUnityTestsToolHandler
  */
-export class GetTestStatusToolHandler extends BaseToolHandler {
+export class TestGetStatusToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'get_test_status',
+      'test_get_status',
       'Get current Unity test execution status and results',
       {
         type: 'object',

package/src/handlers/test/{RunTestsToolHandler.js → TestRunToolHandler.js}

@@ -4,10 +4,10 @@ import { BaseToolHandler } from '../base/BaseToolHandler.js';
  * Handler for running Unity NUnit tests via Test Runner API
  * Implements SPEC-e7c9b50c: Unity Test Execution Feature
  */
-export class RunTestsToolHandler extends BaseToolHandler {
+export class TestRunToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'run_tests',
+      'test_run',
       'Run Unity NUnit tests in the current project',
       {
         type: 'object',

package/src/handlers/ui/{ClickUIElementToolHandler.js → UIClickElementToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class ClickUIElementToolHandler extends BaseToolHandler {
+export class UIClickElementToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
-            'click_ui_element',
+            'ui_click_element',
             'Simulate clicking on UI elements',
             {
                 type: 'object',

package/src/handlers/ui/{FindUIElementsToolHandler.js → UIFindElementsToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class FindUIElementsToolHandler extends BaseToolHandler {
+export class UIFindElementsToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
-            'find_ui_elements',
+            'ui_find_elements',
             'Find UI elements by component type, tag, or name pattern.',
             {
                 type: 'object',

package/src/handlers/ui/{GetUIElementStateToolHandler.js → UIGetElementStateToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class GetUIElementStateToolHandler extends BaseToolHandler {
+export class UIGetElementStateToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
-            'get_ui_element_state',
+            'ui_get_element_state',
             'Get detailed state information about UI elements',
             {
                 type: 'object',

package/src/handlers/ui/{SetUIElementValueToolHandler.js → UISetElementValueToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class SetUIElementValueToolHandler extends BaseToolHandler {
+export class UISetElementValueToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
-            'set_ui_element_value',
+            'ui_set_element_value',
             'Set values for UI input elements',
             {
                 type: 'object',

package/src/handlers/ui/{SimulateUIInputToolHandler.js → UISimulateInputToolHandler.js}

@@ -1,9 +1,9 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class SimulateUIInputToolHandler extends BaseToolHandler {
+export class UISimulateInputToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
-            'simulate_ui_input',
+            'ui_simulate_input',
             'Simulate complex UI interactions and input sequences',
             {
                 type: 'object',

package/src/handlers/video/{CaptureVideoForToolHandler.js → VideoCaptureForToolHandler.js}

@@ -4,10 +4,10 @@
  */
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class CaptureVideoForToolHandler extends BaseToolHandler {
+export class VideoCaptureForToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'capture_video_for',
+      'video_capture_for',
       'Record video for a fixed duration (auto-stop). Optionally enters Play Mode first.',
       {
         type: 'object',
@@ -34,12 +34,12 @@ export class CaptureVideoForToolHandler extends BaseToolHandler {
       let needPlay = !!params.play;
       if (params.play === undefined) {
         try {
-          const s0 = await this.unityConnection.sendCommand('get_editor_state', {});
+          const s0 = await this.unityConnection.sendCommand('playmode_get_state', {});
           needPlay = !(s0 && s0.isPlaying);
         } catch { needPlay = true; }
       }
       if (needPlay) {
-        await this.unityConnection.sendCommand('play_game', {});
+        await this.unityConnection.sendCommand('playmode_play', {});
         for (let i = 0; i < 60; i++) {
           const s = await this.unityConnection.sendCommand('get_editor_state', {});
           if (s && s.isPlaying) { enteredPlay = true; break; }
@@ -49,7 +49,7 @@ export class CaptureVideoForToolHandler extends BaseToolHandler {
 
       // Start with auto-stop
       const { WORKSPACE_ROOT } = await import('../../core/config.js');
-      const startResp = await this.unityConnection.sendCommand('capture_video_start', {
+      const startResp = await this.unityConnection.sendCommand('video_capture_start', {
         captureMode: params.captureMode || 'game',
         width: params.width ?? 1280,
         height: params.height ?? 720,
@@ -65,14 +65,14 @@ export class CaptureVideoForToolHandler extends BaseToolHandler {
       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', {});
+        lastStatus = await this.unityConnection.sendCommand('video_capture_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', {});
+        await this.unityConnection.sendCommand('video_capture_stop', {});
       }
 
       // Final stop result
@@ -88,7 +88,7 @@ export class CaptureVideoForToolHandler extends BaseToolHandler {
       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 {}
+      try { if (enteredPlay) await this.unityConnection.sendCommand('playmode_stop', {}); } catch {}
     }
   }
 }

package/src/handlers/video/{CaptureVideoStartToolHandler.js → VideoCaptureStartToolHandler.js}

@@ -3,10 +3,10 @@
  */
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class CaptureVideoStartToolHandler extends BaseToolHandler {
+export class VideoCaptureStartToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'capture_video_start',
+      'video_capture_start',
       'Start video recording (Game view). Requires com.unity.recorder.',
       {
         type: 'object',

package/src/handlers/video/{CaptureVideoStatusToolHandler.js → VideoCaptureStatusToolHandler.js}

@@ -3,10 +3,10 @@
  */
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class CaptureVideoStatusToolHandler extends BaseToolHandler {
+export class VideoCaptureStatusToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'capture_video_status',
+      'video_capture_status',
       'Get current video recording status.',
       {
         type: 'object',

package/src/handlers/video/{CaptureVideoStopToolHandler.js → VideoCaptureStopToolHandler.js}

@@ -1,12 +1,12 @@
 /**
- * Handler for stopping video capture in Unity Editor (via MCP)
+ * Handler for the video_capture_stop tool
  */
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 
-export class CaptureVideoStopToolHandler extends BaseToolHandler {
+export class VideoCaptureStopToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
-      'capture_video_stop',
+      'video_capture_stop',
       'Stop current video recording and finalize the file.',
       {
         type: 'object',