refactor(visualScripting): expand templates and add utility functions

- Add new AI and NPC behaviors, including NPC Patrol Behavior template
- Introduce UI Interaction Systems with detailed button interaction template
- Implement Audio System template with background music and SFX sources
- Create Particle Effect System template with configurable emission and colors
- Enhance visual scripting template data with tags, category, and ordering
- Add utility functions to filter templates by category, tag, and relevance
- Provide functions to get all template categories and tags, with sorting
- Implement search by name, description, or tags for flexible template lookup
- Add template validation function ensuring structure correctness
- Provide template statistics including counts by category and tag popularity
- Add function to get a random template, optionally filtered by category

fix(unitybridge): improve error handling and logging in bridge

- Add detailed exception logging when stopping HTTP listener fails
- Improve SSE client connection removal with error catching and logging
- Optimize client-side logging to avoid redundant JSON stringification
- Update error message handling in tool call catch block for clarity

chore(server): remove ESLint config and add eventsource types

- Delete server/.eslintrc.json to clean up configuration files
- Add @types/eventsource as a dev dependency in package.json and lockfile

docs(server): add comprehensive type definitions for Unity MCP

- Provide extensive global and module type declarations for MCP usage
- Define Unity-specific types for vectors, colors, bounds, and components
- Include MCP tool argument, result, and resource type definitions
- Add error context, retry config, environment parser, and logging types
- Export all types for use in downstream modules and tools

fix(readme): correct MCP server startup path

- Update MCP server startup command path from PathToFile/MCP to PathToFile/server
- Ensure consistent path for server execution according to current folder structure

Author: ChiR24

README.md

@@ -150,7 +150,7 @@ The server includes automatic console verification. Configure with environment v
 {
   "unity-mcp": {
     "command": "node",
-    "args": ["PathToFile/MCP/server/dist/index.js"],
+    "args": ["PathToFile/server/dist/index.js"],
     "env": {
       "UNITY_BRIDGE_URL": "http://127.0.0.1:58888",
       "UNITY_CONSOLE_VERIFICATION": "true",

UnityBridge/Packages/com.example.mcp.unitybridge/Runtime/Editor/UnityMcpBridge.cs

@@ -136,7 +136,10 @@ private static void StopServer()
                 }
                 _listener.Close();
             }
-            catch { }
+            catch (Exception ex)
+            {
+                Debug.LogError($"[MCP Bridge] Failed to stop HTTP listener: {ex.Message}");
+            }
             finally
             {
                 _listener = null;
@@ -177,7 +180,6 @@ private static async void HandleContext(HttpListenerContext ctx)
                     {
                         body = await reader.ReadToEndAsync();
                     }
-                    try { LogBridge($"-> {path} {Trunc(body, 512)}"); } catch { }
 
                     if (path == "/menu/execute" || path == "/editor/executeMenuItem")
                     {
@@ -1271,8 +1273,14 @@ private static void BroadcastSse(string line)
                         {
                             lock (SseLock)
                             {
-                                try { res.OutputStream.Close(); } catch { }
-                                SseClients.Remove(res);
+                                try
+                                {
+                                    SseClients.Remove(res);
+                                }
+                                catch (Exception ex)
+                                {
+                                    Debug.LogError($"[MCP Bridge] Failed to close SSE client connection: {ex.Message}");
+                                }
                             }
                         }
                     });

client/src/client.ts

@@ -47,7 +47,11 @@ async function main() {
   const call = async (name: string, args: Record<string, unknown> = {}): Promise<McpResult | null> => {
     try {
       const res = await client.callTool({ name, arguments: args }) as McpResult;
-      console.log(`${name} ${JSON.stringify(args)} ->`, JSON.stringify(res));
+      // Optimize logging: avoid double JSON.stringify
+      const argsStr = Object.keys(args).length === 0 ? "{}" : JSON.stringify(args);
+      const resStr = getFirstText(res) || "[no content]";
+      console.log(`${name} ${argsStr} -> ${resStr.length > 200 ? resStr.substring(0, 200) + "..." : resStr}`);
+      
       // After every tool call (except console read itself), read Unity console and print delta
       if (!(name === "unity_console" && (args as Record<string, unknown>)?.action === "read")) {
         try {
@@ -66,7 +70,7 @@ async function main() {
       }
       return res;
     } catch (e) {
-      console.warn(`${name} failed:`, JSON.stringify(e, null, 2));
+      console.warn(`${name} failed:`, (e as Error).message);
       return null;
     }
   };

server/.eslintrc.json

@@ -20,6 +20,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
+    "@types/eventsource": "^1.1.15",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.12.7",
     "eslint": "^9.33.0",

server/package-lock.json

@@ -0,0 +1,157 @@
+/**
+ * Centralized configuration management for Unity MCP Server
+ * Handles all environment variables and configuration constants
+ */
+
+/**
+ * Helper function to parse boolean environment variables
+ * @param name - Environment variable name
+ * @param defaultValue - Default value if variable is not set or invalid
+ * @returns Parsed boolean value
+ */
+function envBool(name: string, defaultValue: boolean): boolean {
+  const v = (process.env[name] ?? "").toString().trim().toLowerCase();
+  if (v === "" || v == null) return defaultValue;
+  if (["1", "true", "yes", "on"].includes(v)) return true;
+  if (["0", "false", "no", "off"].includes(v)) return false;
+  return defaultValue;
+}
+
+/**
+ * Helper function to parse integer environment variables
+ * @param name - Environment variable name
+ * @param defaultValue - Default value if variable is not set or invalid
+ * @returns Parsed integer value, or defaultValue if invalid
+ */
+function envInt(name: string, defaultValue: number): number {
+  const raw = process.env[name];
+  const parsed = raw != null ? Number(raw) : NaN;
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : defaultValue;
+}
+
+/**
+ * Helper function to parse string environment variables with defaults
+ * @param name - Environment variable name
+ * @param defaultValue - Default value if variable is not set
+ * @returns The string value or defaultValue
+ */
+function envString(name: string, defaultValue: string): string {
+  return process.env[name] ?? defaultValue;
+}
+
+/**
+ * Application configuration constants
+ */
+export const CONFIG = {
+  // Unity Bridge Configuration
+  UNITY_BASE_URL: envString("UNITY_BRIDGE_URL", "http://127.0.0.1:58888"),
+  UNITY_BRIDGE_TOKEN: envString("UNITY_BRIDGE_TOKEN", ""),
+  
+  // Debug and Logging
+  DEBUG: envBool("UNITY_MCP_DEBUG", false) || envBool("DEBUG", false),
+  
+  // Console Verification
+  CONSOLE_VERIFICATION_ENABLED: envBool("UNITY_CONSOLE_VERIFICATION", true),
+  CONSOLE_CHECK_DELAY_MS: envInt("UNITY_CONSOLE_CHECK_DELAY_MS", 500),
+  CONSOLE_MAX_LINES: envInt("UNITY_CONSOLE_MAX_LINES", 100),
+  
+  // Compilation and Timeouts
+  COMPILE_TIMEOUT_MS: envInt("UNITY_COMPILE_TIMEOUT_MS", 120_000),
+  DEFAULT_HTTP_TIMEOUT_MS: 45_000,
+  GET_TIMEOUT_MS: 30_000,
+  
+  // Network Configuration
+  MAX_RETRY_ATTEMPTS: envInt("UNITY_MAX_RETRY_ATTEMPTS", 8),
+  RETRY_BASE_DELAY_MS: envInt("UNITY_RETRY_BASE_DELAY_MS", 200),
+  MAX_RETRY_DELAY_MS: envInt("UNITY_MAX_RETRY_DELAY_MS", 5000),
+  
+  // Application Metadata
+  APP_NAME: "unity-mcp",
+  APP_VERSION: "0.1.0",
+
+  // Performance Monitoring
+  ENABLE_PERFORMANCE_MONITORING: envBool("UNITY_PERFORMANCE_MONITORING", false),
+  PERFORMANCE_LOG_INTERVAL_MS: envInt("UNITY_PERFORMANCE_LOG_INTERVAL", 10000),
+  
+  // Error Messages
+  ERROR_MESSAGES: {
+    UNITY_NOT_RUNNING: "Unity Editor is not running or Unity Bridge is not accessible",
+    UNAUTHORIZED: "Unauthorized: Set UNITY_BRIDGE_TOKEN in both Unity and server",
+    COMPILATION_TIMEOUT: "Timed out waiting for Unity to finish compilation",
+    INVALID_OPERATION: "Invalid operation or parameters",
+  } as const,
+  
+  // Resource URIs
+  RESOURCES: {
+    UNITY_LOGS: "unity://logs",
+  } as const,
+} as const;
+
+/**
+ * Type-safe configuration access
+ */
+export type AppConfig = typeof CONFIG;
+
+/**
+ * Validates the current configuration and logs warnings for missing required values
+ * @returns True if configuration is valid, false if critical issues found
+ */
+export function validateConfig(): boolean {
+  let isValid = true;
+
+  // Validate Unity Bridge Configuration
+  if (!CONFIG.UNITY_BRIDGE_TOKEN) {
+    console.warn("[unity-mcp] UNITY_BRIDGE_TOKEN not set; the bridge will accept unauthenticated requests on 127.0.0.1. Set a token in both Unity and server env for security.");
+  }
+
+  // Validate URL format
+  try {
+    new URL(CONFIG.UNITY_BASE_URL);
+  } catch {
+    console.error("[unity-mcp] UNITY_BRIDGE_URL is not a valid URL:", CONFIG.UNITY_BASE_URL);
+    isValid = false;
+  }
+
+  // Validate timeout configurations
+  if (CONFIG.COMPILE_TIMEOUT_MS < 10000) {
+    console.warn("[unity-mcp] COMPILE_TIMEOUT_MS is very low:", CONFIG.COMPILE_TIMEOUT_MS, "ms. Consider increasing to at least 10000ms.");
+  }
+
+  if (CONFIG.DEFAULT_HTTP_TIMEOUT_MS < 5000) {
+    console.warn("[unity-mcp] DEFAULT_HTTP_TIMEOUT_MS is low:", CONFIG.DEFAULT_HTTP_TIMEOUT_MS, "ms. Consider increasing for stability.");
+  }
+
+  // Validate retry configuration
+  if (CONFIG.MAX_RETRY_ATTEMPTS < 1) {
+    console.error("[unity-mcp] MAX_RETRY_ATTEMPTS must be at least 1");
+    isValid = false;
+  }
+
+  if (CONFIG.RETRY_BASE_DELAY_MS < 50) {
+    console.warn("[unity-mcp] RETRY_BASE_DELAY_MS is very low:", CONFIG.RETRY_BASE_DELAY_MS, "ms. This may cause rapid retry storms.");
+  }
+
+  if (CONFIG.MAX_RETRY_DELAY_MS < CONFIG.RETRY_BASE_DELAY_MS) {
+    console.error("[unity-mcp] MAX_RETRY_DELAY_MS should be greater than RETRY_BASE_DELAY_MS");
+    isValid = false;
+  }
+
+  // Validate console configuration
+  if (CONFIG.CONSOLE_MAX_LINES < 10) {
+    console.warn("[unity-mcp] CONSOLE_MAX_LINES is very low:", CONFIG.CONSOLE_MAX_LINES, "lines. Consider increasing for better debugging.");
+  }
+
+  // Log configuration in debug mode
+  if (CONFIG.DEBUG) {
+    console.log("[unity-mcp] Debug mode enabled");
+    console.log("[unity-mcp] Configuration:", {
+      UNITY_BASE_URL: CONFIG.UNITY_BASE_URL,
+      CONSOLE_VERIFICATION_ENABLED: CONFIG.CONSOLE_VERIFICATION_ENABLED,
+      COMPILE_TIMEOUT_MS: CONFIG.COMPILE_TIMEOUT_MS,
+      MAX_RETRY_ATTEMPTS: CONFIG.MAX_RETRY_ATTEMPTS,
+      ENABLE_PERFORMANCE_MONITORING: CONFIG.ENABLE_PERFORMANCE_MONITORING,
+    });
+  }
+
+  return isValid;
+}