uloop-cli 0.44.1

package/src/default-tools.json

@@ -0,0 +1,355 @@
+{
+  "version": "0.44.1",
+  "tools": [
+    {
+      "name": "compile",
+      "description": "Execute Unity project compilation",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ForceRecompile": {
+            "type": "boolean",
+            "description": "Force full recompilation"
+          }
+        }
+      }
+    },
+    {
+      "name": "get-logs",
+      "description": "Retrieve logs from Unity Console",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "LogType": {
+            "type": "string",
+            "description": "Log type filter",
+            "enum": [
+              "Error",
+              "Warning",
+              "Log",
+              "All"
+            ],
+            "default": "All"
+          },
+          "MaxCount": {
+            "type": "integer",
+            "description": "Maximum number of logs to retrieve",
+            "default": 100
+          },
+          "SearchText": {
+            "type": "string",
+            "description": "Text to search within logs"
+          },
+          "IncludeStackTrace": {
+            "type": "boolean",
+            "description": "Include stack trace in output",
+            "default": true
+          },
+          "UseRegex": {
+            "type": "boolean",
+            "description": "Use regex for search"
+          },
+          "SearchInStackTrace": {
+            "type": "boolean",
+            "description": "Search within stack trace"
+          }
+        }
+      }
+    },
+    {
+      "name": "run-tests",
+      "description": "Execute Unity Test Runner",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "TestMode": {
+            "type": "string",
+            "description": "Test mode",
+            "enum": [
+              "EditMode",
+              "PlayMode"
+            ],
+            "default": "EditMode"
+          },
+          "FilterType": {
+            "type": "string",
+            "description": "Filter type",
+            "enum": [
+              "all",
+              "exact",
+              "regex",
+              "assembly"
+            ],
+            "default": "all"
+          },
+          "FilterValue": {
+            "type": "string",
+            "description": "Filter value"
+          },
+          "SaveXml": {
+            "type": "boolean",
+            "description": "Save test results as XML"
+          }
+        }
+      }
+    },
+    {
+      "name": "clear-console",
+      "description": "Clear Unity console logs",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "AddConfirmationMessage": {
+            "type": "boolean",
+            "description": "Add confirmation message after clearing"
+          }
+        }
+      }
+    },
+    {
+      "name": "focus-window",
+      "description": "Bring Unity Editor window to front",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get-hierarchy",
+      "description": "Get Unity Hierarchy structure",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "RootPath": {
+            "type": "string",
+            "description": "Root GameObject path"
+          },
+          "MaxDepth": {
+            "type": "integer",
+            "description": "Maximum depth (-1 for unlimited)",
+            "default": -1
+          },
+          "IncludeComponents": {
+            "type": "boolean",
+            "description": "Include component information",
+            "default": true
+          },
+          "IncludeInactive": {
+            "type": "boolean",
+            "description": "Include inactive GameObjects",
+            "default": true
+          },
+          "IncludePaths": {
+            "type": "boolean",
+            "description": "Include path information"
+          }
+        }
+      }
+    },
+    {
+      "name": "unity-search",
+      "description": "Search Unity project",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "SearchQuery": {
+            "type": "string",
+            "description": "Search query"
+          },
+          "Providers": {
+            "type": "array",
+            "description": "Search providers",
+            "items": {
+              "type": "string"
+            }
+          },
+          "MaxResults": {
+            "type": "integer",
+            "description": "Maximum number of results",
+            "default": 50
+          },
+          "SaveToFile": {
+            "type": "boolean",
+            "description": "Save results to file"
+          }
+        }
+      }
+    },
+    {
+      "name": "get-menu-items",
+      "description": "Retrieve Unity MenuItems",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "FilterText": {
+            "type": "string",
+            "description": "Filter text"
+          },
+          "FilterType": {
+            "type": "string",
+            "description": "Filter type",
+            "enum": [
+              "contains",
+              "exact",
+              "startswith"
+            ],
+            "default": "contains"
+          },
+          "MaxCount": {
+            "type": "integer",
+            "description": "Maximum number of items",
+            "default": 200
+          },
+          "IncludeValidation": {
+            "type": "boolean",
+            "description": "Include validation functions"
+          }
+        }
+      }
+    },
+    {
+      "name": "execute-menu-item",
+      "description": "Execute Unity MenuItem",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "MenuItemPath": {
+            "type": "string",
+            "description": "Menu item path (e.g., \"GameObject/Create Empty\")"
+          },
+          "UseReflectionFallback": {
+            "type": "boolean",
+            "description": "Use reflection fallback",
+            "default": true
+          }
+        }
+      }
+    },
+    {
+      "name": "find-game-objects",
+      "description": "Find GameObjects with search criteria",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "NamePattern": {
+            "type": "string",
+            "description": "Name pattern to search"
+          },
+          "SearchMode": {
+            "type": "string",
+            "description": "Search mode",
+            "enum": [
+              "Exact",
+              "Path",
+              "Regex",
+              "Contains"
+            ],
+            "default": "Contains"
+          },
+          "RequiredComponents": {
+            "type": "array",
+            "description": "Required components",
+            "items": {
+              "type": "string"
+            }
+          },
+          "Tag": {
+            "type": "string",
+            "description": "Tag filter"
+          },
+          "Layer": {
+            "type": "string",
+            "description": "Layer filter"
+          },
+          "MaxResults": {
+            "type": "integer",
+            "description": "Maximum number of results",
+            "default": 20
+          },
+          "IncludeInactive": {
+            "type": "boolean",
+            "description": "Include inactive GameObjects"
+          }
+        }
+      }
+    },
+    {
+      "name": "capture-gameview",
+      "description": "Capture Unity Game View as PNG",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ResolutionScale": {
+            "type": "number",
+            "description": "Resolution scale (0.1 to 1.0)",
+            "default": 1
+          }
+        }
+      }
+    },
+    {
+      "name": "execute-dynamic-code",
+      "description": "Execute C# code in Unity Editor",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "Code": {
+            "type": "string",
+            "description": "C# code to execute"
+          },
+          "CompileOnly": {
+            "type": "boolean",
+            "description": "Compile only without execution"
+          },
+          "AutoQualifyUnityTypesOnce": {
+            "type": "boolean",
+            "description": "Auto-qualify Unity types"
+          }
+        }
+      }
+    },
+    {
+      "name": "get-provider-details",
+      "description": "Get Unity Search provider details",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ProviderId": {
+            "type": "string",
+            "description": "Specific provider ID"
+          },
+          "ActiveOnly": {
+            "type": "boolean",
+            "description": "Only active providers"
+          },
+          "IncludeDescriptions": {
+            "type": "boolean",
+            "description": "Include descriptions",
+            "default": true
+          },
+          "SortByPriority": {
+            "type": "boolean",
+            "description": "Sort by priority",
+            "default": true
+          }
+        }
+      }
+    },
+    {
+      "name": "get-project-info",
+      "description": "Get Unity project information",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get-version",
+      "description": "Get uLoopMCP version information",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    }
+  ]
+}

package/src/direct-unity-client.ts

@@ -0,0 +1,125 @@
+/**
+ * Direct Unity TCP client for CLI usage.
+ * Establishes one-shot TCP connections to Unity without going through MCP server.
+ */
+
+import * as net from 'net';
+import { createFrame, parseFrameFromBuffer, extractFrameFromBuffer } from './simple-framer.js';
+
+const JSONRPC_VERSION = '2.0';
+const DEFAULT_HOST = '127.0.0.1';
+const NETWORK_TIMEOUT_MS = 180000;
+
+export interface JsonRpcRequest {
+  jsonrpc: string;
+  method: string;
+  params?: Record<string, unknown>;
+  id: number;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: string;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+  id: number;
+}
+
+export class DirectUnityClient {
+  private socket: net.Socket | null = null;
+  private requestId: number = 0;
+  private receiveBuffer: Buffer = Buffer.alloc(0);
+
+  constructor(
+    private readonly port: number,
+    private readonly host: string = DEFAULT_HOST,
+  ) {}
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket = new net.Socket();
+
+      this.socket.on('error', (error: Error) => {
+        reject(new Error(`Connection error: ${error.message}`));
+      });
+
+      this.socket.connect(this.port, this.host, () => {
+        resolve();
+      });
+    });
+  }
+
+  async sendRequest<T>(method: string, params?: Record<string, unknown>): Promise<T> {
+    if (!this.socket) {
+      throw new Error('Not connected to Unity');
+    }
+
+    const request: JsonRpcRequest = {
+      jsonrpc: JSONRPC_VERSION,
+      method,
+      params: params ?? {},
+      id: ++this.requestId,
+    };
+
+    const requestJson = JSON.stringify(request);
+    const framedMessage = createFrame(requestJson);
+
+    return new Promise((resolve, reject) => {
+      const socket = this.socket!;
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Request timed out after ${NETWORK_TIMEOUT_MS}ms`));
+      }, NETWORK_TIMEOUT_MS);
+
+      const onData = (chunk: Buffer): void => {
+        this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
+
+        const parseResult = parseFrameFromBuffer(this.receiveBuffer);
+        if (!parseResult.isComplete) {
+          return;
+        }
+
+        const extractResult = extractFrameFromBuffer(
+          this.receiveBuffer,
+          parseResult.contentLength,
+          parseResult.headerLength,
+        );
+
+        if (extractResult.jsonContent === null) {
+          return;
+        }
+
+        clearTimeout(timeoutId);
+        socket.off('data', onData);
+
+        this.receiveBuffer = extractResult.remainingData;
+
+        const response = JSON.parse(extractResult.jsonContent) as JsonRpcResponse;
+
+        if (response.error) {
+          reject(new Error(`Unity error: ${response.error.message}`));
+          return;
+        }
+
+        resolve(response.result as T);
+      };
+
+      socket.on('data', onData);
+      socket.write(framedMessage);
+    });
+  }
+
+  disconnect(): void {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+    this.receiveBuffer = Buffer.alloc(0);
+  }
+
+  isConnected(): boolean {
+    return this.socket !== null && !this.socket.destroyed;
+  }
+}

package/src/execute-tool.ts

@@ -0,0 +1,155 @@
+/**
+ * Tool execution logic for CLI.
+ * Handles dynamic tool execution by connecting to Unity and sending requests.
+ */
+
+import { DirectUnityClient } from './direct-unity-client.js';
+import { resolveUnityPort } from './port-resolver.js';
+import { saveToolsCache, getCacheFilePath, ToolsCache, ToolDefinition } from './tool-cache.js';
+import { VERSION } from './version.js';
+
+export interface GlobalOptions {
+  port?: string;
+}
+
+export async function executeToolCommand(
+  toolName: string,
+  params: Record<string, unknown>,
+  globalOptions: GlobalOptions,
+): Promise<void> {
+  let portNumber: number | undefined;
+  if (globalOptions.port) {
+    const parsed = parseInt(globalOptions.port, 10);
+    if (isNaN(parsed)) {
+      throw new Error(`Invalid port number: ${globalOptions.port}`);
+    }
+    portNumber = parsed;
+  }
+  const port = await resolveUnityPort(portNumber);
+
+  const client = new DirectUnityClient(port);
+
+  try {
+    await client.connect();
+
+    const result = await client.sendRequest(toolName, params);
+
+    // Always output JSON to match MCP response format
+    console.log(JSON.stringify(result, null, 2));
+  } finally {
+    client.disconnect();
+  }
+}
+
+export async function listAvailableTools(globalOptions: GlobalOptions): Promise<void> {
+  let portNumber: number | undefined;
+  if (globalOptions.port) {
+    const parsed = parseInt(globalOptions.port, 10);
+    if (isNaN(parsed)) {
+      throw new Error(`Invalid port number: ${globalOptions.port}`);
+    }
+    portNumber = parsed;
+  }
+  const port = await resolveUnityPort(portNumber);
+
+  const client = new DirectUnityClient(port);
+
+  try {
+    await client.connect();
+
+    const result = await client.sendRequest<{
+      Tools: Array<{ name: string; description: string }>;
+    }>('get-tool-details', { IncludeDevelopmentOnly: false });
+
+    if (!result.Tools || !Array.isArray(result.Tools)) {
+      throw new Error('Unexpected response from Unity: missing Tools array');
+    }
+
+    for (const tool of result.Tools) {
+      console.log(`  - ${tool.name}`);
+    }
+  } finally {
+    client.disconnect();
+  }
+}
+
+interface UnityToolInfo {
+  name: string;
+  description: string;
+  parameterSchema: {
+    Properties: Record<string, UnityPropertyInfo>;
+    Required?: string[];
+  };
+}
+
+interface UnityPropertyInfo {
+  Type: string;
+  Description?: string;
+  DefaultValue?: unknown;
+  Enum?: string[] | null;
+}
+
+function convertProperties(
+  unityProps: Record<string, UnityPropertyInfo>,
+): Record<string, ToolDefinition['inputSchema']['properties'][string]> {
+  const result: Record<string, ToolDefinition['inputSchema']['properties'][string]> = {};
+  for (const [key, prop] of Object.entries(unityProps)) {
+    result[key] = {
+      type: prop.Type?.toLowerCase() ?? 'string',
+      description: prop.Description,
+      default: prop.DefaultValue,
+      enum: prop.Enum ?? undefined,
+    };
+  }
+  return result;
+}
+
+export async function syncTools(globalOptions: GlobalOptions): Promise<void> {
+  let portNumber: number | undefined;
+  if (globalOptions.port) {
+    const parsed = parseInt(globalOptions.port, 10);
+    if (isNaN(parsed)) {
+      throw new Error(`Invalid port number: ${globalOptions.port}`);
+    }
+    portNumber = parsed;
+  }
+  const port = await resolveUnityPort(portNumber);
+
+  const client = new DirectUnityClient(port);
+
+  try {
+    await client.connect();
+
+    const result = await client.sendRequest<{
+      Tools: UnityToolInfo[];
+    }>('get-tool-details', { IncludeDevelopmentOnly: false });
+
+    if (!result.Tools || !Array.isArray(result.Tools)) {
+      throw new Error('Unexpected response from Unity: missing Tools array');
+    }
+
+    const cache: ToolsCache = {
+      version: VERSION,
+      updatedAt: new Date().toISOString(),
+      tools: result.Tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: {
+          type: 'object',
+          properties: convertProperties(tool.parameterSchema.Properties),
+          required: tool.parameterSchema.Required,
+        },
+      })),
+    };
+
+    saveToolsCache(cache);
+
+    console.log(`Synced ${cache.tools.length} tools to ${getCacheFilePath()}`);
+    console.log('\nTools:');
+    for (const tool of cache.tools) {
+      console.log(`  - ${tool.name}`);
+    }
+  } finally {
+    client.disconnect();
+  }
+}

package/src/port-resolver.ts

@@ -0,0 +1,60 @@
+/**
+ * Port resolution utility for CLI.
+ * Resolves Unity server port from various sources.
+ */
+
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { findUnityProjectRoot } from './project-root.js';
+
+const DEFAULT_PORT = 8700;
+
+interface UnityMcpSettings {
+  serverPort?: number;
+  customPort?: number;
+}
+
+export async function resolveUnityPort(explicitPort?: number): Promise<number> {
+  if (explicitPort !== undefined) {
+    return explicitPort;
+  }
+
+  const settingsPort = await readPortFromSettings();
+  if (settingsPort !== null) {
+    return settingsPort;
+  }
+
+  return DEFAULT_PORT;
+}
+
+async function readPortFromSettings(): Promise<number | null> {
+  const projectRoot = findUnityProjectRoot();
+  if (projectRoot === null) {
+    return null;
+  }
+  const settingsPath = join(projectRoot, 'UserSettings/UnityMcpSettings.json');
+
+  let content: string;
+  try {
+    content = await readFile(settingsPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let settings: UnityMcpSettings;
+  try {
+    settings = JSON.parse(content) as UnityMcpSettings;
+  } catch {
+    return null;
+  }
+
+  if (typeof settings.serverPort === 'number') {
+    return settings.serverPort;
+  }
+
+  if (typeof settings.customPort === 'number') {
+    return settings.customPort;
+  }
+
+  return null;
+}