Add MCP resources and pagination (#1)

* 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>

* Simplify: extract shared pagination, fix exceptions, dedupe tests

- Extract _paginate to shared tools/_pagination.py with key parameter;
  all 4 paginated tools now use it instead of inline copies
- Fix redundant except (ConnectionError, Exception) -> except Exception
- Parallelize project settings resource with asyncio.gather (was 8
  sequential WebSocket round-trips)
- Deduplicate mcp_stack fixture into conftest.py
- Remove redundant test_resources.py (covered by test_mcp_resources.py)
- Remove duplicate _paginate unit tests from integration file

81 Python tests, 44 Godot-side (125 total). Coverage: 87%.

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

* Fix logs_read pagination: fetch full buffer for accurate metadata

logs_read was requesting offset+count lines from the GDScript handler,
but get_recent() returns the tail of the buffer — not a window. This
made total_count reflect the request size, not the actual buffer size,
and has_more was always wrong for non-zero offsets.

Now fetches the full buffer (up to 500 lines) and lets paginate()
slice correctly with accurate total_count and has_more.

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

* Bump fastmcp floor to >=3.0.0

FastMCP 2.x lacks Context.lifespan_context and the async
list_resources() API that this codebase relies on. The loose
>=2.0.0 floor allowed installs that would fail at runtime.

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

---------

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                    # 81 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 (81 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 + 81 Python = 125 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
 
 ---

pyproject.toml

@@ -5,7 +5,7 @@ description = "Production-grade MCP server and AI tools for the Godot engine"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "fastmcp>=2.0.0",
+    "fastmcp>=3.0.0",
     "websockets>=13.0",
     "pydantic>=2.0",
 ]

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 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 Exception as e:
+            return json.dumps({"error": str(e), "connected": False})

src/godot_ai/resources/project.py

@@ -0,0 +1,56 @@
+"""MCP resources for project info and settings."""
+
+from __future__ import annotations
+
+import asyncio
+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
+
+        async def _fetch(key: str) -> tuple[str, object | None, str | None]:
+            try:
+                result = await app.client.send("get_project_setting", {"key": key})
+                return key, result.get("value"), None
+            except Exception as e:
+                return key, None, str(e)
+
+        results = await asyncio.gather(*[_fetch(key) for key in COMMON_SETTINGS])
+        settings = {}
+        errors = []
+        for key, value, error in results:
+            if error:
+                errors.append({"key": key, "error": error})
+            else:
+                settings[key] = value
+
+        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 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 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/_pagination.py

@@ -0,0 +1,20 @@
+"""Shared pagination helper for MCP tools."""
+
+from __future__ import annotations
+
+
+def paginate(items: list, offset: int, limit: int, *, key: str = "items") -> dict:
+    """Apply offset/limit pagination to a list.
+
+    Returns a dict with the paginated slice under the given key,
+    plus total_count, offset, limit, and has_more metadata.
+    """
+    total_count = len(items)
+    page = items[offset : offset + limit]
+    return {
+        key: page,
+        "total_count": total_count,
+        "offset": offset,
+        "limit": limit,
+        "has_more": offset + limit < total_count,
+    }