# Godette

MCP server for Godot game development. Provides 45 tools for reading, analyzing, and editing Godot projects through the [Model Context Protocol](https://modelcontextprotocol.io/).

## Features

- **Scene tools** — traverse scene trees, find nodes by type/group/script, trace signal chains, query dependencies
- **Scene editing** — add/remove nodes, connect/disconnect signals, manage groups, modify properties
- **Symbol tools** — find and navigate GDScript symbols with LSP when available, regex parser as fallback
- **Symbol editing** — replace function bodies, insert before/after symbols with hash-verified safety
- **Resource tools** — find resources by type, inspect properties, trace cross-project references
- **File tools** — Godot-enriched file reads (parsed symbols for `.gd`, scene structure for `.tscn`)
- **Runtime tools** — run/stop scenes, capture game state, take screenshots, read console output (requires editor plugin)
- **Memory tools** — persistent key-value memory for project context across sessions

## Prerequisites

- Node.js >= 20
- A Godot 4.x project
- (Optional) Godot editor running for LSP support
- (Optional) [GDScript editor plugin](https://github.com/anthropics/godette-plugin) for runtime tools

## Installation

```bash
npm install godette
```

Or run directly:

```bash
npx godette
```

## Usage

### As an MCP server

Add to your MCP client configuration (e.g. Claude Desktop):

```json
{
  "mcpServers": {
    "godette": {
      "command": "npx",
      "args": ["godette"],
      "env": {
        "GODOT_PROJECT": "/path/to/your/godot/project"
      }
    }
  }
}
```

The server auto-detects the Godot project root from the working directory or `GODOT_PROJECT` env var.

### As a library

```typescript
import { parseTscn, parseGdScript, UnifiedIndex, EventBus } from "godette";

// Parse a scene file
const scene = parseTscn(tscnSource, "/path/to/scene.tscn");
console.log(scene.rootType, scene.nodes.size);

// Parse a GDScript file
const script = parseGdScript(gdSource, "/path/to/script.gd");
console.log(script.className, script.functions.length);
```

## Architecture

```
MCP Client (stdio)
    |
GodetteMcpServer
    |-- EventBus (typed async events)
    |-- ProjectDetector (finds project.godot)
    |-- FileWatcher (recursive fs.watch)
    |-- UnifiedIndex
    |     |-- SceneIndex
    |     |-- ScriptIndex
    |     |-- ResourceIndex
    |     |-- SignalGraph
    |     |-- GroupIndex / NodeTypeIndex
    |     '-- AutoloadIndex
    |-- ToolRegistry (45 tools, 8 categories)
    |-- Middleware (logging, timing, error handling)
    |-- LspClient (JSON-RPC, port 6005)
    '-- PluginClient (NDJSON, port 6006)
```

**Key design decisions:**
- Parsers are pure functions with no side effects
- Types are pure interfaces, barrel-exported from `src/index.ts`
- UnifiedIndex uses lazy recomputation via DirtyTracker
- TSCN parser is two-pass: tokenizer -> block parsers -> assembler
- Serializer preserves raw formatting for unmodified blocks

## Available Tools (45)

### File (7)
`read_file` `list_dir` `find_file` `replace_content` `create_file` `delete_lines` `insert_at_line`

### Scene (8)
`get_scene_tree` `find_node` `find_signal_connections` `find_group_members` `get_scene_dependencies` `trace_signal_chain` `find_scene_instances` `get_node_properties`

### Scene Edit (8)
`add_node` `remove_node` `modify_node_property` `connect_signal` `disconnect_signal` `add_to_group` `remove_from_group` `create_scene`

### Symbol (4)
`find_symbol` `find_references` `get_symbols_overview` `rename_symbol`

### Symbol Edit (3)
`replace_symbol_body` `insert_after_symbol` `insert_before_symbol`

### Resource (4)
`find_resource` `get_resource_properties` `get_resource_references` `find_resources_of_type`

### Project (5)
`get_project_settings` `get_input_map` `get_layer_names` `get_autoloads` `list_project_structure`

### Runtime (8)
`run_project` `stop_project` `capture_state` `get_runtime_state` `get_signal_log` `screenshot` `get_console_output` `get_live_scene_tree`

### Memory (5)
`read_memory` `write_memory` `search_memories` `list_memories` `delete_memory`

## Development

```bash
npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run tests (vitest)
npm run test:watch   # Tests in watch mode
npm run lint         # ESLint
npm run format       # Prettier
npm run check        # Full CI check (typecheck + lint + test)
```

## License

MIT