summer-engine 1.0.0 → 1.0.1

package/dist/mcp/server.js

@@ -36,5 +36,5 @@ export async function startMcpServer() {
     registerAssetTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`[summer-mcp] MCP server running v${version}. 28 tools available.\n`);
+    process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);
 }

package/dist/mcp/tools/project-tools.js

@@ -1,6 +1,93 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function readMainSceneFromProject(projectPath) {
+    if (!projectPath)
+        return null;
+    try {
+        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
+        const match = text.match(/run\/main_scene="([^"]+)"/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export function registerProjectTools(server) {
+    server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
+
+Call this at the start of a fresh chat before touching scenes.
+It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    startupChecklist: [
+                        "Decide first: file edit or engine operation.",
+                        "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+                        "Call summer_get_project_context first.",
+                        "If no scene is open, call summer_open_main_scene.",
+                        "Call summer_get_scene_tree before structural edits.",
+                        "Call summer_save_scene after edits.",
+                    ],
+                    safeDefaults: [
+                        "Never guess scene filenames (main.tscn/Main.tscn).",
+                        "Do not route ordinary code edits through MCP when direct file tools are available.",
+                        "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
+                        "Never write .tscn/.scn with file write tools; use scene ops.",
+                    ],
+                    preferredFlow: [
+                        "summer_get_project_context",
+                        "summer_open_main_scene (if needed)",
+                        "summer_get_scene_tree",
+                        "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
+                        "summer_save_scene",
+                        "summer_get_diagnostics",
+                    ],
+                    recovery: [
+                        "If you see 'no scene open': run summer_open_main_scene.",
+                        "If open_scene fails: re-check mainScene from summer_get_project_context.",
+                        "If save fails: verify scene is open and game is not running.",
+                    ],
+                }, null, 2),
+            },
+        ],
+    }));
+    server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
+- engine health/status
+- project name and path
+- current scene path (if available)
+- main scene path from project.godot
+
+Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
+        const [health, projectState] = await Promise.all([
+            client.health(),
+            client.getProjectState(),
+        ]);
+        const healthObj = (health ?? {});
+        const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string" ? healthObj.project_path : undefined);
+        return {
+            health,
+            project: projectState,
+            mainScene,
+            guidance: mainScene
+                ? "Use `summer_open_scene` with `mainScene` if no scene is open."
+                : "Main scene not found in project.godot. Open a known scene path explicitly.",
+        };
+    }));
+    server.tool("summer_open_main_scene", `Open the project's configured main scene from project.godot.
+
+Safer than guessing scene names like main.tscn/Main.tscn.
+Call this when you get "no scene open".`, {}, async () => withEngine(async (client) => {
+        const health = (await client.health());
+        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
+        const mainScene = await readMainSceneFromProject(projectPath);
+        if (!mainScene) {
+            throw new Error("Could not resolve application/run/main_scene from project.godot. Call `summer_get_project_context` and open a scene explicitly.");
+        }
+        return client.executeOps([{ op: "OpenScene", path: mainScene }]);
+    }));
     server.tool("summer_project_setting", `Set a project setting in project.godot. Common settings:
 - "application/config/name" — project name
 - "application/run/main_scene" — main scene path
@@ -29,7 +116,10 @@ Example: Bind jump to Space and W:
         ];
         return client.executeOps(ops);
     }));
-    server.tool("summer_get_scene_tree", "Get the full scene tree structure of the currently open scene. Returns all nodes with their types, paths, and children. Use this to understand the scene before making changes.", {}, async () => withEngine(async (client) => client.getSceneState()));
+    server.tool("summer_get_scene_tree", `Get the full scene tree structure of the currently open scene.
+
+Use this before structural edits (add/remove/replace).
+If you get "no edited scene", call summer_open_main_scene first.`, {}, async () => withEngine(async (client) => client.getSceneState()));
     server.tool("summer_import_from_url", `Download a file from a URL and import it into the project. Triggers Godot's full import pipeline — generates .import files, extracts textures from .glb models, creates materials.
 
 Use this for:

package/dist/mcp/tools/scene-tools.js

@@ -1,8 +1,79 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function readMainSceneFromProject(projectPath) {
+    if (!projectPath)
+        return null;
+    try {
+        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
+        const match = text.match(/run\/main_scene="([^"]+)"/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export function registerSceneTools(server) {
+    server.tool("summer_create_scene", `Create a new empty scene file safely.
+
+IMPORTANT:
+- This tool uses a temporary mutation strategy: it opens a template scene, removes children, saves to a new path, then restores the previous scene.
+- To prevent accidental destructive actions, you MUST explicitly set allow_temporary_scene_mutation=true.
+- If you don't want this strategy, stop and ask the user for manual scene creation in the editor.
+
+Recommended workflow:
+1) Call summer_get_project_context
+2) Call summer_open_main_scene (optional)
+3) Call summer_create_scene with a new path`, {
+        path: z.string().describe("New scene path, e.g. 'res://scenes/empty_level.tscn'"),
+        rootName: z.string().default("Main").describe("Root node name for the new scene"),
+        allow_temporary_scene_mutation: z
+            .boolean()
+            .default(false)
+            .describe("Safety gate. Must be true to proceed."),
+    }, async ({ path, rootName, allow_temporary_scene_mutation }) => withEngine(async (client) => {
+        if (!allow_temporary_scene_mutation) {
+            throw new Error("Refusing to create scene without explicit approval. Re-run with allow_temporary_scene_mutation=true.");
+        }
+        const health = (await client.health());
+        const currentScene = typeof health.scene === "string" && health.scene.length > 0 ? health.scene : null;
+        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
+        const mainScene = await readMainSceneFromProject(projectPath);
+        const templateScene = currentScene || mainScene;
+        if (!templateScene) {
+            throw new Error("No scene open and could not resolve main scene. Call summer_get_project_context first, then open a known scene.");
+        }
+        await client.executeOps([{ op: "OpenScene", path: templateScene }]);
+        const tree = (await client.getSceneState());
+        const children = tree.data?.children ?? tree.children ?? [];
+        const removeOps = children
+            .map((c) => c.path)
+            .filter((p) => typeof p === "string" && p.length > 0)
+            .map((p) => ({ op: "RemoveNode", path: `./${p}` }));
+        if (removeOps.length > 0) {
+            await client.executeOps(removeOps, { groupUndo: true });
+        }
+        await client.executeOps([{ op: "SetProp", path: ".", key: "name", value: rootName }]);
+        await client.executeOps([{ op: "SaveScene", path }]);
+        if (currentScene && currentScene !== path) {
+            await client.executeOps([{ op: "OpenScene", path: currentScene }]);
+        }
+        return {
+            ok: true,
+            created: path,
+            rootName,
+            templateScene,
+            restoredScene: currentScene,
+        };
+    }));
     server.tool("summer_add_node", `Add a new node to the scene tree.
 
+Preflight (fresh chat):
+1) summer_get_project_context
+2) summer_open_main_scene (if no scene open)
+3) summer_get_scene_tree
+
 Common node types:
 - 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D, Camera3D, DirectionalLight3D, OmniLight3D, SpotLight3D, WorldEnvironment, CollisionShape3D, Area3D
 - 2D: Node2D, Sprite2D, CharacterBody2D, RigidBody2D, StaticBody2D, Camera2D, CollisionShape2D, Area2D, TileMapLayer
@@ -52,14 +123,19 @@ Use when you need to modify a sub-property of a resource, like:
     }, async ({ nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => client.executeOps([
         { op: "SetResourceProperty", nodePath, resourceProperty, subProperty, value },
     ])));
-    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
+    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
     server.tool("summer_save_scene", "Save the current scene to disk. Call this after making scene changes to persist them. Without saving, changes only exist in the editor's memory.", { path: z.string().optional().describe("Save-as path for creating a new scene file, e.g. 'res://levels/level2.tscn'") }, async ({ path }) => withEngine(async (client) => {
         const op = { op: "SaveScene" };
         if (path)
             op.path = path;
         return client.executeOps([op]);
     }));
-    server.tool("summer_open_scene", "Open a scene file in the editor. Use this to switch between scenes (e.g., open a level to edit it).", { path: z.string().describe("Scene path, e.g. 'res://main.tscn' or 'res://levels/level1.tscn'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "OpenScene", path }])));
+    server.tool("summer_open_scene", `Open a scene file in the editor. Use this to switch between scenes.
+
+Do not guess paths. Prefer:
+1) summer_get_project_context (read mainScene)
+2) summer_open_main_scene (open known main scene)
+3) summer_open_scene only when user gave an explicit path.`, { path: z.string().describe("Scene path, e.g. 'res://main.tscn' or 'res://levels/level1.tscn'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "OpenScene", path }])));
     server.tool("summer_instantiate_scene", `Add an existing scene or 3D model as a child node. Use this to:
 - Add a .tscn prefab (reusable scene) as a child
 - Add a .glb/.gltf 3D model into the scene

package/dist/mcp/tools/with-engine.js

@@ -1,6 +1,28 @@
 import { getClient, resetClient } from "../server.js";
 import { getAuthToken } from "../../lib/auth.js";
 const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+function extractOpError(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const op = result;
+    if (op.status === "error" && op.error)
+        return op.error;
+    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
+    return firstFailed?.error ?? null;
+}
+function buildActionHint(message) {
+    const normalized = message.toLowerCase();
+    if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
+        return "No scene is currently open. Call `summer_get_project_context` first, then `summer_open_main_scene` (or `summer_open_scene` with a known .tscn path).";
+    }
+    if (normalized.includes("failed to open scene")) {
+        return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
+    }
+    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
+        return "This MCP operation cannot write .tscn/.scn directly. If your host AI has normal file-edit tools, edit .gd/.tscn files there; use Summer MCP for engine/state/scene-tree operations.";
+    }
+    return null;
+}
 async function checkMcpQuota() {
     const token = await getAuthToken();
     if (!token) {
@@ -55,6 +77,12 @@ export async function withEngine(fn) {
         }
         const client = await getClient();
         const result = await fn(client);
+        const opError = extractOpError(result);
+        if (opError) {
+            const hint = buildActionHint(opError);
+            const message = hint ? `${opError}\n\nHint: ${hint}` : opError;
+            return { content: [{ type: "text", text: message }], isError: true };
+        }
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
     catch (err) {

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "summer-engine",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
-  "keywords": ["game-engine", "godot", "ai", "mcp", "gamedev", "3d", "summer-engine"],
+  "keywords": [
+    "game-engine",
+    "godot",
+    "ai",
+    "mcp",
+    "gamedev",
+    "3d",
+    "summer-engine"
+  ],
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
@@ -14,7 +22,11 @@
   "bin": {
     "summer": "./dist/bin/summer.js"
   },
-  "files": ["dist/", "skills/", "README.md"],
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",