# Specification: GDScript (Godot) MCP Tools

## Overview
Expand the Conductor's AI context-gathering and surgical editing capabilities by introducing full Tree-Sitter parsing support for GDScript (Godot's native scripting language). This will bring GDScript to feature-parity with the existing Python MCP tools, enabling deep AST-driven structural mapping, documentation extraction, and precise code modification.

## Functional Requirements
- **Grammar Integration:**
  - Introduce a stable GDScript Tree-Sitter grammar (`tree-sitter-gdscript`) to the project's parsing environment via Python bindings (or the most robust available method) to generate deterministic Abstract Syntax Trees for `.gd` files.
- **Structural Parsing Tools:**
  - **`gd_get_skeleton`:** Extract a high-level view of a GDScript file, containing all class declarations, signals, exported variables, and function signatures with their associated docstrings, replacing function bodies with `pass` or `...`.
  - **`gd_get_code_outline`:** Generate a hierarchical text outline showing line ranges for major structural elements (classes, functions, macros).
- **Documentation & Context Tools:**
  - **`gd_get_docstring`:** Extract the block comment/docstring immediately preceding a function or class definition.
  - **`gd_find_usages`:** Locate usages of specific GDScript symbols/functions across a file or directory using AST or strict regex boundaries.
- **Surgical Editing Tools:**
  - **`gd_get_definition`:** Extract the full source code of a specific GDScript function or class definition.
  - **`gd_update_definition`:** Surgically replace the implementation of a specific GDScript function without relying on generic search-and-replace strings.
  - **`gd_set_signature`:** Update only the signature (parameters/return type) of a GDScript function.

## Non-Functional Requirements
- **Performance:** Parsing and skeleton generation should be heavily cached (using `mtime` invalidation) to ensure near-instantaneous responses, matching the current Python tool performance.
- **Robustness:** The parser must gracefully handle malformed GDScript code, returning as much structural information as possible rather than failing entirely.

## Acceptance Criteria
- [ ] A new suite of GDScript-specific tools (`gd_get_skeleton`, `gd_get_code_outline`, `gd_get_definition`, `gd_update_definition`) is available via the MCP Client.
- [ ] Automated tests verify that `gd_get_skeleton` correctly identifies classes, inner classes, functions, and Godot-specific keywords (like `@export`, `signal`, `onready`).
- [ ] `gd_update_definition` can successfully replace a multi-line function body while maintaining the surrounding file structure and indentation.
- [ ] The `tree-sitter-gdscript` grammar is successfully integrated into the build/setup pipeline.

## Out of Scope
- Full language server protocol (LSP) features like deep type inference or cross-file variable renaming.
- Automated code formatting or linting for GDScript (formatting relies on external ecosystem tools if needed).
