From bc001d77e67b4ec08a5b8f8fe1cc19928d16e126 Mon Sep 17 00:00:00 2001 From: Jamie Wells Date: Mon, 12 Oct 2026 01:14:12 +0000 Subject: [PATCH] Document Rustic MCP project selection and local execution --- docs/AGENT_INTEGRATION/connect-an-agent.md | 22 ++++++++++++++----- .../limits-and-troubleshooting.md | 13 +++++++++-- 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/docs/AGENT_INTEGRATION/connect-an-agent.md b/docs/AGENT_INTEGRATION/connect-an-agent.md index 73adbc3..34106e0 100644 --- a/docs/AGENT_INTEGRATION/connect-an-agent.md +++ b/docs/AGENT_INTEGRATION/connect-an-agent.md @@ -5,17 +5,29 @@ 1. Install Rustic and open your game project in the Rustic editor once. Opening the project generates its agent information and registers the `rustic-workspace` MCP server in your user Codex and Claude configuration. -2. Start your agent from the game directory (or a directory below it), and reload - its MCP connections if it was already running. The backend discovers the - containing `project.engine` file. You can also explicitly configure its - command as the installed `rustic-agent-backend.exe` and arguments as - `["--project", "C:/Games/MyGame"]`. +2. Reload the agent's MCP connections if it was already running. Starting + from the game directory (or a directory below it) automatically discovers + the containing `project.engine` file. The backend also starts from other + directories: the MCP handshake and tool list do not require a game project. + To bind a game from the Codex desktop app or an engine checkout, call + `workspace_info` with `{"project_root":"C:/Games/MyGame"}`. Use an absolute + directory path; selection is retained for this MCP session. Alternatively, + configure the installed `rustic-agent-backend.exe` with arguments + `["--project", "C:/Games/MyGame"]` and reload the connection. 3. Invoke the `rustic-workspace` skill, or `/rustic-workspace` in Claude, and ask it to inspect your project. Call `workspace_info` first; its `project_root` identifies the game and `agent_directory` identifies its stored information. 4. Read instructions through `read_agent_file` before editing game content. Use `scene_summary` with your scene's relative path before changing a scene. + +The stdio MCP server runs on the same computer as the agent client and the game +files. A local Rustic editor registration is not available to a Codex cloud +chat. Use a local Codex chat with the registered MCP connection to control that +game. Opening a game locally does not expose the backend to a remote executor, +and a missing `@rustic-workspace` entry in a cloud chat does not establish that +the local server crashed. + Only small discovery skills, a Claude command, and client registration settings remain in the user profile so agent applications can find the integration. The full skills and plugin live in Rustic app data. No gameplay script attachment or diff --git a/docs/AGENT_INTEGRATION/limits-and-troubleshooting.md b/docs/AGENT_INTEGRATION/limits-and-troubleshooting.md index bae8bab..f00240c 100644 --- a/docs/AGENT_INTEGRATION/limits-and-troubleshooting.md +++ b/docs/AGENT_INTEGRATION/limits-and-troubleshooting.md @@ -15,8 +15,17 @@ - If the tools are missing, reopen the editor and reload your agent's MCP server. Confirm the installed backend executable exists. You can rerun `rustic-agent-backend.exe --install-user-integrations` to register it again. -- “The supplied folder is not a readable Rustic project” means the agent started - outside a game project. Set `--project` to the directory containing `project.engine`. +- “No Rustic project is selected” is a tool error, not a failed MCP startup. + Call `workspace_info` with `{"project_root":"C:/Games/MyGame"}` using an + absolute path to a readable game directory containing `project.engine`. + Later file and scene tools use that selected game. An invalid selection + reports a tool error and keeps the previous selection; it does not close the + server. You can also set `--project` in the MCP registration and reload it. +- An older backend may exit with “The supplied folder is not a readable Rustic + project” before connecting when Codex starts outside a game. Point that + registration at the game with `--project`, or install the updated backend + and reload the connection. Opening the editor alone does not replace an + already running MCP process. - If a file is missing, call `list_agent_files` and check the scope and relative path. Ordinary `read_file` and `write_file` address game content; agent metadata uses `read_agent_file` and `write_agent_file`.