summer-engine 1.2.0 → 1.2.1

package/dist/lib/skills-registry.js

@@ -0,0 +1,118 @@
+export const AGENT_CLIENTS = [
+    "summer",
+    "codex",
+    "claude-code",
+    "cursor",
+    "windsurf",
+];
+const ALL_CLIENTS = AGENT_CLIENTS;
+export const SKILL_REGISTRY = [
+    {
+        name: "gdscript-patterns",
+        public: true,
+        category: "scripting",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_set_prop",
+            "summer_connect_signal",
+            "summer_input_map_bind",
+            "summer_get_script_errors",
+        ],
+        testScenario: "Create a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
+    },
+    {
+        name: "scene-composition",
+        public: true,
+        category: "scene",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_create_scene",
+            "summer_open_scene",
+            "summer_get_scene_tree",
+            "summer_add_node",
+            "summer_instantiate_scene",
+            "summer_save_scene",
+        ],
+        testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.",
+    },
+    {
+        name: "fps-controller",
+        public: true,
+        category: "gameplay",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_set_resource_property",
+            "summer_input_map_bind",
+        ],
+        testScenario: "Create a CharacterBody3D player with collision, camera, input actions, and a host-edited controller script.",
+    },
+    {
+        name: "3d-lighting",
+        public: true,
+        category: "lighting",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_set_resource_property",
+        ],
+        testScenario: "Add sun, fill lighting, WorldEnvironment, and shadow settings to a simple 3D scene.",
+    },
+    {
+        name: "ui-basics",
+        public: true,
+        category: "ui",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_connect_signal",
+        ],
+        testScenario: "Create a HUD CanvasLayer with labels, a ProgressBar, and a connected Button signal.",
+    },
+    {
+        name: "asset-strategy",
+        public: true,
+        category: "assets",
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_search_assets",
+            "summer_import_asset",
+            "summer_import_from_url",
+            "summer_generate_image",
+            "summer_generate_3d",
+            "summer_generate_audio",
+        ],
+        testScenario: "Choose library, generated, or primitive assets for a small level and import one asset into the project.",
+    },
+    {
+        name: "make-game",
+        public: true,
+        category: "workflow",
+        clients: ALL_CLIENTS,
+        recommended: false,
+        requiresMcpTools: [
+            "summer_get_agent_playbook",
+            "summer_get_project_context",
+            "summer_create_scene",
+            "summer_open_scene",
+            "summer_save_scene",
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_set_resource_property",
+            "summer_instantiate_scene",
+            "summer_play",
+            "summer_stop",
+            "summer_get_diagnostics",
+        ],
+        testScenario: "Build one narrow playable prototype from requirements through scene setup, host-edited scripts, and diagnostics.",
+    },
+];

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

@@ -1,18 +1,83 @@
 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)
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function pickString(record, keys) {
+    if (!record)
         return null;
-    try {
-        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
-        const match = text.match(/run\/main_scene="([^"]+)"/);
-        return match?.[1] ?? null;
+    for (const key of keys) {
+        const value = stringFrom(record[key]);
+        if (value)
+            return value;
     }
-    catch {
+    return null;
+}
+function getProjectData(projectState) {
+    return asRecord(asRecord(projectState)?.data);
+}
+function getProjectSetting(projectState, keys) {
+    const data = getProjectData(projectState);
+    const entries = data?.entries;
+    if (!Array.isArray(entries))
         return null;
+    for (const entry of entries) {
+        const item = asRecord(entry);
+        const key = stringFrom(item?.key);
+        if (key && keys.includes(key)) {
+            return stringFrom(item?.value);
+        }
     }
+    return null;
+}
+function getProjectPath(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, [
+        "projectPath",
+        "project_path",
+        "projectRoot",
+        "project_root",
+        "rootPath",
+        "root_path",
+    ]) ??
+        pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
+        null);
+}
+function getProjectName(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["projectName", "project_name", "name"]) ??
+        pickString(root, ["projectName", "project_name", "name"]) ??
+        getProjectSetting(projectState, ["application/config/name", "config/name"]));
+}
+function getMainScene(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        pickString(root, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        getProjectSetting(projectState, [
+            "application/run/main_scene",
+            "run/main_scene",
+        ]));
+}
+function getCurrentScene(projectState, sceneState) {
+    const sceneRoot = asRecord(sceneState);
+    const sceneData = asRecord(sceneRoot?.data);
+    const sceneProvenance = asRecord(sceneRoot?.provenance);
+    const projectRoot = asRecord(projectState);
+    const projectData = getProjectData(projectState);
+    const projectProvenance = asRecord(projectRoot?.provenance);
+    return (pickString(sceneProvenance, ["scenePath", "scene_path"]) ??
+        pickString(sceneData, ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
+        pickString(projectData, ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
+        pickString(projectProvenance, ["scenePath", "scene_path"]) ??
+        null);
 }
 export function registerProjectTools(server) {
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
@@ -25,7 +90,8 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                 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.",
+                        "Write .gd/.cs/.json/docs/simple config with host file-edit tools directly.",
+                        "Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, screenshots/verification.",
                         "Call summer_get_project_context first.",
                         "If no scene is open, call summer_open_main_scene.",
                         "Call summer_get_scene_tree before structural edits.",
@@ -33,15 +99,16 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                     ],
                     safeDefaults: [
                         "Never guess scene filenames (main.tscn/Main.tscn).",
-                        "Do not route ordinary code edits through MCP when direct file tools are available.",
+                        "Do not route ordinary script, JSON, docs, or simple config 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.",
+                        "Use MCP for scene-tree mutations and inspector-visible values instead of hand-editing live scene state.",
                     ],
                     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",
+                        "write scripts/data/docs/simple config directly with host file-edit tools",
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
@@ -56,35 +123,45 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
     }));
     server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
 - engine health/status
-- project name and path
+- project name and project path when exposed by project state
 - current scene path (if available)
-- main scene path from project.godot
+- main scene path from project settings
 
 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([
+        const [health, projectState, sceneState] = await Promise.all([
             client.health(),
             client.getProjectState(),
+            client.getSceneState().catch((err) => ({
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            })),
         ]);
-        const healthObj = (health ?? {});
-        const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string" ? healthObj.project_path : undefined);
+        const projectPath = getProjectPath(projectState);
+        const projectName = getProjectName(projectState);
+        const mainScene = getMainScene(projectState);
+        const currentScene = getCurrentScene(projectState, sceneState);
         return {
             health,
             project: projectState,
+            scene: sceneState,
+            projectName,
+            projectPath,
+            currentScene,
             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.",
+                : "Main scene not found in project state. Open a known scene path explicitly.",
+            fileEditingGuidance: "Write .gd/.cs/.json/docs/simple config directly with host file tools. Use MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.",
         };
     }));
-    server.tool("summer_open_main_scene", `Open the project's configured main scene from project.godot.
+    server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.
 
 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);
+        const projectState = await client.getProjectState();
+        const mainScene = getMainScene(projectState);
         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.");
+            throw new Error("Could not resolve application/run/main_scene from project state. Call `summer_get_project_context` and open a scene explicitly.");
         }
         return client.executeOps([{ op: "OpenScene", path: mainScene }]);
     }));

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

@@ -1,10 +1,10 @@
 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.ok === false && op.error)
+        return op.error;
     if (op.status === "error" && op.error)
         return op.error;
     const firstFailed = op.results?.find((r) => r.ok === false && r.error);
@@ -19,62 +19,12 @@ function buildActionHint(message) {
         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 "Write .gd/.cs/.json/docs/simple config files with normal file-edit tools. Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.";
     }
     return null;
 }
-async function checkMcpQuota() {
-    const token = await getAuthToken();
-    if (!token) {
-        return {
-            allowed: false,
-            message: "Not signed in. The user needs to run this in their terminal:\n  npx summer-engine login\nOr open: https://www.summerengine.com/login\nMCP tools require a Summer Engine account (free to create).",
-        };
-    }
-    try {
-        const res = await fetch(`${GATEWAY_URL}/api/mcp/log-local-call`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({}),
-            signal: AbortSignal.timeout(10000),
-        });
-        const data = (await res.json().catch(() => ({})));
-        // Hard enforcement errors should block tool execution.
-        if ([401, 402, 403, 429].includes(res.status)) {
-            return {
-                allowed: false,
-                message: data.message || "Quota check failed. Try again.",
-            };
-        }
-        // Soft-fail on service/gateway issues so local tools keep working.
-        if (!res.ok) {
-            return { allowed: true };
-        }
-        if (data.allowed === false) {
-            return {
-                allowed: false,
-                message: data.message || "MCP call limit reached. Upgrade at https://summerengine.com/pricing",
-            };
-        }
-        return { allowed: true };
-    }
-    catch (err) {
-        // Network/transient errors should not brick local MCP usage.
-        return { allowed: true };
-    }
-}
 export async function withEngine(fn) {
     try {
-        const quota = await checkMcpQuota();
-        if (!quota.allowed) {
-            return {
-                content: [{ type: "text", text: quota.message || "Quota exceeded" }],
-                isError: true,
-            };
-        }
         const client = await getClient();
         const result = await fn(client);
         const opError = extractOpError(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",
@@ -31,6 +31,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -48,6 +50,7 @@
   "devDependencies": {
     "@types/diff": "^7.0.0",
     "@types/node": "^20.0.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
   }
 }

package/skills/gdscript-patterns/SKILL.md

@@ -89,8 +89,8 @@ var siblings = get_parent().get_children()
 
 For health systems, input handling, and state machines, see [reference.md](reference.md).
 
-## MCP Integration
+## Scene Integration
 
-When the AI adds a script via `summer_add_node` and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist—use `summer_write_file` to create it first.
+When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create or edit `.gd` files with the host agent's normal file-editing tools, then use Summer MCP only to attach the script and connect scene signals.
 
 For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.

package/skills/make-game/SKILL.md

@@ -12,7 +12,7 @@ compatibility:
 
 Step-by-step workflow for building a complete game. Follow phases 0-6 in order. Each phase must complete before moving to the next.
 
-**Rule**: Scene operations (.tscn) use MCP tools. Script files (.gd) use host file-edit tools (Write/Edit). Never cross the streams.
+**Rule**: Scene operations (.tscn) use Summer MCP tools. Script files (.gd) use the host agent's normal file-editing tools. Never cross the streams.
 
 ---
 
@@ -218,7 +218,7 @@ summer_save_scene()
 
 ## Phase 4: Scripting
 
-**Write .gd files with host file-edit tools (Write/Edit). Attach via MCP.**
+**Write .gd files with the host agent's normal file-editing tools. Attach via MCP.**
 
 Workflow:
 1. Write the script file to disk
@@ -395,7 +395,7 @@ After first playable, ask the user what to improve. Common next steps:
 
 ## Anti-Patterns
 
-- Never write .tscn files with host file tools -- always use MCP scene tools
+- Never write .tscn files with host agent file tools -- always use Summer MCP scene tools
 - Never guess node paths -- call `summer_get_scene_tree()` first
 - Never edit scenes while game is running -- call `summer_stop()` first
 - Never skip `summer_save_scene()` -- unsaved changes are editor-only

package/skills/scene-composition/SKILL.md

@@ -79,7 +79,7 @@ Use `./` for paths relative to the scene root:
 
 1. Build the hierarchy in the main scene
 2. Select the root of what you want to extract
-3. Save as scene: `summer_save_scene(path="res://scenes/player.tscn")` — but note: SaveScene saves the *current* scene. To save a branch, you typically save the open scene first, then in the editor you'd use "Save Branch as Scene." MCP doesn't have a direct "save branch" op—so for now, create the sub-scene as its own file via `summer_write_file` or build it in a separate scene and save.
+3. Save as scene: `summer_save_scene(path="res://scenes/player.tscn")`. SaveScene saves the current open scene, so build reusable scenes in their own open scene and save them there. Do not handwrite `.tscn` files as the preferred path.
 4. In the main scene, add it with `summer_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")`
 
 **Practical approach:** Create reusable scenes (player.tscn, enemy.tscn) as separate scene files, then instantiate them into levels.