From ca27daea1e244871b55889af1674ade6e5b3f1c7 Mon Sep 17 00:00:00 2001 From: Lothsahn Date: Sun, 5 Jul 2026 13:35:32 -0400 Subject: [PATCH] docs(server): guide agents to read resources by URI, not name Add a "Reading resources" section to the FastMCP server instructions string. It states that resources are addressed by URI (slashes), never by name (underscores); that the exact URI should be taken from the client's resources/list rather than constructed from the name; and that payloads are wrapped under a top-level `data` object (field paths look like data.
.). Prevents the common naive failure where an agent turns a resource name into a URI (e.g. editor_state -> mcpforunity://editor_state) and 404s, and the matching failure of guessing a bare top-level field instead of the nested data.* path. Co-Authored-By: Claude Opus 4.8 (1M context) --- Server/src/main.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Server/src/main.py b/Server/src/main.py index 1e6b3c18ad..7bbb57afdf 100644 --- a/Server/src/main.py +++ b/Server/src/main.py @@ -315,6 +315,11 @@ def _build_instructions(project_scoped_tools: bool) -> str: - Use TOOLS to perform actions and mutations (manage_editor for play mode control, tag/layer management, etc) - Always check related resources before modifying the engine state with tools +Reading resources (read this before using ANY resource named below): +- Resources are addressed by URI, never by name. A resource's name and URI are NOT interchangeable: names use underscores (e.g. editor_state) while URIs use slashes (e.g. mcpforunity://editor/state). Do NOT build a URI by swapping separators in the name — you will 404. +- Always read the exact URI from your MCP client's resource listing (resources/list). Where these instructions mention a resource by name, look up its URI in that listing rather than guessing it. +- Resource payloads are wrapped: the content lives under a top-level `data` object, so field paths are `data.
.` (e.g. `data.advice.ready_for_tools`), not bare top-level fields. + Script Management: - After creating or modifying scripts (by your own tools or the `manage_script` tool) use `read_console` to check for compilation errors before proceeding - Only after successful compilation can new components/types be used