gopeak 2.0.1 → 2.1.0

package/README.md

@@ -5,429 +5,71 @@
 [![](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
-                           (((((((             (((((((                          
-                        (((((((((((           (((((((((((                      
-                        (((((((((((((       (((((((((((((                       
-                        (((((((((((((((((((((((((((((((((                       
-                        (((((((((((((((((((((((((((((((((                       
-         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
-       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
-     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
-    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
-      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
-        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
-         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
-         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
-         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
-         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
-         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
-         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
-         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
-         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
-         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
-         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
-         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
-          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
-           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
-              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
-                 (((((((((((((((((((((((((((((((((((((((((((((((                
-                        (((((((((((((((((((((((((((((((((                       
-                                                                                
-
-        /$$$$$$             /$$$$$$$                      /$$      
-       /$$__  $$           | $$__  $$                    | $$      
-      | $$  \__/  /$$$$$$ | $$  \ $$ /$$$$$$   /$$$$$$$ | $$  /$$/
-      | $$ /$$$$//$$__  $$| $$$$$$$//$$__  $$ |____  $$ | $$ /$$/ 
-      | $$|_  $$| $$  \ $$| $$____/| $$$$$$$$  /$$$$$$$ | $$$$$/  
-      | $$  \ $$| $$  | $$| $$     | $$_____/ /$$__  $$ | $$  $$  
-      |  $$$$$$/|  $$$$$$/| $$     |  $$$$$$ |  $$$$$$$ | $$\  $$ 
-       \______/  \______/ |__/      \______/  \_______/ |__/ \__/ 
-```
+![GoPeak Hero](assets/gopeak-hero-v2.png)
 
-**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 is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real projects end-to-end.**
 
-> **Now with Auto Reload!** Scenes and scripts automatically refresh in the Godot editor when modified externally via MCP.
+> Includes Auto Reload: when MCP edits scenes/scripts, the Godot editor refreshes automatically.
 
 ---
 
-## 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.
-
-| 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 |
-
-> **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.
-
-#### 3. **Seamless Editor Integration with Auto Reload**
-
-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
-```
-
-#### 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
-
-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**
-
-The `get_project_health` tool provides a comprehensive analysis of your project:
-
-```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"
-  ]
-}
-```
-
-This turns your AI assistant into a **code reviewer that actually understands your Godot project**.
-
-#### 7. **Dependency Analysis & Circular Reference Detection**
-
-Ever had a project break because of circular dependencies? The `get_dependencies` tool:
-
-- 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
-```
-
-#### 8. **Live Runtime Debugging (Optional Addon)**
-
-Install the included `godot_mcp_runtime` addon and unlock:
-
-- **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
-
-This transforms debugging from "add print statements and restart" to "inspect and modify on the fly."
-
-### 💡 Real-World Use Cases
-
-#### **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.
-
-#### **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.
+## Why GoPeak (Short Version)
 
-#### **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.
+- **Real project feedback loop**: run the game, read logs, fix issues in-context.
+- **95+ tools** across scene, script, resource, runtime, LSP, DAP, input, and assets.
+- **Deep Godot integration**: ClassDB introspection, runtime inspection, debugger hooks.
+- **Faster iteration**: less copy-paste, more direct implementation/testing.
 
-#### **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.
+### Best For
 
-#### **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.
+- Solo/indie developers building quickly with AI assistance
+- Teams that want AI to inspect real project state, not just generate snippets
+- Debug-heavy workflows where runtime introspection and breakpoints matter
 
 ---
 
-## 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 |
+## GoPeak vs Upstream (Coding-Solo/godot-mcp)
+
+| Capability | Upstream | GoPeak |
+|---|---|---|
+| GDScript LSP tools | Not available in README tool list | ✅ `lsp_get_diagnostics`, `lsp_get_completions`, `lsp_get_hover`, `lsp_get_symbols` |
+| DAP debugging tools | Not available in README tool list | ✅ breakpoints, step/continue/pause, stack trace, debug output |
+| Input injection tools | Not available in README tool list | ✅ `inject_action`, `inject_key`, `inject_mouse_click`, `inject_mouse_motion` |
+| Screenshot capture tools | Not available in README tool list | ✅ `capture_screenshot`, `capture_viewport` |
+| Auto Reload editor plugin | Not available | ✅ included `auto_reload` addon |
+| Tool coverage scale | Smaller documented scope | ✅ 95+ MCP tools |
 
 ---
 
 ## Requirements
 
-- [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.)
+- Godot 4.x
+- Node.js 18+
+- MCP-compatible client (Claude Desktop, Cursor, Cline, OpenCode, etc.)
 
 ---
 
-## Installation and Configuration
+## Installation
 
-### 🚀 One-Click Install (Recommended)
-
-**Linux / macOS**
-```bash
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install.sh | bash
-```
-
-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
-
-**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
-```
-
-**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)
+### 1) Fastest (recommended)
 
 ```bash
 npx gopeak
 ```
 
-Or install globally:
+or
+
 ```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
+### 2) Manual (from source)
 
 ```bash
 git clone https://github.com/HaD0Yun/godot-mcp.git
@@ -436,48 +78,19 @@ npm install
 npm run build
 ```
 
-#### Step 2: Configure with Your AI Assistant
+Set `GODOT_PATH` if Godot is not auto-detected.
 
-#### Option A: Configure with Cline (VS Code)
+### MCP Client Config (practical examples)
 
-Add to your Cline MCP settings file:
+Use one of these depending on your client.
 
-**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`
+**A) Global install (`npm install -g gopeak`)**
 
 ```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"],
+      "command": "gopeak",
       "env": {
         "GODOT_PATH": "/path/to/godot"
       }
@@ -486,18 +99,15 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-#### Option D: Configure with OpenCode
-
-Add to your `opencode.json`:
+**B) No global install (npx mode)**
 
 ```json
 {
-  "mcp": {
+  "mcpServers": {
     "godot": {
-      "type": "local",
-      "command": ["node", "/absolute/path/to/godot-mcp/build/index.js"],
-      "enabled": true,
-      "environment": {
+      "command": "npx",
+      "args": ["-y", "gopeak"],
+      "env": {
         "GODOT_PATH": "/path/to/godot"
       }
     }
@@ -505,405 +115,88 @@ Add to your `opencode.json`:
 }
 ```
 
-### Step 3: Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `GODOT_PATH` | Path to Godot executable (auto-detected if not set) |
-| `DEBUG` | Set to "true" for detailed logging |
+> Tip: If your client uses `args` array style only, use `"command": "npx"` + `"args": ["-y", "gopeak"]`.
 
 ---
 
-## Example Prompts
+## Core Capabilities
 
-Once configured, you can use natural language to control Godot:
+- **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)
 
-### 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"
-```
+### Tool Coverage at a Glance
 
-### 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"
-```
+| Area | Examples |
+|---|---|
+| Scene/Node | `create_scene`, `add_node`, `set_node_properties` |
+| Script | `create_script`, `modify_script`, `get_script_info` |
+| Runtime | `inspect_runtime_tree`, `call_runtime_method` |
+| LSP/DAP | `lsp_get_diagnostics`, `dap_set_breakpoint` |
+| Input/Visual | `inject_key`, `inject_mouse_click`, `capture_screenshot` |
 
-### 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"
-```
+## Quick Prompt Examples
 
-### 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"
-```
+### 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."
 
-### 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"
-```
+### 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 the stack trace when hit."
 
-### 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"
-```
+### Runtime Testing
+- "Press `ui_accept`, move mouse to (400, 300), click, then capture a screenshot."
+- "Inspect the live scene tree and report nodes with missing scripts or invalid references."
 
-### 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"
-```
-
-### 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"
-```
+### Refactor / Maintenance
+- "Find all TODO/FIXME comments and group them by file with a priority suggestion."
+- "Analyze project health and list quick wins to improve stability before release."
 
 ---
 
-## Included Addons
-
-### Auto Reload Plugin (Recommended)
-
-**Essential for MCP workflow** - automatically reloads scenes and scripts when modified externally.
-
-#### Installation
+## Auto Reload Addon (Recommended)
 
-**Option 1: One-Click Install**
+Install in your Godot project folder:
 
-**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
-# Run in your Godot project folder
-irm https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 | 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"
-
-#### 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()` |
-
-#### 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
-
-**Data Loss Risk**: If you modify a scene in the editor AND externally at the same time, editor changes will be lost.
-
-**Best Practice**:
-- Use MCP for modifications
-- Use Godot editor for viewing/testing only
-- Save before external modifications
-
----
-
-### Runtime Addon (Optional)
-
-For live debugging features, install the runtime addon:
-
-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
-
-**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
-
----
-
-## 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 |
-
----
-
-## Architecture
-
-GoPeak uses a hybrid architecture:
-
-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
-
-**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
+Then enable plugin in **Project Settings → Plugins**.
 
 ---
 
 ## Troubleshooting
 
-| 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 |
+- **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
 
 ---
 
-## Contributing
+## Docs & Project Links
 
-Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
+- [CHANGELOG](CHANGELOG.md)
+- [ROADMAP](ROADMAP.md)
+- [CONTRIBUTING](CONTRIBUTING.md)
 
 ---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-## 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`
-
----
+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)