godot_run_with_capture
Execute a Godot project or scene for a specified duration to capture runtime output including stdout, stderr, logs, warnings, and errors for debugging and analysis.
Instructions
Run a Godot project or a specific scene for a short capture window and return stdout, stderr, log output, plus parsed warnings and errors.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes | Path to the Godot project directory or its project.godot file. | |
| scene_path | No | Optional scene to run instead of the project's configured main scene. | |
| headless | No | Whether to run in headless mode during capture. | |
| capture_seconds | No | How long to let the project or scene run before stopping it and collecting output. | |
| max_output_chars | No | Maximum number of characters to return for stdout, stderr, and log output excerpts. | |
| godot_executable | No | Optional explicit path to the Godot executable or .app bundle. |
Implementation Reference
- src/godot_mcp/godot.py:2202-2278 (handler)Implementation of the run_with_capture tool logic in the GodotController class.
def run_with_capture( self, project_path: str, scene_path: str | None = None, godot_executable: str | None = None, headless: bool = False, capture_seconds: float = 3.0, max_output_chars: int = 12000, ) -> dict[str, Any]: project_dir = ensure_project_path(project_path) executable, version = resolve_godot_executable(godot_executable) if capture_seconds <= 0: raise GodotError("`capture_seconds` must be greater than 0.") command = [str(executable), "--log-file", str(_create_log_path(project_dir, "run-capture")), "--path", str(project_dir)] absolute_scene_path: Path | None = None resource_scene_path: str | None = None run_target = "project" if headless: command.append("--headless") if scene_path: absolute_scene_path, resource_scene_path = resolve_scene_path(project_dir, scene_path) if not absolute_scene_path.exists(): raise GodotError(f"Scene not found: {absolute_scene_path}") command.append(str(absolute_scene_path)) run_target = "scene" log_path = Path(command[2]) process = subprocess.Popen( command, cwd=project_dir, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, ) terminated_after_capture = False force_killed = False try: stdout_text, stderr_text = process.communicate(timeout=capture_seconds) except subprocess.TimeoutExpired: terminated_after_capture = True process.terminate() try: stdout_text, stderr_text = process.communicate(timeout=5) except subprocess.TimeoutExpired: force_killed = True process.kill() stdout_text, stderr_text = process.communicate(timeout=5) log_text = log_path.read_text(encoding="utf-8", errors="replace") if log_path.exists() else "" stdout_excerpt, stdout_truncated = _truncate_text(stdout_text, max_output_chars) stderr_excerpt, stderr_truncated = _truncate_text(stderr_text, max_output_chars) log_excerpt, log_truncated = _truncate_text(log_text, max_output_chars) debug_output = _classify_debug_lines(stdout_text, stderr_text, log_text) return { "project_path": str(project_dir), "scene_path": str(absolute_scene_path) if absolute_scene_path is not None else None, "scene_resource_path": resource_scene_path, "run_target": run_target, "command": command, "log_path": str(log_path), "headless": headless, "capture_seconds": capture_seconds, "exit_code": process.returncode, "terminated_after_capture": terminated_after_capture, "force_killed": force_killed, "stdout": stdout_excerpt, "stderr": stderr_excerpt, "log_output": log_excerpt, "stdout_truncated": stdout_truncated, "stderr_truncated": stderr_truncated, "log_output_truncated": log_truncated, "debug_output": debug_output, "godot_version": version, } - src/godot_mcp/server.py:891-936 (registration)Registration of the godot_run_with_capture tool in the MCP server.
name="godot_run_with_capture", description="Run a Godot project or a specific scene for a short capture window and return stdout, stderr, log output, plus parsed warnings and errors.", input_schema={ "type": "object", "properties": { "project_path": { "type": "string", "description": "Path to the Godot project directory or its project.godot file.", }, "scene_path": { "type": "string", "description": "Optional scene to run instead of the project's configured main scene.", }, "headless": { "type": "boolean", "description": "Whether to run in headless mode during capture.", "default": False, }, "capture_seconds": { "type": "number", "description": "How long to let the project or scene run before stopping it and collecting output.", "default": 3.0, }, "max_output_chars": { "type": "integer", "description": "Maximum number of characters to return for stdout, stderr, and log output excerpts.", "default": 12000, "minimum": 1, }, "godot_executable": { "type": "string", "description": "Optional explicit path to the Godot executable or .app bundle.", }, }, "required": ["project_path"], "additionalProperties": False, }, handler=lambda args: self.controller.run_with_capture( project_path=args["project_path"], scene_path=args.get("scene_path"), headless=bool(args.get("headless", False)), capture_seconds=float(args.get("capture_seconds", 3.0)), max_output_chars=int(args.get("max_output_chars", 12000)), godot_executable=args.get("godot_executable"), ), ),