Tighten README: clear install steps, collapse details, extract dev docs

dsarno · claude · dsarno · commit 1b01c2cf4503 · 2026-04-12T16:47:31.000-07:00
Move development setup, testing, and PR workflow into
docs/CONTRIBUTING.md. Simplify install instructions with concrete
git clone + cp commands. Collapse tools, resources, and manual config
into &lt;details&gt; sections.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -7,100 +7,56 @@
 [![CI](https://github.com/hi-godot/godot-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/hi-godot/godot-ai/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/hi-godot/godot-ai/graph/badge.svg)](https://codecov.io/gh/hi-godot/godot-ai)
 
-Connect MCP clients directly to a live Godot editor.
+**Connect MCP clients directly to a live Godot editor.** Godot AI bridges AI assistants (Claude Code, Codex, Antigravity, etc.) with your Godot Editor via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Inspect scenes, create nodes, search project data, run tests, and read structured editor resources — all from a prompt.
 
-Godot AI exposes the Godot editor over MCP so tools like Claude Code and other HTTP-capable MCP clients can inspect scenes, search project data, create nodes, run tests, and read structured editor resources from a real project.
+> **Status:** early, usable, and still expanding.
 
-> **Status:** early, usable, and still expanding. The current build already supports scene and project inspection, node creation, in-editor test execution, multi-session routing, client configuration, and MCP resources.
+*Independent community project, not affiliated with the [Godot Foundation](https://godot.foundation). Godot Engine is [MIT-licensed](https://godotengine.org/license).*
 
-*This is an independent community project, not affiliated with or endorsed by the [Godot Foundation](https://godot.foundation). Godot Engine is a free and open-source project under the [MIT license](https://godotengine.org/license).*
-
-## What It Does
-
-- Bridges a running Godot editor to MCP over HTTP.
-- Exposes editor state, scene data, selection, project settings, logs, and sessions as tools and resources.
-- Lets an MCP client create nodes and inspect the project without custom per-client glue.
-- Runs GDScript test suites inside the connected editor and returns structured results.
-- Supports multiple connected Godot sessions with explicit active-session routing.
+---
 
 ## Quick Start
 
 ### Prerequisites
 
 - Godot `4.3+` (`4.4+` recommended)
-- [uv](https://docs.astral.sh/uv/) for user installs
-- An MCP client that can connect to an HTTP MCP server
+- [uv](https://docs.astral.sh/uv/) (used to install the Python server)
+- An MCP client ([Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [Codex](https://openai.com/index/codex/) | [Antigravity](https://www.antigravity.dev/))
 
 ### 1. Install the plugin
 
-Copy `plugin/addons/godot_ai/` into your Godot project's `addons/` folder.
-
-### 2. Enable the plugin
-
-In Godot, open **Project > Project Settings > Plugins** and enable **Godot AI**.
-
-When enabled, the plugin will:
+Clone the repo (or [download the zip](https://github.com/hi-godot/godot-ai/archive/refs/heads/main.zip)) and copy the plugin into your Godot project:
 
-- start or reuse the shared MCP server
-- connect the editor to the server over WebSocket
-- show connection state, client configuration, and logs in the Godot AI dock
+```bash
+git clone https://github.com/hi-godot/godot-ai.git
+cp -r godot-ai/plugin/addons/godot_ai your-project/addons/
+```
 
-The launcher checks for a local development checkout first, then falls back to `uvx`, then a system `godot-ai` install.
+### 2. Enable the plugin
 
-### 3. Connect an MCP client
+In Godot: **Project > Project Settings > Plugins** — enable **Godot AI**.
 
-The dock includes **Configure** buttons for supported clients:
+The plugin will automatically start the MCP server, connect over WebSocket, and show status in the **Godot AI** dock.
 
-- `Claude Code`
-- `Codex`
-- `Antigravity`
+### 3. Connect your MCP client
 
-For other clients, point them at:
+Click a **Configure** button in the dock, or point any HTTP MCP client at:
 
 ```text
 http://127.0.0.1:8000/mcp
 ```
 
-<details>
-<summary><strong>Manual client configuration examples</strong></summary>
-
-**Claude Code**
-
-```bash
-claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8000/mcp
-```
-
-**Codex** (`~/.codex/config.toml`)
-
-```toml
-[mcp_servers."godot-ai"]
-url = "http://127.0.0.1:8000/mcp"
-enabled = true
-```
-
-**Antigravity** (`~/.gemini/antigravity/mcp_config.json`)
-
-```json
-{
-  "mcpServers": {
-    "godot-ai": {
-      "serverUrl": "http://127.0.0.1:8000/mcp",
-      "disabled": false
-    }
-  }
-}
-```
-</details>
+### 4. Try it
 
-### 4. Try a few prompts
+- *"Show me the current scene hierarchy."*
+- *"Create a Camera3D named MainCamera under /Main."*
+- *"Search the project for PackedScene files in ui/."*
+- *"Run the scene test suite."*
 
-- `Show me the current scene hierarchy.`
-- `What nodes are currently selected in the editor?`
-- `Create a Camera3D named MainCamera under /Main.`
-- `Search the project for PackedScene files in ui/.`
-- `Run the scene test suite.`
+---
 
-## Capabilities
+<details>
+<summary><strong>Available Tools</strong></summary>
 
 ### Sessions and Editor
 
@@ -113,19 +69,19 @@ enabled = true
 | `logs_read` | Read recent MCP log lines from the editor |
 | `reload_plugin` | Reload the Godot editor plugin and wait for reconnect |
 
-### Scene and Node Workflows
+### Scene and Nodes
 
 | Tool | Description |
 |------|-------------|
-| `scene_get_hierarchy` | Read the scene tree with pagination support |
+| `scene_get_hierarchy` | Read the scene tree with pagination |
 | `scene_get_roots` | List open scenes in the editor |
 | `node_create` | Create a node by type with optional name and parent path |
 | `node_find` | Search nodes by name, type, or group |
 | `node_get_properties` | Read all properties for a node |
 | `node_get_children` | Read direct children for a node |
 | `node_get_groups` | Read group membership for a node |
 
-### Project and Test Workflows
+### Project and Testing
 
 | Tool | Description |
 |------|-------------|
@@ -141,9 +97,10 @@ enabled = true
 | `client_configure` | Configure a supported MCP client from the editor |
 | `client_status` | Check which supported clients are configured |
 
-## Resources
+</details>
 
-Godot AI also exposes structured MCP resources for clients that prefer reading state directly.
+<details>
+<summary><strong>MCP Resources</strong></summary>
 
 | Resource URI | Description |
 |-------------|-------------|
@@ -155,70 +112,67 @@ Godot AI also exposes structured MCP resources for clients that prefer reading s
 | `godot://project/settings` | Common project settings subset |
 | `godot://logs/recent` | Recent editor log lines |
 
-## Default Ports
+</details>
+
+<details>
+<summary><strong>Manual Client Configuration</strong></summary>
+
+**Claude Code**
+
+```bash
+claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8000/mcp
+```
+
+**Codex** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers."godot-ai"]
+url = "http://127.0.0.1:8000/mcp"
+enabled = true
+```
+
+**Antigravity** (`~/.gemini/antigravity/mcp_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "godot-ai": {
+      "serverUrl": "http://127.0.0.1:8000/mcp",
+      "disabled": false
+    }
+  }
+}
+```
 
-| Port | Purpose |
-|------|---------|
-| `9500` | WebSocket link between Godot and the Python server |
-| `8000` | HTTP MCP endpoint for clients (`/mcp`) |
+</details>
 
-## How It Works
+<details>
+<summary><strong>How It Works</strong></summary>
 
 ```text
 MCP Client
-   | HTTP MCP
+   | HTTP (/mcp)
    v
-Python Server (FastMCP)
-   | WebSocket
+Python Server (FastMCP)      port 8000
+   | WebSocket               port 9500
    v
 Godot Editor Plugin
    | EditorInterface + SceneTree APIs
    v
 Godot Editor
 ```
 
-The Godot plugin is the bridge to the live editor. It starts or reuses the Python server, connects over WebSocket, and exposes editor capabilities as MCP tools and resources over HTTP.
-
-## Development
-
-```bash
-# Create the local dev environment
-script/setup-dev
-
-# Activate the environment
-source .venv/bin/activate
-
-# Run Python tests
-pytest -v
-
-# Lint
-ruff check src/ tests/
-
-# Start the MCP server manually in dev mode
-python -m godot_ai --transport streamable-http --port 8000 --reload
-```
-
-For Godot-side coverage, use the `run_tests` MCP tool against the sample project or a connected editor session.
-
-## Contributing
+The plugin starts or reuses the Python server, connects over WebSocket, and exposes editor capabilities as MCP tools and resources over HTTP.
 
-- Work on feature branches off `main`.
-- Keep Python tests and lint clean before opening a PR.
-- Add tests for new behavior where practical, including Godot-side tests when the change crosses the plugin boundary.
+</details>
 
-```bash
-git checkout -b feature/my-feature
-source .venv/bin/activate
-pytest -v
-ruff check src/ tests/
-git push -u origin feature/my-feature
-gh pr create
-```
+<details>
+<summary><strong>Contributing</strong></summary>
 
-## Visual Roadmap
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup, testing, and PR guidelines.
 
-The current README is still light on visuals. A prioritized asset punch list lives in [docs/readme-visual-punchlist.md](docs/readme-visual-punchlist.md).
+</details>
 
-## License
+---
 
-A repository license file has not been added yet.
+**License:** A repository license file has not been added yet. | **Issues:** [GitHub](https://github.com/hi-godot/godot-ai/issues)
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing to Godot AI
+
+## Development Setup
+
+```bash
+git clone https://github.com/hi-godot/godot-ai.git
+cd godot-ai
+script/setup-dev             # creates .venv, installs deps
+source .venv/bin/activate
+```
+
+## Testing
+
+### Python tests
+
+```bash
+pytest -v                    # unit + integration tests
+ruff check src/ tests/       # lint
+ruff format src/ tests/      # format
+```
+
+### Godot-side tests
+
+GDScript test suites run inside the connected editor via MCP:
+
+```
+run_tests                    # run all suites
+run_tests suite=scene        # run one suite
+get_test_results             # review last results
+```
+
+## Dev Server with Auto-Reload
+
+For Python-side changes without restarting Godot:
+
+```bash
+python -m godot_ai --transport streamable-http --port 8000 --reload
+```
+
+The Godot AI dock also has a **Start/Stop Dev Server** button when running from a dev checkout.
+
+## PR Workflow
+
+1. Branch off `main`
+2. Keep tests and lint clean
+3. Add tests for new behavior — both Python and Godot-side when crossing the plugin boundary
+
+```bash
+git checkout -b feature/my-feature
+pytest -v && ruff check src/ tests/
+git push -u origin feature/my-feature
+gh pr create
+```
