summer-engine 0.0.1 → 1.0.0

package/dist/mcp/tools/asset-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAssetTools(server: McpServer): void;

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

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import { getAuthToken } from "../../lib/auth.js";
+import { getClient } from "../server.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+/** Kenney Cloudinary URL pattern: .../summer_art/kenney/3d/{pack-slug}/{filename}.glb */
+const KENNEY_URL_PATTERN = /\/kenney\/3d\/([^/]+)\//;
+function getPackSlugFromUrl(fileUrl) {
+    return fileUrl.match(KENNEY_URL_PATTERN)?.[1] ?? null;
+}
+function buildKenneyTextureUrl(fileUrl) {
+    const lastSlash = fileUrl.lastIndexOf("/");
+    const base = lastSlash >= 0 ? fileUrl.slice(0, lastSlash) : fileUrl;
+    return `${base}/Textures/colormap.png`;
+}
+async function textureExists(url) {
+    try {
+        const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(5000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build import entries for Kenney 3D assets: texture first, then GLB.
+ * Pack-scoped paths prevent texture collision (each pack has its own Textures/colormap.png).
+ * See: publicsummerengine/Docs/ASSET_IMPORT_END_TO_END.md
+ */
+async function buildKenneyImportEntries(fileUrl, packSlug, fileName) {
+    const textureUrl = buildKenneyTextureUrl(fileUrl);
+    const hasTexture = await textureExists(textureUrl);
+    if (!hasTexture) {
+        return [{ url: fileUrl, path: `res://assets/models/kenney/${packSlug}/${fileName}` }];
+    }
+    const glbPath = `res://assets/models/kenney/${packSlug}/${fileName}`;
+    const glbDir = glbPath.replace(/\/[^/]+$/, "");
+    const texturePath = `${glbDir}/Textures/colormap.png`;
+    return [
+        { url: textureUrl, path: texturePath },
+        { url: fileUrl, path: glbPath },
+    ];
+}
+async function searchAssetsApi(params) {
+    const token = await getAuthToken();
+    if (!token) {
+        return {
+            error: "Not logged in",
+            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\nAsset search requires a Summer Engine account (free to create).",
+        };
+    }
+    const searchParams = new URLSearchParams();
+    searchParams.set("query", params.query);
+    if (params.assetType && params.assetType !== "all") {
+        searchParams.set("assetType", params.assetType);
+    }
+    if (params.limit) {
+        searchParams.set("limit", String(params.limit));
+    }
+    const res = await fetch(`${GATEWAY_URL}/api/mcp/assets?${searchParams}`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (!res.ok) {
+        if (res.status === 402) {
+            return {
+                error: "upgrade_required",
+                message: (data.message || "Asset search requires a Pro subscription.") +
+                    "\nUpgrade at: https://www.summerengine.com/pricing\nFree tier includes all other MCP tools (scene editing, debugging, etc).",
+                plan: data.plan,
+            };
+        }
+        if (res.status === 401) {
+            return {
+                error: "unauthorized",
+                message: (data.message || "Auth token expired.") +
+                    " The user needs to re-authenticate:\n  npx summer-engine login --force",
+            };
+        }
+        return {
+            error: data.error || "Search failed",
+            message: data.message || "Asset search failed",
+        };
+    }
+    return data;
+}
+export function registerAssetTools(server) {
+    server.tool("summer_search_assets", `Search the Summer Engine asset library (25k+ game assets) by description.
+
+Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
+Returns asset names, types, preview URLs, and import-ready file URLs.
+
+Requires authentication. If the user gets an auth error, they need to run 'npx summer-engine login' in their terminal first.`, {
+        query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon', 'wooden crate'"),
+        assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
+        limit: z.number().default(10).describe("Max results (1-20)"),
+    }, async ({ query, assetType, limit }) => {
+        const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20) });
+        if (result.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: result.error, message: result.message, plan: result.plan }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        assets: result.assets,
+                        count: result.count,
+                        summary: result.summary,
+                        message: result.message,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("summer_import_asset", `Search the asset library and import the best match into the project in one step.
+
+Use when the user wants a specific type of asset added: "Add a tree to the scene", "Import a wooden barrel".
+Searches, picks the top result, downloads and imports it, then optionally adds it to the scene.
+
+Requires authentication. If the user gets an auth error, they need to run 'npx summer-engine login' in their terminal first. Summer Engine must be running.`, {
+        query: z.string().describe("What to find, e.g. 'low-poly tree', 'wooden crate'"),
+        parent: z.string().optional().describe("Parent node path to add the asset under, e.g. './World'. If omitted, only imports (no scene placement)"),
+        assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("3d_model").describe("Preferred asset type"),
+    }, async ({ query, parent, assetType }) => {
+        const searchResult = await searchAssetsApi({ query, assetType, limit: 5 });
+        if (searchResult.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: searchResult.error, message: searchResult.message }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const assets = searchResult.assets || [];
+        if (assets.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "No results", message: `No assets found for "${query}". Try different keywords.` }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const best = assets[0];
+        const fileUrl = best.fileUrl;
+        if (!fileUrl) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "Invalid asset", message: "Asset has no download URL." }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const fileName = fileUrl.split("/").pop()?.split("?")[0] || "asset";
+        const packSlug = best.packSlug ?? getPackSlugFromUrl(fileUrl) ?? "misc";
+        let imports;
+        if (best.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
+            imports = await buildKenneyImportEntries(fileUrl, packSlug, fileName);
+        }
+        else {
+            const path = best.type === "3d_model"
+                ? `res://assets/models/${fileName}`
+                : `res://assets/${fileName}`;
+            imports = [{ url: fileUrl, path }];
+        }
+        const importPath = imports[imports.length - 1].path;
+        try {
+            const client = await getClient();
+            const importResult = imports.length === 1
+                ? await client.executeOps([{ op: "ImportFromUrl", url: imports[0].url, path: imports[0].path }])
+                : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
+            const ok = importResult?.results?.[0]?.ok;
+            if (!ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "Import failed",
+                                message: "Could not import asset. Check engine logs.",
+                                asset: best.title,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (parent && best.type === "3d_model") {
+                await client.executeOps([
+                    { op: "InstantiateScene", parent, scene: importPath, name: best.title.replace(/\s+/g, "_") },
+                ]);
+            }
+            // 2D sprites and audio: import only; user adds to scene manually
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            asset: best.title,
+                            type: best.type,
+                            importedTo: importPath,
+                            addedToScene: parent ? true : false,
+                            parent: parent || null,
+                            message: parent
+                                ? `Imported "${best.title}" and added to ${parent}`
+                                : `Imported "${best.title}" to ${importPath}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Engine error",
+                            message: msg,
+                            hint: "Make sure Summer Engine is running.",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/mcp/tools/debug-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDebugTools(server: McpServer): void;

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

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { withEngine } from "./with-engine.js";
+export function registerDebugTools(server) {
+    server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
+
+ALWAYS call this FIRST before diving into summer_get_console or summer_get_debugger_errors. It tells you where to look.
+
+Typical workflow after making changes:
+1. summer_get_diagnostics — are there issues?
+2. If errors: summer_get_console or summer_get_debugger_errors for details
+3. Fix the issues
+4. summer_get_diagnostics again to verify`, {}, async () => withEngine(async (client) => client.getDiagnostics()));
+    server.tool("summer_get_console", "Read recent messages from the editor's Output panel. Shows print statements, warnings, and errors from both the editor and scripts. Use after summer_get_diagnostics indicates console issues.", {
+        max_lines: z.number().optional().default(100).describe("Max lines to return (default 100)"),
+        filter: z.string().optional().describe("Only return lines containing this string"),
+        type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type"),
+    }, async ({ max_lines, filter, type }) => withEngine(async (client) => {
+        const op = { op: "GetConsoleOutput", max_lines };
+        if (filter)
+            op.filter = filter;
+        if (type)
+            op.type = type;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_clear_console", "Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "ClearConsoleOutput" }])));
+    server.tool("summer_get_debugger_errors", "Read runtime errors and warnings from the debugger. These are errors that occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.", {
+        max_errors: z.number().optional().default(50).describe("Max errors to return"),
+        include_stack: z.boolean().optional().describe("Include stack traces for each error"),
+    }, async ({ max_errors, include_stack }) => withEngine(async (client) => {
+        const op = { op: "GetDebuggerErrors", max_errors };
+        if (include_stack !== undefined)
+            op.include_stack = include_stack;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_play", `Start running the game in the engine. The game runs inside Summer Engine's viewport.
+
+After starting, use summer_get_diagnostics to check for runtime errors.
+
+You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.`, {
+        scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
+    }, async ({ scene }) => withEngine(async (client) => client.play(scene)));
+    server.tool("summer_stop", "Stop the running game. Call this before making scene changes — some operations require the game to not be running.", {}, async () => withEngine(async (client) => client.stop()));
+    server.tool("summer_is_running", "Check if the game is currently running. Returns the active scene path if running.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "IsGameRunning" }])));
+    server.tool("summer_get_script_errors", `Check a GDScript file for parse/compile errors without running the game.
+
+Use after writing or editing a .gd file to verify it compiles. Returns line numbers, error messages, and severity. Much faster than running the game to discover script errors.`, {
+        path: z.string().describe("Script path, e.g. 'res://scripts/player.gd' or 'res://player_controller.gd'"),
+    }, async ({ path }) => withEngine(async (client) => client.getScriptErrors(path)));
+}

package/dist/mcp/tools/project-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProjectTools(server: McpServer): void;

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

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { withEngine } from "./with-engine.js";
+export function registerProjectTools(server) {
+    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
+- "rendering/renderer/rendering_method" — "forward_plus", "mobile", or "gl_compatibility"
+- "display/window/size/viewport_width" — window width
+- "display/window/size/viewport_height" — window height
+- "physics/3d/default_gravity" — gravity value (float)`, {
+        key: z.string().describe("Setting key path, e.g. 'application/config/name'"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Setting value"),
+    }, async ({ key, value }) => withEngine(async (client) => client.executeOps([{ op: "ProjectSetting", key, value }])));
+    server.tool("summer_input_map_bind", `Set up input controls. Creates the action if it doesn't exist, then binds events to it.
+
+Event format:
+- Keyboard: { type: "key", key: "W" } or { type: "key", key: "Space" }
+- Mouse button: { type: "mouse_button", button: 1 } (1=left, 2=right, 3=middle)
+- Common keys: "W", "A", "S", "D", "Space", "Shift", "E", "Escape", "Up", "Down", "Left", "Right"
+
+Example: Bind jump to Space and W:
+  name: "jump", events: [{ type: "key", key: "Space" }, { type: "key", key: "W" }]`, {
+        name: z.string().describe("Action name, e.g. 'jump', 'move_forward', 'interact'"),
+        events: z.array(z.record(z.unknown())).describe("Array of input event objects"),
+    }, async ({ name, events }) => withEngine(async (client) => {
+        const ops = [
+            { op: "InputMapAddAction", name },
+            { op: "InputMapBind", name, events },
+        ];
+        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_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:
+- 3D models (.glb, .gltf, .obj)
+- Textures (.png, .jpg, .webp)
+- Audio (.ogg, .wav, .mp3)
+
+The path is auto-inferred from the URL filename if not specified. After import, the asset is immediately usable in scenes.`, {
+        url: z.string().describe("HTTP(S) URL to download from"),
+        path: z.string().optional().describe("Target path in project, e.g. 'res://assets/player.glb'. Auto-inferred from URL if omitted."),
+    }, async ({ url, path }) => withEngine(async (client) => {
+        const op = { op: "ImportFromUrl", url };
+        if (path)
+            op.path = path;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_import_from_url_batch", "Download multiple files from URLs in one operation. Performs a single filesystem scan after all downloads, which is faster than importing one at a time.", {
+        imports: z.array(z.object({
+            url: z.string().describe("URL to download"),
+            path: z.string().describe("Target path in project"),
+        })).describe("Array of {url, path} objects"),
+    }, async ({ imports }) => withEngine(async (client) => client.executeOps([{ op: "ImportFromUrlBatch", imports }])));
+}

package/dist/mcp/tools/scene-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSceneTools(server: McpServer): void;

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

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { withEngine } from "./with-engine.js";
+export function registerSceneTools(server) {
+    server.tool("summer_add_node", `Add a new node to the 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
+- UI: Control, Label, Button, TextEdit, Panel, VBoxContainer, HBoxContainer, MarginContainer
+- Audio: AudioStreamPlayer, AudioStreamPlayer3D
+
+The parent path uses "./" prefix for relative paths from scene root. E.g., "./World" means the "World" child of the root node.`, {
+        parent: z.string().describe("Parent node path, e.g. './World' or './World/Enemies'"),
+        type: z.string().describe("Godot node type, e.g. 'MeshInstance3D', 'CharacterBody3D'"),
+        name: z.string().describe("Name for the new node, e.g. 'Player', 'MainCamera'"),
+    }, async ({ parent, type, name }) => withEngine(async (client) => client.executeOps([{ op: "AddNode", parent, type, name }])));
+    server.tool("summer_set_prop", `Set a property on a node. This is the primary way to configure nodes after adding them.
+
+VALUE FORMAT — Godot string syntax for complex types:
+- Vector3: "Vector3(0, 10, 0)" — position, scale, rotation_degrees
+- Vector2: "Vector2(100, 200)" — 2D position, size
+- Color: "Color(1, 0.5, 0, 1)" — RGBA, always 4 components, values 0.0-1.0
+- Transform3D: "Transform3D(1,0,0, 0,1,0, 0,0,1, 0,5,0)" — basis + origin
+- Resource class name: "BoxMesh", "SphereMesh", "StandardMaterial3D" — auto-instantiated
+- Numbers: 1.5, 42 — native JSON
+- Booleans: true, false — native JSON
+- Strings: "hello" — native JSON
+
+COMMON PROPERTIES:
+- position: "Vector3(x, y, z)" — world position
+- rotation_degrees: "Vector3(rx, ry, rz)" — rotation in degrees
+- scale: "Vector3(sx, sy, sz)" — scale factor
+- visible: true/false — visibility
+- mesh: "BoxMesh", "SphereMesh", "CapsuleMesh", "CylinderMesh", "PlaneMesh"
+- shadow_enabled: true — for lights
+- light_energy: 1.5 — light intensity
+- fov: 75.0 — camera field of view`, {
+        path: z.string().describe("Node path, e.g. './World/Player'"),
+        key: z.string().describe("Property name, e.g. 'position', 'mesh', 'visible'"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format for complex types, native JSON for primitives"),
+    }, async ({ path, key, value }) => withEngine(async (client) => client.executeOps([{ op: "SetProp", path, key, value }])));
+    server.tool("summer_set_resource_property", `Set a nested property on a resource attached to a node.
+
+Use when you need to modify a sub-property of a resource, like:
+- CollisionShape3D shape size: nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="size", value="Vector3(1, 2, 1)"
+- Material albedo color: nodePath="./Floor", resourceProperty="material_override", subProperty="albedo_color", value="Color(0.2, 0.5, 0.2, 1)"
+- Mesh size: nodePath="./Box", resourceProperty="mesh", subProperty="size", value="Vector3(2, 2, 2)"`, {
+        nodePath: z.string().describe("Node path, e.g. './Player/CollisionShape3D'"),
+        resourceProperty: z.string().describe("Resource property on the node, e.g. 'shape', 'mesh', 'material_override'"),
+        subProperty: z.string().describe("Property on the resource, e.g. 'size', 'radius', 'albedo_color'"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format"),
+    }, 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_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_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
+- Compose scenes from smaller scenes (e.g., add a "Player" scene into a "Level" scene)
+
+The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.`, {
+        parent: z.string().describe("Parent node path, e.g. './World'"),
+        scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
+        name: z.string().optional().describe("Override the instance name"),
+    }, async ({ parent, scene, name }) => withEngine(async (client) => {
+        const op = { op: "InstantiateScene", parent, scene };
+        if (name)
+            op.name = name;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
+
+Common signals:
+- "body_entered" / "body_exited" — Area3D/Area2D detects physics bodies
+- "pressed" — Button clicked
+- "timeout" — Timer finished
+- "area_entered" — Area detects another area
+- "input_event" — CollisionObject received input
+
+The receiver node must have a script with the specified method.`, {
+        emitter: z.string().describe("Node that fires the signal, e.g. './Player/HitArea'"),
+        signal: z.string().describe("Signal name, e.g. 'body_entered'"),
+        receiver: z.string().describe("Node with the handler script, e.g. './Player'"),
+        method: z.string().describe("Method name in the receiver's script, e.g. '_on_hit_area_body_entered'"),
+    }, async ({ emitter, signal, receiver, method }) => withEngine(async (client) => client.executeOps([
+        { op: "ConnectSignal", emitter, signal, receiver, method },
+    ])));
+    server.tool("summer_select_node", "Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.", {
+        nodePath: z.string().describe("Node path to select"),
+        scenePath: z.string().optional().describe("Open this scene first, then select the node"),
+    }, async ({ nodePath, scenePath }) => withEngine(async (client) => {
+        const op = { op: "SelectNode", nodePath };
+        if (scenePath)
+            op.scenePath = scenePath;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_replace_node", "Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for changing a StaticBody3D to a RigidBody3D, or swapping a placeholder with a proper prefab.", {
+        path: z.string().describe("Node path to replace"),
+        type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'"),
+        scene: z.string().optional().describe("Scene to replace with, e.g. 'res://enemies/boss.tscn'"),
+    }, async ({ path, type, scene }) => withEngine(async (client) => {
+        const op = { op: "ReplaceNode", path };
+        if (type)
+            op.type = type;
+        if (scene)
+            op.scene = scene;
+        return client.executeOps([op]);
+    }));
+    server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
+
+Call this before modifying a node to understand its current state. Returns every property the Godot inspector would show.
+
+Example: inspect a light to see its energy, color, shadow settings before changing them.`, {
+        path: z.string().describe("Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'"),
+    }, async ({ path }) => withEngine(async (client) => client.inspectNode(path)));
+    server.tool("summer_inspect_resource", `Get all properties of a resource (material, mesh, shape, environment, etc).
+
+Use when you need the sub-properties of a resource attached to a node. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material — this tool tells you that material's albedo_color, metallic, roughness, etc.`, {
+        path: z.string().describe("Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'"),
+    }, async ({ path }) => withEngine(async (client) => client.inspectResource(path)));
+    server.tool("summer_batch", `Execute multiple operations in a single call, grouped into one undo step.
+
+The user can undo everything with a single Ctrl+Z. Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
+
+Each op in the array uses the same format as the individual tools:
+- {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
+- {"op": "SetProp", "path": "Floor", "key": "position", "value": "Vector3(0, -1, 0)"}
+- {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
+- {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}`, {
+        ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
+    }, async ({ ops }) => withEngine(async (client) => client.executeOps(ops, { groupUndo: true })));
+}

package/dist/mcp/tools/with-engine.d.ts

@@ -0,0 +1,10 @@
+import { getClient } from "../server.js";
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>): Promise<ToolResult>;
+export {};

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

@@ -0,0 +1,65 @@
+import { getClient, resetClient } from "../server.js";
+import { getAuthToken } from "../../lib/auth.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+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);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        resetClient();
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }], isError: true };
+    }
+}

package/package.json

@@ -1,20 +1,37 @@
 {
   "name": "summer-engine",
-  "version": "0.0.1",
-  "description": "CLI and MCP tools for Summer Engine - the AI-native game engine",
+  "version": "1.0.0",
+  "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": ["game-engine", "godot", "ai", "mcp", "gamedev", "3d", "summer-engine"],
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/summerengine/cli"
+    "url": "https://github.com/SummerEngine/summer-engine-cli"
   },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",
+  "type": "module",
   "bin": {
-    "summer": "./bin/summer.js"
+    "summer": "./dist/bin/summer.js"
+  },
+  "files": ["dist/", "skills/", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "summer": "node dist/bin/summer.js",
+    "prepublishOnly": "npm run build"
   },
-  "files": ["bin/", "README.md"],
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.0.0",
+    "open": "^10.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
   }
 }