godot-mcp-runtime 2.1.0 → 2.2.1

package/dist/tools/project-tools.d.ts

@@ -24,6 +24,30 @@ export declare function handleRunProject(runner: GodotRunner, args: OperationPar
         text: string;
     }[];
 }>;
+export declare function handleAttachProject(runner: GodotRunner, args: OperationParams): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;
+export declare function handleDetachProject(runner: GodotRunner): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: boolean;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+};
 export declare function handleGetDebugOutput(runner: GodotRunner, args?: OperationParams): {
     content: Array<{
         type: "text";
@@ -79,17 +103,10 @@ export declare function handleTakeScreenshot(runner: GodotRunner, args: Operatio
     }>;
     isError: boolean;
 } | {
-    content: ({
-        type: string;
-        data: string;
-        mimeType: string;
-        text?: undefined;
-    } | {
+    content: {
+        [key: string]: unknown;
         type: string;
-        text: string;
-        data?: undefined;
-        mimeType?: undefined;
-    })[];
+    }[];
 }>;
 export declare function handleSimulateInput(runner: GodotRunner, args: OperationParams): Promise<{
     content: Array<{

package/dist/tools/project-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../src/tools/project-tools.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAMX,eAAe,EACf,cAAc,EACf,MAAM,0BAA0B,CAAC;AAoGlC,eAAO,MAAM,sBAAsB,EAAE,cAAc,EA6RlD,CAAC;AAgFF,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAqDlF;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAiDhF;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,eAAoB;;;;;;;;;;;EAmCnF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;EAoBpD;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAsC7D;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GA4DpF;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;;;;;;;;GA4EpF;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAoEnF;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAsDnF;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAoF/E;AAyJD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAa9D;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA8B5D;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAoB/D;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA+B/D;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAgBhE;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAqB9D;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA4CrE;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAiBnE"}
+{"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../src/tools/project-tools.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAMX,eAAe,EACf,cAAc,EACf,MAAM,0BAA0B,CAAC;AAsGlC,eAAO,MAAM,sBAAsB,EAAE,cAAc,EAoTlD,CAAC;AAkGF,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAqDlF;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAiDhF;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GA+CnF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;EAmBtD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,eAAoB;;;;;;;;;;;EAyDnF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;EAwBpD;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAsC7D;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GA4DpF;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;cAkDpD,MAAM;;GAiCtC;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAuEnF;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAyDnF;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe;;;;;;;;;;;GAkH/E;AAyJD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAa9D;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA8B5D;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAoB/D;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA+B/D;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAgBhE;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAqB9D;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GA4CrE;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,eAAe;;;;;;;;;;;GAiBnE"}

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 = [];
@@ -107,7 +108,7 @@ export const projectToolDefinitions = [
     },
     {
         name: 'run_project',
-        description: 'Run a Godot project in debug mode. Required before calling take_screenshot, simulate_input, get_ui_elements, run_script, or get_debug_output. After starting, wait 2–3 seconds for the MCP bridge to initialize before using those 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. After starting, wait 2–3 seconds for the MCP bridge to initialize before using runtime tools. Call stop_project when done.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -127,9 +128,32 @@ export const projectToolDefinitions = [
             required: ['projectPath'],
         },
     },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: {
+                    type: 'string',
+                    description: 'Path to the Godot project directory',
+                },
+            },
+            required: ['projectPath'],
+        },
+    },
+    {
+        name: 'detach_project',
+        description: 'Clear attached-mode runtime state and remove the injected McpBridge autoload without claiming that the manually launched Godot process was stopped.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
     {
         name: 'get_debug_output',
-        description: 'Get stdout/stderr output from the running Godot project. Requires run_project first. Returns the last N lines of output and errors, a running flag, and an exit code if the process has ended. Use this to check GDScript errors, print() calls, and crash messages.',
+        description: 'Get stdout/stderr output from the running Godot project. Requires run_project first. Returns the last N lines of output and errors, a running flag, and an exit code if the process has ended. In attached mode, this reports that stdout/stderr capture is unavailable because Godot was launched outside MCP.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -256,7 +280,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: {
@@ -376,6 +400,15 @@ 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']);
+    }
+    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;
+}
 function findGodotProjects(directory, recursive) {
     const projects = [];
     try {
@@ -495,7 +528,7 @@ export async function handleRunProject(runner, args) {
         const background = args.background === true;
         runner.runProject(args.projectPath, args.scene, background);
         const lines = [
-            'Godot project started in debug mode.',
+            'Godot project started.',
             '- 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',
@@ -512,13 +545,77 @@ export async function handleRunProject(runner, args) {
         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']);
+    }
+    if (!validatePath(args.projectPath)) {
+        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']);
+        }
+        runner.attachProject(args.projectPath);
+        return {
+            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',
+                        '- 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']);
+    }
+}
+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']);
+    }
+    const result = runner.stopProject();
+    return {
+        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.activeProcess) {
-        return createErrorResponse('No active Godot process.', ['Use run_project to start a Godot project first', 'Check if the Godot process crashed unexpectedly']);
+    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']);
+    }
+    if (runner.activeSessionMode === 'attached') {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        output: [],
+                        errors: [],
+                        running: null,
+                        attached: true,
+                        tip: 'Attached mode does not capture stdout/stderr because Godot was launched outside MCP.',
+                    }),
+                }],
+        };
     }
-    const limit = typeof args.limit === 'number' ? args.limit : 200;
     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']);
+    }
+    const limit = typeof args.limit === 'number' ? args.limit : 200;
     const response = {
         output: proc.output.slice(-limit),
         errors: proc.errors.slice(-limit),
@@ -544,7 +641,11 @@ export function handleStopProject(runner) {
         content: [{
                 type: 'text',
                 text: JSON.stringify({
-                    message: 'Godot project stopped',
+                    message: result.mode === 'attached'
+                        ? 'Attached project detached and MCP bridge state cleaned up'
+                        : 'Godot project stopped',
+                    mode: result.mode,
+                    externalProcessPreserved: result.externalProcessPreserved === true,
                     finalOutput: result.output.slice(-200),
                     finalErrors: result.errors.slice(-200),
                 }),
@@ -623,12 +724,13 @@ export async function handleGetProjectInfo(runner, args) {
 }
 export async function handleTakeScreenshot(runner, args) {
     args = normalizeParameters(args);
-    if (!runner.activeProcess || runner.activeProcess.hasExited) {
-        return createErrorResponse('No active Godot process. A project must be running to take a screenshot.', ['Use run_project to start a Godot project first', 'Wait a few seconds after starting for the game to initialize']);
+    const sessionError = ensureRuntimeSession(runner, 'take a screenshot');
+    if (sessionError) {
+        return sessionError;
     }
     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);
@@ -649,33 +751,41 @@ export async function handleTakeScreenshot(runner, args) {
         }
         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 — wait 2-3 seconds after starting, then check get_debug_output if the issue persists',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
 }
 export async function handleSimulateInput(runner, args) {
     args = normalizeParameters(args);
-    if (!runner.activeProcess || runner.activeProcess.hasExited) {
-        return createErrorResponse('No active Godot process. A project must be running to simulate input.', ['Use run_project to start a Godot project first', 'Wait a few seconds after starting for the game to initialize']);
+    const sessionError = ensureRuntimeSession(runner, 'simulate input');
+    if (sessionError) {
+        return sessionError;
     }
     const actions = args.actions;
     if (!Array.isArray(actions) || actions.length === 0) {
@@ -690,7 +800,7 @@ export async function handleSimulateInput(runner, args) {
     }
     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);
@@ -701,14 +811,18 @@ export async function handleSimulateInput(runner, args) {
         if (parsed.error) {
             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: [{
                     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),
                 }],
         };
     }
@@ -716,22 +830,23 @@ export async function handleSimulateInput(runner, args) {
         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 — wait 2-3 seconds after starting, then check get_debug_output if the issue persists',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
 }
 export async function handleGetUiElements(runner, args) {
     args = normalizeParameters(args);
-    if (!runner.activeProcess || runner.activeProcess.hasExited) {
-        return createErrorResponse('No active Godot process. A project must be running to query UI elements.', ['Use run_project to start a Godot project first', 'Wait a few seconds after starting for the game to initialize']);
+    const sessionError = ensureRuntimeSession(runner, 'query UI elements');
+    if (sessionError) {
+        return sessionError;
     }
     const visibleOnly = args.visibleOnly !== false;
     try {
         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);
@@ -742,13 +857,17 @@ export async function handleGetUiElements(runner, args) {
         if (parsed.error) {
             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: [{
                     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),
                 }],
         };
     }
@@ -756,15 +875,16 @@ export async function handleGetUiElements(runner, args) {
         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 — wait 2-3 seconds after starting, then check get_debug_output if the issue persists',
             'Check that UDP port 9900 is not blocked',
         ]);
     }
 }
 export async function handleRunScript(runner, args) {
     args = normalizeParameters(args);
-    if (!runner.activeProcess || runner.activeProcess.hasExited) {
-        return createErrorResponse('No active Godot process. A project must be running to execute scripts.', ['Use run_project to start a Godot project first', 'Wait a few seconds after starting for the game to initialize']);
+    const sessionError = ensureRuntimeSession(runner, 'execute scripts');
+    if (sessionError) {
+        return sessionError;
     }
     const script = args.script;
     if (typeof script !== 'string' || script.trim() === '') {
@@ -790,7 +910,7 @@ 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);
@@ -801,14 +921,40 @@ export async function handleRunScript(runner, args) {
         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']);
         }
+        // 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: [{
                     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),
                 }],
         };
     }
@@ -816,7 +962,7 @@ export async function handleRunScript(runner, args) {
         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',
         ]);