#!/usr/bin/env node /** * Godot MCP Server * * This MCP server provides tools for interacting with the Godot game engine. * It enables AI assistants to launch the Godot editor, run Godot projects, * capture debug output, manipulate scenes and nodes, and more. */ export declare const allToolDefinitions: ({ readonly name: "list_autoloads"; readonly description: "List all registered autoloads in a project with paths and singleton status. Use first when diagnosing headless failures - broken autoloads crash all headless ops, so this tells you what is loaded. No Godot process required (reads project.godot directly). Returns: [{ name, path, singleton }]."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "add_autoload"; readonly description: "Register a new autoload in a project. autoloadPath accepts \"res://...\" or a project-relative path (auto-prefixed). singleton defaults true (accessible globally by name). No Godot process required. Warning: autoloads initialize in headless mode - a broken script will crash every subsequent headless op; validate before adding. Returns plain-text confirmation with the registered name, path, and singleton flag. Errors if an autoload with the same name already exists; use update_autoload to modify."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly autoloadName: { readonly type: "string"; readonly description: "Name of the autoload node (e.g. \"MyManager\")"; }; readonly autoloadPath: { readonly type: "string"; readonly description: "Path to the script or scene (e.g. \"res://autoload/my_manager.gd\" or \"autoload/my_manager.gd\")"; }; readonly singleton: { readonly type: "boolean"; readonly description: "Register as a globally accessible singleton by name (default: true)"; }; }; readonly required: readonly ["projectPath", "autoloadName", "autoloadPath"]; }; } | { readonly name: "remove_autoload"; readonly description: "Unregister an autoload from a project by name. Use to recover from a broken autoload that is crashing headless ops. No Godot process required. Returns plain-text confirmation on success. Errors if no autoload with that name exists."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly autoloadName: { readonly type: "string"; readonly description: "Name of the autoload to remove"; }; }; readonly required: readonly ["projectPath", "autoloadName"]; }; } | { readonly name: "update_autoload"; readonly description: "Modify an existing autoload's path or singleton flag. Pass either or both - omitted fields keep their current value. Use instead of remove_autoload + add_autoload (single edit, no orphan window). No Godot process required. Returns plain-text confirmation on success. Errors if autoloadName is not registered."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly autoloadName: { readonly type: "string"; readonly description: "Name of the autoload to update"; }; readonly autoloadPath: { readonly type: "string"; readonly description: "New path to the script or scene"; }; readonly singleton: { readonly type: "boolean"; readonly description: "New singleton flag"; }; }; readonly required: readonly ["projectPath", "autoloadName"]; }; } | { readonly name: "delete_nodes"; readonly description: "Remove one or more nodes (and their descendants) from a scene file. Always-array: pass a single-element nodePaths array for one-off deletes. Saves once at the end. Cannot delete the scene root - that entry returns an error and the rest still process. Returns: results array with one entry per nodePath in input order (success or error message). Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project (e.g. \"scenes/main.tscn\")"; }; readonly nodePaths: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "Node paths from scene root to delete (e.g. [\"root/Player/Sprite2D\"])"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePaths"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly results: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; }; readonly success: { readonly type: "boolean"; }; readonly error: { readonly type: "string"; }; }; }; }; }; }; } | { readonly name: "set_node_properties"; readonly description: "Set one or more node properties on a scene in one Godot process. Always-array: pass a single-element updates array for one-off edits. Values are checked against the property's declared type and error instead of silently storing that type's zero value. Object-typed properties (e.g. CollisionShape2D.shape) take a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null to clear; slash-suffixed keys like shader_parameter/ go inside that dict, not on the node. Value coercion, Packed*Array/Array[T] element rules and error details: Property Values in docs/tools.md. Saves once at the end. Returns: results[] with one entry per update in input order (success or error). Errors while a Godot runtime session is active; stop_project or detach_project clears it."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly updates: { readonly type: "array"; readonly description: "Property updates to apply"; readonly items: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root (e.g. \"root/Player\")"; }; readonly property: { readonly type: "string"; readonly description: "GDScript property name in snake_case (e.g. \"position\", \"modulate\", \"collision_layer\")"; }; readonly value: { readonly description: "New property value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through. Packed*Array and script-declared Array[T] properties take a plain array and the element conversions apply per element (e.g. [{\"x\":10,\"y\":20}, ...] for Polygon2D.polygon); an element that cannot represent the element type errors with its index instead of silently storing zeros."; }; }; readonly required: readonly ["nodePath", "property", "value"]; }; }; readonly abortOnError: { readonly type: "boolean"; readonly description: "Stop processing on first error (default: false)"; }; }; readonly required: readonly ["projectPath", "scenePath", "updates"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly results: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; }; readonly property: { readonly type: "string"; }; readonly success: { readonly type: "boolean"; }; readonly error: { readonly type: "string"; }; }; }; }; }; }; } | { readonly name: "get_node_properties"; readonly description: "Read one or more nodes' current property values from a scene file in a single Godot process. Always-array: pass a single-element nodes array for one-off reads. Per-node changedOnly:true filters out properties matching class defaults (useful for compact diffs). Returns: { results: [{ nodePath, nodeType, properties?, error? }] }; failed reads include error and omit properties."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodes: { readonly type: "array"; readonly description: "Nodes to read properties from"; readonly items: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root (e.g. \"root/Player\")"; }; readonly changedOnly: { readonly type: "boolean"; readonly description: "Only return properties differing from defaults (default: false)"; }; }; readonly required: readonly ["nodePath"]; }; }; }; readonly required: readonly ["projectPath", "scenePath", "nodes"]; }; } | { readonly name: "attach_script"; readonly description: "Attach a GDScript or C# script to a node in a scene. Use after writing and validating it via the validate tool. C# needs the Godot .NET build with the class compiled into the project assembly. Replaces any previous script. Saves automatically. Returns: success with nodePath and scriptPath. Errors if the script can't be instantiated (parse errors, @abstract, or an unbuilt C# class), scriptPath doesn't exist, or nodePath isn't found. Errors while a Godot runtime session is active; stop_project (or detach_project) clears it."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root (e.g. \"root/Player\")"; }; readonly scriptPath: { readonly type: "string"; readonly description: "Path to the script file relative to the project (e.g. \"scripts/player.gd\" or \"scripts/Player.cs\"). A .cs file needs the Godot .NET build and its class compiled into the project assembly (dotnet build)."; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath", "scriptPath"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly success: { readonly type: "boolean"; }; readonly nodePath: { readonly type: "string"; }; readonly scriptPath: { readonly type: "string"; }; }; }; } | { readonly name: "get_scene_tree"; readonly description: "Get the scene hierarchy as a nested tree of { name, type, path, script, children }. Use maxDepth:1 for a shallow listing of direct children only; default -1 returns the full tree. parentPath scopes the result to a subtree. Returns the nested tree as JSON text. Errors if scene does not exist or parentPath is not found."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly parentPath: { readonly type: "string"; readonly description: "Scope to a subtree starting at this node path (e.g. \"root/Player\")"; }; readonly maxDepth: { readonly type: "number"; readonly description: "Maximum recursion depth. -1 for unlimited (default: -1). 1 returns only direct children."; }; }; readonly required: readonly ["projectPath", "scenePath"]; }; } | { readonly name: "duplicate_node"; readonly description: "Duplicate a node and its descendants in a Godot scene, without rebuilding it node-by-node via add_node. newName defaults to the original name + \"2\"; targetParentPath defaults to the original parent. Saves automatically. Returns: success with originalPath and the newPath where the duplicate now lives. Errors if nodePath does not exist or targetParentPath cannot accept children. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root to duplicate"; }; readonly newName: { readonly type: "string"; readonly description: "Name for the duplicated node (default: original name + \"2\")"; }; readonly targetParentPath: { readonly type: "string"; readonly description: "Parent node path for the duplicate (default: same parent as original)"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly success: { readonly type: "boolean"; }; readonly originalPath: { readonly type: "string"; }; readonly newPath: { readonly type: "string"; }; }; }; } | { readonly name: "get_node_signals"; readonly description: "List all signals defined on a node and their current connections. Use before connect_signal/disconnect_signal to verify signal/method names. The connections[].target field is already scene-root-relative in the \"root/...\" form connect_signal/disconnect_signal accept as targetNodePath (a self-connection reports as \"root\") - pass it straight through with no conversion. Returns: nodeType and signals[], each with name and current connections (signal/target/method). Errors if node not found."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root (e.g. \"root/Button\")"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; }; readonly nodeType: { readonly type: "string"; }; readonly signals: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly connections: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly signal: { readonly type: "string"; }; readonly target: { readonly type: "string"; readonly description: "Scene-root-relative path in \"root/...\" form (a self-connection is \"root\"), directly usable as targetNodePath in connect_signal/disconnect_signal. \"unknown\" for a freed or null object."; }; readonly method: { readonly type: "string"; }; }; }; }; }; }; }; }; }; } | { readonly name: "connect_signal"; readonly description: "Connect a signal on a source node to a method on a target node, persisting it in the .tscn. Use get_node_signals first to confirm names - connecting the same pair twice creates a duplicate connection. Saves automatically. Returns a plain-text confirmation naming source, signal, target, and method. Errors if the signal or method does not exist. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Source node path from scene root"; }; readonly signal: { readonly type: "string"; readonly description: "Signal name on the source node (e.g. \"pressed\", \"body_entered\")"; }; readonly targetNodePath: { readonly type: "string"; readonly description: "Target node path from scene root that receives the signal"; }; readonly method: { readonly type: "string"; readonly description: "Method name on the target node to call when the signal fires"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath", "signal", "targetNodePath", "method"]; }; } | { readonly name: "disconnect_signal"; readonly description: "Remove an existing signal connection between two nodes, persisting the change in the .tscn. Use get_node_signals first to confirm the connection exists; recovery requires reconnecting via connect_signal. Saves automatically. Returns a plain-text confirmation naming the disconnected signal and target. Errors if the connection does not exist. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Source node path from scene root"; }; readonly signal: { readonly type: "string"; readonly description: "Signal name on the source node"; }; readonly targetNodePath: { readonly type: "string"; readonly description: "Target node path from scene root"; }; readonly method: { readonly type: "string"; readonly description: "Method name on the target node"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath", "signal", "targetNodePath", "method"]; }; } | { readonly name: "profile_project"; readonly description: "Capture a window of Godot's function profiler - the editor's Profiler tab numbers. Requires run_project with profiling: true. Blocks for `seconds` (default 5). Times are elapsed, not CPU; inclusive rows overlap - never sum totalMs. Returns: rows (function, file, line, calls, selfMs/totalMs, per-frame averages, percentOfFrame, peak), the frame budget, servers, worstFrame, plus frames/frameGaps/limitReached for capture quality. Errors if profiling was off at launch or a capture is already open."; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: false; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly seconds: { readonly type: "number"; readonly description: "Capture duration in seconds, greater than 0 and at most 60 (default: 5)."; }; readonly top: { readonly type: "number"; readonly description: "How many functions to return, 1..100 (default: 20)."; }; readonly sort: { readonly type: "string"; readonly enum: readonly import("./utils/profiler.js").ProfileSort[]; readonly description: "Rank by own time (\"selfMs\", default), inclusive time (\"totalMs\"), or invocation count (\"calls\")."; }; readonly captureLimit: { readonly type: "number"; readonly description: "Rows the engine puts in each frame packet, 16..512 (default: 512). Godot selects them by inclusive time, so a lower limit hides cheap functions and sets limitReached."; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly seconds: { readonly type: "number"; }; readonly frames: { readonly type: "number"; }; readonly framesReceived: { readonly type: "number"; }; readonly firstFrame: { readonly type: readonly ["number", "null"]; }; readonly lastFrame: { readonly type: readonly ["number", "null"]; }; readonly frameGaps: { readonly type: "number"; }; readonly undecodablePackets: { readonly type: "number"; }; readonly captureLimit: { readonly type: "number"; }; readonly limitReached: { readonly type: "boolean"; }; readonly sort: { readonly type: "string"; readonly enum: readonly import("./utils/profiler.js").ProfileSort[]; }; readonly functionsReceived: { readonly type: "number"; }; readonly unresolvedFunctions: { readonly type: "number"; }; readonly frame: { readonly type: "object"; readonly properties: { readonly frameMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly processMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly physicsMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly physicsFrameMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly scriptMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; }; }; readonly servers: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly msPerFrame: { readonly type: "number"; }; readonly functions: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly msPerFrame: { readonly type: "number"; }; }; }; }; }; }; }; readonly rows: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly signature: { readonly type: "string"; }; readonly function: { readonly type: "string"; }; readonly file: { readonly type: "string"; }; readonly line: { readonly type: "number"; }; readonly sourceResolved: { readonly type: "boolean"; }; readonly calls: { readonly type: "number"; }; readonly selfMs: { readonly type: "number"; }; readonly totalMs: { readonly type: "number"; }; readonly callsPerFrame: { readonly type: "number"; }; readonly selfMsPerFrame: { readonly type: "number"; }; readonly totalMsPerFrame: { readonly type: "number"; }; readonly msPerCall: { readonly type: "number"; }; readonly percentOfFrame: { readonly type: "number"; }; readonly peak: { readonly type: readonly ["object", "null"]; readonly properties: { readonly frame: { readonly type: "number"; }; readonly calls: { readonly type: "number"; }; readonly selfMs: { readonly type: "number"; }; readonly totalMs: { readonly type: "number"; }; }; }; }; }; }; readonly worstFrame: { readonly type: readonly ["object", "null"]; }; }; }; } | { readonly name: "start_profiler"; readonly description: "Start a profiler capture and return immediately, so simulate_input, run_script and screenshots can drive the game while it records. Requires run_project with profiling: true. Stops itself after `seconds` (default 30, max 60); call stop_profiler for the results. Returns: active, firstFrame, captureLimit, maxSeconds. Use profile_project instead for an unattended window. Errors if a capture is already running or profiling was not enabled at launch."; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: false; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly seconds: { readonly type: "number"; readonly description: "Maximum capture duration before the automatic stop, greater than 0 and at most 60 (default: 30)."; }; readonly captureLimit: { readonly type: "number"; readonly description: "Rows the engine puts in each frame packet, 16..512 (default: 512). Godot selects them by inclusive time, so a lower limit hides cheap functions and sets limitReached."; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly active: { readonly type: "boolean"; }; readonly maxSeconds: { readonly type: "number"; }; readonly firstFrame: { readonly type: readonly ["number", "null"]; }; readonly captureLimit: { readonly type: "number"; }; }; }; } | { readonly name: "stop_profiler"; readonly description: "Stop the capture started by start_profiler and rank the recorded functions; a capture that already hit its time limit is read back as-is, and can be re-read with a different sort. Times are elapsed, not CPU; inclusive rows overlap - never sum totalMs. Returns: the same payload as profile_project - rows (file, line, function, calls, selfMs/totalMs, per-frame averages, percentOfFrame, peak frame), frame budget, servers, worstFrame, frames, frameGaps, limitReached. Errors if no capture was started."; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: false; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly top: { readonly type: "number"; readonly description: "How many functions to return, 1..100 (default: 20)."; }; readonly sort: { readonly type: "string"; readonly enum: readonly import("./utils/profiler.js").ProfileSort[]; readonly description: "Rank by own time (\"selfMs\", default), inclusive time (\"totalMs\"), or invocation count (\"calls\")."; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly seconds: { readonly type: "number"; }; readonly frames: { readonly type: "number"; }; readonly framesReceived: { readonly type: "number"; }; readonly firstFrame: { readonly type: readonly ["number", "null"]; }; readonly lastFrame: { readonly type: readonly ["number", "null"]; }; readonly frameGaps: { readonly type: "number"; }; readonly undecodablePackets: { readonly type: "number"; }; readonly captureLimit: { readonly type: "number"; }; readonly limitReached: { readonly type: "boolean"; }; readonly sort: { readonly type: "string"; readonly enum: readonly import("./utils/profiler.js").ProfileSort[]; }; readonly functionsReceived: { readonly type: "number"; }; readonly unresolvedFunctions: { readonly type: "number"; }; readonly frame: { readonly type: "object"; readonly properties: { readonly frameMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly processMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly physicsMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly physicsFrameMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; readonly scriptMs: { readonly type: "object"; readonly properties: { readonly avg: { readonly type: "number"; }; readonly max: { readonly type: "number"; }; }; }; }; }; readonly servers: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly msPerFrame: { readonly type: "number"; }; readonly functions: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly msPerFrame: { readonly type: "number"; }; }; }; }; }; }; }; readonly rows: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly signature: { readonly type: "string"; }; readonly function: { readonly type: "string"; }; readonly file: { readonly type: "string"; }; readonly line: { readonly type: "number"; }; readonly sourceResolved: { readonly type: "boolean"; }; readonly calls: { readonly type: "number"; }; readonly selfMs: { readonly type: "number"; }; readonly totalMs: { readonly type: "number"; }; readonly callsPerFrame: { readonly type: "number"; }; readonly selfMsPerFrame: { readonly type: "number"; }; readonly totalMsPerFrame: { readonly type: "number"; }; readonly msPerCall: { readonly type: "number"; }; readonly percentOfFrame: { readonly type: "number"; }; readonly peak: { readonly type: readonly ["object", "null"]; readonly properties: { readonly frame: { readonly type: "number"; }; readonly calls: { readonly type: "number"; }; readonly selfMs: { readonly type: "number"; }; readonly totalMs: { readonly type: "number"; }; }; }; }; }; }; readonly worstFrame: { readonly type: readonly ["object", "null"]; }; }; }; } | { readonly name: "list_projects"; readonly description: "Find Godot projects under a directory by locating project.godot files. Use to discover available projects when the user has not specified one; for inspecting a known project, use check_project. recursive:true descends into subdirectories (skipping hidden ones); default false checks only the directory itself and its immediate children. Returns: [{ path, name }], empty array on no matches."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly directory: { readonly type: "string"; readonly description: "Directory to search for Godot projects"; }; readonly recursive: { readonly type: "boolean"; readonly description: "Whether to search recursively (default: false)"; }; }; readonly required: readonly ["directory"]; }; } | { readonly name: "check_project"; readonly description: "Get project metadata (name, path, Godot version, structure summary) plus an always-present runtime block reporting whether a runtime session is active, its bridge is responsive, and its process is alive. Omit projectPath for just the Godot version and runtime status. Use as the first call before driving a running project. Never errors on the runtime probe itself. Returns: { name?, path?, structure?, godotVersion, runtime }. Errors if projectPath is set but lacks project.godot."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory (optional - omit to get Godot version and runtime status only)"; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly path: { readonly type: "string"; }; readonly godotVersion: { readonly type: "string"; }; readonly structure: { readonly type: "object"; readonly properties: { readonly scenes: { readonly type: "number"; }; readonly scripts: { readonly type: "number"; }; readonly assets: { readonly type: "number"; }; readonly other: { readonly type: "number"; }; }; }; readonly runtime: { readonly type: "object"; readonly properties: { readonly activeSession: { readonly type: "boolean"; }; readonly sessionMode: { readonly type: "string"; readonly enum: readonly ["spawned", "attached"]; }; readonly projectPath: { readonly type: "string"; }; readonly processExited: { readonly type: "boolean"; }; readonly bridgeResponsive: { readonly type: "boolean"; }; readonly diagnostics: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; }; readonly required: readonly ["activeSession"]; }; }; readonly required: readonly ["godotVersion", "runtime"]; }; } | { readonly name: "get_project_files"; readonly description: "Return a recursive file tree of a Godot project. Use to discover project structure when paths are unknown. Pass extensions to filter (e.g. [\"gd\",\"tscn\"]); maxDepth caps recursion (-1 unlimited). Skips hidden (dot-prefixed) entries and the .mcp directory. Returns: { name, type, path, extension?, children? } (nested tree)."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly maxDepth: { readonly type: "number"; readonly description: "Maximum recursion depth. -1 means unlimited (default: -1)"; }; readonly extensions: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "Filter to only these file extensions (e.g. [\"gd\", \"tscn\"]). Omit to include all."; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "search_project"; readonly description: "Plain-text (substring) search across project files. Use to find references, callers, or signatures across the codebase. Default fileTypes is [\"gd\",\"tscn\",\"cs\",\"gdshader\"]; caseSensitive default false; maxResults default 100. Skips hidden entries and the .mcp directory. Returns: matches[] (project-relative file, 1-indexed lineNumber, line text) and truncated:true when maxResults was hit - consider raising it."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly pattern: { readonly type: "string"; readonly description: "Plain-text string to search for"; }; readonly fileTypes: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "File extensions to search (default: [\"gd\", \"tscn\", \"cs\", \"gdshader\"])"; }; readonly caseSensitive: { readonly type: "boolean"; readonly description: "Case-sensitive search (default: false)"; }; readonly maxResults: { readonly type: "number"; readonly description: "Maximum matches to return (default: 100)"; }; }; readonly required: readonly ["projectPath", "pattern"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly matches: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly file: { readonly type: "string"; }; readonly lineNumber: { readonly type: "number"; }; readonly line: { readonly type: "string"; }; }; }; }; readonly truncated: { readonly type: "boolean"; }; }; }; } | { readonly name: "get_scene_dependencies"; readonly description: "Parse a .tscn file for ext_resource references (scripts, textures, subscenes). Use to inspect what a scene depends on before refactoring or moving files. Returns: the queried scene path and dependencies[] from ext_resource refs (path, type, optional uid). Errors if scene file does not exist."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Path to the .tscn file relative to the project root (e.g. \"scenes/main.tscn\")"; }; }; readonly required: readonly ["projectPath", "scenePath"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly scene: { readonly type: "string"; }; readonly dependencies: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly path: { readonly type: "string"; }; readonly type: { readonly type: "string"; }; readonly uid: { readonly type: "string"; }; }; }; }; }; }; } | { readonly name: "get_project_settings"; readonly description: "Parse project.godot into structured JSON. Use to inspect configured display, input, rendering, etc. settings without launching Godot. Pass section to filter to one INI section (e.g. \"display\", \"application\"). Returns: { settings: { [section]: { [key]: value } } } or { settings: { [key]: value } } when section is given. Complex Godot types (including multi-line arrays/dicts, e.g. the full \"[input]\" action map) are returned as their complete raw string, not just the first line; keys outside any section appear under __global__."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly section: { readonly type: "string"; readonly description: "Filter to a specific INI section (e.g. \"display\", \"application\"). Omit for all sections."; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "launch_editor"; readonly description: "Open the Godot editor GUI for a project for the human user. Use only when the user explicitly asks to \"open the editor\"; for any agent-driven work, use the headless scene/node tools (add_node, set_node_properties, etc.) instead - the editor cannot be controlled programmatically. Returns plain-text confirmation after spawning the editor process. Errors if projectPath has no project.godot."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "run_project"; readonly description: "Spawn a Godot project as a child process with stdout/stderr captured. Required before take_screenshot, simulate_input, get_ui_elements, run_script, or get_debug_output. Set profiling: true at launch to enable the profiler tools. Use attach_project for one you launched yourself. Verifies MCP bridge readiness before returning success. Returns status with the assigned bridge port. Call stop_project when done. Errors if projectPath is not a Godot project or another session is already active."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scene: { readonly type: "string"; readonly description: "Scene to run (path relative to project, e.g. \"scenes/main.tscn\"). Omit to use the project's main scene."; }; readonly background: { readonly type: "boolean"; readonly description: "If true, hides the Godot window off-screen and blocks all physical keyboard and mouse input, while keeping programmatic input (simulate_input, run_script) and screenshots fully active. Useful for automated agent-driven testing where the window should not be visible or interactive."; }; readonly bridgePort: { readonly type: "number"; readonly minimum: 1; readonly maximum: 65535; readonly description: "TCP port for the MCP bridge. Omit to auto-select a free port (recommended). Delivered to the spawned process via an environment variable, so the bridge script on disk is unaffected by which port this session uses - safe for multiple sessions on the same project."; }; readonly profiling: { readonly type: "boolean"; readonly description: "Attach Godot's own remote debugger so profile_project, start_profiler and stop_profiler can measure this session. Must be set at launch - a session already running cannot be profiled - and costs a little runtime overhead."; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "attach_project"; readonly description: "Inject the MCP bridge into a Godot process you launch yourself, then wait up to 20s for the bridge to start listening and up to 45s total once it has, so a large project's cold start is absorbed; a port that listens but answers no ping gives up sooner. Call BEFORE Godot launches - Godot reads autoloads only at process start, so a late call returns \"bridge did not respond.\" Recommended pattern: kick off the Godot launch in parallel with this call so the wait absorbs startup. Prefer run_project unless MCP must not spawn Godot. Only one attach session is supported per project at a time (attach mode has no env-var channel, so port and token must be baked into the one shared script); a second attach_project on a project another session already attached to is refused, naming that session. Returns plain-text status with the resolved bridge port. Call detach_project or stop_project when done."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly bridgePort: { readonly type: "number"; readonly minimum: 1; readonly maximum: 65535; readonly description: "TCP port for the MCP bridge. Omit to auto-select a free port (recommended). The chosen port is baked into the project's `mcp_bridge.gd` at inject time, so the running Godot listens on exactly this port."; }; }; readonly required: readonly ["projectPath"]; }; } | { readonly name: "detach_project"; readonly description: "Clear attached-mode runtime state and remove the injected McpBridge autoload. Does NOT stop the manually launched Godot process - that stays running. Use after attach_project when you are done driving the game from MCP. For spawned sessions (run_project), use stop_project instead. Mostly optional now: when the bridge disconnects (you closed Godot), the next runtime tool call probes once and ends the attached session itself, removing the autoload. Calling it afterwards still succeeds idempotently, wording the message to distinguish \"an attached session existed and already ended\" from \"this server never attached to a project\". Returns: message confirming detach plus externalProcessPreserved (always true here - that is the point of detach vs stop_project). Errors only when a spawned session is what is active; use stop_project for those."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: {}; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly message: { readonly type: "string"; }; readonly externalProcessPreserved: { readonly type: "boolean"; }; }; }; } | { readonly name: "get_debug_output"; readonly description: "Get captured stdout/stderr from a spawned Godot project. Use whenever runtime tools fail unexpectedly - script errors, missing nodes, and crash backtraces all surface here. Still works after the process exits or crashes: the session clears itself on exit but the captured logs are retained until stop_project. Requires run_project (not attach_project; attached mode does not capture output). Returns: output/errors (last `limit` lines each, default 200), running (false after exit, null when attached), exitCode after exit, attached:true with empty arrays in attached mode."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly limit: { readonly type: "number"; readonly description: "Max lines to return (default: 200, from end of output)"; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly output: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly errors: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly running: { readonly type: readonly ["boolean", "null"]; }; readonly exitCode: { readonly type: readonly ["number", "null"]; }; readonly attached: { readonly type: "boolean"; }; readonly tip: { readonly type: "string"; }; }; }; } | { readonly name: "stop_project"; readonly description: "Stop the spawned Godot project and clean up bridge state. Call when done with runtime testing, even after a crash, and even if you closed the Godot window yourself: it frees the process slot and clears the flag blocking scene-editing tools. A process that exited on its own already removed the bridge autoload at that moment, and this still succeeds - it reports alreadyExited:true with the exit code and the logs captured before the exit, and leaves a finished profiler capture readable. Attached sessions detach without killing the external process. Returns: message, mode, externalProcessPreserved, alreadyExited, exitCode (already-exited case), and condensed finalOutput/finalErrors (capped at 200); get_debug_output has the full log. Errors only when there is no session and no exited process to report."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: {}; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly message: { readonly type: "string"; }; readonly mode: { readonly type: "string"; }; readonly externalProcessPreserved: { readonly type: "boolean"; }; readonly alreadyExited: { readonly type: "boolean"; }; readonly exitCode: { readonly type: readonly ["number", "null"]; }; readonly finalOutput: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly finalErrors: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; }; }; } | { readonly name: "take_screenshot"; readonly description: "Capture a PNG of the running viewport. responseMode: preview (default - saves full PNG, returns bounded inline preview at 960x540), full (full inline PNG; use for small text or pixel-level inspection), path_only (saved-path only, no inline image). Saved under .mcp/godot-runtime/screenshots/ (persists after stop_project). Returns: inline image block (full/preview modes), plus path and size of the saved PNG; previewPath/previewSize in preview mode; warnings for non-fatal runtime errors. Errors if no session or bridge times out (default 10000ms)."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly timeout: { readonly type: "number"; readonly description: "Timeout in milliseconds to wait for the screenshot (default: 10000)"; }; readonly responseMode: { readonly type: "string"; readonly enum: readonly ["full", "preview", "path_only"]; readonly description: "Response payload mode. \"preview\" returns a bounded inline preview plus paths (default). \"full\" returns the full inline PNG. \"path_only\" returns paths only."; }; readonly previewMaxWidth: { readonly type: "number"; readonly description: "Maximum preview width in pixels when responseMode is \"preview\" (default: 960)"; }; readonly previewMaxHeight: { readonly type: "number"; readonly description: "Maximum preview height in pixels when responseMode is \"preview\" (default: 540)"; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly responseMode: { readonly type: "string"; }; readonly path: { readonly type: "string"; }; readonly size: { readonly type: "object"; readonly properties: { readonly width: { readonly type: "number"; }; readonly height: { readonly type: "number"; }; }; }; readonly previewPath: { readonly type: "string"; }; readonly previewSize: { readonly type: "object"; readonly properties: { readonly width: { readonly type: "number"; }; readonly height: { readonly type: "number"; }; }; }; readonly warnings: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; }; }; } | { readonly name: "simulate_input"; readonly description: "Simulate sequential input in a running project and report what each action did. Action `type`: key, mouse_button, mouse_motion, click_element, action, text, wait. For key/mouse_button/action, omit `pressed` to tap (press+release); set it to hold or release. click_element resolves by node path/name (see get_ui_elements), not visible text. Returns: results[] per action with ok, timing, signals fired, the Control hit, UI `changes` (appeared/disappeared/changed), `watch` samples, and `errors` from input handlers (spawned sessions only). Invalid batches inject nothing; a runtime failure stops the batch and skips the rest."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly actions: { readonly type: "array"; readonly description: "Array of input actions to execute sequentially. Each object must have a \"type\" field."; readonly items: { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["key", "mouse_button", "mouse_motion", "click_element", "action", "text", "wait"]; readonly description: "The type of input action"; }; readonly key: { readonly type: "string"; readonly description: "[key] Godot KEY_* constant name without the prefix (e.g. \"W\", \"Space\", \"Escape\", \"Enter\", \"Tab\", \"Up\", \"PageUp\"). Errors on unrecognized names."; }; readonly pressed: { readonly type: "boolean"; readonly description: "[key, mouse_button, action] Omit to tap: the action presses, holds briefly, and releases by itself. Set true to press and hold across later actions (reported in still_held), false to release an earlier hold. Cannot be combined with hold_ms."; }; readonly hold_ms: { readonly type: "number"; readonly description: "[key, mouse_button, action] Tap hold duration in milliseconds, overriding the default (one process frame plus one physics frame for key/action, zero gap for mouse_button). Use it for code polling is_action_pressed over real time. Rejected when pressed is also set. Max 10000."; }; readonly shift: { readonly type: "boolean"; readonly description: "[key] Shift modifier"; }; readonly ctrl: { readonly type: "boolean"; readonly description: "[key] Ctrl modifier"; }; readonly alt: { readonly type: "boolean"; readonly description: "[key] Alt modifier"; }; readonly unicode: { readonly type: "number"; readonly description: "[key] Unicode codepoint for text-entry Controls (LineEdit, TextEdit). Auto-derived for ASCII letters/digits (respecting shift); pass explicitly for symbols or non-ASCII. E.g. 33 for \"!\", 64 for \"@\"."; }; readonly button: { readonly type: "string"; readonly enum: readonly ["left", "right", "middle"]; readonly description: "[mouse_button, click_element] Mouse button (default: left)"; }; readonly x: { readonly type: "number"; readonly description: "[mouse_button, mouse_motion] X position in viewport pixels (0,0 = top-left)"; }; readonly y: { readonly type: "number"; readonly description: "[mouse_button, mouse_motion] Y position in viewport pixels (0,0 = top-left)"; }; readonly relative_x: { readonly type: "number"; readonly description: "[mouse_motion] Relative X movement in pixels"; }; readonly relative_y: { readonly type: "number"; readonly description: "[mouse_motion] Relative Y movement in pixels"; }; readonly double_click: { readonly type: "boolean"; readonly description: "[mouse_button, click_element] Double click"; }; readonly element: { readonly type: "string"; readonly 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."; }; readonly action: { readonly type: "string"; readonly description: "[action] Godot input action name (as defined in Project Settings > Input Map)"; }; readonly strength: { readonly type: "number"; readonly description: "[action] Action strength (0 to 1, default 1.0)"; }; readonly text: { readonly type: "string"; readonly description: "[text] String to type into whatever Control currently holds focus, expanded to one key press+release per character. Fails when nothing holds focus - click or focus the LineEdit first. Max 1000 characters."; }; readonly ms: { readonly type: "number"; readonly description: "[wait] Real-time pause in milliseconds, for time-driven things such as cooldowns and animations (~16ms = one frame at 60fps). Exactly one of ms or frames is required. Uncapped, but a batch whose total wait approaches 60s may be cut off by your client before the server answers: split it across calls."; }; readonly frames: { readonly type: "number"; readonly description: "[wait] Deterministic pause of N engine process frames, for stepping game logic rather than waiting on the clock. Exactly one of ms or frames is required. Max 600, budgeted at a 10fps floor, so a wait of several hundred frames may be cut off by your client before the server answers."; }; }; readonly required: readonly ["type"]; }; }; readonly watch: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly maxItems: 16; readonly description: "Godot NodePath:property strings sampled after every action and reported per result, e.g. \"/root/Main/Player:position\". Property subnames are allowed (\"/root/Main/Player:position:x\"). Read-only; an unresolvable path samples as null instead of failing the batch."; }; }; readonly required: readonly ["actions"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly success: { readonly type: "boolean"; readonly description: "False when an action failed and the remaining actions were skipped."; }; readonly results: { readonly type: "array"; readonly description: "One entry per requested action, in order."; readonly items: { readonly type: "object"; readonly properties: { readonly index: { readonly type: "number"; }; readonly type: { readonly type: "string"; }; readonly ok: { readonly type: "boolean"; }; readonly skipped: { readonly type: "boolean"; readonly description: "Present when an earlier failure ended the batch before this action."; }; readonly frame: { readonly type: "number"; readonly description: "Process frames elapsed since batch start."; }; readonly elapsed_ms: { readonly type: "number"; readonly description: "Milliseconds since batch start."; }; readonly error: { readonly type: "string"; }; readonly hit: { readonly type: "string"; readonly description: "Path of the Control under the pointer after the action settled."; }; readonly focus: { readonly type: "string"; readonly description: "Path of the focus owner after the action."; }; readonly value: { readonly type: "string"; readonly description: "Resulting text of the focused text Control."; }; readonly position: { readonly type: "object"; readonly properties: { readonly x: { readonly type: "number"; }; readonly y: { readonly type: "number"; }; }; }; readonly pressed: { readonly type: "boolean"; readonly description: "Whether the input action is still held after this entry."; }; readonly signals: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "Which of pressed, toggled, item_selected, text_submitted the target emitted within the settle frame. A signal emitted later (call_deferred, a tween, a timer) is not observed, so an absent entry means \"not within one frame\", not \"never\"."; }; readonly errors: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly changes: { readonly type: "object"; readonly properties: { readonly appeared: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly disappeared: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly changed: { readonly type: "array"; readonly items: { readonly type: "object"; }; }; readonly scene: { readonly type: "string"; }; readonly focus: { readonly type: "string"; }; readonly truncated: { readonly type: "number"; }; }; }; readonly watch: { readonly type: "object"; readonly additionalProperties: true; }; }; readonly required: readonly ["index", "type"]; }; }; readonly still_held: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "Inputs this batch pressed and did not release, e.g. \"key:W\", \"action:jump\"."; }; }; }; } | { readonly name: "get_ui_elements"; readonly description: "Walk the running scene tree and return all Control nodes with positions, sizes, types, and text content. Always call this before simulate_input click_element actions to discover valid element names and paths. Requires an active runtime session (run_project or attach_project). visibleOnly defaults true; pass false to include hidden Controls. filter narrows by class. Returns: elements[] with path/type/rect/visible plus optional text/disabled/tooltip."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly visibleOnly: { readonly type: "boolean"; readonly description: "Only return nodes where Control.visible is true (default: true). Set false to include hidden elements."; }; readonly filter: { readonly type: "string"; readonly description: "Filter by Control node type (e.g. \"Button\", \"Label\", \"LineEdit\")"; }; }; readonly required: readonly []; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly elements: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly name: { readonly type: "string"; }; readonly path: { readonly type: "string"; }; readonly type: { readonly type: "string"; }; readonly rect: { readonly type: "object"; readonly properties: { readonly x: { readonly type: "number"; }; readonly y: { readonly type: "number"; }; readonly width: { readonly type: "number"; }; readonly height: { readonly type: "number"; }; }; }; readonly visible: { readonly type: "boolean"; }; readonly text: { readonly type: "string"; }; readonly placeholder: { readonly type: "string"; }; readonly disabled: { readonly type: "boolean"; }; readonly tooltip: { readonly type: "string"; }; }; }; }; readonly warnings: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly tip: { readonly type: "string"; }; }; }; } | { readonly name: "run_script"; readonly description: "Execute a custom GDScript in the live running project with full scene tree access. Requires an active runtime session. 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). Use print() for debug output - it appears in get_debug_output, not in the result. In spawned mode, stderr runtime errors escalate to errors (when the script returns null) or surface as warnings. Returns: { success, result, warnings?, tip? } where result is the JSON-serialized return value of execute()."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly script: { readonly type: "string"; readonly description: "GDScript source code. Must contain \"extends RefCounted\" and \"func execute(scene_tree: SceneTree) -> Variant\"."; }; readonly timeout: { readonly type: "number"; readonly description: "Timeout in ms (default: 30000). Increase for long-running scripts."; }; }; readonly required: readonly ["script"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly success: { readonly type: "boolean"; }; readonly result: {}; readonly warnings: { readonly type: "array"; readonly items: { readonly type: "string"; }; }; readonly tip: { readonly type: "string"; }; }; }; } | { readonly name: "create_scene"; readonly description: "Create a new Godot scene file with a single root node. Writes a fresh .tscn at scenePath. Use when starting a new scene from scratch; for adding nodes to an existing scene, use add_node. rootNodeType defaults to Node2D - pass \"Node3D\" for 3D scenes or \"Control\" for UI. Saves automatically. Overwrites silently if the file already exists. Returns: success and the scenePath that was written. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project (e.g. \"scenes/main.tscn\")"; }; readonly rootNodeType: { readonly type: "string"; readonly description: "Root node type (default: Node2D)"; }; }; readonly required: readonly ["projectPath", "scenePath"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly success: { readonly type: "boolean"; }; readonly scenePath: { readonly type: "string"; }; }; }; } | { readonly name: "add_node"; readonly description: "Add a node to a Godot scene. Saves automatically. position, rotation, scale, visible, modulate are top-level params; anything else goes in properties. Values are checked against the property's declared type and error instead of silently storing that type's zero value. Object-typed properties take a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null; slash-suffixed keys like shader_parameter/ go inside that dict, not on the node. Value coercion, Packed*Array/Array[T] element rules and error details: Property Values in docs/tools.md. Returns plain-text confirmation of the new node and type. Errors and adds nothing if nodeType is not a registered class, the parent is missing, or a property name or value is invalid. Errors while a Godot runtime session is active; stop_project or detach_project clears it."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodeType: { readonly type: "string"; readonly description: "Godot node class to instantiate (e.g. \"Sprite2D\", \"CollisionShape2D\", \"Label\"), or a project-relative scene path (.tscn or .scn, e.g. \"scenes/enemy.tscn\") to instance an existing scene as a child - instanced children serialize as `instance=ExtResource(...)` on save"; }; readonly nodeName: { readonly type: "string"; readonly description: "Name for the new node as it appears in the scene tree"; }; readonly parentNodePath: { readonly type: "string"; readonly description: "Parent node path from scene root (e.g. \"root/Player\"). Defaults to the root node."; }; readonly position: { readonly type: "object"; readonly description: "Position: {\"x\": 100, \"y\": 200} on a 2D node, {\"x\": 0, \"y\": 1, \"z\": 0} on a 3D node"; readonly properties: { readonly x: { readonly type: "number"; }; readonly y: { readonly type: "number"; }; readonly z: { readonly type: "number"; }; }; }; readonly rotation: { readonly type: "number"; readonly description: "Rotation in radians"; }; readonly scale: { readonly type: "object"; readonly description: "Vector2 scale (e.g. {\"x\": 2, \"y\": 2})"; readonly properties: { readonly x: { readonly type: "number"; }; readonly y: { readonly type: "number"; }; }; }; readonly visible: { readonly type: "boolean"; readonly description: "Whether the node is visible"; }; readonly modulate: { readonly type: "object"; readonly description: "Color modulation (e.g. {\"r\": 1, \"g\": 0, \"b\": 0, \"a\": 1})"; readonly properties: { readonly r: { readonly type: "number"; }; readonly g: { readonly type: "number"; }; readonly b: { readonly type: "number"; }; readonly a: { readonly type: "number"; }; }; }; readonly properties: { readonly type: "object"; readonly description: "Additional property values as a JSON object. Top-level params (position, rotation, etc.) take precedence over keys in this dict."; }; }; readonly required: readonly ["projectPath", "scenePath", "nodeType", "nodeName"]; }; } | { readonly name: "load_sprite"; readonly description: "Set the texture on an existing Sprite2D, Sprite3D, or TextureRect node. For new nodes, pass texture via add_node properties instead. Saves automatically. texturePath must be a real file under projectPath. Returns a plain-text confirmation message naming the loaded texture. Errors if the node is not one of those three classes, or the texture file does not exist. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly nodePath: { readonly type: "string"; readonly description: "Path to the target node from scene root (e.g. \"root/Player/Sprite2D\")"; }; readonly texturePath: { readonly type: "string"; readonly description: "Path to the texture file relative to the project (e.g. \"assets/player.png\")"; }; }; readonly required: readonly ["projectPath", "scenePath", "nodePath", "texturePath"]; }; } | { readonly name: "save_scene"; readonly description: "Re-pack and save a scene, optionally to a different path (save-as). Most mutations (add_node, set_node_properties, delete_nodes, etc.) auto-save - only use this for save-as via newPath, or to re-canonicalize a hand-edited .tscn. Overwrites silently. Returns a plain-text confirmation naming the save path. Errors if the scene file does not exist. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly idempotentHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly newPath: { readonly type: "string"; readonly description: "Save to a different path (relative to project) instead of overwriting the original"; }; }; readonly required: readonly ["projectPath", "scenePath"]; }; } | { readonly name: "export_mesh_library"; readonly description: "Export a scene of MeshInstance3D nodes as a MeshLibrary .res file for use in GridMap. For grid-based 3D tile palettes only, not 2D scenes. Source scene must contain MeshInstance3D children. Pass meshItemNames for a subset, or omit for all. Saves to outputPath, overwriting silently. Returns a plain-text confirmation with the exported item count. Errors if the scene contains no valid meshes. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path relative to the project"; }; readonly outputPath: { readonly type: "string"; readonly description: "Output path for the MeshLibrary .res file (relative to project)"; }; readonly meshItemNames: { readonly type: "array"; readonly items: { readonly type: "string"; }; readonly description: "Names of specific mesh items to export. Omit to export all."; }; }; readonly required: readonly ["projectPath", "scenePath", "outputPath"]; }; } | { readonly name: "batch_scene_operations"; readonly description: "Use this instead of chaining add_node / load_sprite / save_scene calls when you have multiple mutations on the same or related scenes - runs in one Godot process (~3s startup avoided per call) and shares an in-memory scene cache, saving once at the end. Each item picks its own sub-operation (add_node, load_sprite, set_node_properties, save) and supplies its own params; add_node items accept the same promoted spatial params (position, rotation, scale, visible, modulate) as the standalone tool; set_node_properties items accept the same per-update params (nodePath, property, value) and per-operation scenePath and abortOnError as the standalone tool; abortOnError stops on first failure (default false continues). Returns: results[] in input order, each tagged with operation and scenePath plus success or error. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it."; readonly annotations: { readonly destructiveHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly operations: { readonly type: "array"; readonly description: "Ordered list of scene operations. Each item has its own operation and scenePath."; readonly items: { readonly type: "object"; readonly properties: { readonly operation: { readonly type: "string"; readonly enum: readonly ["add_node", "load_sprite", "set_node_properties", "save"]; readonly description: "The sub-operation to perform"; }; readonly scenePath: { readonly type: "string"; readonly description: "Scene file path for this operation"; }; readonly nodeType: { readonly type: "string"; readonly description: "[add_node] Node class to instantiate"; }; readonly nodeName: { readonly type: "string"; readonly description: "[add_node] Name for the new node"; }; readonly parentNodePath: { readonly type: "string"; readonly description: "[add_node] Parent node path (defaults to root)"; }; readonly properties: { readonly type: "object"; readonly description: "[add_node] Initial property values"; }; readonly updates: { readonly type: "array"; readonly description: "[set_node_properties] Property updates to apply in this operation"; readonly items: { readonly type: "object"; readonly properties: { readonly nodePath: { readonly type: "string"; readonly description: "Node path from scene root"; }; readonly property: { readonly type: "string"; readonly description: "Property name in snake_case"; }; readonly value: { readonly description: "New value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through. For Packed*Array properties, a plain array applies the same conversions element-wise (e.g. [{\"x\":10,\"y\":20}, ...] for Polygon2D.polygon); an element that cannot represent the packed element type errors instead of silently storing zeros."; }; }; readonly required: readonly ["nodePath", "property", "value"]; }; }; readonly abortOnError: { readonly type: "boolean"; readonly description: "[set_node_properties] Stop processing on first error"; }; readonly position: { readonly type: "object"; readonly description: "[add_node] Position - {\"x\",\"y\"} for 2D nodes, {\"x\",\"y\",\"z\"} for 3D. Shorthand for properties.position"; }; readonly rotation: { readonly type: "number"; readonly description: "[add_node] Rotation in radians - shorthand for properties.rotation"; }; readonly scale: { readonly type: "object"; readonly description: "[add_node] Vector2 scale - shorthand for properties.scale"; }; readonly visible: { readonly type: "boolean"; readonly description: "[add_node] Visibility - shorthand for properties.visible"; }; readonly modulate: { readonly type: "object"; readonly description: "[add_node] Color modulation - shorthand for properties.modulate"; }; readonly nodePath: { readonly type: "string"; readonly description: "[load_sprite] Target node path"; }; readonly texturePath: { readonly type: "string"; readonly description: "[load_sprite] Texture file path relative to project"; }; readonly newPath: { readonly type: "string"; readonly description: "[save] Save to a different path instead of overwriting"; }; }; readonly required: readonly ["operation"]; }; }; readonly abortOnError: { readonly type: "boolean"; readonly description: "Stop processing on first error (default: false)"; }; }; readonly required: readonly ["projectPath", "operations"]; }; readonly outputSchema: { readonly type: "object"; readonly properties: { readonly results: { readonly type: "array"; readonly items: { readonly type: "object"; readonly properties: { readonly operation: { readonly type: "string"; }; readonly scenePath: { readonly type: "string"; }; readonly success: { readonly type: "boolean"; }; readonly error: { readonly type: "string"; }; }; }; }; }; }; } | { readonly name: "validate"; readonly description: "Validate GDScript syntax or scene integrity using headless Godot. Use before attach_script or run_script to catch parse errors early. Give exactly one of scriptPath, source, or scenePath, or a targets array validated in one Godot process. Returns { valid, errors } for one target, { results: [{ target, valid, errors }] } for a batch. An errors entry is { line?, message } for a parse error, or { check, problem?, message } for a checks[] finding. checks requires scenePath and instantiates the scene, running each attached script's _init(). Any parse error yields valid:false."; readonly annotations: { readonly readOnlyHint: true; }; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly projectPath: { readonly type: "string"; readonly description: "Path to the Godot project directory"; }; readonly scriptPath: { readonly type: "string"; readonly description: "[single] Path to a .gd file relative to the project to validate (e.g. \"scripts/player.gd\")"; }; readonly source: { readonly type: "string"; readonly description: "[single] Inline GDScript source code to validate. Written to a temporary file and validated against the project."; }; readonly scenePath: { readonly type: "string"; readonly description: "[single] Path to a .tscn scene file relative to the project to validate (e.g. \"scenes/main.tscn\")"; }; readonly checks: { readonly type: "array"; readonly description: "[single, requires scenePath] Structural and signal-verification checks to run against the scene. Types: \"structure\" (validate node tree against a schema) and \"signals\" (verify signal connections and handler methods, optional nodePath scope). Merged into the errors array with a \"check\" discriminator."; readonly items: { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["structure", "signals"]; readonly description: "The kind of check to run"; }; readonly schema: { readonly type: "object"; readonly description: "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree."; }; readonly nodePath: { readonly type: "string"; readonly description: "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")"; }; }; readonly required: readonly ["type"]; }; }; readonly targets: { readonly type: "array"; readonly description: "[batch] Array of targets to validate in a single Godot process. Each item must have exactly one of: scriptPath, source, or scenePath."; readonly items: { readonly type: "object"; readonly properties: { readonly scriptPath: { readonly type: "string"; readonly description: "Path to a .gd file relative to the project"; }; readonly source: { readonly type: "string"; readonly description: "Inline GDScript source code"; }; readonly scenePath: { readonly type: "string"; readonly description: "Path to a .tscn scene file relative to the project"; }; readonly checks: { readonly type: "array"; readonly description: "[requires scenePath] Structural / signal checks for this target, run in the same Godot process as the rest of the batch. Same shape as the top-level checks array."; readonly items: { readonly type: "object"; readonly properties: { readonly type: { readonly type: "string"; readonly enum: readonly ["structure", "signals"]; readonly description: "The kind of check to run"; }; readonly schema: { readonly type: "object"; readonly description: "[structure] Recursive node schema: { type?: string, children?: Schema[], hasProperty?: string }. Checks the root node and subtree."; }; readonly nodePath: { readonly type: "string"; readonly description: "[signals] Optional node path to scope the check to a subtree (e.g. \"root/HUD\")"; }; }; readonly required: readonly ["type"]; }; }; }; }; }; }; readonly required: readonly ["projectPath"]; }; })[]; export declare const serverInstructions = "Godot MCP Server - AI-driven Godot 4.x project manipulation.\n\nTool categories:\n- Project management: launch_editor, run_project, attach_project, detach_project, stop_project, get_debug_output, list_projects, check_project\n- Scene editing (headless): create_scene, add_node, load_sprite, save_scene, export_mesh_library, batch_scene_operations\n- Node editing (headless): delete_nodes, set_node_properties, get_node_properties, attach_script, get_scene_tree, duplicate_node, get_node_signals, connect_signal, disconnect_signal\n- Runtime (requires run_project or attach_project): take_screenshot, simulate_input, get_ui_elements, run_script\n- Profiling (requires run_project with profiling: true): profile_project, start_profiler, stop_profiler\n- Project config (no Godot process): list_autoloads, add_autoload, remove_autoload, update_autoload, get_project_files, search_project, get_scene_dependencies, get_project_settings\n- Validation: validate\n\nKey behaviors:\n- All mutation operations (add_node, set_node_properties, delete_nodes, etc.) save the scene automatically. Only use save_scene for save-as (newPath) or re-canonicalization.\n- Headless Godot initializes ALL registered autoloads. If any autoload is broken, headless operations will fail. Use list_autoloads / remove_autoload to diagnose.\n- run_project verifies bridge readiness before returning success. If it reports degraded status, retry runtime tools after a moment or check get_debug_output.\n- attach_project is the fallback path for a manually launched Godot process. It injects the bridge and marks the project active, but it does not spawn Godot or capture stdout/stderr.\n- A runtime session ends by itself when the game exits or an attached bridge disconnects: the bridge autoload is removed at that moment and the scene-editing tools unblock. stop_project is still worth calling (it frees the retained process slot and returns the captured logs) and succeeds either way.\n- click_element in simulate_input resolves by node path or node name (BFS search), NOT by visible text. Use get_ui_elements to discover valid element identifiers.\n- simulate_input reports per-action results (signals fired, the Control hit, UI changes, watched values), so it needs no take_screenshot round trip to tell whether an action landed. Omitting `pressed` taps; set it only to hold or release across actions.\n- run_script expects GDScript with \"extends RefCounted\" and \"func execute(scene_tree: SceneTree) -> Variant\".\n- run_project spawns Godot without -d so runtime errors do not pause execution; the `breakpoint` keyword in user code is a no-op (no debugger is attached). SCRIPT ERROR output and GDScript backtraces still appear in stderr.\n- profiling: true attaches Godot's own remote debugger for the profiling tools. Errors and `breakpoint` still do not pause the game - the server answers every debugger break with continue.\n\nSecurity gate (run_script / run_project): a static-analysis scan classifies GDScript into three tiers - Tier 1 hard-blocks (OS.execute and similar), Tier 2 asks for confirmation via elicitation, Tier 3 just warns. Three env vars change this: GODOT_MCP_STRICT promotes every Tier 2 finding to Tier 1 for unattended operation; GODOT_MCP_DISABLE_ELICITATION skips the Tier 2 prompt and runs findings unprompted (for clients that cannot service elicitation); GODOT_MCP_DISABLE_SECURITY turns the whole gate off, Tier 1 included, and is a human-only decision - decline to set it on a user's behalf. See docs/security.md for the full rule catalogue."; //# sourceMappingURL=index.d.ts.map