gopeak 2.0.1 → 2.2.0

package/README.md

@@ -5,905 +5,267 @@
 [![](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
 [![](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white 'TypeScript')](https://www.typescriptlang.org/)
 [![npm](https://img.shields.io/npm/v/gopeak?style=flat&logo=npm&logoColor=white 'npm')](https://www.npmjs.com/package/gopeak)
-
 [![](https://img.shields.io/github/last-commit/HaD0Yun/godot-mcp 'Last Commit')](https://github.com/HaD0Yun/godot-mcp/commits/main)
 [![](https://img.shields.io/github/stars/HaD0Yun/godot-mcp 'Stars')](https://github.com/HaD0Yun/godot-mcp/stargazers)
 [![](https://img.shields.io/github/forks/HaD0Yun/godot-mcp 'Forks')](https://github.com/HaD0Yun/godot-mcp/network/members)
 [![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
 
-```text
-                           (((((((             (((((((                          
-                        (((((((((((           (((((((((((                      
-                        (((((((((((((       (((((((((((((                       
-                        (((((((((((((((((((((((((((((((((                       
-                        (((((((((((((((((((((((((((((((((                       
-         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
-       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
-     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
-    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
-      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
-        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
-         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
-         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
-         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
-         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
-         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
-         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
-         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
-         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
-         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
-         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
-         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
-          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
-           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
-              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
-                 (((((((((((((((((((((((((((((((((((((((((((((((                
-                        (((((((((((((((((((((((((((((((((                       
-                                                                                
-
-        /$$$$$$             /$$$$$$$                      /$$      
-       /$$__  $$           | $$__  $$                    | $$      
-      | $$  \__/  /$$$$$$ | $$  \ $$ /$$$$$$   /$$$$$$$ | $$  /$$/
-      | $$ /$$$$//$$__  $$| $$$$$$$//$$__  $$ |____  $$ | $$ /$$/ 
-      | $$|_  $$| $$  \ $$| $$____/| $$$$$$$$  /$$$$$$$ | $$$$$/  
-      | $$  \ $$| $$  | $$| $$     | $$_____/ /$$__  $$ | $$  $$  
-      |  $$$$$$/|  $$$$$$/| $$     |  $$$$$$ |  $$$$$$$ | $$\  $$ 
-       \______/  \______/ |__/      \______/  \_______/ |__/ \__/ 
-```
-
-**The most comprehensive Model Context Protocol (MCP) server for Godot Engine — enabling AI assistants to build, modify, and debug Godot games with unprecedented depth and precision.**
+![GoPeak Hero](assets/gopeak-hero-v2.png)
 
-> **Now with Auto Reload!** Scenes and scripts automatically refresh in the Godot editor when modified externally via MCP.
+**GoPeak is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real projects end-to-end.**
 
 ---
 
-## Why GoPeak? The Game-Changing Benefits
-
-### 🚀 Transform Your Game Development Workflow
-
-GoPeak isn't just another tool — it's a **paradigm shift** in how AI assistants interact with game engines. Here's why this matters:
-
-#### 1. **AI That Truly Understands Godot**
-
-Traditional AI assistants can write GDScript, but they're essentially working blind. They generate code based on training data, hoping it works. **GoPeak changes everything:**
-
-- **Real-time Feedback Loop**: When you ask "run my project and show me errors," the AI actually runs your project, captures the output, and sees exactly what went wrong
-- **Context-Aware Assistance**: The AI can inspect your actual scene tree, understand your node hierarchy, and provide suggestions based on your real project structure
-- **Validation Before Suggesting**: Before suggesting you use a resource, the AI can verify it exists in your project
-
-#### 2. **95+ Tools with Dynamic ClassDB Introspection**
-
-Instead of hardcoding tools for every Godot class, GoPeak provides **generic tools** (`add_node`, `create_resource`) that work with ANY ClassDB class, plus **ClassDB introspection tools** that let AI discover classes, properties, and methods dynamically.
+## Quick Start (3 Minutes)
 
-| Category | What You Can Do | Tools |
-|----------|-----------------|-------|
-| **Scene Management** | Build entire scene trees programmatically | `create_scene`, `add_node`, `delete_node`, `duplicate_node`, `reparent_node`, `list_scene_nodes`, `get_node_properties`, `set_node_properties` |
-| **ClassDB Introspection** | Dynamically discover Godot classes, properties, methods, signals | `query_classes`, `query_class_info`, `inspect_inheritance` |
-| **GDScript Operations** | Write and modify scripts with surgical precision | `create_script`, `modify_script`, `get_script_info` |
-| **Resource Management** | Create any resource type, modify existing resources | `create_resource`, `modify_resource`, `create_material`, `create_shader` |
-| **Animation System** | Build animations and state machines | `create_animation`, `add_animation_track`, `create_animation_tree`, `add_animation_state`, `connect_animation_states` |
-| **2D Tile System** | Create tilesets and populate tilemaps | `create_tileset`, `set_tilemap_cells` |
-| **Signal Management** | Wire up your game's event system | `connect_signal`, `disconnect_signal`, `list_connections` |
-| **Project Configuration** | Manage settings, autoloads, and inputs | `get_project_setting`, `set_project_setting`, `add_autoload`, `add_input_action` |
-| **Developer Experience** | Analyze, debug, and maintain your project | `get_dependencies`, `find_resource_usages`, `parse_error_log`, `get_project_health`, `search_project` |
-| **Runtime Debugging** | Inspect and modify running games | `inspect_runtime_tree`, `set_runtime_property`, `call_runtime_method`, `get_runtime_metrics` |
-| **Screenshot Capture** | Capture viewport screenshots from running games | `capture_screenshot`, `capture_viewport` |
-| **Input Injection** | Simulate keyboard, mouse, and action inputs | `inject_action`, `inject_key`, `inject_mouse_click`, `inject_mouse_motion` |
-| **GDScript LSP** | Diagnostics, completions, hover, and symbols via Godot's built-in Language Server | `lsp_get_diagnostics`, `lsp_get_completions`, `lsp_get_hover`, `lsp_get_symbols` |
-| **Debug Adapter (DAP)** | Breakpoints, stepping, stack traces, and debug output capture | `dap_get_output`, `dap_set_breakpoint`, `dap_continue`, `dap_step_over`, `dap_get_stack_trace` |
-| **MCP Resources** | Access project files via `godot://` URIs | `godot://project/info`, `godot://scene/{path}`, `godot://script/{path}` |
-| **Audio System** | Create audio buses, configure effects | `create_audio_bus`, `get_audio_buses`, `set_audio_bus_effect`, `set_audio_bus_volume` |
-| **Navigation** | AI pathfinding setup | `create_navigation_region`, `create_navigation_agent` |
-| **UI/Themes** | Create and apply custom themes with shaders | `set_theme_color`, `set_theme_font_size`, `apply_theme_shader` |
-| **Asset Library** | Search and download CC0 assets from multiple sources | `search_assets`, `fetch_asset`, `list_asset_providers` |
-| **Auto Reload** | Instant editor refresh on external changes | Built-in Editor Plugin |
+### Requirements
 
-> **Design Philosophy**: Rather than providing 90+ specialized tools (e.g., `create_camera`, `create_light`, `create_physics_material`), GoPeak uses generic `add_node` and `create_resource` tools that work with ANY Godot class. The AI uses `query_classes` to discover available types and `query_class_info` to learn their properties — just like a developer using the Godot docs.
+- Godot 4.x
+- Node.js 18+
+- MCP-compatible client (Claude Desktop, Cursor, Cline, OpenCode, etc.)
 
-#### 3. **Seamless Editor Integration with Auto Reload**
+### 1) Run GoPeak
 
-The included **Auto Reload plugin** eliminates the friction of external editing:
-
-- **No Manual Refresh**: When MCP modifies a scene or script, the Godot editor automatically reloads it
-- **1-Second Detection**: Lightweight polling with negligible performance impact (~0.01ms/sec)
-- **Smart Watching**: Monitors open scenes AND their attached scripts
-- **Zero Configuration**: Just enable the plugin and forget about it
-
-```
-MCP modifies file → Auto Reload detects change → Editor reloads → You see the result instantly
+```bash
+npx -y gopeak
 ```
 
-#### 4. **Eliminate the Copy-Paste-Debug Cycle**
-
-**Before GoPeak:**
-1. Ask AI for code
-2. Copy code to your project
-3. Run project, encounter error
-4. Copy error back to AI
-5. Get fix, paste it
-6. Repeat 10+ times
-
-**With GoPeak:**
-1. "Create a player character with health, movement, and jumping"
-2. AI creates the scene, writes the script, adds the nodes, connects signals, and tests it
-3. Done.
-
-The AI doesn't just write code — it **implements features end-to-end**.
-
-#### 5. **Type-Safe, Error-Resistant Operations**
-
-Every operation in GoPeak includes:
-
-- **Path Validation**: Prevents invalid file operations
-- **Type Serialization**: Correctly handles Vector2, Vector3, Color, Transform, and all Godot types
-- **Error Recovery**: Meaningful error messages with suggested fixes
-- **Atomic Operations**: Changes are applied consistently or not at all
+or install globally:
 
-Example: When you ask to set a node's position, GoPeak:
-1. Validates the scene exists
-2. Validates the node path
-3. Deserializes `{"x": 100, "y": 200}` to `Vector2(100, 200)`
-4. Sets the property
-5. Saves the scene
-6. Confirms success or reports exactly what went wrong
-
-#### 6. **Project Health Intelligence**
+```bash
+npm install -g gopeak
+gopeak
+```
 
-The `get_project_health` tool provides a comprehensive analysis of your project:
+### 2) Add MCP client config
 
 ```json
 {
-  "score": 85,
-  "grade": "B",
-  "checks": {
-    "structure": { "passed": true },
-    "resources": { "issues": ["3 textures need reimporting"] },
-    "scripts": { "issues": ["5 TODO comments found"] },
-    "config": { "passed": true }
-  },
-  "recommendations": [
-    "Configure export presets for your target platforms",
-    "Review and resolve TODO items before release"
-  ]
+  "mcpServers": {
+    "godot": {
+      "command": "npx",
+      "args": ["-y", "gopeak"],
+      "env": {
+        "GODOT_PATH": "/path/to/godot",
+        "GOPEAK_TOOL_PROFILE": "compact"
+      }
+    }
+  }
 }
 ```
 
-This turns your AI assistant into a **code reviewer that actually understands your Godot project**.
+> `GOPEAK_TOOL_PROFILE=compact` is the default. It keeps prompt/tool-list token usage low while preserving access to the full toolset via catalog discovery.
 
-#### 7. **Dependency Analysis & Circular Reference Detection**
+### 3) First prompts to try
 
-Ever had a project break because of circular dependencies? The `get_dependencies` tool:
+- "List Godot projects in `/your/projects` and show project info."
+- "Create `scenes/Player.tscn` with `CharacterBody2D` root and add a movement script."
+- "Run project, get debug output, then fix top error."
 
-- Maps every resource dependency in your project
-- Detects circular references before they cause runtime errors
-- Shows you the complete dependency chain for any resource
+---
 
-```
-PlayerScene.tscn
-├── PlayerScript.gd
-│   └── WeaponBase.gd
-│       └── ⚠️ CIRCULAR: PlayerScript.gd
-└── PlayerSprite.png
-```
+## Why GoPeak
 
-#### 8. **Live Runtime Debugging (Optional Addon)**
+- **Real project feedback loop**: run the game, inspect logs, and fix in-context.
+- **95+ tools available** across scene/script/resource/runtime/LSP/DAP/input/assets.
+- **Token-efficient by default**: compact tool surface for lower context overhead.
+- **Discoverability built-in**: use `tool.catalog` (alias of `tool_catalog`) to find hidden or legacy tools by keyword.
+- **Deep Godot integration**: ClassDB queries, runtime inspection, debugger hooks, bridge-based scene/resource edits.
 
-Install the included `godot_mcp_runtime` addon and unlock:
+### Best For
 
-- **Live Scene Tree Inspection**: See your game's actual node tree while it runs
-- **Hot Property Modification**: Change values in real-time without restarting
-- **Remote Method Calling**: Trigger functions in your running game
-- **Performance Monitoring**: Track FPS, memory, draw calls, and more
+- Solo/indie developers moving quickly with AI assistance
+- Teams that need AI grounded in actual project/runtime state
+- Debug-heavy workflows (breakpoints, stack traces, live runtime checks)
 
-This transforms debugging from "add print statements and restart" to "inspect and modify on the fly."
+---
 
-### 💡 Real-World Use Cases
+## Tool Surface Model (Important)
 
-#### **Rapid Prototyping**
-```
-"Create a basic platformer with a player that can move, jump, and collect coins"
-```
-The AI creates scenes, scripts, nodes, signals, and input actions — a playable prototype in minutes.
+GoPeak supports three exposure profiles:
 
-#### **Refactoring at Scale**
-```
-"Find all uses of the old PlayerData resource and update them to use the new PlayerStats"
-```
-Search the entire project, identify every reference, and make consistent changes.
+- `compact` (default): exposes a curated alias set (about 20 core tools)
+- `full`: exposes full legacy tool list (95+)
+- `legacy`: same exposed behavior as `full`
 
-#### **Debugging Complex Issues**
-```
-"My player keeps falling through the floor. Check my collision setup and tell me what's wrong"
-```
-Inspect node properties, analyze scene structure, and identify configuration issues.
+Configure with either:
 
-#### **Learning Godot**
-```
-"Show me how signals work by creating a button that changes a label's text when clicked"
-```
-Instead of just explaining, the AI builds a working example in your actual project.
+- `GOPEAK_TOOL_PROFILE`
+- `MCP_TOOL_PROFILE` (fallback alias)
 
-#### **Maintaining Large Projects**
-```
-"Run a health check on my project and tell me what needs attention"
-```
-Get actionable insights about project structure, unused resources, and potential issues.
+### How to discover hidden tools in compact mode
 
----
+Call:
 
-## Features
-
-### Core Features
-- **Launch Godot Editor**: Open the Godot editor for a specific project
-- **Run Godot Projects**: Execute Godot projects in debug mode
-- **Capture Debug Output**: Retrieve console output and error messages
-- **Control Execution**: Start and stop Godot projects programmatically
-- **Get Godot Version**: Retrieve the installed Godot version
-- **List Godot Projects**: Find Godot projects in a specified directory
-- **Project Analysis**: Get detailed information about project structure
-
-### Scene Management
-- Create new scenes with specified root node types
-- Add, delete, duplicate, and reparent nodes
-- Set node properties with type-safe serialization
-- List scene tree structure with full hierarchy
-- Load sprites and textures into Sprite2D nodes
-- Export 3D scenes as MeshLibrary resources for GridMap
-
-### GDScript Operations
-- **Create Scripts**: Generate new GDScript files with templates (singleton, state_machine, component, resource)
-- **Modify Scripts**: Add functions, variables, and signals to existing scripts
-- **Analyze Scripts**: Get detailed information about script structure, dependencies, and exports
-
-### Signal & Connection Management
-- Connect signals between nodes in scenes
-- Disconnect signal connections
-- List all signal connections in a scene
-
-### ClassDB Introspection (New!)
-- **Query Classes**: Discover available Godot classes with filtering by name, category (node, node2d, node3d, control, resource, etc.), and instantiability
-- **Query Class Info**: Get detailed methods, properties, signals, and enums for any class
-- **Inspect Inheritance**: Explore class hierarchy — ancestors, children, and all descendants
-
-### Resource Management
-- **Create Resources**: Generate ANY resource type as .tres files (replaces specialized create_* tools)
-- **Modify Resources**: Update properties of existing .tres/.res files
-- **Create Materials**: StandardMaterial3D, ShaderMaterial, CanvasItemMaterial, ParticleProcessMaterial
-- **Create Shaders**: canvas_item, spatial, particles, sky, fog shaders with templates
-
-### Animation System
-- Create new animations in AnimationPlayer nodes
-- Add property and method tracks to animations
-- Insert keyframes with proper value serialization
-
-### 2D Tile System
-- Create TileSet resources with atlas texture sources
-- Set TileMap cells programmatically
-
-### Import/Export Pipeline
-- Get import status and options for resources
-- Modify import settings and trigger reimport
-- List export presets and validate project for export
-- Export projects using Godot CLI
-
-### Project Configuration
-- Get and set project settings
-- Manage autoload singletons (add, remove, list)
-- Set main scene
-- Add input actions with key, mouse, and joypad events
-
-### Plugin Management
-- List installed plugins with status
-- Enable and disable plugins
-
-### Developer Experience
-- **Dependency Analysis**: Get resource dependency graphs with circular reference detection
-- **Resource Usage Finder**: Find all usages of a resource across the project
-- **Error Log Parser**: Parse Godot error logs with suggestions
-- **Project Health Check**: Comprehensive project analysis with scoring
-- **Project Search**: Search for text/patterns across all project files
-
-### Runtime Connection (Optional Addon)
-- Real-time scene tree inspection
-- Live property modification
-- Remote method calling
-- Performance metrics monitoring
-- Signal watching
-
-### Screenshot Capture (New!)
-- Capture the running game's viewport as a base64 PNG/JPG image
-- Specify target resolution for resized captures
-- Capture specific viewports by node path
-
-### Input Injection (New!)
-- Simulate Godot input actions (press/release) for automated testing
-- Inject keyboard key events with modifier support (Shift, Ctrl, Alt)
-- Simulate mouse clicks (left/right/middle, single/double)
-- Simulate mouse movement (absolute and relative)
-
-### GDScript Language Server (New!)
-- Get real-time diagnostics (errors/warnings) from Godot's built-in LSP
-- Code completions at any position in a GDScript file
-- Hover information for symbols, functions, and variables
-- Document symbol outlines for navigation
-- Lazy connection to Godot editor's LSP (port 6005)
-
-### Debug Adapter Protocol (New!)
-- Capture debug console output from running Godot games
-- Set and remove breakpoints in GDScript files
-- Step over, continue, and pause execution
-- Inspect stack traces at breakpoints
-- Lazy connection to Godot's built-in DAP (port 6006)
-
-### MCP Resources (New!)
-- Access Godot project files via `godot://` URI protocol
-- `godot://project/info` — parsed project.godot metadata as JSON
-- `godot://scene/{path}` — read .tscn scene files
-- `godot://script/{path}` — read .gd script files
-- `godot://resource/{path}` — read .tres/.tscn/.gd files
-- Path traversal protection built-in
-
-### UID Management (Godot 4.4+)
-- Get UID for specific files
-- Update UID references by resaving resources
-
-### Multi-Source Asset Library (CC0)
-- **Unified Search**: Search for 3D models, textures, HDRIs across multiple CC0 asset providers
-- **Automatic Download**: Fetch assets directly into your Godot project
-- **Provider Priority**: Searches Poly Haven → AmbientCG → Kenney in order
-- **Attribution Tracking**: Automatic CREDITS.md generation for proper attribution
-
-**Supported Providers:**
-
-| Provider | Asset Types | License |
-|----------|-------------|---------|
-| [Poly Haven](https://polyhaven.com) | Models, Textures, HDRIs | CC0 |
-| [AmbientCG](https://ambientcg.com) | Textures, Models, HDRIs | CC0 |
-| [Kenney](https://kenney.nl) | Models, Textures, 2D, Audio | CC0 |
+- `tool.catalog` (compact alias)
+- `tool_catalog` (legacy name)
 
----
+Example intent:
 
-## Requirements
+> "Use `tool.catalog` with query `animation` and show relevant tools."
 
-- [Godot Engine 4.x](https://godotengine.org/download) installed on your system
-- Node.js 18+ and npm
-- An AI assistant that supports MCP (Claude Desktop, Cline, Cursor, OpenCode, etc.)
+This lets assistants start with a small, efficient default surface but still find and use the full capability set when needed.
 
 ---
 
-## Installation and Configuration
-
-### 🚀 One-Click Install (Recommended)
-
-**Linux / macOS**
-```bash
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash
-```
+## Installation Options
 
-This script will:
-- ✅ Check prerequisites (Git, Node.js 18+, npm)
-- ✅ Clone the repository to `~/.local/share/godot-mcp`
-- ✅ Install dependencies and build automatically
-- ✅ Auto-detect Godot installation
-- ✅ Show configuration instructions for your AI assistant
+### A) Recommended: npx
 
-**Advanced Options:**
 ```bash
-# Custom installation directory
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --dir ~/my-godot-mcp
-
-# Specify Godot path
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --godot /usr/bin/godot4
-
-# Get configuration for specific AI assistant
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash -s -- --configure claude
+npx -y gopeak
 ```
 
-**Available options:**
-| Option | Description |
-|--------|-------------|
-| `-d, --dir PATH` | Installation directory (default: `~/.local/share/godot-mcp`) |
-| `-g, --godot PATH` | Path to Godot executable |
-| `-c, --configure NAME` | Show config for: `claude`, `cursor`, `cline`, `opencode` |
-| `-h, --help` | Show help message |
-
----
-
-### Install via npm (Fastest)
-
-```bash
-npx gopeak
-```
+### B) Global install
 
-Or install globally:
 ```bash
 npm install -g gopeak
 gopeak
 ```
 
-Then configure your AI assistant to run `gopeak` (or `npx gopeak`) instead of `node /path/to/build/index.js`.
-
----
-
-### Manual Installation
-
-#### Step 1: Install and Build
+### C) From source
 
 ```bash
 git clone https://github.com/HaD0Yun/godot-mcp.git
 cd godot-mcp
 npm install
 npm run build
+node build/index.js
 ```
 
-#### Step 2: Configure with Your AI Assistant
-
-#### Option A: Configure with Cline (VS Code)
-
-Add to your Cline MCP settings file:
-
-**macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-**Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "node",
-      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
-      "env": {
-        "GODOT_PATH": "/path/to/godot",
-        "DEBUG": "true"
-      },
-      "disabled": false
-    }
-  }
-}
-```
-
-#### Option B: Configure with Cursor
-
-1. Go to **Cursor Settings** > **Features** > **MCP**
-2. Click **+ Add New MCP Server**
-3. Name: `godot`, Type: `command`
-4. Command: `node /absolute/path/to/godot-mcp/build/index.js`
-
-#### Option C: Configure with Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "node",
-      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
-      "env": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
-```
-
-#### Option D: Configure with OpenCode
-
-Add to your `opencode.json`:
-
-```json
-{
-  "mcp": {
-    "godot": {
-      "type": "local",
-      "command": ["node", "/absolute/path/to/godot-mcp/build/index.js"],
-      "enabled": true,
-      "environment": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
-```
-
-### Step 3: Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `GODOT_PATH` | Path to Godot executable (auto-detected if not set) |
-| `DEBUG` | Set to "true" for detailed logging |
-
----
-
-## Example Prompts
-
-Once configured, you can use natural language to control Godot:
-
-### Scene Building
-```
-"Create a new scene with a CharacterBody2D root node called Player"
-"Add a Sprite2D and CollisionShape2D to my Player scene"
-"Duplicate the Enemy node and name it Enemy2"
-```
-
-### Script Operations
-```
-"Create a GDScript for my player with movement and jumping"
-"Add a take_damage function to my player script that emits a health_changed signal"
-"Show me the structure of my PlayerController script"
-```
-
-### Resource Management
-```
-"Create a red StandardMaterial3D for my enemy"
-"Create a canvas_item shader with a dissolve effect"
-"Generate a TileSet from my tilemap_atlas.png with 16x16 tiles"
-"Modify the environment resource to enable fog and glow"
-```
-
-### ClassDB Discovery
-```
-"What 3D light types are available in Godot?"
-"Show me all properties of CharacterBody3D"
-"What classes inherit from Control?"
-"Find all instantiable physics body types"
-```
-
-### Project Analysis
-```
-"Check my project health and show me any issues"
-"Find all files that use the PlayerData resource"
-"Show me the dependency graph for my main scene"
-"Search my project for 'TODO' comments"
-```
-
-### Configuration
-```
-"Add a 'jump' input action mapped to Space and gamepad button 0"
-"Register my GameManager script as an autoload singleton"
-"Set the main scene to res://scenes/main_menu.tscn"
-```
-
-### Debugging
-```
-"Run my project and show me any errors"
-"Parse my Godot error log and suggest fixes"
-"Inspect the scene tree of my running game"
-```
-
-### Asset Library
-```
-"Search for a chair model across all asset sources"
-"Find rock textures from AmbientCG"
-"Download the nature-kit asset pack from Kenney"
-"List all available asset providers"
-```
-
-### Screenshot & Input
-```
-"Take a screenshot of the running game"
-"Press the jump action and capture the result"
-"Click at position (400, 300) in the game"
-"Simulate pressing the W key"
-```
-
-### GDScript Analysis (LSP)
-```
-"Check my player script for errors using the language server"
-"Get code completions at line 25 in movement.gd"
-"Show me hover info for the 'velocity' variable"
-"Get the symbol outline for my main script"
-```
+GoPeak also exposes two CLI bin names:
 
-### Debug Adapter
-```
-"Set a breakpoint at line 42 in player.gd"
-"Show me the stack trace"
-"Continue execution after the breakpoint"
-"Get the debug console output"
-```
+- `gopeak`
+- `godot-mcp`
 
 ---
 
-## Included Addons
-
-### Auto Reload Plugin (Recommended)
+## Addons (Recommended)
 
-**Essential for MCP workflow** - automatically reloads scenes and scripts when modified externally.
+### Auto Reload + Runtime Addon installer
 
-#### Installation
+Install in your Godot project folder:
 
-**Option 1: One-Click Install**
-
-**Linux / macOS (Bash)**
 ```bash
-# Run in your Godot project folder
 curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash
 ```
 
-**Windows (PowerShell)**
+PowerShell:
+
 ```powershell
-# Run in your Godot project folder
-irm https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 | iex
+iwr https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex
 ```
 
-**Option 2: Manual Install**
-1. Copy `build/addon/auto_reload` to your project's `addons/` folder
-2. Open your project in Godot
-3. Go to **Project > Project Settings > Plugins**
-4. Enable "Godot MCP Auto Reload"
+Then enable plugin in **Project Settings → Plugins**.
 
-#### How It Works
-
-```
-[1 sec polling] → Check file modification times → Reload changed files
-```
+---
 
-| Feature | Detail |
-|---------|--------|
-| **Performance** | ~0.01ms per second (negligible) |
-| **Watched Files** | Current scene + attached scripts |
-| **Detection** | OS file modification timestamp |
-| **Reload Method** | `EditorInterface.reload_scene_from_path()` |
+## Core Capabilities
+
+- **Project control**: launch editor, run/stop project, capture debug output
+- **Scene editing**: create scenes, add/delete/reparent nodes, edit properties
+- **Script workflows**: create/modify scripts, inspect script structure
+- **Resources**: create/modify resources, materials, shaders, tilesets
+- **Signals/animation**: connect signals, build animations/tracks/state machines
+- **Runtime tools**: inspect live tree, set properties, call methods, metrics
+- **LSP + DAP**: diagnostics/completion/hover + breakpoints/step/stack trace
+- **Input + screenshots**: keyboard/mouse/action injection and viewport capture
+- **Asset library**: search/fetch CC0 assets (Poly Haven, AmbientCG, Kenney)
+
+### Tool families (examples)
+
+| Area | Examples |
+|---|---|
+| Project | `project.list`, `project.info`, `editor.run` |
+| Scene/Node | `scene.create`, `scene.node.add`, `set_node_properties` |
+| Script | `script.create`, `script.modify`, `script.info` |
+| Runtime | `runtime.status`, `inspect_runtime_tree`, `call_runtime_method` |
+| LSP/DAP | `lsp.diagnostics`, `lsp_get_hover`, `dap_set_breakpoint`, `dap.output` |
+| Input/Visual | `inject_key`, `inject_mouse_click`, `capture_screenshot` |
 
-#### Output Messages
-```
-[Godot MCP - AutoReload] Plugin activated - watching for external changes
-[Godot MCP - AutoReload] Scene changed: res://scenes/player.tscn
-[Godot MCP - AutoReload] Scene reloaded: res://scenes/player.tscn
-```
+---
 
-#### Warning
+## Project Visualizer
 
-**Data Loss Risk**: If you modify a scene in the editor AND externally at the same time, editor changes will be lost.
+Visualize your entire project architecture with `visualizer.map` (`map_project` legacy). Scripts are grouped by folder structure into color-coded categories.
 
-**Best Practice**:
-- Use MCP for modifications
-- Use Godot editor for viewing/testing only
-- Save before external modifications
+![Project Visualizer — AI-generated architecture map](assets/visualizer-category-map.png)
 
 ---
 
-### Runtime Addon (Optional)
+## Quick Prompt Examples
 
-For live debugging features, install the runtime addon:
+### Build
+- "Create a Player scene with CharacterBody2D, Sprite2D, CollisionShape2D, and a basic movement script."
+- "Add an enemy spawner scene and wire spawn signals to GameManager."
 
-1. Copy `build/addon/godot_mcp_runtime` to your project's `addons/` folder
-2. Enable in **Project Settings > Plugins**
-3. The addon starts a TCP server on port 7777 when your game runs
+### Debug
+- "Run the project, collect errors, and fix the top 3 issues automatically."
+- "Set a breakpoint at `scripts/player.gd:42`, continue execution, and show stack trace when hit."
 
-**Runtime Tools:**
-- `get_runtime_status` - Check if game is running
-- `inspect_runtime_tree` - View live scene tree
-- `set_runtime_property` - Modify properties in real-time
-- `call_runtime_method` - Invoke methods remotely
-- `get_runtime_metrics` - Monitor FPS, memory, draw calls
-- `capture_screenshot` - Capture viewport as base64 image
-- `capture_viewport` - Capture specific viewport texture
-- `inject_action` / `inject_key` / `inject_mouse_click` / `inject_mouse_motion` - Input simulation
+### Runtime testing
+- "Press `ui_accept`, move mouse to (400, 300), click, then capture a screenshot."
+- "Inspect live scene tree and report nodes with missing scripts or invalid references."
 
----
-
-## Complete Tool Reference
-
-### Core Tools (7)
-| Tool | Description |
-|------|-------------|
-| `launch_editor` | Open Godot editor for a project |
-| `run_project` | Execute project in debug mode |
-| `stop_project` | Stop running project |
-| `get_debug_output` | Get console output and errors |
-| `get_godot_version` | Get installed Godot version |
-| `list_projects` | Find projects in a directory |
-| `get_project_info` | Get project structure info |
-
-### Scene Tools (9)
-| Tool | Description |
-|------|-------------|
-| `create_scene` | Create new scene file |
-| `add_node` | Add ANY node type to scene (universal — replaces all specialized create_* node tools) |
-| `delete_node` | Remove node from scene |
-| `duplicate_node` | Clone node in scene |
-| `reparent_node` | Move node to new parent |
-| `list_scene_nodes` | Get scene tree structure |
-| `get_node_properties` | Get all node properties |
-| `set_node_properties` | Set multiple properties |
-| `save_scene` | Save scene changes |
-
-### Script Tools (3)
-| Tool | Description |
-|------|-------------|
-| `create_script` | Create GDScript with templates |
-| `modify_script` | Add functions/variables/signals |
-| `get_script_info` | Analyze script structure |
-
-### ClassDB Introspection Tools (3)
-| Tool | Description |
-|------|-------------|
-| `query_classes` | Discover available Godot classes with filtering by name, category, and instantiability |
-| `query_class_info` | Get methods, properties, signals, and enums for any class |
-| `inspect_inheritance` | Explore class hierarchy — ancestors, children, all descendants |
-
-### Resource Tools (7)
-| Tool | Description |
-|------|-------------|
-| `create_resource` | Create ANY resource type as .tres file |
-| `modify_resource` | Modify properties of existing .tres/.res files |
-| `create_material` | Create material resource |
-| `create_shader` | Create shader file |
-| `load_sprite` | Load texture into Sprite2D |
-| `export_mesh_library` | Export as MeshLibrary |
-| `create_tileset` | Create TileSet resource |
-
-### Animation Tools (2)
-| Tool | Description |
-|------|-------------|
-| `create_animation` | Create animation in AnimationPlayer |
-| `add_animation_track` | Add track with keyframes |
-
-### Signal Tools (3)
-| Tool | Description |
-|------|-------------|
-| `connect_signal` | Connect signal to method |
-| `disconnect_signal` | Remove signal connection |
-| `list_connections` | List all connections in scene |
-
-### Import/Export Tools (7)
-| Tool | Description |
-|------|-------------|
-| `get_import_status` | Check resource import status |
-| `get_import_options` | Get import settings |
-| `set_import_options` | Modify import settings |
-| `reimport_resource` | Trigger reimport |
-| `list_export_presets` | List export configurations |
-| `export_project` | Build for distribution |
-| `validate_project` | Check export readiness |
-
-### Configuration Tools (7)
-| Tool | Description |
-|------|-------------|
-| `get_project_setting` | Read project setting |
-| `set_project_setting` | Write project setting |
-| `add_autoload` | Register singleton |
-| `remove_autoload` | Unregister singleton |
-| `list_autoloads` | List all autoloads |
-| `set_main_scene` | Set startup scene |
-| `add_input_action` | Add input mapping |
-
-### Plugin Tools (3)
-| Tool | Description |
-|------|-------------|
-| `list_plugins` | List installed plugins |
-| `enable_plugin` | Enable a plugin |
-| `disable_plugin` | Disable a plugin |
-
-### DX Tools (5)
-| Tool | Description |
-|------|-------------|
-| `get_dependencies` | Map resource dependencies |
-| `find_resource_usages` | Find all resource references |
-| `parse_error_log` | Parse errors with suggestions |
-| `get_project_health` | Comprehensive health check |
-| `search_project` | Search across all files |
-
-### Runtime Tools (5)
-| Tool | Description |
-|------|-------------|
-| `get_runtime_status` | Check runtime connection |
-| `inspect_runtime_tree` | Live scene inspection |
-| `set_runtime_property` | Modify runtime property |
-| `call_runtime_method` | Call method on running node |
-| `get_runtime_metrics` | Get performance metrics |
-
-### UID Tools (2)
-| Tool | Description |
-|------|-------------|
-| `get_uid` | Get file UID (Godot 4.4+) |
-| `update_project_uids` | Regenerate UIDs |
-
-### Asset Library Tools (3)
-| Tool | Description |
-|------|-------------|
-| `search_assets` | Search CC0 assets across Poly Haven, AmbientCG, and Kenney |
-| `fetch_asset` | Download asset to your Godot project |
-| `list_asset_providers` | List available providers and their capabilities |
-
-### Screenshot Tools (2)
-| Tool | Description |
-|------|-------------|
-| `capture_screenshot` | Capture running game viewport as base64 image |
-| `capture_viewport` | Capture a specific viewport node's texture |
-
-### Input Injection Tools (4)
-| Tool | Description |
-|------|-------------|
-| `inject_action` | Simulate Godot input action press/release |
-| `inject_key` | Simulate keyboard key event with modifiers |
-| `inject_mouse_click` | Simulate mouse click at position |
-| `inject_mouse_motion` | Simulate mouse movement |
-
-### GDScript LSP Tools (4)
-| Tool | Description |
-|------|-------------|
-| `lsp_get_diagnostics` | Get errors/warnings from Godot Language Server |
-| `lsp_get_completions` | Get code completions at a position |
-| `lsp_get_hover` | Get hover info for a symbol |
-| `lsp_get_symbols` | Get document symbol outline |
-
-### DAP (Debug) Tools (7)
-| Tool | Description |
-|------|-------------|
-| `dap_get_output` | Get captured debug console output |
-| `dap_set_breakpoint` | Set breakpoint in a GDScript file |
-| `dap_remove_breakpoint` | Remove a breakpoint |
-| `dap_continue` | Continue execution after breakpoint |
-| `dap_pause` | Pause running debug target |
-| `dap_step_over` | Step over current line |
-| `dap_get_stack_trace` | Get current stack trace |
+### Discovery in compact mode
+- "Use `tool.catalog` with query `tilemap` and list the most relevant tools."
+- "Find import pipeline tools with `tool.catalog` query `import` and run the best one for texture settings."
 
 ---
 
-## Architecture
+## Technical Reference
 
-GoPeak uses a hybrid architecture:
+### Environment variables
 
-1. **Direct CLI Commands**: Simple operations use Godot's built-in CLI
-2. **Bundled GDScript**: Complex operations use a comprehensive `godot_operations.gd` script with ClassDB introspection
-3. **Runtime Addon**: TCP server (port 7777) for live debugging, screenshot capture, and input injection
-4. **Godot LSP Integration**: Connects to Godot editor's Language Server (port 6005) for GDScript diagnostics
-5. **Godot DAP Integration**: Connects to Godot editor's Debug Adapter (port 6006) for breakpoints and stepping
-6. **MCP Resources**: `godot://` URI protocol for direct project file access
+| Name | Purpose | Default |
+|---|---|---|
+| `GOPEAK_TOOL_PROFILE` | Tool exposure profile: `compact`, `full`, `legacy` | `compact` |
+| `MCP_TOOL_PROFILE` | Fallback profile env alias | `compact` |
+| `GODOT_PATH` | Explicit Godot executable path | auto-detect |
+| `DEBUG` | Enable server debug logs (`true`/`false`) | `false` |
+| `LOG_MODE` | Recording mode: `lite` or `full` | `lite` |
 
-**Key Design Decisions:**
-- **ClassDB-based dynamic approach**: Instead of hardcoding tools for every Godot class, generic tools (`add_node`, `create_resource`) work with ANY class. AI discovers capabilities via `query_classes` and `query_class_info`
-- **Type-safe serialization**: Automatic conversion for Vector2, Vector3, Color, Rect2, NodePath, and other Godot types
-- **No temporary files**: Everything runs through the bundled GDScript operations dispatcher
-- **Consistent error handling**: All operations validate inputs and provide meaningful error messages
+### Ports
 
----
+| Port | Service |
+|---|---|
+| `6505` | Unified Godot Bridge + Visualizer server (+ `/health`, `/mcp`) |
+| `6005` | Godot LSP |
+| `6006` | Godot DAP |
+| `7777` | Runtime addon command socket (only needed for runtime tools) |
 
-## Troubleshooting
+### Minimal port profiles
 
-| Issue | Solution |
-|-------|----------|
-| Godot not found | Set `GODOT_PATH` environment variable |
-| Connection issues | Restart your AI assistant |
-| Invalid project path | Ensure path contains `project.godot` |
-| Build errors | Run `npm install` to install dependencies |
-| Runtime tools not working | Install and enable the addon in your project |
+- **Core editing only**: `6505`
+- **Core + runtime actions (screenshots/input/runtime inspect)**: `6505` + `7777`
+- **Full debugging + diagnostics**: `6505` + `6005` + `6006` + `7777`
 
 ---
 
-## Contributing
+## Troubleshooting
 
-Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
+- **Godot not found** → set `GODOT_PATH`
+- **No MCP tools visible** → restart your MCP client
+- **Project path invalid** → confirm `project.godot` exists
+- **Runtime tools not working** → install/enable runtime addon plugin
+- **Need a tool that is not visible** → run `tool.catalog` and search by capability keyword
 
 ---
 
-## License
+## Docs & Project Links
 
-MIT License - see [LICENSE](LICENSE) for details.
+- [CHANGELOG](CHANGELOG.md)
+- [ROADMAP](ROADMAP.md)
+- [CONTRIBUTING](CONTRIBUTING.md)
 
 ---
 
-## Stats
-
-- **95+ Tools** — comprehensive tools covering scene management, scripting, resources, animation, configuration, debugging, screenshots, input injection, LSP, DAP, and asset management
-- **MCP Resources** — `godot://` URI protocol for direct project file access
-- **GDScript LSP** — real-time diagnostics, completions, hover, and symbols via Godot's Language Server
-- **Debug Adapter (DAP)** — breakpoints, stepping, stack traces, and console output capture
-- **Screenshot Capture** — viewport capture from running games via runtime addon
-- **Input Injection** — keyboard, mouse, and action simulation for automated testing
-- **ClassDB Introspection** — AI dynamically discovers Godot classes, properties, and methods instead of relying on hardcoded tool definitions
-- **20,000+ lines** of TypeScript and GDScript
-- **~85% coverage** of Godot Engine's capabilities
-- **Godot 4.x** full support (including 4.4+ UID features)
-- **Auto Reload** plugin for seamless MCP integration
-- **Multi-Source Asset Library** with CC0 assets from Poly Haven, AmbientCG, and Kenney
-- **npm package** — install with `npx gopeak` or `npm install -g gopeak`
+## License
 
----
+MIT — see [LICENSE](LICENSE).
 
 ## Credits
 
 - Original MCP server by [Coding-Solo](https://github.com/Coding-Solo/godot-mcp)
-- Auto Reload plugin and unified package by [HaD0Yun](https://github.com/HaD0Yun)
+- GoPeak enhancements by [HaD0Yun](https://github.com/HaD0Yun)
+- Project visualizer inspired by [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp)