virtualmatter 0.1.0 → 0.3.0

package/dist/index.js

@@ -3,29 +3,59 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { resolveSession, sessionBaseUrl, fetchNativeClients, whoami } from "./api.js";
-import { clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
+import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
 import { openInBrowser } from "./browser.js";
+import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
+import { apiBase, packageVersion } from "./config.js";
 import { FilesClient } from "./files.js";
-import { runMcpServer, resolveFramingId } from "./mcp.js";
+import { runMcpServer } from "./mcp.js";
 import { pullCommand } from "./pull.js";
-import { requireState } from "./state.js";
+import { NeedsChoiceError, formatProjectList, makeFramingOf, resolveImplicitTarget, resolveTarget, } from "./resolve.js";
+import { loadState, requireState } from "./state.js";
 import { SyncEngine, runSyncLoop } from "./sync.js";
-import { parseTarget, PROJECT_URL_HELP } from "./urls.js";
 const program = new Command();
 program
     .name("virtualmatter")
-    .description("Build with Virtual Matter from your terminal: sync montage files, run Lua, capture screenshots, and expose it all to coding agents over MCP.")
-    .version("0.1.0");
+    .description("Build with Virtual Matter from your terminal or coding agent: list and create worlds, mirror their files, live-sync edits, run Lua, capture screenshots, open the native client, and expose it all over MCP.")
+    .version(packageVersion());
 function fail(message) {
     console.error(message);
     process.exit(1);
 }
+/** The device-code sign-in, shared by `login` and the automatic first-use sign-in. */
+async function signIn() {
+    const { auth, tokenEndpoint } = await startDeviceFlow();
+    const url = auth.verification_uri_complete ?? auth.verification_uri;
+    console.log(`Sign in with Virtual Matter: open ${url}`);
+    console.log(`and enter the code: ${auth.user_code}`);
+    console.log("(waiting for you to approve it in the browser ...)");
+    openInBrowser(url);
+    const creds = await pollForToken(tokenEndpoint, auth);
+    saveCredentials(creds);
+    const me = await whoami();
+    console.log(`Signed in as ${me.username ?? me.email ?? me.id}.`);
+}
+/**
+ * Run a command. Not signed in yet? Sign in right here and run it again -
+ * a first-time user should never have to learn that `login` exists.
+ * Set VIRTUALMATTER_NO_AUTO_LOGIN=1 to get the old error instead.
+ */
 async function run(fn) {
     try {
         await fn();
     }
     catch (err) {
+        if (err instanceof NotLoggedInError && !process.env.VIRTUALMATTER_NO_AUTO_LOGIN) {
+            try {
+                await signIn();
+                await fn();
+                return;
+            }
+            catch (again) {
+                fail(again instanceof Error ? again.message : String(again));
+            }
+        }
         fail(err instanceof Error ? err.message : String(err));
     }
 }
@@ -35,20 +65,45 @@ async function clientForDir(dir) {
     const session = await resolveSession(state.framing_id);
     return { client: new FilesClient(sessionBaseUrl(session), state.framing_id), framingId: state.framing_id };
 }
+/** A target from the argument, else from the folder, else the only project. */
+async function resolveTargetOrImplicit(target, dir) {
+    if (target)
+        return resolveTarget(target);
+    try {
+        return await resolveImplicitTarget(dir);
+    }
+    catch (err) {
+        if (err instanceof NeedsChoiceError)
+            fail(err.message);
+        throw err;
+    }
+}
+function slugFor(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "world";
+}
+function reportPull(result, dest) {
+    console.log(`Pulled ${result.fileCount} files into ${dest}.`);
+    const files = result.agentFiles;
+    if (files && files.written.length > 0) {
+        console.log(`Wrote ${files.written.join(", ")} so Claude Code, Codex, and Cursor find their way around.`);
+    }
+    const rel = path.relative(process.cwd(), dest) || ".";
+    // A relative path is friendlier only while it stays short; a folder far
+    // from the cwd reads better as the absolute path it is.
+    const shown = rel.startsWith("..") ? dest : rel;
+    console.log(`Next: cd ${JSON.stringify(shown).slice(1, -1).includes(" ") ? `"${shown}"` : shown} && npx virtualmatter sync`);
+    console.log(`      (or open the folder in your agent - the MCP server is registered in .mcp.json)`);
+}
 program
     .command("login")
-    .description("Sign in with Virtual Matter using a device code")
-    .action(() => run(async () => {
-    const { auth, tokenEndpoint } = await startDeviceFlow();
-    const url = auth.verification_uri_complete ?? auth.verification_uri;
-    console.log(`Open ${url}`);
-    console.log(`and enter the code: ${auth.user_code}`);
-    openInBrowser(url);
-    const creds = await pollForToken(tokenEndpoint, auth);
-    saveCredentials(creds);
-    const me = await whoami();
-    console.log(`Signed in as ${me.username ?? me.email ?? me.id}.`);
-}));
+    .description("Sign in with Virtual Matter using a device code (other commands do this automatically)")
+    .action(() => run(signIn));
 program
     .command("logout")
     .description("Forget the stored credentials")
@@ -61,25 +116,106 @@ program
     .description("Show who is signed in")
     .action(() => run(async () => {
     if (!loadCredentials())
-        fail("Not signed in. Run `virtualmatter login` first.");
+        throw new NotLoggedInError();
     const me = await whoami();
     console.log(JSON.stringify(me, null, 2));
 }));
+program
+    .command("embed <target>")
+    .description("Get iframe markup and required hosting setup for a shared world; no sign-in")
+    .action((target) => run(async () => console.log(JSON.stringify(await getEmbed(target), null, 2))));
+program
+    .command("build <name>")
+    .description("Create a private world and send a build prompt to VM's agent (uses VM credits)")
+    .requiredOption("--prompt <text>", "What VM should build")
+    .requiredOption("--request-id <id>", "Stable identifier for this request; reuse on retries")
+    .option("--region <region>", "NA, EU, or AS", defaultRegion())
+    .action((name, opts) => run(async () => console.log(JSON.stringify(await createWebsiteBuild({ name, prompt: opts.prompt, request_id: opts.requestId, region: opts.region }), null, 2))));
+program
+    .command("build-status <build-id>")
+    .description("Read a previously requested VM build's progress")
+    .action((id) => run(async () => console.log(JSON.stringify(await getWebsiteBuild(id), null, 2))));
+program
+    .command("list")
+    .alias("ls")
+    .alias("projects")
+    .description("List your worlds (projects) with their editing framing ids and URLs")
+    .option("--json", "machine-readable output")
+    .action((opts) => run(async () => {
+    const projects = await listProjects();
+    if (opts.json) {
+        console.log(JSON.stringify(projects.map((p) => ({
+            name: p.name,
+            id: p.id,
+            region: p.region,
+            framing_id: p.make_framing_id,
+            edit_url: p.make_framing_id ? editUrl(p.make_framing_id, p.url_slug) : null,
+            play_url: p.play_framing_id ? playUrl(p.play_framing_id) : null,
+            updated_at: p.updated_at ?? null,
+        })), null, 2));
+        return;
+    }
+    if (projects.length === 0) {
+        console.log('No worlds yet. Create one: npx virtualmatter create "My world"');
+        return;
+    }
+    console.log(formatProjectList(projects));
+    console.log("");
+    console.log("Pull one: npx virtualmatter pull <framing id or URL>");
+}));
+program
+    .command("create")
+    .description("Create a new world and mirror its files into a local folder")
+    .argument("<name>", "the world's name")
+    .argument("[dir]", "destination folder (default: ./<name-as-slug>)")
+    .option("--region <region>", "NA, EU, or AS (default: nearest)")
+    .option("--description <text>", "one-line description")
+    .option("--track <track>", "engine track: stable or master", "stable")
+    .option("--no-pull", "create only; do not download the files")
+    .option("--open", "also open the new world in the native client")
+    .option("--json", "machine-readable output")
+    .action((name, dir, opts) => run(async () => {
+    const region = (opts.region ?? defaultRegion()).toUpperCase();
+    if (!["NA", "EU", "AS"].includes(region))
+        fail("--region must be NA, EU, or AS");
+    if (opts.track !== "stable" && opts.track !== "master")
+        fail("--track must be stable or master");
+    const project = await createProject({
+        name,
+        description: opts.description,
+        region,
+        engine_track: opts.track,
+    });
+    const framingId = makeFramingOf(project);
+    const url = editUrl(framingId, project.url_slug);
+    let pulled = null;
+    let dest = null;
+    if (opts.pull) {
+        dest = path.resolve(dir ?? slugFor(project.name));
+        pulled = await pullCommand(framingId, dest);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ name: project.name, id: project.id, region: project.region, framing_id: framingId, edit_url: url, dir: dest, file_count: pulled?.fileCount ?? null }, null, 2));
+    }
+    else {
+        console.log(`Created "${project.name}" in ${project.region}.`);
+        console.log(`Edit in the browser: ${url}`);
+        if (pulled && dest)
+            reportPull(pulled, dest);
+    }
+    if (opts.open)
+        await openNative(framingId, url);
+}));
 program
     .command("pull")
-    .description("Download a framing's file tree into a local folder")
-    .argument("<target>", "an /edit, /play, or /m URL - or a bare framing id")
-    .argument("[dir]", "destination folder (default: ./<framing-id>)")
+    .description("Download a world's file tree into a local folder")
+    .argument("[target]", "any Virtual Matter link (/edit, /play, /g, /p, /projects) or a framing id; omitted = your only world")
+    .argument("[dir]", "destination folder (default: ./<world name or framing id>)")
     .action((target, dir) => run(async () => {
-    const parsed = parseTarget(target);
-    if (parsed.kind === "project")
-        fail(PROJECT_URL_HELP);
-    if (parsed.kind === "invalid")
-        fail(parsed.reason);
-    const dest = path.resolve(dir ?? parsed.framingId);
-    const result = await pullCommand(parsed.framingId, dest);
-    console.log(`Pulled ${result.fileCount} files into ${dest}.`);
-    console.log(`Next: cd ${path.relative(process.cwd(), dest) || "."} && virtualmatter sync`);
+    const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    const dest = path.resolve(dir ?? (resolved.project ? slugFor(resolved.project.name) : resolved.framingId));
+    const result = await pullCommand(resolved.framingId, dest);
+    reportPull(result, dest);
 }));
 program
     .command("sync")
@@ -116,43 +252,84 @@ program
     const { client } = await clientForDir(path.resolve(dir));
     console.log(JSON.stringify(await client.engineErrors(), null, 2));
 }));
+/** Parse an "x,y,z" flag into a numeric triple. */
+function triple(value, flag) {
+    const parts = value.split(",").map((p) => Number(p.trim()));
+    if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) {
+        fail(`${flag} takes three numbers, e.g. ${flag} 0,20,20`);
+    }
+    return [parts[0], parts[1], parts[2]];
+}
 program
     .command("screenshot")
-    .description("Capture a PNG of the engine's current view")
+    .description("Capture a PNG of the world - a default overview, or aimed with --at/--rot or --target")
     .argument("[dir]", "a synced folder", ".")
     .option("-o, --out <file>", "output file", "screenshot.png")
+    .option("--at <x,y,z>", "camera position (default: 0,20,20)")
+    .option("--rot <yaw,pitch,roll>", "camera rotation in degrees, yaw first (default: 0,-45,0)")
+    .option("--target <id-or-name>", "frame this object instead of using a camera pose")
+    .option("--distance <meters>", "framing distance for --target (default: from the object's bounds)")
     .action((dir, opts) => run(async () => {
     const { client } = await clientForDir(path.resolve(dir));
-    const png = await client.screenshot();
+    const png = await client.screenshot({
+        at: opts.at ? triple(opts.at, "--at") : undefined,
+        rot: opts.rot ? triple(opts.rot, "--rot") : undefined,
+        target: opts.target,
+        distance: opts.distance === undefined ? undefined : Number(opts.distance),
+    });
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);
 }));
+/** Install the native client if needed, sign it in, and launch it into a world. */
+async function openNative(framingId, url, force = false) {
+    const installed = await ensureClientInstalled({ framingId, force });
+    const seeded = seedNativeAuth(installed);
+    if (seeded.length > 0)
+        console.log("Signed the native client in with your account.");
+    launchClient(installed, url);
+    console.log(`Opening ${url} in the Virtual Matter client (${installed.dir}).`);
+    if (installed.platform === "linux") {
+        console.log("Linux: the client starts through run.sh with its bundled libraries. If no window appears, read the newest file in ~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/ - \"Failed to initialize graphics adapter\" means this build has no renderer for your setup yet; the world still runs in the browser at the URL above, and every CLI command works without the client.");
+    }
+}
 program
-    .command("client")
-    .description("Print the native client download URL for this OS")
-    .action(() => run(async () => {
-    const clients = await fetchNativeClients();
-    const platform = process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux";
-    const matches = clients.filter((c) => c.platform.toLowerCase().includes(platform));
-    if (matches.length === 0) {
-        console.log(`No native client published for ${platform} yet. All available:`);
-        for (const c of clients)
-            console.log(`  ${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+    .command("open")
+    .alias("client")
+    .description("Open a world in the native desktop client - downloads and signs it in on first use")
+    .argument("[target]", "any Virtual Matter link or framing id; omitted = this folder's world, or your only one")
+    .option("--install-only", "download and unpack the client without launching it")
+    .option("--print", "only print the download URL for this OS")
+    .option("--force", "re-download the client even if this build is already unpacked")
+    .action((target, opts) => run(async () => {
+    if (opts.print) {
+        const catalog = await fetchNativeClientCatalog(loadState(path.resolve("."))?.framing_id);
+        const platform = detectPlatform();
+        const mine = catalog.clients.filter((c) => c.platform.toLowerCase() === platform);
+        const rows = mine.length > 0 ? mine : catalog.clients;
+        if (mine.length === 0)
+            console.log(`No native client published for ${platform} yet. All available:`);
+        for (const c of rows) {
+            const u = c.url.startsWith("http") ? c.url : `${apiBase()}${c.url}`;
+            console.log(`${c.platform} (${c.kind}): ${u}`);
+        }
         return;
     }
-    for (const c of matches)
-        console.log(`${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+    if (opts.installOnly) {
+        const installed = await ensureClientInstalled({ force: opts.force });
+        const seeded = seedNativeAuth(installed);
+        console.log(`Installed the Virtual Matter client at ${installed.dir}${seeded.length ? " and signed it in." : "."}`);
+        return;
+    }
+    const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    await openNative(resolved.framingId, editUrl(resolved.framingId, resolved.project?.url_slug), opts.force);
 }));
 program
     .command("mcp")
-    .description("Run the stdio MCP server for coding agents")
-    .argument("[dir]", "a synced folder whose state file names the framing", ".")
+    .description("Run the stdio MCP server for coding agents (works with or without a selected world)")
+    .argument("[dir]", "a synced folder whose state file names the world", ".")
     .option("--framing <id>", "framing id (overrides the state file)")
     .action((dir, opts) => run(async () => {
-    const abs = path.resolve(dir);
-    // Validate early so misconfiguration fails loudly at registration time.
-    resolveFramingId(abs, opts.framing);
-    await runMcpServer(abs, opts.framing);
+    await runMcpServer(path.resolve(dir), opts.framing);
 }));
 program.parseAsync(process.argv).catch((err) => {
     fail(err instanceof Error ? err.message : String(err));

package/dist/mcp.js

@@ -1,44 +1,77 @@
 /**
  * `virtualmatter mcp` - a stdio MCP server that gives a coding agent direct
- * hands on a live Virtual Matter session: montage files, Lua execution,
- * engine errors, and screenshots.
+ * hands on Virtual Matter: the account's projects, creating one, a live
+ * session's files, Lua execution, engine errors, screenshots, and the
+ * native client.
+ *
+ * The server starts without a world selected when the folder has no
+ * state file and no --framing was given; `list_projects`, `create_project`
+ * and `select_project` work in that state, and every world-bound tool says
+ * how to pick one.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { resolveSession, sessionBaseUrl } from "./api.js";
-import { apiBase } from "./config.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
+import { ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
+import { packageVersion } from "./config.js";
 import { ConflictError, FilesClient } from "./files.js";
+import { pullCommand } from "./pull.js";
+import { makeFramingOf, resolveTarget } from "./resolve.js";
 import { loadState } from "./state.js";
 export function resolveFramingId(dir, framingFlag) {
     if (framingFlag)
         return framingFlag;
     const state = loadState(dir);
-    if (state)
-        return state.framing_id;
-    throw new Error(`No .virtualmatter.json in ${dir} and no --framing flag. Run \`virtualmatter pull\` there first, or pass --framing <id>.`);
+    return state ? state.framing_id : null;
 }
+const NO_WORLD = "No world is selected. Call select_project with a Virtual Matter URL or id, create_project to make a new one, or list_projects to see what exists.";
 function makeContext(framingId) {
     let session = null;
     let client = null;
-    const getSession = async () => {
-        if (!session)
-            session = await resolveSession(framingId);
-        return session;
-    };
-    return {
+    const ctx = {
         framingId,
-        getSession,
+        project: null,
+        select(id, project) {
+            if (id !== ctx.framingId) {
+                session = null;
+                client = null;
+            }
+            ctx.framingId = id;
+            ctx.project = project ?? null;
+        },
+        requireFraming() {
+            if (!ctx.framingId)
+                throw new Error(NO_WORLD);
+            return ctx.framingId;
+        },
+        async getSession() {
+            if (!session)
+                session = await resolveSession(ctx.requireFraming());
+            return session;
+        },
         async getClient() {
             if (!client)
-                client = new FilesClient(sessionBaseUrl(await getSession()), framingId);
+                client = new FilesClient(sessionBaseUrl(await ctx.getSession()), ctx.requireFraming());
             return client;
         },
     };
+    return ctx;
 }
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
+function projectSummary(p) {
+    return {
+        name: p.name,
+        id: p.id,
+        region: p.region,
+        framing_id: p.make_framing_id,
+        edit_url: p.make_framing_id ? editUrl(p.make_framing_id, p.url_slug) : null,
+        play_url: p.play_framing_id ? playUrl(p.play_framing_id) : null,
+        updated_at: p.updated_at ?? null,
+    };
+}
 /**
  * write_file etag handling: look up the current etag from a listing, PUT with
  * If-Match (or If-None-Match: * for a new file), and on 412 retry ONCE with a
@@ -62,9 +95,75 @@ export async function writeWithRetry(client, filePath, body) {
     }
 }
 export async function runMcpServer(dir, framingFlag) {
-    const framingId = resolveFramingId(dir, framingFlag);
-    const ctx = makeContext(framingId);
-    const server = new McpServer({ name: "virtualmatter", version: "0.1.0" });
+    const ctx = makeContext(resolveFramingId(dir, framingFlag));
+    const server = new McpServer({ name: "virtualmatter", version: packageVersion() });
+    server.registerTool("get_embed", {
+        description: "Get canonical iframe markup and hosting instructions for a shared Virtual Matter world URL. No sign-in needed. Follow the instructions and verify the published page.",
+        inputSchema: { target: z.string() },
+    }, async ({ target }) => textResult(JSON.stringify(await getEmbed(target))));
+    server.registerTool("get_build_status", {
+        description: "Check a VM build by build_id. Do not create another project to check progress. Review the world and enable sharing before embedding.",
+        inputSchema: { build_id: z.string() },
+    }, async ({ build_id }) => textResult(JSON.stringify(await getWebsiteBuild(build_id))));
+    server.registerTool("list_projects", {
+        description: "List the signed-in maker's Virtual Matter projects (worlds): name, id, region, the editing framing id, and edit/play URLs. Call this to find a world to work in, then select_project.",
+        inputSchema: {},
+    }, async () => textResult(JSON.stringify((await listProjects()).map(projectSummary), null, 2)));
+    server.registerTool("create_project", {
+        description: "Create a new Virtual Matter world (project) for the signed-in maker and select it for this session. The world spins up live on Virtual Matter servers; its content is SDK Lua plus assets that hot-reload as you write them. Region defaults to the one nearest this machine.",
+        inputSchema: {
+            name: z.string().min(1).max(100).describe("Project name, e.g. \"Lava Arena\""),
+            prompt: z.string().min(1).max(16000).optional().describe("Optional build prompt to send to VM's agent, using VM credits. Requires request_id. Starts privately."),
+            request_id: z.string().min(8).max(100).optional().describe("Stable id for a prompted build; reuse unchanged on retries."),
+            description: z.string().max(1000).optional().describe("One-line description (optional)"),
+            region: z.enum(["NA", "EU", "AS"]).optional().describe("Hosting region (default: nearest)"),
+            pull_to: z
+                .string()
+                .optional()
+                .describe("Local folder to mirror the new world's files into (optional; sync works from there)"),
+        },
+    }, async ({ name, description, region, pull_to, prompt, request_id }) => {
+        if (prompt) {
+            if (!request_id)
+                throw new Error("A stable request_id is required when sending a build prompt.");
+            if (pull_to || description)
+                throw new Error("Prompted builds run in VM. Omit pull_to/description and use select_project afterwards if local files are needed.");
+            const build = await createWebsiteBuild({ name, prompt, request_id, region: region ?? defaultRegion() });
+            if (build.framing_id)
+                ctx.select(build.framing_id);
+            return textResult(JSON.stringify(build));
+        }
+        const project = await createProject({ name, description, region: region ?? defaultRegion() });
+        const framingId = makeFramingOf(project);
+        ctx.select(framingId, project);
+        let pulled = null;
+        if (pull_to) {
+            const result = await pullCommand(framingId, pull_to);
+            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+        }
+        return textResult(JSON.stringify({ ...projectSummary(project), selected: true, pulled }, null, 2));
+    });
+    server.registerTool("select_project", {
+        description: "Select the world this session works on. Accepts any Virtual Matter link (/edit, /play, /g, /p, /projects, with or without a readable slug) or a bare framing id. Optionally mirrors its files into a local folder.",
+        inputSchema: {
+            target: z.string().describe("A Virtual Matter URL or framing id"),
+            pull_to: z.string().optional().describe("Local folder to mirror the world's files into (optional)"),
+        },
+    }, async ({ target, pull_to }) => {
+        const resolved = await resolveTarget(target);
+        ctx.select(resolved.framingId, resolved.project);
+        let pulled = null;
+        if (pull_to) {
+            const result = await pullCommand(resolved.framingId, pull_to);
+            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+        }
+        return textResult(JSON.stringify({
+            framing_id: resolved.framingId,
+            edit_url: editUrl(resolved.framingId, resolved.project?.url_slug),
+            project: resolved.project ? projectSummary(resolved.project) : null,
+            pulled,
+        }, null, 2));
+    });
     server.registerTool("list_files", {
         description: "List every file in the live Virtual Matter session's Montage tree. Returns path, size, mtime_ms, and etag per file. Call this before reading or writing to learn what exists. Lua scripts under this tree hot-reload in the engine when written.",
         inputSchema: {},
@@ -113,26 +212,58 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify(await client.engineErrors(), null, 2));
     });
     server.registerTool("capture_screenshot", {
-        description: "Capture a PNG screenshot of the engine's current view and return it as an image. Use it to visually verify what a change actually looks like in the world.",
-        inputSchema: {},
-    }, async () => {
+        description: "Capture a PNG screenshot of the world and return it as an image - how you SEE what you built. With no arguments it shoots a default overview of the world origin. Pass target to frame one object by name or id (easiest and usually what you want), or a full at + rot camera pose. Use it to visually verify a change instead of assuming it worked.",
+        inputSchema: {
+            target: z
+                .string()
+                .optional()
+                .describe("Object name or id to frame; the engine picks the distance"),
+            at: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera position [x, y, z]; Y is up and -Z is forward"),
+            rot: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera rotation in degrees as [yaw, pitch, roll] - that order. Yaw 0 faces -Z; pitch -90 looks straight down, 0 is the horizon. Default [0, -45, 0] looks down at the origin."),
+        },
+    }, async ({ target, at, rot }) => {
         const client = await ctx.getClient();
-        const png = await client.screenshot();
+        const png = await client.screenshot({
+            target,
+            at: at,
+            rot: rot,
+        });
         return {
             content: [
                 { type: "image", data: png.toString("base64"), mimeType: "image/png" },
             ],
         };
     });
+    server.registerTool("open_native_client", {
+        description: "Open the selected world on this machine in the Virtual Matter native desktop client (higher performance than the browser). Downloads and unpacks the client on first use, signs it in with the CLI's account, and launches it into the world. Returns where the client lives and the URL it opened.",
+        inputSchema: {},
+    }, async () => {
+        const framingId = ctx.requireFraming();
+        const installed = await ensureClientInstalled({ framingId, log: () => undefined });
+        const signedIn = seedNativeAuth(installed);
+        const url = editUrl(framingId);
+        launchClient(installed, url);
+        return textResult(JSON.stringify({ launched: true, url, client_dir: installed.dir, signed_in_via_cli: signedIn.length > 0 }, null, 2));
+    });
     server.registerTool("world_info", {
-        description: "Return the framing id plus the URLs for this session: the editor and play links a human can open, and the session API base this server talks to.",
+        description: "Return the selected world's framing id plus its URLs: the editor and play links a human can open, and the session API base this server talks to.",
         inputSchema: {},
     }, async () => {
+        const framingId = ctx.requireFraming();
         const session = await ctx.getSession();
         return textResult(JSON.stringify({
-            framing_id: ctx.framingId,
-            edit_url: `${apiBase()}/edit/${ctx.framingId}`,
-            play_url: `${apiBase()}/play/${ctx.framingId}`,
+            framing_id: framingId,
+            project: ctx.project ? projectSummary(ctx.project) : null,
+            edit_url: editUrl(framingId, ctx.project?.url_slug),
+            play_url: playUrl(framingId),
             session_api_base: sessionBaseUrl(session),
             voxel_host: session.voxel_host,
             session_id: session.session_id,