@akiojin/unity-mcp-server 2.38.0 → 2.39.0

package/README.md

@@ -4,7 +4,8 @@ MCP (Model Context Protocol) server for Unity Editor integration. Enables AI ass
 
 ## Features
 
-- **70 comprehensive tools** across 13 categories for Unity Editor automation
+- **106 comprehensive tools** across 16+ categories for Unity Editor automation
+- **Tool discovery** - Efficient `search_tools` meta-tool for discovering relevant tools (96.2% token reduction)
 - **GameObject management** - Create, find, modify, delete GameObjects with full hierarchy control
 - **Component system** - Add, remove, modify components with property control
 - **Scene management** - Create, load, save, list scenes with build settings integration
@@ -13,10 +14,66 @@ MCP (Model Context Protocol) server for Unity Editor integration. Enables AI ass
 - **UI automation** - Find, click, and interact with UI elements programmatically
 - **Input simulation** - Simulate keyboard, mouse, gamepad, and touch input
 - **Play mode controls** - Start, pause, stop Unity play mode for testing
+- **Performance profiling** - Record profiling sessions, collect metrics, save .data files for analysis
 - **Project settings** - Read and update Unity project settings safely
-- **Editor operations** - Console logs, screenshots, compilation monitoring
+- **Editor operations** - Console logs, screenshots, video capture, compilation monitoring
 - **Editor control** - Manage tags, layers, selection, windows, and tools
 
+## Tool Discovery
+
+Unity MCP Server provides a **`search_tools`** meta-tool for efficient tool discovery, helping you find relevant tools quickly.
+
+### Usage Examples
+
+```javascript
+// Find tools for GameObject manipulation
+{
+  "tool": "search_tools",
+  "params": {
+    "query": "gameobject",
+    "limit": 10
+  }
+}
+// Returns: gameobject_create, gameobject_find, gameobject_modify, ...
+
+// Filter by category
+{
+  "tool": "search_tools",
+  "params": {
+    "category": "scene",
+    "limit": 10
+  }
+}
+// Returns: scene_create, scene_load, scene_save, scene_list, scene_info_get
+
+// Filter by tags
+{
+  "tool": "search_tools",
+  "params": {
+    "tags": ["create", "asset"],
+    "limit": 5
+  }
+}
+// Returns tools that create assets
+
+// Include full input schemas (when needed)
+{
+  "tool": "search_tools",
+  "params": {
+    "query": "screenshot",
+    "includeSchemas": true
+  }
+}
+// Returns full tool definitions with inputSchema
+```
+
+### Benefits
+
+- **Smart filtering** - Search by keywords, categories, tags, or scope (read/write/execute)
+- **Relevance scoring** - Results sorted by relevance to your query
+- **On-demand schemas** - Full inputSchema only when explicitly requested
+- **Easy discovery** - Find the right tool without browsing all 103 tools manually
+
 ## Quick Start
 
 ### Using npx (Recommended)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "description": "MCP server and Unity Editor bridge — enables AI assistants to control Unity for AI-assisted workflows",
   "type": "module",
   "main": "src/core/server.js",

package/src/core/config.js

@@ -17,6 +17,32 @@ function merge(a, b) {
   return out;
 }
 
+function resolvePackageVersion() {
+  const candidates = [];
+
+  // Resolve relative to this module (always inside mcp-server/src/core)
+  try {
+    const moduleDir = path.dirname(new URL(import.meta.url).pathname);
+    candidates.push(path.resolve(moduleDir, '../../package.json'));
+  } catch {}
+
+  // When executed from workspace root (monorepo) or inside mcp-server package
+  try {
+    const here = findUpSync('package.json', { cwd: process.cwd() });
+    if (here) candidates.push(here);
+  } catch {}
+
+  for (const candidate of candidates) {
+    try {
+      if (!candidate || !fs.existsSync(candidate)) continue;
+      const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      if (pkg?.version) return pkg.version;
+    } catch {}
+  }
+
+  return '0.1.0';
+}
+
 /**
  * Base configuration for Unity MCP Server Server
  */
@@ -44,7 +70,7 @@ const baseConfig = {
   // Server settings
   server: {
     name: 'unity-mcp-server',
-    version: '0.1.0',
+    version: resolvePackageVersion(),
     description: 'MCP server for Unity Editor integration'
   },
 

package/src/handlers/base/BaseToolHandler.js

@@ -74,11 +74,19 @@ function sanitizeSchema(schema) {
 }
 
 export class BaseToolHandler {
-  constructor(name, description, inputSchema = {}) {
+  constructor(name, description, inputSchema = {}, metadata = {}) {
     this.name = name;
     this.description = description;
     const clonedSchema = cloneSchema(inputSchema) || {};
     this.inputSchema = sanitizeSchema(clonedSchema);
+
+    // Metadata for search_tools optimization
+    this.metadata = {
+      category: metadata.category || 'general',
+      scope: metadata.scope || 'read',
+      keywords: metadata.keywords || [],
+      tags: metadata.tags || []
+    };
   }
 
   /**
@@ -191,13 +199,20 @@ export class BaseToolHandler {
 
   /**
    * Returns the tool definition for MCP
+   * @param {boolean} includeMetadata - Include metadata in the definition
    * @returns {object} Tool definition
    */
-  getDefinition() {
-    return {
+  getDefinition(includeMetadata = false) {
+    const definition = {
       name: this.name,
       description: this.description,
       inputSchema: this.inputSchema
     };
+
+    if (includeMetadata) {
+      definition.metadata = this.metadata;
+    }
+
+    return definition;
   }
 }

package/src/handlers/base/categories.js

@@ -0,0 +1,69 @@
+/**
+ * Tool metadata categories and constants for search_tools optimization
+ */
+
+/**
+ * Tool categories for grouping related functionality
+ */
+export const CATEGORIES = {
+  SYSTEM: 'system',
+  GAMEOBJECT: 'gameobject',
+  SCENE: 'scene',
+  ANALYSIS: 'analysis',
+  PLAYMODE: 'playmode',
+  UI: 'ui',
+  INPUT: 'input',
+  ASSET: 'asset',
+  PREFAB: 'prefab',
+  MATERIAL: 'material',
+  ADDRESSABLES: 'addressables',
+  MENU: 'menu',
+  CONSOLE: 'console',
+  SCREENSHOT: 'screenshot',
+  VIDEO: 'video',
+  COMPONENT: 'component',
+  COMPILATION: 'compilation',
+  TEST: 'test',
+  EDITOR: 'editor',
+  SETTINGS: 'settings',
+  PACKAGE: 'package',
+  SCRIPT: 'script'
+};
+
+/**
+ * Tool scopes indicating read/write/execute permissions
+ */
+export const SCOPES = {
+  READ: 'read',
+  WRITE: 'write',
+  EXECUTE: 'execute'
+};
+
+/**
+ * Common tags for cross-cutting concerns
+ */
+export const TAGS = {
+  // Operation types
+  CREATE: 'create',
+  READ: 'read',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  QUERY: 'query',
+  ANALYZE: 'analyze',
+
+  // Scope tags
+  HIERARCHY: 'hierarchy',
+  PREFAB_MODE: 'prefab_mode',
+  PLAYMODE: 'playmode',
+  EDITOR_ONLY: 'editor_only',
+
+  // Resource types
+  ASSET: 'asset',
+  SCENE: 'scene',
+  RUNTIME: 'runtime',
+
+  // Input/Output
+  INPUT: 'input',
+  OUTPUT: 'output',
+  VISUAL: 'visual'
+};

package/src/handlers/index.js

@@ -80,6 +80,10 @@ import { VideoCaptureStartToolHandler } from './video/VideoCaptureStartToolHandl
 import { VideoCaptureStopToolHandler } from './video/VideoCaptureStopToolHandler.js';
 import { VideoCaptureStatusToolHandler } from './video/VideoCaptureStatusToolHandler.js';
 import { VideoCaptureForToolHandler } from './video/VideoCaptureForToolHandler.js';
+import { ProfilerStartToolHandler } from './profiler/ProfilerStartToolHandler.js';
+import { ProfilerStopToolHandler } from './profiler/ProfilerStopToolHandler.js';
+import { ProfilerStatusToolHandler } from './profiler/ProfilerStatusToolHandler.js';
+import { ProfilerGetMetricsToolHandler } from './profiler/ProfilerGetMetricsToolHandler.js';
 import { ComponentAddToolHandler } from './component/ComponentAddToolHandler.js';
 import { ComponentRemoveToolHandler } from './component/ComponentRemoveToolHandler.js';
 import { ComponentModifyToolHandler } from './component/ComponentModifyToolHandler.js';
@@ -113,7 +117,9 @@ import { ScriptCreateClassToolHandler } from './script/ScriptCreateClassToolHand
 import { ScriptRemoveSymbolToolHandler } from './script/ScriptRemoveSymbolToolHandler.js';
 import { CodeIndexUpdateToolHandler } from './script/CodeIndexUpdateToolHandler.js';
 import { CodeIndexBuildToolHandler } from './script/CodeIndexBuildToolHandler.js';
+import { SearchToolsHandler } from './search/SearchToolsHandler.js';
 export { BaseToolHandler } from './base/BaseToolHandler.js';
+export { SearchToolsHandler } from './search/SearchToolsHandler.js';
 
 // System handlers
 export { SystemPingToolHandler } from './system/SystemPingToolHandler.js';
@@ -214,6 +220,12 @@ export { VideoCaptureStopToolHandler } from './video/VideoCaptureStopToolHandler
 export { VideoCaptureStatusToolHandler } from './video/VideoCaptureStatusToolHandler.js';
 export { VideoCaptureForToolHandler } from './video/VideoCaptureForToolHandler.js';
 
+// Profiler handlers
+export { ProfilerStartToolHandler } from './profiler/ProfilerStartToolHandler.js';
+export { ProfilerStopToolHandler } from './profiler/ProfilerStopToolHandler.js';
+export { ProfilerStatusToolHandler } from './profiler/ProfilerStatusToolHandler.js';
+export { ProfilerGetMetricsToolHandler } from './profiler/ProfilerGetMetricsToolHandler.js';
+
 // Component handlers
 export { ComponentAddToolHandler } from './component/ComponentAddToolHandler.js';
 export { ComponentRemoveToolHandler } from './component/ComponentRemoveToolHandler.js';
@@ -356,6 +368,11 @@ const HANDLER_CLASSES = [
   VideoCaptureStopToolHandler,
   VideoCaptureStatusToolHandler,
   VideoCaptureForToolHandler,
+  // Profiler handlers
+  ProfilerStartToolHandler,
+  ProfilerStopToolHandler,
+  ProfilerStatusToolHandler,
+  ProfilerGetMetricsToolHandler,
   // Script handlers
   ScriptPackagesListToolHandler,
   ScriptReadToolHandler,
@@ -425,6 +442,15 @@ export function createHandlers(unityConnection) {
     }
   }
 
+  // Add SearchToolsHandler with reference to all handlers
+  try {
+    const searchHandler = new SearchToolsHandler(unityConnection, handlers);
+    handlers.set(searchHandler.name, searchHandler);
+  } catch (error) {
+    failedHandlers.push('SearchToolsHandler');
+    console.error(`[MCP] Failed to create SearchToolsHandler:`, error.message);
+  }
+
   if (failedHandlers.length > 0) {
     console.error(
       `[MCP] Failed to initialize ${failedHandlers.length} handlers: ${failedHandlers.join(', ')}`
@@ -432,7 +458,7 @@ export function createHandlers(unityConnection) {
   }
 
   console.error(
-    `[MCP] Successfully initialized ${handlers.size}/${HANDLER_CLASSES.length} handlers`
+    `[MCP] Successfully initialized ${handlers.size}/${HANDLER_CLASSES.length + 1} handlers (including search_tools)`
   );
 
   return handlers;

package/src/handlers/profiler/ProfilerGetMetricsToolHandler.js

@@ -0,0 +1,52 @@
+/**
+ * Handler for getting Unity Profiler metrics (via MCP)
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ProfilerGetMetricsToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'profiler_get_metrics',
+      'Get available profiler metrics or current metric values. Can list all available metrics by category, or query current values of specific metrics.',
+      {
+        type: 'object',
+        properties: {
+          listAvailable: {
+            type: 'boolean',
+            default: false,
+            description:
+              'If true, return list of all available metrics grouped by category. If false, return current values of specified metrics.'
+          },
+          metrics: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              "Specific metrics to query (only used when listAvailable=false). Leave empty to get all current metric values. Examples: 'System Used Memory', 'Draw Calls Count'"
+          }
+        }
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params, _context) {
+    // Validate metrics parameter
+    if (params?.metrics !== undefined && !Array.isArray(params.metrics)) {
+      return {
+        error: 'Invalid metrics parameter. Must be an array of strings.',
+        code: 'E_INVALID_PARAMETER'
+      };
+    }
+
+    if (Array.isArray(params?.metrics) && params.metrics.some(m => typeof m !== 'string')) {
+      return {
+        error: 'Invalid metrics parameter. All elements must be strings.',
+        code: 'E_INVALID_PARAMETER'
+      };
+    }
+
+    const result = await this.unityConnection.sendCommand('profiler_get_metrics', params || {});
+    return result;
+  }
+}

package/src/handlers/profiler/ProfilerStartToolHandler.js

@@ -0,0 +1,81 @@
+/**
+ * Handler for starting Unity Profiler recording session (via MCP)
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ProfilerStartToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'profiler_start',
+      'Start Unity Profiler recording session. Records CPU, memory, rendering, and GC metrics. Data can be saved to .data file for later analysis in Unity Profiler Window.',
+      {
+        type: 'object',
+        properties: {
+          mode: {
+            type: 'string',
+            enum: ['normal', 'deep'],
+            default: 'normal',
+            description:
+              "Profiling mode. 'normal' for standard profiling, 'deep' for deep profiling (more detailed but higher overhead)"
+          },
+          recordToFile: {
+            type: 'boolean',
+            default: true,
+            description:
+              'Save profiling data to .data file in .unity/capture/ directory. Set to false for real-time metrics only.'
+          },
+          metrics: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              "Specific metrics to record. Leave empty to record all available metrics. Examples: 'System Used Memory', 'Draw Calls Count', 'GC Allocated In Frame'"
+          },
+          maxDurationSec: {
+            type: 'number',
+            minimum: 0,
+            description:
+              'Auto-stop profiling after N seconds. Set to 0 for unlimited recording (manual stop required).'
+          }
+        }
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params, _context) {
+    // Validate mode parameter
+    if (params?.mode && !['normal', 'deep'].includes(params.mode)) {
+      return {
+        error: `Invalid mode '${params.mode}'. Must be 'normal' or 'deep'.`,
+        code: 'E_INVALID_MODE'
+      };
+    }
+
+    // Validate maxDurationSec parameter
+    if (params?.maxDurationSec !== undefined && params.maxDurationSec < 0) {
+      return {
+        error: `Invalid maxDurationSec '${params.maxDurationSec}'. Must be >= 0.`,
+        code: 'E_INVALID_PARAMETER'
+      };
+    }
+
+    // Validate metrics parameter
+    if (params?.metrics !== undefined && !Array.isArray(params.metrics)) {
+      return {
+        error: 'Invalid metrics parameter. Must be an array of strings.',
+        code: 'E_INVALID_PARAMETER'
+      };
+    }
+
+    if (Array.isArray(params?.metrics) && params.metrics.some(m => typeof m !== 'string')) {
+      return {
+        error: 'Invalid metrics parameter. All elements must be strings.',
+        code: 'E_INVALID_PARAMETER'
+      };
+    }
+
+    const result = await this.unityConnection.sendCommand('profiler_start', params || {});
+    return result;
+  }
+}

package/src/handlers/profiler/ProfilerStatusToolHandler.js

@@ -0,0 +1,24 @@
+/**
+ * Handler for getting Unity Profiler recording status (via MCP)
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ProfilerStatusToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'profiler_status',
+      'Get current Unity Profiler recording status. Returns information about active session, elapsed time, and remaining time (if auto-stop is configured).',
+      {
+        type: 'object',
+        properties: {}
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params, _context) {
+    const result = await this.unityConnection.sendCommand('profiler_status', params || {});
+    return result;
+  }
+}

package/src/handlers/profiler/ProfilerStopToolHandler.js

@@ -0,0 +1,46 @@
+/**
+ * Handler for stopping Unity Profiler recording session (via MCP)
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+
+export class ProfilerStopToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'profiler_stop',
+      'Stop Unity Profiler recording and save data to .data file. Returns profiling session summary including duration, frame count, and optionally recorded metrics.',
+      {
+        type: 'object',
+        properties: {
+          sessionId: {
+            type: 'string',
+            description:
+              'Optional session ID to stop. If not provided, stops the current active session.'
+          }
+        }
+      }
+    );
+    this.unityConnection = unityConnection;
+  }
+
+  /** @override */
+  async execute(params, _context) {
+    // Validate sessionId format (32 hex characters, no hyphens)
+    if (params?.sessionId) {
+      if (typeof params.sessionId !== 'string') {
+        return {
+          error: 'Invalid sessionId parameter. Must be a string.',
+          code: 'E_INVALID_PARAMETER'
+        };
+      }
+      if (!/^[0-9a-f]{32}$/.test(params.sessionId)) {
+        return {
+          error: `Invalid sessionId format '${params.sessionId}'. Must be 32 hex characters without hyphens.`,
+          code: 'E_INVALID_PARAMETER'
+        };
+      }
+    }
+
+    const result = await this.unityConnection.sendCommand('profiler_stop', params || {});
+    return result;
+  }
+}

package/src/handlers/script/ScriptEditSnippetToolHandler.js

@@ -9,7 +9,7 @@ const MAX_INSTRUCTIONS = 10;
 const MAX_DIFF_CHARS = 80;
 const PREVIEW_MAX = 1000;
 
-const normalizeSlashes = (p) => p.replace(/\\/g, '/');
+const normalizeSlashes = p => p.replace(/\\/g, '/');
 
 export class ScriptEditSnippetToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
@@ -21,11 +21,13 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
         properties: {
           path: {
             type: 'string',
-            description: 'Project-relative C# path starting with Assets/ or Packages/ (e.g., Assets/Scripts/Foo.cs).'
+            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.'
+            description:
+              'If true, run validation and return preview text without writing to disk. Default=false.'
           },
           instructions: {
             type: 'array',
@@ -42,14 +44,19 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
                 },
                 anchor: {
                   type: 'object',
-                  description: 'Positioning info. Currently supports type=text with exact target snippet.',
+                  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).' },
+                    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).'
+                      description:
+                        'For insert operations, whether to insert before or after the anchor text (default=after).'
                     }
                   },
                   required: ['type', 'target']
@@ -150,9 +157,12 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     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 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/')) {
@@ -167,20 +177,27 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
   #applyInstruction(text, instruction, index) {
     const anchor = instruction.anchor;
     const target = anchor.target;
+
+    // Normalize line endings to LF for consistent matching
+    const normalizedText = text.replace(/\r\n/g, '\n');
+    const normalizedTarget = target.replace(/\r\n/g, '\n');
+
     const occurrences = [];
-    let pos = text.indexOf(target);
+    let pos = normalizedText.indexOf(normalizedTarget);
     while (pos !== -1) {
       occurrences.push(pos);
-      pos = text.indexOf(target, pos + 1);
+      pos = normalizedText.indexOf(normalizedTarget, 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`);
+      throw new Error(
+        `anchor_not_unique: instructions[${index}] matches ${occurrences.length} locations`
+      );
     }
     const start = occurrences[0];
-    const end = start + target.length;
+    const end = start + normalizedTarget.length;
 
     let replacement = '';
     if (instruction.operation === 'delete') {
@@ -190,14 +207,30 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     } 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);
+        return this.#replaceRange(
+          normalizedText,
+          start,
+          start,
+          instruction.newText,
+          normalizedTarget,
+          index
+        );
       }
       if (position !== 'after') {
-        throw new Error(`Unsupported anchor.position "${instruction.anchor.position}" at instructions[${index}]`);
+        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(
+        normalizedText,
+        end,
+        end,
+        instruction.newText,
+        normalizedTarget,
+        index
+      );
     }
-    return this.#replaceRange(text, start, end, replacement, target, index);
+    return this.#replaceRange(normalizedText, start, end, replacement, normalizedTarget, index);
   }
 
   #replaceRange(text, start, end, newText, anchorTarget, index) {
@@ -253,11 +286,14 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
 
   #clipSnippet(s) {
     if (!s) return '';
-    return s.length > 120 ? (s.slice(0, 117) + '…') : s;
+    return s.length > 120 ? s.slice(0, 117) + '…' : s;
   }
 
   #hash(content) {
-    return crypto.createHash('sha256').update(content ?? '', 'utf8').digest('hex');
+    return crypto
+      .createHash('sha256')
+      .update(content ?? '', 'utf8')
+      .digest('hex');
   }
 
   #severityIsError(severity) {

package/src/handlers/search/SearchToolsHandler.js

@@ -0,0 +1,194 @@
+/**
+ * Handler for searching available tools by keywords, categories, or tags
+ * This meta-tool enables token-efficient tool discovery
+ */
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { CATEGORIES, SCOPES } from '../base/categories.js';
+
+export class SearchToolsHandler extends BaseToolHandler {
+  constructor(unityConnection, handlersMap) {
+    super(
+      'search_tools',
+      'Search available Unity MCP tools by keywords, categories, or tags. Use this to discover relevant tools before calling them.',
+      {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description:
+              'Search query (keywords to match against tool names, descriptions, and metadata)'
+          },
+          category: {
+            type: 'string',
+            description: `Filter by category (${Object.values(CATEGORIES).join(', ')})`
+          },
+          tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Filter by tags (e.g., ["create", "scene"], ["read", "gameobject"])'
+          },
+          scope: {
+            type: 'string',
+            enum: Object.values(SCOPES),
+            description: 'Filter by scope: read, write, or execute'
+          },
+          limit: {
+            type: 'number',
+            description: 'Maximum number of results to return (default: 10, max: 50)',
+            minimum: 1,
+            maximum: 50
+          },
+          includeSchemas: {
+            type: 'boolean',
+            description: 'Include full inputSchema in results (default: false for token efficiency)'
+          }
+        }
+      },
+      {
+        category: CATEGORIES.SYSTEM,
+        scope: SCOPES.READ,
+        keywords: ['search', 'discover', 'find', 'tools', 'list'],
+        tags: ['meta', 'query', 'discovery']
+      }
+    );
+
+    this.unityConnection = unityConnection;
+    this.handlersMap = handlersMap;
+  }
+
+  /**
+   * Calculate relevance score for a handler against the search query
+   * @param {BaseToolHandler} handler - Handler to score
+   * @param {string} query - Search query
+   * @param {Array<string>} tags - Tag filters
+   * @returns {number} Relevance score (0-100)
+   */
+  calculateRelevance(handler, query, tags) {
+    let score = 0;
+
+    if (!query && (!tags || tags.length === 0)) {
+      return 50; // Neutral score for no filters
+    }
+
+    const lowerQuery = query ? query.toLowerCase() : '';
+    const searchableText = [handler.name, handler.description, ...(handler.metadata.keywords || [])]
+      .join(' ')
+      .toLowerCase();
+
+    // Exact name match: highest priority
+    if (handler.name.toLowerCase() === lowerQuery) {
+      score += 100;
+    }
+    // Name contains query: high priority
+    else if (handler.name.toLowerCase().includes(lowerQuery)) {
+      score += 50;
+    }
+    // Description/keywords contain query: medium priority
+    else if (searchableText.includes(lowerQuery)) {
+      score += 25;
+    }
+
+    // Tag matches: bonus points
+    if (tags && tags.length > 0) {
+      const matchedTags = tags.filter(tag => handler.metadata.tags.includes(tag));
+      score += matchedTags.length * 10;
+    }
+
+    return Math.min(score, 100);
+  }
+
+  async execute(params) {
+    const { query = '', category, tags = [], scope, limit = 10, includeSchemas = false } = params;
+
+    // Get all handlers from the map
+    const allHandlers = Array.from(this.handlersMap.values());
+
+    // Filter handlers
+    let filteredHandlers = allHandlers.filter(handler => {
+      // Skip search_tools itself from results
+      if (handler.name === 'search_tools') {
+        return false;
+      }
+
+      // Category filter
+      if (category && handler.metadata.category !== category) {
+        return false;
+      }
+
+      // Scope filter
+      if (scope && handler.metadata.scope !== scope) {
+        return false;
+      }
+
+      // Tag filter (AND logic: all specified tags must match)
+      if (tags.length > 0) {
+        const hasAllTags = tags.every(tag => handler.metadata.tags.includes(tag));
+        if (!hasAllTags) {
+          return false;
+        }
+      }
+
+      // Query filter (if specified)
+      if (query) {
+        const lowerQuery = query.toLowerCase();
+        const searchableText = [
+          handler.name,
+          handler.description,
+          ...(handler.metadata.keywords || [])
+        ]
+          .join(' ')
+          .toLowerCase();
+
+        if (!searchableText.includes(lowerQuery)) {
+          return false;
+        }
+      }
+
+      return true;
+    });
+
+    // Calculate relevance scores and sort
+    const scoredHandlers = filteredHandlers.map(handler => ({
+      handler,
+      relevance: this.calculateRelevance(handler, query, tags)
+    }));
+
+    scoredHandlers.sort((a, b) => b.relevance - a.relevance);
+
+    // Apply limit
+    const limitedHandlers = scoredHandlers.slice(0, limit);
+
+    // Format results
+    const results = limitedHandlers.map(({ handler, relevance }) => {
+      const result = {
+        name: handler.name,
+        description: handler.description,
+        category: handler.metadata.category,
+        scope: handler.metadata.scope,
+        tags: handler.metadata.tags,
+        keywords: handler.metadata.keywords,
+        relevance: Math.round(relevance)
+      };
+
+      if (includeSchemas) {
+        result.inputSchema = handler.inputSchema;
+      }
+
+      return result;
+    });
+
+    return {
+      success: true,
+      results,
+      totalMatches: filteredHandlers.length,
+      returned: results.length,
+      query: {
+        query,
+        category,
+        tags,
+        scope,
+        limit
+      }
+    };
+  }
+}

package/src/handlers/system/SystemPingToolHandler.js

@@ -1,4 +1,5 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { CATEGORIES, SCOPES } from '../base/categories.js';
 
 /**
  * Handler for the system_ping tool
@@ -18,9 +19,15 @@ export class SystemPingToolHandler extends BaseToolHandler {
           }
         },
         required: []
+      },
+      {
+        category: CATEGORIES.SYSTEM,
+        scope: SCOPES.READ,
+        keywords: ['ping', 'test', 'connection', 'health', 'status'],
+        tags: ['system', 'diagnostic', 'health-check']
       }
     );
-    
+
     this.unityConnection = unityConnection;
   }
 
@@ -34,12 +41,12 @@ export class SystemPingToolHandler extends BaseToolHandler {
     if (!this.unityConnection.isConnected()) {
       await this.unityConnection.connect();
     }
-    
+
     // Send ping command with optional message
     const result = await this.unityConnection.sendCommand('ping', {
       message: params.message || 'ping'
     });
-    
+
     // Format the result for the response
     return {
       message: result.message,

package/src/lsp/CSharpLspUtils.js

@@ -134,17 +134,38 @@ export class CSharpLspUtils {
     if (!desired) throw new Error('mcp-server version not found; cannot resolve LSP tag');
     const current = this.readLocalVersion(rid);
     if (fs.existsSync(p) && current === desired) return p;
-    await this.autoDownload(rid, desired);
+    const resolved = await this.autoDownload(rid, desired);
     if (!fs.existsSync(p)) throw new Error('csharp-lsp binary not found after download');
-    this.writeLocalVersion(rid, desired);
+    this.writeLocalVersion(rid, resolved || desired);
     return p;
   }
 
   async autoDownload(rid, version) {
     const repo = process.env.GITHUB_REPOSITORY || 'akiojin/unity-mcp-server';
-    const tag = `v${version}`;
-    const manifestUrl = `https://github.com/${repo}/releases/download/${tag}/csharp-lsp-manifest.json`;
-    const manifest = await this.fetchJson(manifestUrl);
+
+    const fetchManifest = async ver => {
+      const tag = `v${ver}`;
+      const manifestUrl = `https://github.com/${repo}/releases/download/${tag}/csharp-lsp-manifest.json`;
+      const manifest = await this.fetchJson(manifestUrl);
+      return { manifest, tag };
+    };
+
+    let targetVersion = version;
+    let manifest;
+    try {
+      ({ manifest } = await fetchManifest(targetVersion));
+    } catch (e) {
+      // Gracefully fall back to the latest release when the requested manifest is missing (404).
+      if (String(e?.message || '').includes('HTTP 404')) {
+        const latest = await this.fetchLatestReleaseVersion(repo);
+        if (!latest) throw e;
+        targetVersion = latest;
+        ({ manifest } = await fetchManifest(targetVersion));
+      } else {
+        throw e;
+      }
+    }
+
     const entry = manifest?.assets?.[rid];
     if (!entry?.url || !entry?.sha256) throw new Error(`manifest missing entry for ${rid}`);
 
@@ -154,17 +175,35 @@ export class CSharpLspUtils {
     await this.downloadTo(entry.url, tmp);
     const actual = await this.sha256File(tmp);
     if (String(actual).toLowerCase() !== String(entry.sha256).toLowerCase()) {
-      try { fs.unlinkSync(tmp); } catch {}
+      try {
+        fs.unlinkSync(tmp);
+      } catch {}
       throw new Error('checksum mismatch for csharp-lsp asset');
     }
     // atomic replace
-    try { fs.renameSync(tmp, dest); } catch (e) {
+    try {
+      fs.renameSync(tmp, dest);
+    } catch (e) {
       // Windows may need removal before rename
-      try { fs.unlinkSync(dest); } catch {}
+      try {
+        fs.unlinkSync(dest);
+      } catch {}
       fs.renameSync(tmp, dest);
     }
-    try { if (process.platform !== 'win32') fs.chmodSync(dest, 0o755); } catch {}
+    try {
+      if (process.platform !== 'win32') fs.chmodSync(dest, 0o755);
+    } catch {}
     logger.info(`[csharp-lsp] downloaded: ${path.basename(dest)} @ ${path.dirname(dest)}`);
+    return targetVersion;
+  }
+
+  async fetchLatestReleaseVersion(repo) {
+    const url = `https://api.github.com/repos/${repo}/releases/latest`;
+    const json = await this.fetchJson(url);
+    const tag = json?.tag_name || '';
+    const version = tag.replace(/^v/, '');
+    if (!version) throw new Error('latest release version not found');
+    return version;
   }
 
   async fetchJson(url) {