godot-mcp-runtime 2.2.0 → 2.2.2

package/dist/tools/project-tools.js

@@ -1,6 +1,7 @@
 import { join, basename, sep } from 'path';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { normalizeParameters, validatePath, validateProjectArgs, createErrorResponse, logDebug, } from '../utils/godot-runner.js';
+const MAX_RUNTIME_ERROR_CONTEXT_LINES = 30;
 function parseAutoloads(projectFilePath) {
     const content = readFileSync(projectFilePath, 'utf8');
     const autoloads = [];
@@ -27,7 +28,7 @@ function addAutoloadEntry(projectFilePath, name, path, singleton) {
     const content = readFileSync(projectFilePath, 'utf8');
     const lines = content.split('\n');
     const entry = `${name}="${singleton ? '*' : ''}${normalizeAutoloadPath(path)}"`;
-    const sectionIdx = lines.findIndex(l => l.trim() === '[autoload]');
+    const sectionIdx = lines.findIndex((l) => l.trim() === '[autoload]');
     if (sectionIdx === -1) {
         writeFileSync(projectFilePath, content.trimEnd() + '\n\n[autoload]\n' + entry + '\n', 'utf8');
         return;
@@ -44,7 +45,7 @@ function removeAutoloadEntry(projectFilePath, name) {
     const lines = content.split('\n');
     let inAutoloadSection = false;
     let removed = false;
-    const newLines = lines.filter(line => {
+    const newLines = lines.filter((line) => {
         const trimmed = line.trim();
         if (trimmed.startsWith('[')) {
             inAutoloadSection = trimmed === '[autoload]';
@@ -68,7 +69,7 @@ function updateAutoloadEntry(projectFilePath, name, newPath, singleton) {
     const lines = content.split('\n');
     let inAutoloadSection = false;
     let updated = false;
-    const newLines = lines.map(line => {
+    const newLines = lines.map((line) => {
         const trimmed = line.trim();
         if (trimmed.startsWith('[')) {
             inAutoloadSection = trimmed === '[autoload]';
@@ -107,7 +108,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'run_project',
-        description: 'Run a Godot project in debug mode. Preferred path for runtime tools. Required before calling take_screenshot, simulate_input, get_ui_elements, run_script, or get_debug_output unless you intentionally use attach_project for a manually launched game. After starting, wait 2–3 seconds for the MCP bridge to initialize before using runtime tools. Call stop_project when done.',
+        description: 'Run a Godot project with stdout/stderr captured. Preferred path for runtime tools. Required before calling take_screenshot, simulate_input, get_ui_elements, run_script, or get_debug_output unless you intentionally use attach_project for a manually launched game. Verifies MCP bridge readiness before returning success. Call stop_project when done.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -129,7 +130,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'attach_project',
-        description: 'Attach runtime MCP tools to a project without spawning Godot. This injects the McpBridge autoload and marks the project as the active runtime session so you can launch the game manually from your own shell, then use take_screenshot, simulate_input, get_ui_elements, and run_script against that running game. Use detach_project or stop_project when done. get_debug_output is not available in attached mode because stdout/stderr are not captured.',
+        description: 'Attach runtime MCP tools to a project without spawning Godot. This injects the McpBridge autoload and marks the project as the active runtime session so you can launch the game manually from your own shell, then use take_screenshot, simulate_input, get_ui_elements, and run_script against that running game. Set waitForBridge to true after launching Godot to block until the bridge is confirmed ready. Use detach_project or stop_project when done. get_debug_output is not available in attached mode because stdout/stderr are not captured.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -137,6 +138,10 @@ export const projectToolDefinitions = [
                     type: 'string',
                     description: 'Path to the Godot project directory',
                 },
+                waitForBridge: {
+                    type: 'boolean',
+                    description: 'If true, poll the bridge until it responds (up to 15 seconds). Use this after Godot is already running to confirm runtime tools are ready. Defaults to false.',
+                },
             },
             required: ['projectPath'],
         },
@@ -207,7 +212,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'take_screenshot',
-        description: 'Capture a PNG screenshot of the running Godot viewport. Requires run_project first; wait 2–3 seconds after starting for the bridge to initialize. Returns the image inline. Screenshots are also saved to .mcp/screenshots/ in the project directory.',
+        description: 'Capture a PNG screenshot of the running Godot viewport. Requires an active runtime session (run_project or attach_project). Returns the image inline. Screenshots are also saved to .mcp/screenshots/ in the project directory.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -221,7 +226,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'simulate_input',
-        description: 'Simulate batched sequential input in a running Godot project. Requires run_project first; wait 2–3 seconds after starting. Use get_ui_elements first to discover element names and paths for click_element actions.\n\nEach action object requires a "type" field. Valid types and their specific fields:\n- key: keyboard event (key: string, pressed: bool, shift/ctrl/alt: bool)\n- mouse_button: click at coordinates (x, y: number, button: "left"|"right"|"middle", pressed: bool, double_click: bool)\n- mouse_motion: move cursor (x, y: number, relative_x, relative_y: number)\n- click_element: click a UI element by node path or node name (element: string, button, double_click)\n- action: fire a Godot input action (action: string, pressed: bool, strength: 0–1)\n- wait: pause between actions (ms: number)\n\nExamples:\n1. Press and release Space: [{type:"key",key:"Space",pressed:true},{type:"wait",ms:100},{type:"key",key:"Space",pressed:false}]\n2. Click a UI button (discover path with get_ui_elements first): [{type:"click_element",element:"StartButton"}]\n3. Left-click at viewport coordinates: [{type:"mouse_button",x:400,y:300,button:"left",pressed:true},{type:"mouse_button",x:400,y:300,button:"left",pressed:false}]\n4. Fire a Godot action: [{type:"action",action:"jump",pressed:true},{type:"wait",ms:200},{type:"action",action:"jump",pressed:false}]\n5. Type "hello": [{type:"key",key:"H",pressed:true},{type:"key",key:"H",pressed:false},{type:"key",key:"E",pressed:true},{type:"key",key:"E",pressed:false},{type:"key",key:"L",pressed:true},{type:"key",key:"L",pressed:false},{type:"key",key:"L",pressed:true},{type:"key",key:"L",pressed:false},{type:"key",key:"O",pressed:true},{type:"key",key:"O",pressed:false}]',
+        description: 'Simulate batched sequential input in a running Godot project. Requires an active runtime session (run_project or attach_project). Use get_ui_elements first to discover element names and paths for click_element actions.\n\nEach action object requires a "type" field. Valid types and their specific fields:\n- key: keyboard event (key: string, pressed: bool, shift/ctrl/alt: bool)\n- mouse_button: click at coordinates (x, y: number, button: "left"|"right"|"middle", pressed: bool, double_click: bool)\n- mouse_motion: move cursor (x, y: number, relative_x, relative_y: number)\n- click_element: click a UI element by node path or node name (element: string, button, double_click)\n- action: fire a Godot input action (action: string, pressed: bool, strength: 0–1)\n- wait: pause between actions (ms: number)\n\nExamples:\n1. Press and release Space: [{type:"key",key:"Space",pressed:true},{type:"wait",ms:100},{type:"key",key:"Space",pressed:false}]\n2. Click a UI button (discover path with get_ui_elements first): [{type:"click_element",element:"StartButton"}]\n3. Left-click at viewport coordinates: [{type:"mouse_button",x:400,y:300,button:"left",pressed:true},{type:"mouse_button",x:400,y:300,button:"left",pressed:false}]\n4. Fire a Godot action: [{type:"action",action:"jump",pressed:true},{type:"wait",ms:200},{type:"action",action:"jump",pressed:false}]\n5. Type "hello": [{type:"key",key:"H",pressed:true},{type:"key",key:"H",pressed:false},{type:"key",key:"E",pressed:true},{type:"key",key:"E",pressed:false},{type:"key",key:"L",pressed:true},{type:"key",key:"L",pressed:false},{type:"key",key:"L",pressed:true},{type:"key",key:"L",pressed:false},{type:"key",key:"O",pressed:true},{type:"key",key:"O",pressed:false}]',
         inputSchema: {
             type: 'object',
             properties: {
@@ -236,21 +241,58 @@ export const projectToolDefinitions = [
                                 enum: ['key', 'mouse_button', 'mouse_motion', 'click_element', 'action', 'wait'],
                                 description: 'The type of input action',
                             },
-                            key: { type: 'string', description: '[key] Key name (e.g. "W", "Space", "Escape", "Up")' },
-                            pressed: { type: 'boolean', description: '[key, mouse_button, action] Whether the input is pressed (true) or released (false)' },
+                            key: {
+                                type: 'string',
+                                description: '[key] Key name (e.g. "W", "Space", "Escape", "Up")',
+                            },
+                            pressed: {
+                                type: 'boolean',
+                                description: '[key, mouse_button, action] Whether the input is pressed (true) or released (false)',
+                            },
                             shift: { type: 'boolean', description: '[key] Shift modifier' },
                             ctrl: { type: 'boolean', description: '[key] Ctrl modifier' },
                             alt: { type: 'boolean', description: '[key] Alt modifier' },
-                            button: { type: 'string', enum: ['left', 'right', 'middle'], description: '[mouse_button, click_element] Mouse button (default: left)' },
-                            x: { type: 'number', description: '[mouse_button, mouse_motion] X position in viewport pixels' },
-                            y: { type: 'number', description: '[mouse_button, mouse_motion] Y position in viewport pixels' },
-                            relative_x: { type: 'number', description: '[mouse_motion] Relative X movement in pixels' },
-                            relative_y: { type: 'number', description: '[mouse_motion] Relative Y movement in pixels' },
-                            double_click: { type: 'boolean', description: '[mouse_button, click_element] Double click' },
-                            element: { type: 'string', description: '[click_element] Identifies the UI element to click. Accepts: absolute node path (e.g. "/root/HUD/Button"), relative node path, or node name (BFS matched). Use get_ui_elements to discover valid names and paths.' },
-                            action: { type: 'string', description: '[action] Godot input action name (as defined in Project Settings > Input Map)' },
-                            strength: { type: 'number', description: '[action] Action strength (0–1, default 1.0)' },
-                            ms: { type: 'number', description: '[wait] Duration in milliseconds to pause before the next action' },
+                            button: {
+                                type: 'string',
+                                enum: ['left', 'right', 'middle'],
+                                description: '[mouse_button, click_element] Mouse button (default: left)',
+                            },
+                            x: {
+                                type: 'number',
+                                description: '[mouse_button, mouse_motion] X position in viewport pixels',
+                            },
+                            y: {
+                                type: 'number',
+                                description: '[mouse_button, mouse_motion] Y position in viewport pixels',
+                            },
+                            relative_x: {
+                                type: 'number',
+                                description: '[mouse_motion] Relative X movement in pixels',
+                            },
+                            relative_y: {
+                                type: 'number',
+                                description: '[mouse_motion] Relative Y movement in pixels',
+                            },
+                            double_click: {
+                                type: 'boolean',
+                                description: '[mouse_button, click_element] Double click',
+                            },
+                            element: {
+                                type: 'string',
+                                description: '[click_element] Identifies the UI element to click. Accepts: absolute node path (e.g. "/root/HUD/Button"), relative node path, or node name (BFS matched). Use get_ui_elements to discover valid names and paths.',
+                            },
+                            action: {
+                                type: 'string',
+                                description: '[action] Godot input action name (as defined in Project Settings > Input Map)',
+                            },
+                            strength: {
+                                type: 'number',
+                                description: '[action] Action strength (0–1, default 1.0)',
+                            },
+                            ms: {
+                                type: 'number',
+                                description: '[wait] Duration in milliseconds to pause before the next action',
+                            },
                         },
                         required: ['type'],
                     },
@@ -261,7 +303,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'get_ui_elements',
-        description: 'Get Control nodes from a running Godot project with their positions, sizes, types, and text. Requires run_project first; wait 2–3 seconds after starting. Call this before simulate_input with click_element to discover valid element names and paths. Returns: { elements: [{ name, path, type, rect: {x,y,width,height}, visible, text? (Button/Label/LineEdit/TextEdit), disabled? (buttons), tooltip? }] }',
+        description: 'Get Control nodes from a running Godot project with their positions, sizes, types, and text. Requires an active runtime session (run_project or attach_project). Call this before simulate_input with click_element to discover valid element names and paths. Returns: { elements: [{ name, path, type, rect: {x,y,width,height}, visible, text? (Button/Label/LineEdit/TextEdit), disabled? (buttons), tooltip? }] }',
         inputSchema: {
             type: 'object',
             properties: {
@@ -279,7 +321,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'run_script',
-        description: 'Execute a custom GDScript in the live running project with full scene tree access. Requires run_project first. Script must extend RefCounted and define func execute(scene_tree: SceneTree) -> Variant. Return values are JSON-serialized (primitives, Vector2/3, Color, Dictionary, Array, and Node path strings are supported). Use print() for debug output — it appears in get_debug_output, not in the script result.',
+        description: 'Execute a custom GDScript in the live running project with full scene tree access. Requires run_project first. Script must extend RefCounted and define func execute(scene_tree: SceneTree) -> Variant. Return values are JSON-serialized (primitives, Vector2/3, Color, Dictionary, Array, and Node path strings are supported). Use print() for debug output — it appears in get_debug_output, not in the script result. In spawned mode, runtime errors emitted to stderr are detected and either escalated (when the script returns null) or surfaced as warnings. In attached mode a null result includes a caveat since stderr is not captured.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -313,9 +355,18 @@ export const projectToolDefinitions = [
             type: 'object',
             properties: {
                 projectPath: { type: 'string', description: 'Path to the Godot project directory' },
-                autoloadName: { type: 'string', description: 'Name of the autoload node (e.g. "MyManager")' },
-                autoloadPath: { type: 'string', description: 'Path to the script or scene (e.g. "res://autoload/my_manager.gd" or "autoload/my_manager.gd")' },
-                singleton: { type: 'boolean', description: 'Register as a globally accessible singleton by name (default: true)' },
+                autoloadName: {
+                    type: 'string',
+                    description: 'Name of the autoload node (e.g. "MyManager")',
+                },
+                autoloadPath: {
+                    type: 'string',
+                    description: 'Path to the script or scene (e.g. "res://autoload/my_manager.gd" or "autoload/my_manager.gd")',
+                },
+                singleton: {
+                    type: 'boolean',
+                    description: 'Register as a globally accessible singleton by name (default: true)',
+                },
             },
             required: ['projectPath', 'autoloadName', 'autoloadPath'],
         },
@@ -334,7 +385,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'update_autoload',
-        description: 'Modify an existing autoload\'s path or singleton flag. No Godot process required.',
+        description: "Modify an existing autoload's path or singleton flag. No Godot process required.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -353,8 +404,15 @@ export const projectToolDefinitions = [
             type: 'object',
             properties: {
                 projectPath: { type: 'string', description: 'Path to the Godot project directory' },
-                maxDepth: { type: 'number', description: 'Maximum recursion depth. -1 means unlimited (default: -1)' },
-                extensions: { type: 'array', items: { type: 'string' }, description: 'Filter to only these file extensions (e.g. ["gd", "tscn"]). Omit to include all.' },
+                maxDepth: {
+                    type: 'number',
+                    description: 'Maximum recursion depth. -1 means unlimited (default: -1)',
+                },
+                extensions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Filter to only these file extensions (e.g. ["gd", "tscn"]). Omit to include all.',
+                },
             },
             required: ['projectPath'],
         },
@@ -367,7 +425,11 @@ export const projectToolDefinitions = [
             properties: {
                 projectPath: { type: 'string', description: 'Path to the Godot project directory' },
                 pattern: { type: 'string', description: 'Plain-text string to search for' },
-                fileTypes: { type: 'array', items: { type: 'string' }, description: 'File extensions to search (default: ["gd", "tscn", "cs", "gdshader"])' },
+                fileTypes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'File extensions to search (default: ["gd", "tscn", "cs", "gdshader"])',
+                },
                 caseSensitive: { type: 'boolean', description: 'Case-sensitive search (default: false)' },
                 maxResults: { type: 'number', description: 'Maximum matches to return (default: 100)' },
             },
@@ -381,7 +443,10 @@ export const projectToolDefinitions = [
             type: 'object',
             properties: {
                 projectPath: { type: 'string', description: 'Path to the Godot project directory' },
-                scenePath: { type: 'string', description: 'Path to the .tscn file relative to the project root (e.g. "scenes/main.tscn")' },
+                scenePath: {
+                    type: 'string',
+                    description: 'Path to the .tscn file relative to the project root (e.g. "scenes/main.tscn")',
+                },
             },
             required: ['projectPath', 'scenePath'],
         },
@@ -393,7 +458,10 @@ export const projectToolDefinitions = [
             type: 'object',
             properties: {
                 projectPath: { type: 'string', description: 'Path to the Godot project directory' },
-                section: { type: 'string', description: 'Filter to a specific INI section (e.g. "display", "application"). Omit for all sections.' },
+                section: {
+                    type: 'string',
+                    description: 'Filter to a specific INI section (e.g. "display", "application"). Omit for all sections.',
+                },
             },
             required: ['projectPath'],
         },
@@ -401,10 +469,17 @@ export const projectToolDefinitions = [
 ];
 function ensureRuntimeSession(runner, actionDescription) {
     if (!runner.activeSessionMode || !runner.activeProjectPath) {
-        return createErrorResponse(`No active runtime session. A project must be running or attached to ${actionDescription}.`, ['Use run_project to start a Godot project first', 'Or use attach_project before launching Godot manually']);
+        return createErrorResponse(`No active runtime session. A project must be running or attached to ${actionDescription}.`, [
+            'Use run_project to start a Godot project first',
+            'Or use attach_project before launching Godot manually',
+        ]);
     }
-    if (runner.activeSessionMode === 'spawned' && (!runner.activeProcess || runner.activeProcess.hasExited)) {
-        return createErrorResponse(`The spawned Godot process has exited and cannot ${actionDescription}.`, ['Use get_debug_output to inspect the last captured logs', 'Call stop_project to clean up, then run_project again']);
+    if (runner.activeSessionMode === 'spawned' &&
+        (!runner.activeProcess || runner.activeProcess.hasExited)) {
+        return createErrorResponse(`The spawned Godot process has exited and cannot ${actionDescription}.`, [
+            'Use get_debug_output to inspect the last captured logs',
+            'Call stop_project to clean up, then run_project again',
+        ]);
     }
     return null;
 }
@@ -481,21 +556,31 @@ function getProjectStructure(projectPath) {
 export async function handleLaunchEditor(runner, args) {
     args = normalizeParameters(args);
     if (!args.projectPath) {
-        return createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
+        return createErrorResponse('Project path is required', [
+            'Provide a valid path to a Godot project directory',
+        ]);
     }
     if (!validatePath(args.projectPath)) {
-        return createErrorResponse('Invalid project path', ['Provide a valid path without ".." or other potentially unsafe characters']);
+        return createErrorResponse('Invalid project path', [
+            'Provide a valid path without ".." or other potentially unsafe characters',
+        ]);
     }
     try {
         if (!runner.getGodotPath()) {
             await runner.detectGodotPath();
             if (!runner.getGodotPath()) {
-                return createErrorResponse('Could not find a valid Godot executable path', ['Ensure Godot is installed correctly', 'Set GODOT_PATH environment variable']);
+                return createErrorResponse('Could not find a valid Godot executable path', [
+                    'Ensure Godot is installed correctly',
+                    'Set GODOT_PATH environment variable',
+                ]);
             }
         }
         const projectFile = join(args.projectPath, 'project.godot');
         if (!existsSync(projectFile)) {
-            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, ['Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects']);
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, [
+                'Ensure the path points to a directory containing a project.godot file',
+                'Use list_projects to find valid Godot projects',
+            ]);
         }
         logDebug(`Launching Godot editor for project: ${args.projectPath}`);
         const process = runner.launchEditor(args.projectPath);
@@ -503,34 +588,75 @@ export async function handleLaunchEditor(runner, args) {
             console.error('Failed to start Godot editor:', err);
         });
         return {
-            content: [{ type: 'text', text: `Godot editor launched successfully for project at ${args.projectPath}.\nNote: the editor is a GUI application and cannot be controlled programmatically. Use the scene and node editing tools (add_node, set_node_property, etc.) to modify the project headlessly without the editor.` }],
+            content: [
+                {
+                    type: 'text',
+                    text: `Godot editor launched successfully for project at ${args.projectPath}.\nNote: the editor is a GUI application and cannot be controlled programmatically. Use the scene and node editing tools (add_node, set_node_property, etc.) to modify the project headlessly without the editor.`,
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to launch Godot editor: ${errorMessage}`, ['Ensure Godot is installed correctly', 'Check if the GODOT_PATH environment variable is set correctly']);
+        return createErrorResponse(`Failed to launch Godot editor: ${errorMessage}`, [
+            'Ensure Godot is installed correctly',
+            'Check if the GODOT_PATH environment variable is set correctly',
+        ]);
     }
 }
 export async function handleRunProject(runner, args) {
     args = normalizeParameters(args);
     if (!args.projectPath) {
-        return createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
+        return createErrorResponse('Project path is required', [
+            'Provide a valid path to a Godot project directory',
+        ]);
     }
     if (!validatePath(args.projectPath)) {
-        return createErrorResponse('Invalid project path', ['Provide a valid path without ".." or other potentially unsafe characters']);
+        return createErrorResponse('Invalid project path', [
+            'Provide a valid path without ".." or other potentially unsafe characters',
+        ]);
     }
     try {
         const projectFile = join(args.projectPath, 'project.godot');
         if (!existsSync(projectFile)) {
-            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, ['Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects']);
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, [
+                'Ensure the path points to a directory containing a project.godot file',
+                'Use list_projects to find valid Godot projects',
+            ]);
         }
         const background = args.background === true;
         runner.runProject(args.projectPath, args.scene, background);
+        const bridgeResult = await runner.waitForBridge();
+        if (!bridgeResult.ready) {
+            if (runner.activeProcess && runner.activeProcess.hasExited) {
+                return createErrorResponse(`Godot process exited before the MCP bridge could initialize.\n${bridgeResult.error || ''}`, [
+                    'Check get_debug_output for runtime errors',
+                    'Verify a display server is available (Wayland/X11)',
+                    'Check for broken autoloads with list_autoloads',
+                    'Call stop_project to clean up, then try again',
+                ]);
+            }
+            const lines = [
+                'Godot process started, but the MCP bridge did not respond within 8 seconds.',
+                '- The process is running — bridge may still be initializing',
+                '- Use get_debug_output to investigate',
+                '- Runtime tools may work if you retry after a moment',
+                '- Call stop_project when done',
+            ];
+            if (background) {
+                lines.push('- Background mode: window hidden, physical input blocked');
+            }
+            return createErrorResponse(lines.join('\n'), [
+                'Use get_debug_output to inspect the last captured logs',
+                'Check that UDP port 9900 is not occupied by another Godot process',
+                'Call stop_project to clean up, then run_project again',
+            ]);
+        }
         const lines = [
-            'Godot project started in debug mode.',
+            'Godot project started and MCP bridge is ready.',
+            '- Runtime tools (take_screenshot, simulate_input, get_ui_elements, run_script) are available now',
             '- Use get_debug_output to check runtime output and errors',
-            '- Wait 2–3 seconds before calling take_screenshot, simulate_input, get_ui_elements, or run_script (bridge needs time to initialize)',
-            '- Always call stop_project when done — it terminates the process and cleans up the MCP bridge',
+            '- Call stop_project when done',
         ];
         if (background) {
             lines.push('- Background mode: window hidden, physical input blocked');
@@ -541,64 +667,112 @@ export async function handleRunProject(runner, args) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to run Godot project: ${errorMessage}`, ['Ensure Godot is installed correctly', 'Check if the GODOT_PATH environment variable is set correctly']);
+        return createErrorResponse(`Failed to run Godot project: ${errorMessage}`, [
+            'Ensure Godot is installed correctly',
+            'Check if the GODOT_PATH environment variable is set correctly',
+        ]);
     }
 }
 export async function handleAttachProject(runner, args) {
     args = normalizeParameters(args);
     if (!args.projectPath) {
-        return createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
+        return createErrorResponse('Project path is required', [
+            'Provide a valid path to a Godot project directory',
+        ]);
     }
     if (!validatePath(args.projectPath)) {
-        return createErrorResponse('Invalid project path', ['Provide a valid path without ".." or other potentially unsafe characters']);
+        return createErrorResponse('Invalid project path', [
+            'Provide a valid path without ".." or other potentially unsafe characters',
+        ]);
     }
     try {
         const projectFile = join(args.projectPath, 'project.godot');
         if (!existsSync(projectFile)) {
-            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, ['Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects']);
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, [
+                'Ensure the path points to a directory containing a project.godot file',
+                'Use list_projects to find valid Godot projects',
+            ]);
         }
         runner.attachProject(args.projectPath);
+        if (args.waitForBridge === true) {
+            const bridgeResult = await runner.waitForBridgeAttached();
+            if (!bridgeResult.ready) {
+                return createErrorResponse(`Project attached but the MCP bridge is not ready.\n${bridgeResult.error || ''}`, [
+                    'Verify Godot is running with this project',
+                    'The McpBridge autoload must be initialized and listening on UDP port 9900',
+                    'Check that no other Godot project is occupying port 9900',
+                    'Use detach_project or stop_project when done',
+                ]);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: [
+                            'Project attached and MCP bridge is ready.',
+                            '- Runtime tools (take_screenshot, simulate_input, get_ui_elements, run_script) are available now',
+                            '- get_debug_output is unavailable in attached mode because MCP did not spawn the process',
+                            '- Use detach_project or stop_project when done to clean up the injected bridge state',
+                        ].join('\n'),
+                    },
+                ],
+            };
+        }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
                     text: [
                         'Project attached for manual runtime use.',
-                        '- Launch Godot yourself after this call so the injected McpBridge can initialize',
-                        '- Wait 2–3 seconds after launch before calling take_screenshot, simulate_input, get_ui_elements, or run_script',
+                        '- Launch Godot yourself, then call attach_project again with waitForBridge: true to confirm readiness',
+                        '- Or use runtime tools directly — they will fail with a clear error if the bridge is not yet listening',
                         '- get_debug_output is unavailable in attached mode because MCP did not spawn the process',
                         '- Use detach_project or stop_project when done to clean up the injected bridge state',
                     ].join('\n'),
-                }],
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to attach project: ${errorMessage}`, ['Check if project.godot is accessible', 'Ensure MCP can write the bridge autoload into the project']);
+        return createErrorResponse(`Failed to attach project: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+            'Ensure MCP can write the bridge autoload into the project',
+        ]);
     }
 }
 export function handleDetachProject(runner) {
     if (runner.activeSessionMode !== 'attached') {
-        return createErrorResponse('No attached project to detach.', ['Use attach_project first for manual-launch workflows', 'If MCP launched the game, use stop_project instead']);
+        return createErrorResponse('No attached project to detach.', [
+            'Use attach_project first for manual-launch workflows',
+            'If MCP launched the game, use stop_project instead',
+        ]);
     }
     const result = runner.stopProject();
     return {
-        content: [{
+        content: [
+            {
                 type: 'text',
                 text: JSON.stringify({
                     message: 'Detached attached project and cleaned MCP bridge state',
                     externalProcessPreserved: result.externalProcessPreserved === true,
                 }),
-            }],
+            },
+        ],
     };
 }
 export function handleGetDebugOutput(runner, args = {}) {
     args = normalizeParameters(args);
     if (!runner.activeSessionMode) {
-        return createErrorResponse('No active runtime session.', ['Use run_project to start a Godot project first', 'Or use attach_project before launching Godot manually']);
+        return createErrorResponse('No active runtime session.', [
+            'Use run_project to start a Godot project first',
+            'Or use attach_project before launching Godot manually',
+        ]);
     }
     if (runner.activeSessionMode === 'attached') {
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
                     text: JSON.stringify({
                         output: [],
@@ -607,12 +781,16 @@ export function handleGetDebugOutput(runner, args = {}) {
                         attached: true,
                         tip: 'Attached mode does not capture stdout/stderr because Godot was launched outside MCP.',
                     }),
-                }],
+                },
+            ],
         };
     }
     const proc = runner.activeProcess;
     if (!proc) {
-        return createErrorResponse('No active spawned process is available for debug output.', ['Use run_project to start a Godot project first', 'Or use attach_project only when stdout/stderr capture is not needed']);
+        return createErrorResponse('No active spawned process is available for debug output.', [
+            'Use run_project to start a Godot project first',
+            'Or use attach_project only when stdout/stderr capture is not needed',
+        ]);
     }
     const limit = typeof args.limit === 'number' ? args.limit : 200;
     const response = {
@@ -622,22 +800,29 @@ export function handleGetDebugOutput(runner, args = {}) {
     };
     if (proc.hasExited) {
         response.exitCode = proc.exitCode;
-        response.tip = 'Process has exited. Call stop_project to clean up the process slot before starting a new one.';
+        response.tip =
+            'Process has exited. Call stop_project to clean up the process slot before starting a new one.';
     }
     return {
-        content: [{
+        content: [
+            {
                 type: 'text',
                 text: JSON.stringify(response),
-            }],
+            },
+        ],
     };
 }
 export function handleStopProject(runner) {
     const result = runner.stopProject();
     if (!result) {
-        return createErrorResponse('No active Godot process to stop.', ['Use run_project to start a Godot project first', 'The process may have already terminated']);
+        return createErrorResponse('No active Godot process to stop.', [
+            'Use run_project to start a Godot project first',
+            'The process may have already terminated',
+        ]);
     }
     return {
-        content: [{
+        content: [
+            {
                 type: 'text',
                 text: JSON.stringify({
                     message: result.mode === 'attached'
@@ -648,20 +833,27 @@ export function handleStopProject(runner) {
                     finalOutput: result.output.slice(-200),
                     finalErrors: result.errors.slice(-200),
                 }),
-            }],
+            },
+        ],
     };
 }
 export async function handleListProjects(args) {
     args = normalizeParameters(args);
     if (!args.directory) {
-        return createErrorResponse('Directory is required', ['Provide a valid directory path to search for Godot projects']);
+        return createErrorResponse('Directory is required', [
+            'Provide a valid directory path to search for Godot projects',
+        ]);
     }
     if (!validatePath(args.directory)) {
-        return createErrorResponse('Invalid directory path', ['Provide a valid path without ".." or other potentially unsafe characters']);
+        return createErrorResponse('Invalid directory path', [
+            'Provide a valid path without ".." or other potentially unsafe characters',
+        ]);
     }
     try {
         if (!existsSync(args.directory)) {
-            return createErrorResponse(`Directory does not exist: ${args.directory}`, ['Provide a valid directory path that exists on the system']);
+            return createErrorResponse(`Directory does not exist: ${args.directory}`, [
+                'Provide a valid directory path that exists on the system',
+            ]);
         }
         const recursive = args.recursive === true;
         const projects = findGodotProjects(args.directory, recursive);
@@ -671,7 +863,10 @@ export async function handleListProjects(args) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to list projects: ${errorMessage}`, ['Ensure the directory exists and is accessible', 'Check if you have permission to read the directory']);
+        return createErrorResponse(`Failed to list projects: ${errorMessage}`, [
+            'Ensure the directory exists and is accessible',
+            'Check if you have permission to read the directory',
+        ]);
     }
 }
 export async function handleGetProjectInfo(runner, args) {
@@ -685,11 +880,16 @@ export async function handleGetProjectInfo(runner, args) {
             };
         }
         if (!validatePath(args.projectPath)) {
-            return createErrorResponse('Invalid project path', ['Provide a valid path without ".." or other potentially unsafe characters']);
+            return createErrorResponse('Invalid project path', [
+                'Provide a valid path without ".." or other potentially unsafe characters',
+            ]);
         }
         const projectFile = join(args.projectPath, 'project.godot');
         if (!existsSync(projectFile)) {
-            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, ['Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects']);
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, [
+                'Ensure the path points to a directory containing a project.godot file',
+                'Use list_projects to find valid Godot projects',
+            ]);
         }
         const projectStructure = getProjectStructure(args.projectPath);
         let projectName = basename(args.projectPath);
@@ -705,7 +905,8 @@ export async function handleGetProjectInfo(runner, args) {
             logDebug(`Error reading project file: ${error}`);
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
                     text: JSON.stringify({
                         name: projectName,
@@ -713,12 +914,16 @@ export async function handleGetProjectInfo(runner, args) {
                         godotVersion: version,
                         structure: projectStructure,
                     }),
-                }],
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to get project info: ${errorMessage}`, ['Ensure Godot is installed correctly', 'Check if the GODOT_PATH environment variable is set correctly']);
+        return createErrorResponse(`Failed to get project info: ${errorMessage}`, [
+            'Ensure Godot is installed correctly',
+            'Check if the GODOT_PATH environment variable is set correctly',
+        ]);
     }
 }
 export async function handleTakeScreenshot(runner, args) {
@@ -729,46 +934,64 @@ export async function handleTakeScreenshot(runner, args) {
     }
     const timeout = typeof args.timeout === 'number' ? args.timeout : 10000;
     try {
-        const responseStr = await runner.sendCommand('screenshot', {}, timeout);
+        const { response: responseStr, runtimeErrors } = await runner.sendCommandWithErrors('screenshot', {}, timeout);
         let parsed;
         try {
             parsed = JSON.parse(responseStr);
         }
         catch {
-            return createErrorResponse(`Invalid response from screenshot server: ${responseStr}`, ['The game may not have fully initialized yet', 'Try again after a few seconds']);
+            return createErrorResponse(`Invalid response from screenshot server: ${responseStr}`, [
+                'The game may not have fully initialized yet',
+                'Try again after a few seconds',
+            ]);
         }
         if (parsed.error) {
-            return createErrorResponse(`Screenshot server error: ${parsed.error}`, ['Ensure the game viewport is active', 'Try again after a moment']);
+            return createErrorResponse(`Screenshot server error: ${parsed.error}`, [
+                'Ensure the game viewport is active',
+                'Try again after a moment',
+            ]);
         }
         if (!parsed.path) {
-            return createErrorResponse('Screenshot server returned no file path', ['Try again after a few seconds']);
+            return createErrorResponse('Screenshot server returned no file path', [
+                'Try again after a few seconds',
+            ]);
         }
         // Normalize path for the local filesystem (forward slashes from GDScript)
         const screenshotPath = sep === '\\' ? parsed.path.replace(/\//g, '\\') : parsed.path;
         if (!existsSync(screenshotPath)) {
-            return createErrorResponse(`Screenshot file not found at: ${screenshotPath}`, ['The screenshot may have failed to save', 'Check disk space and permissions']);
+            return createErrorResponse(`Screenshot file not found at: ${screenshotPath}`, [
+                'The screenshot may have failed to save',
+                'Check disk space and permissions',
+            ]);
         }
         const imageBuffer = readFileSync(screenshotPath);
         const base64Data = imageBuffer.toString('base64');
-        return {
-            content: [
-                {
-                    type: 'image',
-                    data: base64Data,
-                    mimeType: 'image/png',
-                },
-                {
-                    type: 'text',
-                    text: `Screenshot saved to: ${parsed.path}`,
-                },
-            ],
-        };
+        const content = [
+            {
+                type: 'image',
+                data: base64Data,
+                mimeType: 'image/png',
+            },
+            {
+                type: 'text',
+                text: `Screenshot saved to: ${parsed.path}`,
+            },
+        ];
+        if (runtimeErrors.length > 0) {
+            content.push({
+                type: 'text',
+                text: JSON.stringify({
+                    warnings: runtimeErrors.slice(0, MAX_RUNTIME_ERROR_CONTEXT_LINES),
+                }),
+            });
+        }
+        return { content };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         return createErrorResponse(`Failed to take screenshot: ${errorMessage}`, [
             'Ensure the project is running (use run_project first)',
-            'Wait 2-3 seconds after starting for the screenshot server to initialize',
+            'The bridge may not be ready yet — use get_debug_output to investigate',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
@@ -781,44 +1004,61 @@ export async function handleSimulateInput(runner, args) {
     }
     const actions = args.actions;
     if (!Array.isArray(actions) || actions.length === 0) {
-        return createErrorResponse('actions must be a non-empty array of input actions', ['Provide at least one action object with a "type" field']);
+        return createErrorResponse('actions must be a non-empty array of input actions', [
+            'Provide at least one action object with a "type" field',
+        ]);
     }
     // Calculate timeout: sum of all wait durations + 10s buffer
     let totalWaitMs = 0;
     for (const action of actions) {
-        if (typeof action === 'object' && action !== null && action.type === 'wait' && typeof action.ms === 'number') {
+        if (typeof action === 'object' &&
+            action !== null &&
+            action.type === 'wait' &&
+            typeof action.ms === 'number') {
             totalWaitMs += action.ms;
         }
     }
     const timeoutMs = totalWaitMs + 10000;
     try {
-        const responseStr = await runner.sendCommand('input', { actions }, timeoutMs);
+        const { response: responseStr, runtimeErrors } = await runner.sendCommandWithErrors('input', { actions }, timeoutMs);
         let parsed;
         try {
             parsed = JSON.parse(responseStr);
         }
         catch {
-            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, ['The game may not have fully initialized yet', 'Try again after a few seconds']);
+            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, [
+                'The game may not have fully initialized yet',
+                'Try again after a few seconds',
+            ]);
         }
         if (parsed.error) {
-            return createErrorResponse(`Input simulation error: ${parsed.error}`, ['Check action types and parameters', 'Ensure key names are valid Godot key names']);
+            return createErrorResponse(`Input simulation error: ${parsed.error}`, [
+                'Check action types and parameters',
+                'Ensure key names are valid Godot key names',
+            ]);
+        }
+        const payload = {
+            success: true,
+            actions_processed: parsed.actions_processed,
+            tip: 'Call take_screenshot to verify the input had the intended visual effect.',
+        };
+        if (runtimeErrors.length > 0) {
+            payload.warnings = runtimeErrors.slice(0, MAX_RUNTIME_ERROR_CONTEXT_LINES);
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
-                    text: JSON.stringify({
-                        success: true,
-                        actions_processed: parsed.actions_processed,
-                        tip: 'Call take_screenshot to verify the input had the intended visual effect.',
-                    }),
-                }],
+                    text: JSON.stringify(payload),
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         return createErrorResponse(`Failed to simulate input: ${errorMessage}`, [
             'Ensure the project is running (use run_project first)',
-            'Wait 2-3 seconds after starting for the bridge to initialize',
+            'The bridge may not be ready yet — use get_debug_output to investigate',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
@@ -834,32 +1074,43 @@ export async function handleGetUiElements(runner, args) {
         const cmdParams = { visible_only: visibleOnly };
         if (args.filter)
             cmdParams.type_filter = args.filter;
-        const responseStr = await runner.sendCommand('get_ui_elements', cmdParams);
+        const { response: responseStr, runtimeErrors } = await runner.sendCommandWithErrors('get_ui_elements', cmdParams);
         let parsed;
         try {
             parsed = JSON.parse(responseStr);
         }
         catch {
-            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, ['The game may not have fully initialized yet', 'Try again after a few seconds']);
+            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, [
+                'The game may not have fully initialized yet',
+                'Try again after a few seconds',
+            ]);
         }
         if (parsed.error) {
-            return createErrorResponse(`UI element query error: ${parsed.error}`, ['Ensure the game has a UI with Control nodes']);
+            return createErrorResponse(`UI element query error: ${parsed.error}`, [
+                'Ensure the game has a UI with Control nodes',
+            ]);
+        }
+        const payload = {
+            ...parsed,
+            tip: "Use simulate_input with type 'click_element' and a node_path or text value from this list to interact with these elements.",
+        };
+        if (runtimeErrors.length > 0) {
+            payload.warnings = runtimeErrors.slice(0, MAX_RUNTIME_ERROR_CONTEXT_LINES);
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
-                    text: JSON.stringify({
-                        ...parsed,
-                        tip: "Use simulate_input with type 'click_element' and a node_path or text value from this list to interact with these elements.",
-                    }),
-                }],
+                    text: JSON.stringify(payload),
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         return createErrorResponse(`Failed to get UI elements: ${errorMessage}`, [
             'Ensure the project is running (use run_project first)',
-            'Wait 2-3 seconds after starting for the bridge to initialize',
+            'The bridge may not be ready yet — use get_debug_output to investigate',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
@@ -872,7 +1123,9 @@ export async function handleRunScript(runner, args) {
     }
     const script = args.script;
     if (typeof script !== 'string' || script.trim() === '') {
-        return createErrorResponse('script is required and must be a non-empty string', ['Provide GDScript source code with extends RefCounted and func execute(scene_tree: SceneTree) -> Variant']);
+        return createErrorResponse('script is required and must be a non-empty string', [
+            'Provide GDScript source code with extends RefCounted and func execute(scene_tree: SceneTree) -> Variant',
+        ]);
     }
     if (!script.includes('func execute')) {
         return createErrorResponse('Script must define func execute(scene_tree: SceneTree) -> Variant', ['Add a func execute(scene_tree: SceneTree) -> Variant method to your script']);
@@ -894,33 +1147,70 @@ export async function handleRunScript(runner, args) {
     }
     const timeout = typeof args.timeout === 'number' ? args.timeout : 30000;
     try {
-        const responseStr = await runner.sendCommand('run_script', { source: script }, timeout);
+        const { response: responseStr, runtimeErrors } = await runner.sendCommandWithErrors('run_script', { source: script }, timeout);
         let parsed;
         try {
             parsed = JSON.parse(responseStr);
         }
         catch {
-            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, ['The script may have produced non-JSON output', 'Check get_debug_output for print() statements']);
+            return createErrorResponse(`Invalid response from bridge: ${responseStr}`, [
+                'The script may have produced non-JSON output',
+                'Check get_debug_output for print() statements',
+            ]);
         }
         if (parsed.error) {
-            return createErrorResponse(`Script execution error: ${parsed.error}`, ['Check your GDScript syntax', 'Ensure the script extends RefCounted', 'Check get_debug_output for details']);
+            return createErrorResponse(`Script execution error: ${parsed.error}`, [
+                'Check your GDScript syntax',
+                'Ensure the script extends RefCounted',
+                'Check get_debug_output for details',
+            ]);
+        }
+        // Detect false-positive success: GDScript has no try-catch, so runtime errors
+        // return null and the real error only appears in stderr.
+        if (parsed.success && parsed.result === null && runner.activeSessionMode === 'spawned') {
+            if (runtimeErrors.length > 0) {
+                const errorContext = runtimeErrors.slice(0, MAX_RUNTIME_ERROR_CONTEXT_LINES).join('\n');
+                return createErrorResponse(`Script runtime error detected:\n${errorContext}`, [
+                    'Fix the GDScript error in your script and retry',
+                    'Use get_debug_output for full process output',
+                ]);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            result: null,
+                            warning: 'Script returned null. If unexpected, check get_debug_output for runtime errors — GDScript does not propagate exceptions.',
+                            tip: 'Call take_screenshot to verify any visual changes, or get_debug_output to review print() output from your script.',
+                        }),
+                    },
+                ],
+            };
+        }
+        const payload = {
+            success: true,
+            result: parsed.result,
+            tip: 'Call take_screenshot to verify any visual changes, or get_debug_output to review print() output from your script.',
+        };
+        if (runtimeErrors.length > 0) {
+            payload.warnings = runtimeErrors.slice(0, MAX_RUNTIME_ERROR_CONTEXT_LINES);
         }
         return {
-            content: [{
+            content: [
+                {
                     type: 'text',
-                    text: JSON.stringify({
-                        success: true,
-                        result: parsed.result,
-                        tip: 'Call take_screenshot to verify any visual changes, or get_debug_output to review print() output from your script.',
-                    }),
-                }],
+                    text: JSON.stringify(payload),
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         return createErrorResponse(`Failed to execute script: ${errorMessage}`, [
             'Ensure the project is running (use run_project first)',
-            'Wait 2-3 seconds after starting for the bridge to initialize',
+            'The bridge may not be ready yet — wait 2-3 seconds after starting, then check get_debug_output if the issue persists',
             'Check that UDP port 9900 is not blocked',
             'For long-running scripts, increase the timeout parameter',
         ]);
@@ -1061,7 +1351,9 @@ export async function handleListAutoloads(args) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to list autoloads: ${errorMessage}`, ['Check if project.godot is accessible']);
+        return createErrorResponse(`Failed to list autoloads: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+        ]);
     }
 }
 export async function handleAddAutoload(args) {
@@ -1070,7 +1362,9 @@ export async function handleAddAutoload(args) {
     if ('isError' in v)
         return v;
     if (!args.autoloadName || !args.autoloadPath) {
-        return createErrorResponse('autoloadName and autoloadPath are required', ['Provide the autoload node name and script/scene path']);
+        return createErrorResponse('autoloadName and autoloadPath are required', [
+            'Provide the autoload node name and script/scene path',
+        ]);
     }
     if (!validatePath(args.autoloadPath)) {
         return createErrorResponse('Invalid autoload path', ['Provide a valid path without ".."']);
@@ -1078,18 +1372,28 @@ export async function handleAddAutoload(args) {
     try {
         const projectFile = join(v.projectPath, 'project.godot');
         const existing = parseAutoloads(projectFile);
-        if (existing.some(a => a.name === args.autoloadName)) {
-            return createErrorResponse(`Autoload '${args.autoloadName}' already exists`, ['Use update_autoload to modify it', 'Use list_autoloads to see current autoloads']);
+        if (existing.some((a) => a.name === args.autoloadName)) {
+            return createErrorResponse(`Autoload '${args.autoloadName}' already exists`, [
+                'Use update_autoload to modify it',
+                'Use list_autoloads to see current autoloads',
+            ]);
         }
         const isSingleton = args.singleton !== false;
         addAutoloadEntry(projectFile, args.autoloadName, args.autoloadPath, isSingleton);
         return {
-            content: [{ type: 'text', text: `Autoload '${args.autoloadName}' registered at '${args.autoloadPath}' (singleton: ${isSingleton}).\nWarning: autoloads initialize in headless mode too. If this script has errors, all headless operations will fail. Verify by running get_scene_tree — if it fails, use remove_autoload to remove it.` }],
+            content: [
+                {
+                    type: 'text',
+                    text: `Autoload '${args.autoloadName}' registered at '${args.autoloadPath}' (singleton: ${isSingleton}).\nWarning: autoloads initialize in headless mode too. If this script has errors, all headless operations will fail. Verify by running get_scene_tree — if it fails, use remove_autoload to remove it.`,
+                },
+            ],
         };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to add autoload: ${errorMessage}`, ['Check if project.godot is accessible']);
+        return createErrorResponse(`Failed to add autoload: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+        ]);
     }
 }
 export async function handleRemoveAutoload(args) {
@@ -1098,19 +1402,27 @@ export async function handleRemoveAutoload(args) {
     if ('isError' in v)
         return v;
     if (!args.autoloadName) {
-        return createErrorResponse('autoloadName is required', ['Provide the name of the autoload to remove']);
+        return createErrorResponse('autoloadName is required', [
+            'Provide the name of the autoload to remove',
+        ]);
     }
     try {
         const projectFile = join(v.projectPath, 'project.godot');
         const removed = removeAutoloadEntry(projectFile, args.autoloadName);
         if (!removed) {
-            return createErrorResponse(`Autoload '${args.autoloadName}' not found`, ['Use list_autoloads to see existing autoloads']);
+            return createErrorResponse(`Autoload '${args.autoloadName}' not found`, [
+                'Use list_autoloads to see existing autoloads',
+            ]);
         }
-        return { content: [{ type: 'text', text: `Autoload '${args.autoloadName}' removed successfully.` }] };
+        return {
+            content: [{ type: 'text', text: `Autoload '${args.autoloadName}' removed successfully.` }],
+        };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to remove autoload: ${errorMessage}`, ['Check if project.godot is accessible']);
+        return createErrorResponse(`Failed to remove autoload: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+        ]);
     }
 }
 export async function handleUpdateAutoload(args) {
@@ -1119,7 +1431,9 @@ export async function handleUpdateAutoload(args) {
     if ('isError' in v)
         return v;
     if (!args.autoloadName) {
-        return createErrorResponse('autoloadName is required', ['Provide the name of the autoload to update']);
+        return createErrorResponse('autoloadName is required', [
+            'Provide the name of the autoload to update',
+        ]);
     }
     if (args.autoloadPath && !validatePath(args.autoloadPath)) {
         return createErrorResponse('Invalid autoload path', ['Provide a valid path without ".."']);
@@ -1128,13 +1442,20 @@ export async function handleUpdateAutoload(args) {
         const projectFile = join(v.projectPath, 'project.godot');
         const updated = updateAutoloadEntry(projectFile, args.autoloadName, args.autoloadPath, args.singleton);
         if (!updated) {
-            return createErrorResponse(`Autoload '${args.autoloadName}' not found`, ['Use list_autoloads to see existing autoloads', 'Use add_autoload to register a new one']);
+            return createErrorResponse(`Autoload '${args.autoloadName}' not found`, [
+                'Use list_autoloads to see existing autoloads',
+                'Use add_autoload to register a new one',
+            ]);
         }
-        return { content: [{ type: 'text', text: `Autoload '${args.autoloadName}' updated successfully.` }] };
+        return {
+            content: [{ type: 'text', text: `Autoload '${args.autoloadName}' updated successfully.` }],
+        };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to update autoload: ${errorMessage}`, ['Check if project.godot is accessible']);
+        return createErrorResponse(`Failed to update autoload: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+        ]);
     }
 }
 export async function handleGetProjectFiles(args) {
@@ -1145,14 +1466,16 @@ export async function handleGetProjectFiles(args) {
     try {
         const maxDepth = typeof args.maxDepth === 'number' ? args.maxDepth : -1;
         const extensions = Array.isArray(args.extensions)
-            ? args.extensions.map(e => e.toLowerCase().replace(/^\./, ''))
+            ? args.extensions.map((e) => e.toLowerCase().replace(/^\./, ''))
             : null;
         const tree = buildFilesystemTree(v.projectPath, '', maxDepth, 0, extensions);
         return { content: [{ type: 'text', text: JSON.stringify(tree) }] };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to get project files: ${errorMessage}`, ['Check if the project directory is accessible']);
+        return createErrorResponse(`Failed to get project files: ${errorMessage}`, [
+            'Check if the project directory is accessible',
+        ]);
     }
 }
 export async function handleSearchProject(args) {
@@ -1165,7 +1488,7 @@ export async function handleSearchProject(args) {
     }
     try {
         const fileTypes = Array.isArray(args.fileTypes)
-            ? args.fileTypes.map(e => e.toLowerCase().replace(/^\./, ''))
+            ? args.fileTypes.map((e) => e.toLowerCase().replace(/^\./, ''))
             : ['gd', 'tscn', 'cs', 'gdshader'];
         const caseSensitive = args.caseSensitive === true;
         const maxResults = typeof args.maxResults === 'number' ? args.maxResults : 100;
@@ -1174,7 +1497,9 @@ export async function handleSearchProject(args) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to search project: ${errorMessage}`, ['Check if the project directory is accessible']);
+        return createErrorResponse(`Failed to search project: ${errorMessage}`, [
+            'Check if the project directory is accessible',
+        ]);
     }
 }
 export async function handleGetSceneDependencies(args) {
@@ -1183,7 +1508,9 @@ export async function handleGetSceneDependencies(args) {
     if ('isError' in v)
         return v;
     if (!args.scenePath || typeof args.scenePath !== 'string') {
-        return createErrorResponse('scenePath is required', ['Provide a path relative to the project root, e.g. "scenes/main.tscn"']);
+        return createErrorResponse('scenePath is required', [
+            'Provide a path relative to the project root, e.g. "scenes/main.tscn"',
+        ]);
     }
     if (!validatePath(args.scenePath)) {
         return createErrorResponse('Invalid scenePath', ['Provide a valid path without ".."']);
@@ -1191,7 +1518,10 @@ export async function handleGetSceneDependencies(args) {
     try {
         const sceneFullPath = join(v.projectPath, args.scenePath);
         if (!existsSync(sceneFullPath)) {
-            return createErrorResponse(`Scene file not found: ${args.scenePath}`, ['Verify the path is relative to the project root', 'Use get_project_files to list available .tscn files']);
+            return createErrorResponse(`Scene file not found: ${args.scenePath}`, [
+                'Verify the path is relative to the project root',
+                'Use get_project_files to list available .tscn files',
+            ]);
         }
         const sceneContent = readFileSync(sceneFullPath, 'utf8');
         const dependencies = [];
@@ -1213,11 +1543,15 @@ export async function handleGetSceneDependencies(args) {
                 dependencies.push(dep);
             }
         }
-        return { content: [{ type: 'text', text: JSON.stringify({ scene: args.scenePath, dependencies }) }] };
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ scene: args.scenePath, dependencies }) }],
+        };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to get scene dependencies: ${errorMessage}`, ['Check if the scene file is accessible']);
+        return createErrorResponse(`Failed to get scene dependencies: ${errorMessage}`, [
+            'Check if the scene file is accessible',
+        ]);
     }
 }
 export async function handleGetProjectSettings(args) {
@@ -1236,7 +1570,9 @@ export async function handleGetProjectSettings(args) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        return createErrorResponse(`Failed to get project settings: ${errorMessage}`, ['Check if project.godot is accessible']);
+        return createErrorResponse(`Failed to get project settings: ${errorMessage}`, [
+            'Check if project.godot is accessible',
+        ]);
     }
 }
 //# sourceMappingURL=project-tools.js.map