Add MCP resources, pagination, and full-stack test coverage

Add 6 new MCP resources (scene/current, scene/hierarchy,
selection/current, project/info, project/settings, logs/recent)
alongside the existing sessions resource. Add offset/limit
pagination to scene_get_hierarchy, logs_read, node_find, and
filesystem_search tools. Fix all resources to return JSON strings
(FastMCP requires str, not dict).

New full-stack integration tests exercise every tool and resource
through the complete FastMCP Client → MCP server → WebSocket →
mock Godot plugin pipeline. Coverage up from 68% to 87%.

89 Python tests, 44 Godot-side tests (133 total).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dsarno

CLAUDE.md

@@ -54,7 +54,7 @@ python -m godot_ai --transport streamable-http --port 8000 --reload
 
 ### Python tests
 ```bash
-pytest -v                    # 38 unit + integration tests
+pytest -v                    # 89 unit + integration tests
 ```
 
 ### Godot-side tests

README.md

@@ -95,6 +95,18 @@ claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8000/mcp
 | `client_configure` | Configure an MCP client (Claude Code / Antigravity) |
 | `client_status` | Check which clients are configured |
 
+## Resources
+
+| Resource URI | Description |
+|-------------|-------------|
+| `godot://sessions` | All connected editor sessions with metadata |
+| `godot://scene/current` | Current scene path, project name, play state |
+| `godot://scene/hierarchy` | Full scene tree (nodes, types, paths) |
+| `godot://selection/current` | Currently selected nodes |
+| `godot://project/info` | Project name, Godot version, paths |
+| `godot://project/settings` | Common settings (display, physics, rendering) |
+| `godot://logs/recent` | Last 100 log lines from the editor console |
+
 ## Ports
 
 | Port | Purpose |
@@ -113,7 +125,7 @@ claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8000/mcp
 # Setup (handles macOS Python 3.13 .pth fix automatically)
 script/setup-dev
 
-# Run Python tests (38 unit + integration)
+# Run Python tests (89 unit + integration)
 pytest -v
 
 # Run Godot-side tests (44 handler tests, requires editor running)
@@ -126,6 +138,22 @@ ruff check src/ tests/
 python -m godot_ai --transport streamable-http --port 8000 --reload
 ```
 
+### Contributing
+
+Work on feature branches and open PRs against `main`:
+
+```bash
+git checkout -b feature/my-feature
+# ... make changes ...
+pytest -v                    # Python tests must pass
+ruff check src/ tests/       # Lint must pass
+# Also run Godot-side tests via the run_tests MCP tool
+git push -u origin feature/my-feature
+gh pr create
+```
+
+PRs should include tests for new functionality (both Python and Godot-side where applicable).
+
 ## License
 
 TBD

docs/implementation-plan.md

@@ -448,10 +448,10 @@ Large results (scene trees with 1000+ nodes, long log buffers) need pagination:
 - [x] Batch 1: Session and editor tools
 - [x] Batch 2: Scene read tools (6 tools)
 - [x] Batch 3: Project reads (project_settings.get, filesystem.search)
-- [ ] Batch 4: MCP Resources
+- [x] Batch 4: MCP Resources (7 resources: sessions, scene/current, scene/hierarchy, selection/current, project/info, project/settings, logs/recent)
 - [x] Batch 5: Editor dock panel with setup status
-- [x] Batch 6: Test harness (35 Godot-side + 32 Python = 67 total tests)
-- [ ] Pagination for large results
+- [x] Batch 6: Test harness (44 Godot-side + 89 Python = 133 total tests)
+- [x] Pagination for large results (offset/limit on scene_get_hierarchy, logs_read, node_find, filesystem_search)
 - [ ] Manual test: Claude describes the open scene
 
 ---

src/godot_ai/resources/editor.py

@@ -0,0 +1,27 @@
+"""MCP resources for editor state — selection and logs."""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import Context, FastMCP
+
+
+def register_editor_resources(mcp: FastMCP) -> None:
+    @mcp.resource("godot://selection/current", mime_type="application/json")
+    async def get_current_selection(ctx: Context) -> str:
+        """Currently selected nodes in the Godot editor."""
+        app = ctx.lifespan_context
+        try:
+            return json.dumps(await app.client.send("get_selection"))
+        except (ConnectionError, Exception) as e:
+            return json.dumps({"error": str(e), "connected": False})
+
+    @mcp.resource("godot://logs/recent", mime_type="application/json")
+    async def get_recent_logs(ctx: Context) -> str:
+        """Last 100 log lines from the Godot editor console."""
+        app = ctx.lifespan_context
+        try:
+            return json.dumps(await app.client.send("get_logs", {"count": 100}))
+        except (ConnectionError, Exception) as e:
+            return json.dumps({"error": str(e), "connected": False})

src/godot_ai/resources/project.py

@@ -0,0 +1,47 @@
+"""MCP resources for project info and settings."""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import Context, FastMCP
+
+COMMON_SETTINGS = [
+    "application/config/name",
+    "application/config/description",
+    "application/run/main_scene",
+    "display/window/size/viewport_width",
+    "display/window/size/viewport_height",
+    "rendering/renderer/rendering_method",
+    "physics/2d/default_gravity",
+    "physics/3d/default_gravity",
+]
+
+
+def register_project_resources(mcp: FastMCP) -> None:
+    @mcp.resource("godot://project/info", mime_type="application/json")
+    async def get_project_info(ctx: Context) -> str:
+        """Project name, Godot version, paths, and play state."""
+        app = ctx.lifespan_context
+        session = app.registry.get_active()
+        if session is None:
+            return json.dumps({"error": "No active Godot session", "connected": False})
+
+        info = session.to_dict()
+        info.pop("connected_at", None)
+        return json.dumps(info)
+
+    @mcp.resource("godot://project/settings", mime_type="application/json")
+    async def get_project_settings(ctx: Context) -> str:
+        """Common project settings subset (display, physics, rendering)."""
+        app = ctx.lifespan_context
+        settings = {}
+        errors = []
+        for key in COMMON_SETTINGS:
+            try:
+                result = await app.client.send("get_project_setting", {"key": key})
+                settings[key] = result.get("value")
+            except Exception as e:
+                errors.append({"key": key, "error": str(e)})
+
+        return json.dumps({"settings": settings, "errors": errors if errors else None})

src/godot_ai/resources/scenes.py

@@ -0,0 +1,32 @@
+"""MCP resources for scene data."""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import Context, FastMCP
+
+
+def register_scene_resources(mcp: FastMCP) -> None:
+    @mcp.resource("godot://scene/current", mime_type="application/json")
+    async def get_current_scene(ctx: Context) -> str:
+        """Current scene path and root node info from the active Godot editor."""
+        app = ctx.lifespan_context
+        try:
+            state = await app.client.send("get_editor_state")
+            return json.dumps({
+                "current_scene": state.get("current_scene", ""),
+                "project_name": state.get("project_name", ""),
+                "is_playing": state.get("is_playing", False),
+            })
+        except (ConnectionError, Exception) as e:
+            return json.dumps({"error": str(e), "connected": False})
+
+    @mcp.resource("godot://scene/hierarchy", mime_type="application/json")
+    async def get_scene_hierarchy(ctx: Context) -> str:
+        """Full scene tree hierarchy from the active Godot editor."""
+        app = ctx.lifespan_context
+        try:
+            return json.dumps(await app.client.send("get_scene_tree", {"depth": 10}))
+        except (ConnectionError, Exception) as e:
+            return json.dumps({"error": str(e), "connected": False})

src/godot_ai/resources/sessions.py

@@ -2,17 +2,19 @@
 
 from __future__ import annotations
 
+import json
+
 from fastmcp import Context, FastMCP
 
 
 def register_session_resources(mcp: FastMCP) -> None:
-    @mcp.resource("godot://sessions")
-    def get_sessions(ctx: Context) -> dict:
+    @mcp.resource("godot://sessions", mime_type="application/json")
+    def get_sessions(ctx: Context) -> str:
         """All connected Godot editor sessions and their metadata."""
         app = ctx.lifespan_context
         sessions = app.registry.list_all()
         active_id = app.registry.active_session_id
-        return {
+        return json.dumps({
             "sessions": [{**s.to_dict(), "is_active": s.session_id == active_id} for s in sessions],
             "count": len(sessions),
-        }
+        })

src/godot_ai/server.py

@@ -11,6 +11,9 @@
 from fastmcp import FastMCP
 
 from godot_ai.godot_client.client import GodotClient
+from godot_ai.resources.editor import register_editor_resources
+from godot_ai.resources.project import register_project_resources
+from godot_ai.resources.scenes import register_scene_resources
 from godot_ai.resources.sessions import register_session_resources
 from godot_ai.sessions.registry import SessionRegistry
 from godot_ai.tools.client import register_client_tools
@@ -69,5 +72,8 @@ async def _lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     register_client_tools(mcp)
     register_testing_tools(mcp)
     register_session_resources(mcp)
+    register_scene_resources(mcp)
+    register_editor_resources(mcp)
+    register_project_resources(mcp)
 
     return mcp

src/godot_ai/tools/editor.py

@@ -26,14 +26,31 @@ async def editor_selection_get(ctx: Context) -> dict:
         return await app.client.send("get_selection")
 
     @mcp.tool()
-    async def logs_read(ctx: Context, count: int = 50) -> dict:
+    async def logs_read(
+        ctx: Context,
+        count: int = 50,
+        offset: int = 0,
+    ) -> dict:
         """Read recent log lines from the Godot editor console.
 
-        Returns the most recent log lines captured by the MCP plugin,
+        Returns paginated log lines captured by the MCP plugin,
         including MCP command traffic when logging is enabled.
 
         Args:
-            count: Number of recent lines to return. Default 50.
+            count: Maximum number of lines to return. Default 50.
+            offset: Number of lines to skip from the start. Default 0.
         """
         app = ctx.lifespan_context
-        return await app.client.send("get_logs", {"count": count})
+        # Request more lines than needed to support offset
+        total_request = offset + count
+        result = await app.client.send("get_logs", {"count": total_request})
+        lines = result.get("lines", [])
+        total_count = len(lines)
+        page = lines[offset : offset + count]
+        return {
+            "lines": page,
+            "total_count": total_count,
+            "offset": offset,
+            "limit": count,
+            "has_more": offset + count < total_count,
+        }

src/godot_ai/tools/node.py

@@ -36,22 +36,36 @@ async def node_find(
         name: str = "",
         type: str = "",
         group: str = "",
+        offset: int = 0,
+        limit: int = 100,
     ) -> dict:
         """Find nodes in the scene tree by name, type, or group.
 
         At least one filter must be provided. Filters are combined with AND
-        logic — a node must match all specified filters.
+        logic — a node must match all specified filters. Results are paginated.
 
         Args:
             name: Substring match on node name (case-insensitive).
             type: Exact Godot class name (e.g. "MeshInstance3D").
             group: Group name the node must belong to.
+            offset: Number of results to skip. Default 0.
+            limit: Maximum number of results to return. Default 100.
         """
         app = ctx.lifespan_context
-        return await app.client.send(
+        result = await app.client.send(
             "find_nodes",
             {"name": name, "type": type, "group": group},
         )
+        nodes = result.get("nodes", [])
+        total_count = len(nodes)
+        page = nodes[offset : offset + limit]
+        return {
+            "nodes": page,
+            "total_count": total_count,
+            "offset": offset,
+            "limit": limit,
+            "has_more": offset + limit < total_count,
+        }
 
     @mcp.tool()
     async def node_get_properties(ctx: Context, path: str) -> dict: