docs: Update cline_docs for resave_resources fix

Author: alienfrenZyNo1

cline_docs/codebaseSummary.md

@@ -0,0 +1,81 @@
+# Codebase Summary: Godot MCP Server
+
+## Key Components and Their Interactions
+
+### 1. MCP Server (`src/index.ts`)
+- **Purpose:** Acts as the bridge between the MCP client (e.g., AI assistant) and the Godot engine.
+- **Functionality:**
+    - Initializes an MCP server using `@modelcontextprotocol/sdk`.
+    - Defines available tools (`create_scene`, `add_node`, etc.) with their input/output schemas using `setRequestHandler`.
+    - Handles incoming `CallToolRequest` messages.
+    - Normalizes incoming parameters (camelCase to snake_case).
+    - Detects the Godot executable path.
+    - Constructs command-line arguments, including the operation name and a JSON string of parameters.
+    - Invokes the `godot_operations.gd` script using `child_process.spawn` (configured with `shell: false`).
+    - Captures stdout/stderr from the Godot process.
+    - Formats and returns the result or error to the MCP client.
+- **Key Methods:** `constructor`, `setupToolHandlers`, `executeOperation`, individual tool handlers (`handleCreateScene`, etc.).
+
+### 2. Godot Operations Script (`src/scripts/godot_operations.gd`)
+- **Purpose:** Executes specific Godot engine actions based on commands received from the MCP server.
+- **Functionality:**
+    - Runs as a headless Godot script (`extends SceneTree`).
+    - Parses command-line arguments to get the operation name and JSON parameter string.
+    - Uses `JSON.parse()` to convert the JSON string into a Godot Dictionary (`params`).
+    - Uses a `match` statement to call the appropriate function based on the operation name.
+    - Contains functions for each tool operation (e.g., `create_scene`, `add_node`).
+    - Interacts with Godot APIs (`ResourceSaver`, `PackedScene`, `Node`, `ClassDB`, `DirAccess`, `FileAccess`, etc.) to perform actions.
+    - Includes specific cleanup logic (e.g., freeing instantiated nodes (`scene_root.free()`), adding delays) in functions like `add_node`, `create_scene`, `load_sprite`, `export_mesh_library`, and `save_scene` to prevent resource leaks or issues in headless mode.
+    - Prints success messages to stdout or error messages to stderr.
+    - Exits using `quit()`.
+- **Key Methods:** `_init`, `create_scene`, `add_node`, `load_sprite`, `export_mesh_library`, `save_scene`, etc., `log_*`, `instantiate_class`.
+
+### Interaction Flow (`create_scene` example)
+1.  MCP client sends `CallToolRequest` for `create_scene` with arguments (projectPath, scenePath, rootNodeType).
+2.  `src/index.ts` receives the request via `setRequestHandler(CallToolRequestSchema, ...)`.
+3.  `handleCreateScene` is called.
+4.  Parameters are normalized (camelCase to snake_case).
+5.  `executeOperation` is called with operation "create_scene" and snake_case params.
+6.  `executeOperation` converts params to a JSON string.
+7.  `executeOperation` calls `spawn` with the Godot executable path, `--headless`, `--path`, `--script`, the operation name ("create_scene"), and the JSON string as arguments (`shell: false`).
+8.  `godot_operations.gd` starts execution.
+9.  `_init` parses command-line args, extracts "create_scene" and the JSON string.
+10. `_init` calls `JSON.parse()` on the JSON string.
+11. `_init` calls the `create_scene(params)` function with the parsed Dictionary.
+12. `create_scene` function uses Godot APIs to create the root node, pack the scene, ensure the directory exists, and save the `.tscn` file using `ResourceSaver.save()`.
+13. `create_scene` prints success/error messages.
+14. Godot script exits (`quit()`).
+15. `executeOperation` in `src/index.ts` resolves its promise with stdout/stderr.
+16. `handleCreateScene` processes stdout/stderr and returns a result object to the MCP client.
+
+## Data Flow
+- **Input:** MCP `CallToolRequest` with JSON arguments (camelCase or snake_case).
+- **Internal:**
+    - Node.js normalizes arguments to snake_case.
+    - Node.js serializes snake_case arguments to a JSON string.
+    - JSON string passed as a command-line argument to GDScript.
+    - GDScript parses the JSON string back into a Dictionary.
+- **Output:** MCP response object containing success/error message and relevant data (e.g., created scene path). Stdout/stderr from Godot script captured by Node.js.
+
+## External Dependencies
+- **@modelcontextprotocol/sdk:** Core dependency for MCP communication. Managed via `package.json` and `npm`.
+- **Godot Engine:** External executable. Path is auto-detected or configured via environment variable/server config. The server relies on Godot's command-line interface and headless execution capabilities.
+
+## Recent Significant Changes
+- **Argument Passing:** Switched from `spawn` with `shell: true` and manual escaping to `spawn` with `shell: false` and passing the raw JSON string. This resolved issues with argument parsing on Windows.
+- **MCP SDK Usage:** Refactored tool registration from `server.registerTool` to using `server.setRequestHandler` for `ListToolsRequestSchema` and `CallToolRequestSchema`, aligning with current SDK practices.
+- **GDScript Error Fix:** Removed incorrect `scene_root.owner = scene_root` assignment in `create_scene` function, resolving a Godot engine assertion error during `PackedScene.pack()`.
+- **Logging:** Added detailed debug logging in both `index.ts` and `godot_operations.gd` to trace argument passing and execution flow.
+- **`add_node` Fixes:** Debugged and resolved multiple issues in the `add_node` GDScript function:
+    - Addressed initial "RID allocation leak" errors by adding `scene_root.free()`.
+    - Resolved subsequent node duplication issues (likely caused by freeing `scene_root` too early) by adding a small delay (`OS.delay_msec(100)`) after `ResourceSaver.save()` but before `scene_root.free()` in `add_node`.
+    - Corrected a "Can't free a RefCounted object" error introduced by incorrectly trying to free the `PackedScene` resource.
+- **RID Leak Fix:** Added missing `scene_root.free()` calls to the end of `create_scene`, `load_sprite`, `export_mesh_library`, and `save_scene` functions in `godot_operations.gd` to resolve RID allocation leaks observed during testing.
+- **`resave_resources` Fix:** Addressed issues with the `resave_resources` tool:
+    - Modified `godot_operations.gd` (`_init`) to make the JSON parameter optional and default to an empty dictionary if not provided.
+    - Added explicit parameter validation checks within specific GDScript functions that require them.
+    - Added a small delay (`OS.delay_msec(100)`) before `quit()` in `godot_operations.gd` to potentially aid output buffer flushing.
+    - Updated the `handleUpdateProjectUids` function in `index.ts` to infer success based on the Godot script's exit code (0) and the absence of "ERROR" in stderr, improving reliability over parsing stdout.
+
+## User Feedback Integration
+- N/A (No user feedback integrated yet for this specific task).

cline_docs/currentTask.md

@@ -0,0 +1,35 @@
+# Current Task: Update Fork with RID Leak Fix
+
+## Objective
+- Update the user's fork (`alienfrenZyNo1/godot-mcp`) with the commit containing the fix for the RID allocation leaks, ensuring documentation files are *not* included in this update.
+
+## Context
+- The previous task involved fixing the `add_node` tool and preparing a PR.
+- Further testing revealed similar RID allocation leaks in other scene modification tools (`load_sprite`, `create_scene`, `export_mesh_library`, `save_scene`).
+- These leaks were traced back to missing `scene_root.free()` calls in the corresponding functions within `src/scripts/godot_operations.gd`.
+- The fix involved adding the necessary `scene_root.free()` calls to all affected functions.
+
+## Completed Steps
+1.  Identified missing `scene_root.free()` calls in `create_scene`, `load_sprite`, `export_mesh_library`, and `save_scene` functions in `src/scripts/godot_operations.gd`.
+2.  Applied the fix by adding the `scene_root.free()` calls to these functions using `replace_in_file`.
+3.  Rebuilt the project (`npm run build`).
+4.  Successfully tested the `load_sprite` tool, confirming the RID leak was resolved.
+5.  Successfully used the `save_scene` tool to persist the changes.
+6.  Updated `cline_docs` (`currentTask.md`, `projectRoadmap.md`, `codebaseSummary.md`) to reflect the completion of the RID leak fix across multiple tools.
+
+## Next Steps
+- Stage the documentation changes (`git add cline_docs/`).
+- Debugged and fixed the `resave_resources` tool:
+    - Modified `godot_operations.gd` to handle optional parameters correctly.
+    - Added debugging logs to trace parameter parsing in GDScript.
+    - Modified `index.ts` (`handleUpdateProjectUids`) to check for the correct stdout message ("Resave operation complete").
+    - Added a delay (`OS.delay_msec(100)`) before `quit()` in `godot_operations.gd` to attempt to fix output flushing issues.
+    - Modified `index.ts` (`handleUpdateProjectUids`) again to infer success based on exit code 0 and lack of "ERROR" in stderr, as stdout parsing remained unreliable.
+- Rebuilt the server (`npm run build`) multiple times.
+- Confirmed `resave_resources` works correctly after server restart.
+
+## Next Steps
+- Stage the code changes (`src/index.ts`, `src/scripts/godot_operations.gd`).
+- Commit the code changes with an appropriate message.
+- Push the commit to the user's fork (`fork main`).
+- Update local documentation (`cline_docs/`) and commit separately (locally only).

cline_docs/projectRoadmap.md

@@ -0,0 +1,37 @@
+# Project Roadmap: Godot MCP Server
+
+## Goals
+- Provide robust tools for interacting with the Godot engine via MCP.
+- Ensure reliable communication between Node.js server and Godot scripts.
+
+## Features
+- [x] `create_scene`: Create new Godot scene files. (Fixed RID leak)
+- [x] `add_node`: Add nodes to existing scenes. (Fixed RID leak)
+- [x] `load_sprite`: Load textures onto sprite nodes. (Fixed RID leak)
+- [x] `export_mesh_library`: Export meshes to a MeshLibrary. (Fixed RID leak)
+- [x] `save_scene`: Save scene changes. (Fixed RID leak)
+- [ ] `get_uid`: Retrieve resource UIDs.
+- [x] `resave_resources`: Update project UIDs. (Fixed argument/output handling)
+- [ ] `launch_editor`: Launch the Godot editor.
+- [ ] `run_project`: Run a Godot project.
+- [ ] `get_debug_output`: Capture debug output.
+- [ ] `stop_project`: Stop a running project.
+- [ ] `get_godot_version`: Get Godot version.
+- [ ] `list_projects`: List projects in a directory.
+- [ ] `get_project_info`: Get project scene/script info.
+
+## Completion Criteria
+- All defined tools function correctly across platforms (especially Windows).
+- Argument passing between Node.js and Godot is reliable.
+- Error handling is robust.
+
+## Progress Tracker
+- Initial setup and basic tool implementation.
+- Debugging and fixing argument passing for `create_scene`.
+
+## Completed Tasks
+- [x] Debug and fix JSON argument passing for `create_scene` tool.
+- [x] Correct node ownership issue in `create_scene` GDScript function.
+- [x] Debug and fix resource leaks and node duplication issues for `add_node` tool.
+- [x] Debug and fix RID allocation leaks in `create_scene`, `load_sprite`, `export_mesh_library`, and `save_scene` by ensuring `scene_root.free()` is called.
+- [x] Debug and fix argument handling and success reporting for `resave_resources` tool.

cline_docs/techStack.md

@@ -0,0 +1,21 @@
+# Tech Stack: Godot MCP Server
+
+## Core Technologies
+- **Node.js:** Runtime environment for the MCP server.
+- **TypeScript:** Primary language for the server codebase, providing static typing.
+- **Godot Engine:** Target game engine for interactions.
+- **GDScript:** Language used for the Godot-side operations script (`godot_operations.gd`).
+
+## Key Libraries/Modules
+- **@modelcontextprotocol/sdk:** Used for MCP server implementation (`Server`, `StdioServerTransport`, schemas).
+- **Node.js `child_process`:**
+    - `spawn`: Used for executing the Godot command-line tool reliably, especially for passing complex arguments like JSON strings. Configured with `shell: false` for better cross-platform argument handling.
+    - `exec` / `execAsync`: Potentially used for simpler commands like `--version` or launching the editor.
+- **Node.js `fs`:** Used for file system checks (`existsSync`, `readdirSync`).
+- **Node.js `path`:** Used for path manipulation and normalization (`join`, `dirname`, `basename`, `normalize`).
+
+## Architecture Decisions
+- **MCP Server (`src/index.ts`):** Handles incoming MCP tool requests, validates parameters, prepares arguments, and invokes the Godot operations script.
+- **Godot Operations Script (`src/scripts/godot_operations.gd`):** A headless Godot script that receives commands and JSON parameters via command-line arguments. It performs the actual Godot engine operations (e.g., creating scenes, adding nodes).
+- **Argument Passing:** JSON strings are passed as command-line arguments from Node.js to the GDScript. Using `spawn` with `shell: false` is crucial for correct parsing on Windows, avoiding shell interpretation issues.
+- **Parameter Normalization:** The Node.js server normalizes incoming MCP arguments (potentially camelCase) to snake_case before sending them to the GDScript, which expects snake_case.