@akiojin/unity-mcp-server 2.14.14

package/src/handlers/package/RegistryConfigToolHandler.js

@@ -0,0 +1,198 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Registry Configuration Tool Handler for Unity MCP
+ * Handles Unity Package Registry configuration (OpenUPM, Unity NuGet, etc.)
+ */
+
+export default class RegistryConfigToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'registry_config',
+      'Configure package registries (OpenUPM/NuGet): list/add/remove scopes or recommend.',
+      {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'add_openupm', 'add_nuget', 'remove', 'add_scope', 'recommend'],
+            description: 'The registry operation to perform'
+          },
+          registryName: {
+            type: 'string',
+            description: 'Name of the registry (for remove and add_scope actions)'
+          },
+          scope: {
+            type: 'string',
+            description: 'Package scope to add (e.g., com.unity, com.cysharp)'
+          },
+          scopes: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Array of package scopes to add'
+          },
+          autoAddPopular: {
+            type: 'boolean',
+            description: 'Automatically add popular package scopes (default: true)'
+          },
+          registry: {
+            type: 'string',
+            enum: ['openupm', 'nuget'],
+            description: 'Registry type for recommendations'
+          }
+        },
+        required: ['action']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  validate(params) {
+    const { action, registryName, scope } = params || {};
+    if (!action) throw new Error('action is required');
+
+    const valid = ['list', 'add_openupm', 'add_nuget', 'remove', 'add_scope', 'recommend'];
+    if (!valid.includes(action)) {
+      throw new Error(`Invalid action: ${action}. Must be one of: ${valid.join(', ')}`);
+    }
+
+    switch (action) {
+      case 'remove':
+        if (!registryName) throw new Error('Registry name is required for remove action');
+        break;
+      case 'add_scope':
+        if (!registryName || !scope) throw new Error('Registry name and scope are required for add_scope 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('registry_config', {
+      action,
+      ...parameters
+    });
+
+    return this.formatResponse(action, result);
+  }
+
+  formatResponse(action, result) {
+    if (result && result.error) {
+      return { success: false, error: result.error };
+    }
+
+    switch (action) {
+      case 'list':
+        return {
+          success: result.success,
+          action: 'list',
+          totalCount: result.totalCount || 0,
+          registries: (result.registries || []).map(reg => ({
+            name: reg.name,
+            url: reg.url,
+            scopeCount: reg.scopes ? reg.scopes.length : 0,
+            scopes: reg.scopes || []
+          })),
+          message: result.message || `Found ${result.totalCount || 0} configured registries`
+        };
+
+      case 'add_openupm':
+        return {
+          success: result.success,
+          action: 'add_openupm',
+          registryUrl: result.registryUrl,
+          scopes: result.scopes || [],
+          message: result.message || 'Successfully configured OpenUPM registry',
+          instructions: [
+            'OpenUPM registry has been added to your project.',
+            'You can now install packages from OpenUPM using their package IDs.',
+            'Popular packages include:',
+            '  - com.cysharp.unitask (UniTask)',
+            '  - com.neuecc.unirx (UniRx)',
+            '  - jp.keijiro.noiseshader (Noise Shader)'
+          ]
+        };
+
+      case 'add_nuget':
+        return {
+          success: result.success,
+          action: 'add_nuget',
+          registryUrl: result.registryUrl,
+          scopes: result.scopes || [],
+          message: result.message || 'Successfully configured Unity NuGet registry',
+          instructions: [
+            'Unity NuGet registry has been added to your project.',
+            'You can now install NuGet packages that are compatible with Unity.',
+            'Popular packages include:',
+            '  - org.nuget.newtonsoft.json (Newtonsoft.Json)',
+            '  - org.nuget.system.threading.tasks.extensions',
+            '  - org.nuget.sqlite-net-pcl (SQLite)'
+          ]
+        };
+
+      case 'remove':
+        return {
+          success: result.success,
+          action: 'remove',
+          message: result.message || `Successfully removed registry`
+        };
+
+      case 'add_scope':
+        return {
+          success: result.success,
+          action: 'add_scope',
+          scopes: result.scopes || [],
+          message: result.message || 'Successfully added scope to registry'
+        };
+
+      case 'recommend':
+        if (result.allRecommendations) {
+          const formatted = {
+            success: result.success,
+            action: 'recommend',
+            recommendations: {},
+            message: result.message || 'Package recommendations for available registries'
+          };
+          for (const [registry, packages] of Object.entries(result.allRecommendations)) {
+            formatted.recommendations[registry] = packages.map(pkg => ({
+              packageId: pkg.packageId,
+              name: pkg.name,
+              description: pkg.description,
+              scope: pkg.scope
+            }));
+          }
+          return formatted;
+        }
+        return {
+          success: result.success,
+          action: 'recommend',
+          registry: result.registry,
+          packages: (result.packages || []).map(pkg => ({
+            packageId: pkg.packageId,
+            name: pkg.name,
+            description: pkg.description,
+            scope: pkg.scope
+          })),
+          message: result.message || `Recommendations for ${result.registry}`
+        };    }
+  }
+
+  static getExamples() {
+    return [
+      { description: 'List configured registries', input: { action: 'list' } },
+      { description: 'Add OpenUPM registry with popular scopes', input: { action: 'add_openupm', autoAddPopular: true } },
+      { description: 'Add OpenUPM with custom scopes', input: { action: 'add_openupm', scopes: ['com.cysharp', 'com.neuecc', 'jp.keijiro'], autoAddPopular: false } },
+      { description: 'Add Unity NuGet registry', input: { action: 'add_nuget', autoAddPopular: true } },
+      { description: 'Add scope to existing registry', input: { action: 'add_scope', registryName: 'OpenUPM', scope: 'com.yasirkula' } },
+      { description: 'Remove a registry', input: { action: 'remove', registryName: 'OpenUPM' } },
+      { description: 'Get recommended packages for OpenUPM', input: { action: 'recommend', registry: 'openupm' } },
+      { description: 'Get all registry recommendations', input: { action: 'recommend' } }
+    ];
+  }
+}

package/src/handlers/playmode/GetEditorStateToolHandler.js

@@ -0,0 +1,81 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for getting Unity editor state
+ */
+export class GetEditorStateToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_editor_state',
+      'Get editor state (play mode, platform, selected objects, etc.). Optionally wait for a target state.',
+      {
+        type: 'object',
+        properties: {
+          waitFor: {
+            type: 'object',
+            properties: { isPlaying: { type: 'boolean' } },
+            required: ['isPlaying']
+          },
+          timeoutMs: { type: 'number' },
+          pollMs: { type: 'number' }
+        },
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+    // 軽量なソフトキャッシュ（単発取得時のみ使用）
+    this._last = { t: 0, state: null };
+    this._minIntervalMs = parseInt(process.env.MIN_EDITOR_STATE_INTERVAL_MS || '', 10);
+    if (!(this._minIntervalMs >= 0)) this._minIntervalMs = 250; // 既定250ms
+  }
+
+  /**
+   * Executes the get editor state command
+   * @param {object} params - Empty object for this command
+   * @returns {Promise<object>} Editor state information
+   */
+  async execute(params) {
+    const wait = params?.waitFor;
+    const timeoutMs = typeof params?.timeoutMs === 'number' ? params.timeoutMs : null;
+    const pollMs = typeof params?.pollMs === 'number' ? params.pollMs : 500;
+
+    const getOnce = async () => {
+      // 非waitモード時はキャッシュを活用
+      if (!wait && this._last.state && Date.now() - this._last.t < this._minIntervalMs) {
+        return this._last.state;
+      }
+      if (!this.unityConnection.isConnected()) {
+        await this.unityConnection.connect();
+      }
+      const result = await this.unityConnection.sendCommand('get_editor_state', {});
+      if (result.status === 'error') {
+        const error = new Error(result.error);
+        error.code = 'UNITY_ERROR';
+        throw error;
+      }
+      if (!wait) {
+        this._last = { t: Date.now(), state: result };
+      }
+      return result;
+    };
+
+    if (!wait) {
+      return await getOnce();
+    }
+
+    const want = !!wait.isPlaying;
+    const start = Date.now();
+    for (;;) {
+      try {
+        const state = await this.unityConnection.sendCommand('get_editor_state', {});
+        if (state && !!state.isPlaying === want) {
+          return { status: 'success', state, waitedMs: Date.now() - start };
+        }
+      } catch {}
+      await new Promise(r => setTimeout(r, pollMs));
+      if (timeoutMs != null && Date.now() - start > timeoutMs) {
+        return await getOnce();
+      }
+    }
+  }
+}

package/src/handlers/playmode/PauseToolHandler.js

@@ -0,0 +1,44 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for pausing/resuming Unity play mode
+ */
+export class PauseToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'pause_game',
+      'Toggle Pause/Resume in Play Mode.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the pause/resume command
+   * @param {object} params - Empty object for this command
+   * @returns {Promise<object>} Play mode state
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      throw new Error('Unity connection not available');
+    }
+    
+    // Send pause command to Unity
+    const result = await this.unityConnection.sendCommand('pause_game', params);
+    
+    // Check for Unity-side errors
+    if (result.status === 'error') {
+      const error = new Error(result.error);
+      error.code = 'UNITY_ERROR';
+      throw error;
+    }
+    
+    // Return the result with state information
+    return result;
+  }
+}

package/src/handlers/playmode/PlayToolHandler.js

@@ -0,0 +1,91 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for starting Unity play mode
+ */
+export class PlayToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'play_game',
+      'Enter Play Mode.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the play command
+   * @param {object} params - Empty object for this command
+   * @returns {Promise<object>} Play mode state
+   */
+  async execute(params) {
+    const initialDelayMs = typeof params?.initialDelayMs === 'number' ? params.initialDelayMs : 3000;
+    const reconnectIntervalMs = typeof params?.reconnectIntervalMs === 'number' ? params.reconnectIntervalMs : 500;
+    const pollIntervalMs = typeof params?.pollIntervalMs === 'number' ? params.pollIntervalMs : 800;
+    const maxWaitMs = typeof params?.maxWaitMs === 'number' ? params.maxWaitMs : null; // null = unlimited
+
+    try {
+      if (!this.unityConnection.isConnected()) {
+        await this.unityConnection.connect();
+      }
+      const result = await this.unityConnection.sendCommand('play_game', params);
+      if (result?.status === 'error') {
+        const error = new Error(result.error || 'Unity returned error');
+        error.code = 'UNITY_ERROR';
+        throw error;
+      }
+      const startOk = Date.now();
+      for (;;) {
+        try {
+          const state = await this.unityConnection.sendCommand('get_editor_state', {});
+          if (state && state.isPlaying) {
+            return { status: 'success', message: 'Entered play mode', state };
+          }
+        } catch {}
+        await sleep(pollIntervalMs);
+        if (maxWaitMs != null && Date.now() - startOk > maxWaitMs) {
+          return result;
+        }
+      }
+    } catch (err) {
+      const msg = err?.message || '';
+      const transient = /(Connection closed|timeout|ECONNRESET|EPIPE|socket|Not connected)/i.test(msg);
+      if (!transient) throw err;
+
+      const start = Date.now();
+      await sleep(initialDelayMs);
+      // Reconnect until connected (unlimited unless maxWaitMs specified)
+      for (;;) {
+        if (this.unityConnection.isConnected()) break;
+        try { await this.unityConnection.connect(); } catch {}
+        await sleep(reconnectIntervalMs);
+        if (maxWaitMs != null && Date.now() - start > maxWaitMs) {
+          const e = new Error('Timed out waiting to reconnect after Play start');
+          e.code = 'RECONNECT_TIMEOUT';
+          throw e;
+        }
+      }
+      // Poll for isPlaying
+      for (;;) {
+        try {
+          const state = await this.unityConnection.sendCommand('get_editor_state', {});
+          if (state && state.isPlaying) {
+            return { status: 'success', message: 'Entered play mode (reconnected after reload)', state };
+          }
+        } catch {}
+        await sleep(pollIntervalMs);
+        if (maxWaitMs != null && Date.now() - start > maxWaitMs) {
+          const e = new Error('Timed out waiting for Play mode after reconnect');
+          e.code = 'PLAY_WAIT_TIMEOUT';
+          throw e;
+        }
+      }
+    }
+  }
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/src/handlers/playmode/StopToolHandler.js

@@ -0,0 +1,77 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for stopping Unity play mode
+ */
+export class StopToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'stop_game',
+      'Exit Play Mode and return to Edit Mode.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Executes the stop command
+   * @param {object} params - Empty object for this command
+   * @returns {Promise<object>} Play mode state
+   */
+  async execute(params) {
+    const reconnectIntervalMs = typeof params?.reconnectIntervalMs === 'number' ? params.reconnectIntervalMs : 500;
+    const pollIntervalMs = typeof params?.pollIntervalMs === 'number' ? params.pollIntervalMs : 500;
+    const maxWaitMs = typeof params?.maxWaitMs === 'number' ? params.maxWaitMs : null; // null = unlimited
+
+    try {
+      if (!this.unityConnection.isConnected()) {
+        await this.unityConnection.connect();
+      }
+      const result = await this.unityConnection.sendCommand('stop_game', params);
+      if (result?.status === 'error') {
+        const error = new Error(result.error || 'Unity returned error');
+        error.code = 'UNITY_ERROR';
+        throw error;
+      }
+      const startOk = Date.now();
+      for (;;) {
+        try {
+          const state = await this.unityConnection.sendCommand('get_editor_state', {});
+          if (state && !state.isPlaying) {
+            return { status: 'success', message: 'Exited play mode', state };
+          }
+        } catch {}
+        await sleep(pollIntervalMs);
+        if (maxWaitMs != null && Date.now() - startOk > maxWaitMs) return result;
+      }
+    } catch (err) {
+      const transient = /(Connection closed|timeout|ECONNRESET|EPIPE|socket|Not connected)/i.test(err?.message || '');
+      if (!transient) throw err;
+      const start = Date.now();
+      for (;;) {
+        if (!this.unityConnection.isConnected()) {
+          try { await this.unityConnection.connect(); } catch {}
+          await sleep(reconnectIntervalMs);
+        }
+        try {
+          const state = await this.unityConnection.sendCommand('get_editor_state', {});
+          if (state && !state.isPlaying) {
+            return { status: 'success', message: 'Exited play mode (reconnected after reload)', state };
+          }
+        } catch {}
+        await sleep(pollIntervalMs);
+        if (maxWaitMs != null && Date.now() - start > maxWaitMs) {
+          const e = new Error('Timed out waiting for stop');
+          e.code = 'PLAY_WAIT_TIMEOUT';
+          throw e;
+        }
+      }
+    }
+  }
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/src/handlers/playmode/WaitForEditorStateToolHandler.js

@@ -0,0 +1,45 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class WaitForEditorStateToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'wait_for_editor_state',
+      'Wait until the Unity editor reaches the requested state (e.g., isPlaying).',
+      {
+        type: 'object',
+        properties: {
+          isPlaying: { type: 'boolean', description: 'Target play state (true=Play, false=Edit)' },
+          timeoutMs: { type: 'number', description: 'Max wait time (null/omitted = unlimited)' },
+          pollMs: { type: 'number', description: 'Polling interval in ms (default 500)' }
+        },
+        required: ['isPlaying']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  async execute(params) {
+    const want = !!params.isPlaying;
+    const timeoutMs = typeof params?.timeoutMs === 'number' ? params.timeoutMs : null;
+    const pollMs = typeof params?.pollMs === 'number' ? params.pollMs : 500;
+
+    const start = Date.now();
+    for (;;) {
+      if (!this.unityConnection.isConnected()) {
+        try { await this.unityConnection.connect(); } catch {}
+      }
+      try {
+        const state = await this.unityConnection.sendCommand('get_editor_state', {});
+        if (!!state?.isPlaying === want) {
+          return { status: 'success', state, waitedMs: Date.now() - start };
+        }
+      } catch {}
+      await new Promise(r => setTimeout(r, pollMs));
+      if (timeoutMs != null && Date.now() - start > timeoutMs) {
+        const state = this.unityConnection.isConnected() ? await this.unityConnection.sendCommand('get_editor_state', {}).catch(() => ({})) : {};
+        return { status: 'timeout', state, waitedMs: Date.now() - start };
+      }
+    }
+  }
+}
+

package/src/handlers/scene/CreateSceneToolHandler.js

@@ -0,0 +1,91 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+/**
+ * Handler for creating new scenes in Unity
+ */
+export class CreateSceneToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'create_scene',
+      'Create a new scene (optionally load it and add to build settings).',
+      {
+        type: 'object',
+        properties: {
+          sceneName: {
+            type: 'string',
+            description: 'Name of the scene to create'
+          },
+          path: {
+            type: 'string',
+            description: 'Path where the scene should be saved (e.g., "Assets/Scenes/"). If not specified, defaults to "Assets/Scenes/"'
+          },
+          loadScene: {
+            type: 'boolean',
+            description: 'Whether to load the scene after creation (default: true)'
+          },
+          addToBuildSettings: {
+            type: 'boolean',
+            description: 'Whether to add the scene to build settings (default: false)'
+          }
+        },
+        required: ['sceneName']
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /**
+   * Validates the input parameters
+   * @param {object} params - Input parameters
+   * @throws {Error} If validation fails
+   */
+  validate(params) {
+    super.validate(params);
+    
+    // Additional validation for scene name
+    if (!params.sceneName || params.sceneName.trim() === '') {
+      throw new Error('Scene name cannot be empty');
+    }
+    
+    // Check for invalid characters in scene name
+    if (params.sceneName.includes('/') || params.sceneName.includes('\\')) {
+      throw new Error('Scene name contains invalid characters');
+    }
+  }
+
+  /**
+   * Executes the create scene command
+   * @param {object} params - Validated input parameters
+   * @returns {Promise<object>} Creation result
+   */
+  async execute(params) {
+    // Ensure connected
+    if (!this.unityConnection.isConnected()) {
+      throw new Error('Unity connection not available');
+    }
+    
+    // Send command to Unity
+    const result = await this.unityConnection.sendCommand('create_scene', params);
+    
+    // Check for Unity-side errors
+    if (result.status === 'error') {
+      const error = new Error(result.error);
+      error.code = 'UNITY_ERROR';
+      throw error;
+    }
+    
+    // Handle undefined or null results from Unity
+    if (result.result === undefined || result.result === null) {
+      return {
+        status: 'success',
+        sceneName: params.sceneName,
+        path: params.path || 'Assets/Scenes/',
+        loadScene: params.loadScene !== false,
+        addToBuildSettings: params.addToBuildSettings === true,
+        message: 'Scene creation completed but Unity returned no details'
+      };
+    }
+    
+    return result.result;
+  }
+}

package/src/handlers/scene/GetSceneInfoToolHandler.js

@@ -0,0 +1,20 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { getSceneInfoToolDefinition, getSceneInfoHandler } from '../../tools/scene/getSceneInfo.js';
+
+/**
+ * Handler for get_scene_info tool
+ */
+export class GetSceneInfoToolHandler extends BaseToolHandler {
+    constructor(unityConnection) {
+        super(
+            getSceneInfoToolDefinition.name,
+            getSceneInfoToolDefinition.description,
+            getSceneInfoToolDefinition.inputSchema
+        );
+        this.unityConnection = unityConnection;
+    }
+
+    async execute(args) {
+        return getSceneInfoHandler(this.unityConnection, args);
+    }
+}