@mavonengine/cli 0.0.1 → 0.0.2

package/dist/index.js

@@ -1,173 +1,208 @@
 #!/usr/bin/env node
+import {
+  DEFAULT_DOCS_URL,
+  MCP_CONFIG_FILE,
+  version,
+  writeMcpConfig
+} from "./chunk-TNN4S5K4.js";
 
 // src/index.ts
-import process6 from "process";
-
-// package.json
-var version = "0.0.1";
+import process9 from "process";
 
-// src/commands/create.ts
-import { existsSync as existsSync3 } from "fs";
-import process5 from "process";
-import { createInterface } from "readline/promises";
+// src/commands/build.ts
+import { spawn as spawn3 } from "child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3, resolve as resolve3 } from "path";
+import process4 from "process";
 import { parseArgs as parseArgs3 } from "util";
 
-// src/create/project.ts
-import { spawn } from "child_process";
-import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
+// ../core/dist/Plugins/ProjectConfig.js
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, relative, resolve } from "path";
-import process from "process";
-import { Readable, Transform } from "stream";
-import { pipeline } from "stream/promises";
-import AdmZip from "adm-zip";
-
-// src/dashboard/format.ts
-var BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB"];
-function formatBytes(bytes, decimals = 1) {
-  if (!Number.isFinite(bytes) || bytes <= 0)
-    return "0 B";
-  const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), BYTE_UNITS.length - 1);
-  const value = bytes / 1024 ** exponent;
-  return `${exponent === 0 ? value : value.toFixed(decimals)} ${BYTE_UNITS[exponent]}`;
+var CONFIG_FILE = "mavonengine.json";
+var TARGETS = ["client", "server", "both"];
+var PluginConfigError = class extends Error {
+};
+function configPath(root) {
+  return join(root, CONFIG_FILE);
+}
+function readConfig(root) {
+  const path = configPath(root);
+  if (!existsSync(path))
+    return { plugins: {} };
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new PluginConfigError(`${path} is not valid JSON: ${err.message}`);
+  }
+  if (!config || typeof config !== "object" || Array.isArray(config))
+    throw new PluginConfigError(`${path} must contain a JSON object`);
+  const result = config;
+  if (result.plugins === void 0)
+    result.plugins = {};
+  else if (!result.plugins || typeof result.plugins !== "object" || Array.isArray(result.plugins))
+    throw new PluginConfigError(`"plugins" in ${path} must be an object`);
+  return result;
+}
+function writeConfig(root, config) {
+  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}
+`);
 }
-function formatRate(bytesPerSecond) {
-  return `${formatBytes(bytesPerSecond)}/s`;
+function updateConfig(root, change) {
+  const config = readConfig(root);
+  if (!change(config))
+    return false;
+  writeConfig(root, config);
+  return true;
 }
-function formatDuration(totalSeconds) {
-  const seconds = Math.max(0, Math.floor(totalSeconds));
-  const d = Math.floor(seconds / 86400);
-  const h = Math.floor(seconds % 86400 / 3600);
-  const m = Math.floor(seconds % 3600 / 60);
-  const s = seconds % 60;
-  if (d > 0)
-    return `${d}d ${h}h ${m}m`;
-  if (h > 0)
-    return `${h}h ${m}m ${s}s`;
-  if (m > 0)
-    return `${m}m ${s}s`;
-  return `${s}s`;
+function addPluginToConfig(root, pkg) {
+  return updateConfig(root, (config) => {
+    const existing = config.plugins[pkg];
+    if (existing && existing.enabled !== false)
+      return false;
+    config.plugins[pkg] = existing ? { ...existing, enabled: true } : { enabled: true };
+    return true;
+  });
 }
-function formatMs(ms) {
-  return `${ms.toFixed(ms < 10 ? 2 : 1)} ms`;
+function findPackageDir(root, pkg) {
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", pkg);
+    if (existsSync(join(candidate, "package.json")))
+      return candidate;
+    if (dirname(dir) === dir)
+      return void 0;
+  }
 }
-function formatPercent(value) {
-  return `${value.toFixed(1)}%`;
+function validateManifest(pkg, value) {
+  if (!value || typeof value !== "object")
+    throw new PluginConfigError(`${pkg}: "mavonengine" in package.json must be an object`);
+  const manifest = value;
+  if (!TARGETS.includes(manifest.target))
+    throw new PluginConfigError(`${pkg}: "mavonengine.target" must be one of ${TARGETS.join(", ")}`);
+  for (const side of ["client", "server"]) {
+    if (runsOn(manifest.target, side) && typeof manifest[side] !== "string")
+      throw new PluginConfigError(`${pkg}: "mavonengine.${side}" is required for target "${manifest.target}"`);
+  }
+  return manifest;
 }
-
-// src/create/project.ts
-var TEMPLATE_URL = "https://github.com/MavonEngine/Core/archive/refs/tags/0.0.15-alpha.zip";
-var TEMPLATE_SUBPATH = "packages/multiplayer-template";
-var PROJECT_NAME_RE = /^[\w@./-][\w@./\- ]*$/;
-function projectDirFor(projectName, parentDir) {
-  return resolve(parentDir, projectName);
+function readPluginManifest(root, pkg) {
+  const dir = findPackageDir(root, pkg);
+  if (!dir)
+    return void 0;
+  const packageJson = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  if (packageJson.mavonengine === void 0)
+    return void 0;
+  return { package: pkg, version: packageJson.version, dir, manifest: validateManifest(pkg, packageJson.mavonengine) };
 }
-async function downloadZip(url, { report, signal, fetch = globalThis.fetch }) {
-  const response = await fetch(url, { signal });
-  if (!response.ok || !response.body)
-    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
-  const total = Number(response.headers.get("content-length")) || 0;
-  let received = 0;
-  const progress = new Transform({
-    transform(chunk, _encoding, callback) {
-      received += chunk.length;
-      report.step(`Downloading the template\u2026 ${formatBytes(received)}${total ? ` of ${formatBytes(total)}` : ""}`);
-      callback(null, chunk);
-    }
-  });
-  const dest = join(tmpdir(), `mavonengine-create-${process.pid}-${Date.now()}.zip`);
-  try {
-    await pipeline(Readable.fromWeb(response.body), progress, createWriteStream(dest), { signal });
-  } catch (err) {
-    rmSync(dest, { force: true });
-    throw err;
-  }
-  return dest;
+function runsOn(target, side) {
+  return target === "both" || target === side;
 }
-function extractTemplate(zipPath, templateSubpath, destDir) {
-  const entries = new AdmZip(zipPath).getEntries();
-  if (entries.length === 0)
-    throw new Error("Downloaded zip archive is empty");
-  const rootFolder = entries[0].entryName.split("/")[0];
-  const templatePrefix = `${rootFolder}/${templateSubpath}/`;
-  const templateEntries = entries.filter((e) => e.entryName.startsWith(templatePrefix));
-  if (templateEntries.length === 0)
-    throw new Error(`Template path "${templateSubpath}" not found in zip archive (root: ${rootFolder})`);
-  const root = resolve(destDir);
-  let files = 0;
-  for (const entry of templateEntries) {
-    const relativePath = entry.entryName.slice(templatePrefix.length);
-    if (!relativePath)
+function resolveInside(base, path) {
+  const full = resolve(base, path);
+  const inside = relative(base, full);
+  return inside && !inside.startsWith("..") && !isAbsolute(inside) ? full : void 0;
+}
+function assetsDir(plugin) {
+  return resolve(plugin.dir, plugin.manifest.assets?.dir ?? "assets");
+}
+function enabledPlugins(root, side) {
+  const plugins = [];
+  const warnings = [];
+  for (const [pkg, entry] of Object.entries(readConfig(root).plugins)) {
+    if (entry?.enabled === false)
+      continue;
+    let installed;
+    try {
+      installed = readPluginManifest(root, pkg);
+    } catch (err) {
+      warnings.push(err.message);
+      continue;
+    }
+    if (!installed) {
+      warnings.push(`${pkg} is listed in ${CONFIG_FILE} but is not installed or is not a MavonEngine plugin`);
+      continue;
+    }
+    if (!runsOn(installed.manifest.target, side))
+      continue;
+    const entryPath = resolveInside(installed.dir, installed.manifest[side]);
+    if (!entryPath || !existsSync(entryPath)) {
+      warnings.push(`${pkg}: ${side} entry ${installed.manifest[side]} not found, is the plugin built?`);
       continue;
-    const outputPath = resolve(root, relativePath);
-    const inside = relative(root, outputPath);
-    if (inside.startsWith("..") || isAbsolute(inside))
-      throw new Error(`Refusing to extract ${entry.entryName} outside the project`);
-    if (entry.isDirectory) {
-      mkdirSync(outputPath, { recursive: true });
-    } else {
-      mkdirSync(dirname(outputPath), { recursive: true });
-      writeFileSync(outputPath, entry.getData());
-      files++;
     }
+    plugins.push({
+      ...installed,
+      options: entry?.options ?? {},
+      prefabs: Array.isArray(entry?.prefabs) ? entry.prefabs : [],
+      entry: entryPath
+    });
   }
-  return files;
+  return { plugins, warnings };
+}
+function shippedAssetPaths(manifest, usedPrefabs) {
+  const assets = manifest.assets;
+  const paths = [...assets?.shared ?? []];
+  for (const prefab of usedPrefabs)
+    paths.push(...assets?.prefabs?.[prefab] ?? []);
+  return [...new Set(paths)];
+}
+function releaseAssets(root) {
+  const { plugins, warnings } = enabledPlugins(root, "client");
+  const assets = [];
+  for (const plugin of plugins) {
+    const base = assetsDir(plugin);
+    for (const path of shippedAssetPaths(plugin.manifest, plugin.prefabs)) {
+      const from = resolveInside(base, path);
+      if (!from) {
+        warnings.push(`${plugin.package}: asset ${path} points outside its assets directory`);
+        continue;
+      }
+      if (!existsSync(from)) {
+        warnings.push(`${plugin.package}: asset ${path} not found`);
+        continue;
+      }
+      assets.push({ package: plugin.package, from, to: `plugins/${plugin.package}/${path}`, path });
+    }
+  }
+  return { assets, warnings };
 }
-function runCommand(command, args, cwd, { report, signal }) {
-  return new Promise((resolvePromise, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      // npm is a .cmd shim on Windows
-      shell: process.platform === "win32",
-      signal
-    });
-    child.stdout.setEncoding("utf8").on("data", report.output);
-    child.stderr.setEncoding("utf8").on("data", report.output);
-    child.on("error", (err) => {
-      reject(err.code === "ENOENT" ? new Error(`'${command}' was not found on your PATH`) : err);
-    });
-    child.on("exit", (code, exitSignal) => {
-      if (code === 0)
-        resolvePromise();
-      else
-        reject(new Error(`'${command} ${args.join(" ")}' ${code === null ? `was stopped by ${exitSignal}` : `exited with code ${code}`}`));
-    });
-  });
+
+// src/commands/dashboard.ts
+import process2 from "process";
+import { parseArgs } from "util";
+
+// src/browser.ts
+import { spawn } from "child_process";
+import process from "process";
+var AMPERSAND_RE = /&/g;
+function openCommand(url, platform = process.platform) {
+  if (platform === "darwin")
+    return ["open", [url]];
+  if (platform === "win32")
+    return ["cmd", ["/c", "start", '""', url.replace(AMPERSAND_RE, "^&")]];
+  return ["xdg-open", [url]];
 }
-async function createProject({ projectName, parentDir, report, signal, templateUrl = TEMPLATE_URL, fetch, install = true }) {
-  const projectDir = projectDirFor(projectName, parentDir);
-  if (existsSync(projectDir))
-    throw new Error(`Directory "${projectDir}" already exists`);
-  report.output(`Creating project "${projectName}" in ${projectDir}
-`);
-  mkdirSync(projectDir, { recursive: true });
-  report.step("Downloading the template\u2026");
-  report.output(`Downloading the template from ${templateUrl}
-`);
-  const zipPath = await downloadZip(templateUrl, { report, signal, fetch });
+function openBrowser(url) {
+  const [command, args] = openCommand(url);
   try {
-    report.step("Extracting the template\u2026");
-    const files = extractTemplate(zipPath, TEMPLATE_SUBPATH, projectDir);
-    report.output(`Extracted ${files} files
-`);
-  } finally {
-    rmSync(zipPath, { force: true });
-  }
-  const pkgJsonPath = join(projectDir, "package.json");
-  if (existsSync(pkgJsonPath)) {
-    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
-    pkg.name = projectName;
-    writeFileSync(pkgJsonPath, `${JSON.stringify(pkg, null, 2)}
-`);
+    const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
   }
-  if (install) {
-    signal?.throwIfAborted();
-    report.step("Installing dependencies\u2026");
-    report.output("Running 'npm install'\n");
-    await runCommand("npm", ["install"], projectDir, { report, signal });
+}
+function canOpenBrowserHere(env = process.env) {
+  return !env.SSH_CONNECTION && !env.SSH_TTY;
+}
+async function servesPage(url, { timeoutMs = 3e3, fetch = globalThis.fetch } = {}) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    await res.body?.cancel();
+    return res.ok && (res.headers.get("content-type") ?? "").includes("text/html");
+  } catch {
+    return false;
   }
-  return projectDir;
 }
 
 // src/dashboard/snapshot.ts
@@ -483,44 +518,6 @@ var MetricsClient = class {
   }
 };
 
-// src/commands/dashboard.ts
-import process3 from "process";
-import { parseArgs } from "util";
-
-// src/browser.ts
-import { spawn as spawn2 } from "child_process";
-import process2 from "process";
-var AMPERSAND_RE = /&/g;
-function openCommand(url, platform = process2.platform) {
-  if (platform === "darwin")
-    return ["open", [url]];
-  if (platform === "win32")
-    return ["cmd", ["/c", "start", '""', url.replace(AMPERSAND_RE, "^&")]];
-  return ["xdg-open", [url]];
-}
-function openBrowser(url) {
-  const [command, args] = openCommand(url);
-  try {
-    const child = spawn2(command, args, { stdio: "ignore", detached: true, windowsHide: true });
-    child.on("error", () => {
-    });
-    child.unref();
-  } catch {
-  }
-}
-function canOpenBrowserHere(env = process2.env) {
-  return !env.SSH_CONNECTION && !env.SSH_TTY;
-}
-async function servesPage(url, { timeoutMs = 3e3, fetch = globalThis.fetch } = {}) {
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-    await res.body?.cancel();
-    return res.ok && (res.headers.get("content-type") ?? "").includes("text/html");
-  } catch {
-    return false;
-  }
-}
-
 // src/dashboard/simulator.ts
 var HISTORY_LENGTH = 60;
 function mulberry32(seed) {
@@ -715,6 +712,39 @@ function bootBanner({ version: version2, threeRevision, rapierVersion, mode }) {
 // src/dashboard/view.ts
 import { DEFAULT_COLOR, hex } from "@profullstack/hqtui";
 
+// src/dashboard/format.ts
+var BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB"];
+function formatBytes(bytes, decimals = 1) {
+  if (!Number.isFinite(bytes) || bytes <= 0)
+    return "0 B";
+  const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), BYTE_UNITS.length - 1);
+  const value = bytes / 1024 ** exponent;
+  return `${exponent === 0 ? value : value.toFixed(decimals)} ${BYTE_UNITS[exponent]}`;
+}
+function formatRate(bytesPerSecond) {
+  return `${formatBytes(bytesPerSecond)}/s`;
+}
+function formatDuration(totalSeconds) {
+  const seconds = Math.max(0, Math.floor(totalSeconds));
+  const d = Math.floor(seconds / 86400);
+  const h = Math.floor(seconds % 86400 / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = seconds % 60;
+  if (d > 0)
+    return `${d}d ${h}h ${m}m`;
+  if (h > 0)
+    return `${h}h ${m}m ${s}s`;
+  if (m > 0)
+    return `${m}m ${s}s`;
+  return `${s}s`;
+}
+function formatMs(ms) {
+  return `${ms.toFixed(ms < 10 ? 2 : 1)} ms`;
+}
+function formatPercent(value) {
+  return `${value.toFixed(1)}%`;
+}
+
 // src/dashboard/logo.ts
 var LOGO_SIZES = [
   [
@@ -1290,7 +1320,7 @@ Options:
 var STARTUP_POLL_MS = 250;
 var UsageError = class extends Error {
 };
-function parseDashboardArgs(args, env = process3.env) {
+function parseDashboardArgs(args, env = process2.env) {
   const { values } = parseArgs({
     args,
     options: {
@@ -1378,19 +1408,22 @@ async function runDashboard(options, signal) {
 }
 
 // src/commands/dev.ts
-import { execFileSync, spawn as spawn3 } from "child_process";
+import { execFileSync, spawn as spawn2 } from "child_process";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { constants } from "os";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
-import process4 from "process";
+import process3 from "process";
 import { setTimeout as delay } from "timers/promises";
 import { parseArgs as parseArgs2 } from "util";
 var DEV_HELP = `Usage: mavonengine dev [options]
 
-Run the dev script of the MavonEngine project you are in (game server and client)
+Run the dev servers of the MavonEngine project you are in (game server and client)
 and show the dashboard for it. Once the game server is up, the game opens in the
 browser. Quitting the dashboard stops the dev servers.
 
+Runs the project's 'dev:server' script, or its 'dev' script when there is none.
+So 'dev' can be 'mavonengine dev' itself, as in the multiplayer template.
+
 Options:
   --cwd <dir>        Start looking for the project here (default: current directory)
   --no-dashboard     Only run the dev script, with its output in the terminal
@@ -1411,6 +1444,9 @@ var LOCKFILES = [
   ["package-lock.json", "npm"]
 ];
 var WHITESPACE_RE = /\s+/;
+var RUNS_MAVONENGINE_DEV_RE = /\bmavonengine\s+dev\b/;
+var DEV_ENV_FLAG = "MAVONENGINE_DEV_SCRIPT";
+var DEV_SERVER_SCRIPT = "dev:server";
 var DEV_FLAGS = {
   cwd: { type: "string" },
   dashboard: { type: "boolean", default: true },
@@ -1420,7 +1456,7 @@ var DEV_FLAGS = {
   open: { type: "boolean", default: true },
   help: { type: "boolean", short: "h", default: false }
 };
-function parseDevArgs(args, cwd = process4.cwd(), env = process4.env) {
+function parseDevArgs(args, cwd = process3.cwd(), env = process3.env) {
   const { values } = parseArgs2({
     args,
     options: DEV_FLAGS,
@@ -1455,11 +1491,28 @@ function readPackageJson(dir) {
     return void 0;
   }
 }
+function devScriptOf(pkg) {
+  const scripts = pkg?.scripts ?? {};
+  if (typeof scripts[DEV_SERVER_SCRIPT] === "string")
+    return DEV_SERVER_SCRIPT;
+  return typeof scripts.dev === "string" ? "dev" : void 0;
+}
+function checkDevScript(root, env = process3.env) {
+  const pkg = readPackageJson(root);
+  const script = devScriptOf(pkg);
+  if (!script)
+    throw new UsageError(`${join2(root, "package.json")} has no '${DEV_SERVER_SCRIPT}' or 'dev' script`);
+  const command = String(pkg?.scripts?.[script] ?? "");
+  if (env[DEV_ENV_FLAG] || RUNS_MAVONENGINE_DEV_RE.test(command)) {
+    throw new UsageError(`the '${script}' script starts 'mavonengine dev' again. Put the command that starts the game server in a '${DEV_SERVER_SCRIPT}' script: 'mavonengine dev' runs that instead of 'dev'`);
+  }
+  return script;
+}
 function findProjectRoot(start) {
   for (let dir = resolve2(start); ; dir = dirname2(dir)) {
     const pkg = readPackageJson(dir);
     const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
-    if ("@mavonengine/core" in deps && typeof pkg?.scripts?.dev === "string")
+    if ("@mavonengine/core" in deps && devScriptOf(pkg))
       return dir;
     if (dirname2(dir) === dir)
       return void 0;
@@ -1490,7 +1543,7 @@ function descendants(root, psOutput) {
   return found;
 }
 function processTree(pid) {
-  if (process4.platform === "win32")
+  if (process3.platform === "win32")
     return [];
   try {
     return [pid, ...descendants(pid, execFileSync("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8" }))];
@@ -1501,14 +1554,14 @@ function processTree(pid) {
 function signalAll(pids, signal) {
   for (const p of pids) {
     try {
-      process4.kill(p, signal);
+      process3.kill(p, signal);
     } catch {
     }
   }
 }
 function isAlive(pid) {
   try {
-    process4.kill(pid, 0);
+    process3.kill(pid, 0);
     return true;
   } catch {
     return false;
@@ -1520,7 +1573,7 @@ async function waitForExit(pids, timeoutMs) {
     await delay(50);
 }
 function killTree(pid, signal) {
-  if (process4.platform === "win32") {
+  if (process3.platform === "win32") {
     try {
       execFileSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
     } catch {
@@ -1531,22 +1584,24 @@ function killTree(pid, signal) {
 }
 function startDev(root, { capture = false } = {}) {
   const pm = detectPackageManager(root);
-  const child = spawn3(pm, ["run", "dev"], {
+  const script = checkDevScript(root);
+  const child = spawn2(pm, ["run", script], {
     cwd: root,
+    env: { ...process3.env, [DEV_ENV_FLAG]: "1" },
     stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
     // npm, pnpm and yarn are .cmd shims on Windows
-    shell: process4.platform === "win32"
+    shell: process3.platform === "win32"
   });
   let output = "";
   const keep = (chunk) => {
     output = (output + chunk).slice(-MAX_CAPTURED_OUTPUT);
   };
-  const announce = `mavonengine: running '${pm} run dev' in ${root}
+  const announce = `mavonengine: running '${pm} run ${script}' in ${root}
 `;
   if (capture)
     keep(announce);
   else
-    process4.stdout.write(announce);
+    process3.stdout.write(announce);
   child.stdout?.setEncoding("utf8").on("data", keep);
   child.stderr?.setEncoding("utf8").on("data", keep);
   let running = true;
@@ -1554,17 +1609,17 @@ function startDev(root, { capture = false } = {}) {
   };
   const forward = (signal) => child.pid && killTree(child.pid, signal);
   const onExit = () => running && child.pid && killTree(child.pid, "SIGTERM");
-  process4.on("SIGINT", onInterrupt);
-  process4.on("SIGTERM", forward);
-  process4.on("SIGHUP", forward);
-  process4.on("exit", onExit);
+  process3.on("SIGINT", onInterrupt);
+  process3.on("SIGTERM", forward);
+  process3.on("SIGHUP", forward);
+  process3.on("exit", onExit);
   const exited = new Promise((resolvePromise, reject) => {
     const cleanup = () => {
       running = false;
-      process4.off("SIGINT", onInterrupt);
-      process4.off("SIGTERM", forward);
-      process4.off("SIGHUP", forward);
-      process4.off("exit", onExit);
+      process3.off("SIGINT", onInterrupt);
+      process3.off("SIGTERM", forward);
+      process3.off("SIGHUP", forward);
+      process3.off("exit", onExit);
     };
     child.on("error", (err) => {
       cleanup();
@@ -1577,7 +1632,7 @@ function startDev(root, { capture = false } = {}) {
   });
   const stop = async () => {
     if (running && child.pid) {
-      if (process4.platform === "win32") {
+      if (process3.platform === "win32") {
         killTree(child.pid, "SIGTERM");
       } else {
         const tree = processTree(child.pid);
@@ -1612,7 +1667,7 @@ async function runDevWithDashboard(root, dashboard) {
   if (quit)
     return 0;
   const exitCode = await dev.exited;
-  process4.stderr.write(`${dev.output()}
+  process3.stderr.write(`${dev.output()}
 mavonengine: the dev script exited with code ${exitCode}
 `);
   return exitCode;
@@ -1621,11 +1676,218 @@ async function runDevCommand(options) {
   const root = findProjectRoot(options.cwd);
   if (!root)
     throw new UsageError(`no MavonEngine project found in ${options.cwd} or its parents (looking for a package.json with @mavonengine/core and a dev script)`);
-  if (options.dashboard && process4.stdout.isTTY && process4.stdin.isTTY)
+  checkDevScript(root);
+  if (options.dashboard && process3.stdout.isTTY && process3.stdin.isTTY)
     return runDevWithDashboard(root, options.dashboard);
   return runDev(root);
 }
 
+// src/commands/build.ts
+var BUILD_HELP = `Usage: mavonengine build [options]
+
+Build the MavonEngine project you are in for release by running its build script.
+Plugin assets go into the client's output under plugins/<package>/: the shared
+ones, and those of the prefabs listed in ${CONFIG_FILE}. The others are left out.
+
+Options:
+  --cwd <dir>        Start looking for the project here (default: current directory)
+  -h, --help         Show this help
+`;
+function parseBuildArgs(args, cwd = process4.cwd()) {
+  const { values } = parseArgs3({
+    args,
+    options: {
+      cwd: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    strict: true,
+    allowPositionals: false
+  });
+  if (values.help)
+    return "help";
+  return { cwd: resolve3(cwd, values.cwd ?? ".") };
+}
+function summarizeReleaseAssets(root, assets, warnings) {
+  const plugins = readConfig(root).plugins;
+  const enabled = Object.entries(plugins).filter(([, entry]) => entry?.enabled !== false);
+  if (enabled.length === 0)
+    return "";
+  const lines = [`
+Plugins in ${CONFIG_FILE}:`];
+  for (const [pkg, entry] of enabled) {
+    const count = assets.filter((a) => a.package === pkg).length;
+    const prefabs = entry?.prefabs?.length ? `, prefabs: ${entry.prefabs.join(", ")}` : "";
+    lines.push(`  ${pkg}: ${count} asset${count === 1 ? "" : "s"}${prefabs}`);
+  }
+  for (const warning of warnings)
+    lines.push(`  warning: ${warning}`);
+  return `${lines.join("\n")}
+`;
+}
+function run(command, args, cwd) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn3(command, args, { cwd, stdio: "inherit", shell: process4.platform === "win32" });
+    child.on("error", (err) => {
+      reject(err.code === "ENOENT" ? new Error(`'${command}' was not found on your PATH`) : err);
+    });
+    child.on("exit", (code) => resolvePromise(code ?? 1));
+  });
+}
+async function runBuildCommand(options) {
+  const root = findProjectRoot(options.cwd);
+  if (!root)
+    throw new UsageError(`no MavonEngine project found in ${options.cwd} or its parents (looking for a package.json with @mavonengine/core and a dev script)`);
+  const pkg = JSON.parse(readFileSync3(join3(root, "package.json"), "utf8"));
+  if (typeof pkg.scripts?.build !== "string")
+    throw new UsageError(`${join3(root, "package.json")} has no build script`);
+  const pm = detectPackageManager(root);
+  process4.stdout.write(`mavonengine: running '${pm} run build' in ${root}
+`);
+  const code = await run(pm, ["run", "build"], root);
+  if (code !== 0) {
+    process4.stderr.write(`mavonengine: the build script exited with code ${code}
+`);
+    return code;
+  }
+  if (existsSync3(join3(root, CONFIG_FILE))) {
+    const { assets, warnings } = releaseAssets(root);
+    process4.stdout.write(summarizeReleaseAssets(root, assets, warnings));
+  }
+  return 0;
+}
+
+// src/commands/create.ts
+import { existsSync as existsSync5 } from "fs";
+import process6 from "process";
+import { createInterface } from "readline/promises";
+import { parseArgs as parseArgs4 } from "util";
+
+// src/create/project.ts
+import { spawn as spawn4 } from "child_process";
+import { createWriteStream, existsSync as existsSync4, mkdirSync, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve4 } from "path";
+import process5 from "process";
+import { Readable, Transform } from "stream";
+import { pipeline } from "stream/promises";
+import AdmZip from "adm-zip";
+var TEMPLATE_URL = "https://github.com/MavonEngine/Core/archive/refs/tags/0.0.16-alpha.zip";
+var TEMPLATE_SUBPATH = "packages/multiplayer-template";
+var PROJECT_NAME_RE = /^[\w@./-][\w@./\- ]*$/;
+function projectDirFor(projectName, parentDir) {
+  return resolve4(parentDir, projectName);
+}
+async function downloadZip(url, { report, signal, fetch = globalThis.fetch }) {
+  const response = await fetch(url, { signal });
+  if (!response.ok || !response.body)
+    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+  const total = Number(response.headers.get("content-length")) || 0;
+  let received = 0;
+  const progress = new Transform({
+    transform(chunk, _encoding, callback) {
+      received += chunk.length;
+      report.step(`Downloading the template\u2026 ${formatBytes(received)}${total ? ` of ${formatBytes(total)}` : ""}`);
+      callback(null, chunk);
+    }
+  });
+  const dest = join4(tmpdir(), `mavonengine-create-${process5.pid}-${Date.now()}.zip`);
+  try {
+    await pipeline(Readable.fromWeb(response.body), progress, createWriteStream(dest), { signal });
+  } catch (err) {
+    rmSync(dest, { force: true });
+    throw err;
+  }
+  return dest;
+}
+function extractTemplate(zipPath, templateSubpath, destDir) {
+  const entries = new AdmZip(zipPath).getEntries();
+  if (entries.length === 0)
+    throw new Error("Downloaded zip archive is empty");
+  const rootFolder = entries[0].entryName.split("/")[0];
+  const templatePrefix = `${rootFolder}/${templateSubpath}/`;
+  const templateEntries = entries.filter((e) => e.entryName.startsWith(templatePrefix));
+  if (templateEntries.length === 0)
+    throw new Error(`Template path "${templateSubpath}" not found in zip archive (root: ${rootFolder})`);
+  const root = resolve4(destDir);
+  let files = 0;
+  for (const entry of templateEntries) {
+    const relativePath = entry.entryName.slice(templatePrefix.length);
+    if (!relativePath)
+      continue;
+    const outputPath = resolve4(root, relativePath);
+    const inside = relative2(root, outputPath);
+    if (inside.startsWith("..") || isAbsolute2(inside))
+      throw new Error(`Refusing to extract ${entry.entryName} outside the project`);
+    if (entry.isDirectory) {
+      mkdirSync(outputPath, { recursive: true });
+    } else {
+      mkdirSync(dirname3(outputPath), { recursive: true });
+      writeFileSync2(outputPath, entry.getData());
+      files++;
+    }
+  }
+  return files;
+}
+function runCommand(command, args, cwd, { report, signal }) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn4(command, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      // npm is a .cmd shim on Windows
+      shell: process5.platform === "win32",
+      signal
+    });
+    child.stdout.setEncoding("utf8").on("data", report.output);
+    child.stderr.setEncoding("utf8").on("data", report.output);
+    child.on("error", (err) => {
+      reject(err.code === "ENOENT" ? new Error(`'${command}' was not found on your PATH`) : err);
+    });
+    child.on("exit", (code, exitSignal) => {
+      if (code === 0)
+        resolvePromise();
+      else
+        reject(new Error(`'${command} ${args.join(" ")}' ${code === null ? `was stopped by ${exitSignal}` : `exited with code ${code}`}`));
+    });
+  });
+}
+async function createProject({ projectName, parentDir, report, signal, templateUrl = TEMPLATE_URL, fetch, install = true }) {
+  const projectDir = projectDirFor(projectName, parentDir);
+  if (existsSync4(projectDir))
+    throw new Error(`Directory "${projectDir}" already exists`);
+  report.output(`Creating project "${projectName}" in ${projectDir}
+`);
+  mkdirSync(projectDir, { recursive: true });
+  report.step("Downloading the template\u2026");
+  report.output(`Downloading the template from ${templateUrl}
+`);
+  const zipPath = await downloadZip(templateUrl, { report, signal, fetch });
+  try {
+    report.step("Extracting the template\u2026");
+    const files = extractTemplate(zipPath, TEMPLATE_SUBPATH, projectDir);
+    report.output(`Extracted ${files} files
+`);
+  } finally {
+    rmSync(zipPath, { force: true });
+  }
+  const pkgJsonPath = join4(projectDir, "package.json");
+  if (existsSync4(pkgJsonPath)) {
+    const pkg = JSON.parse(readFileSync4(pkgJsonPath, "utf-8"));
+    pkg.name = projectName;
+    writeFileSync2(pkgJsonPath, `${JSON.stringify(pkg, null, 2)}
+`);
+  }
+  if (writeMcpConfig(projectDir))
+    report.output(`Wrote ${MCP_CONFIG_FILE} so AI assistants with MCP support can inspect the running game server
+`);
+  if (install) {
+    signal?.throwIfAborted();
+    report.step("Installing dependencies\u2026");
+    report.output("Running 'npm install'\n");
+    await runCommand("npm", ["install"], projectDir, { report, signal });
+  }
+  return projectDir;
+}
+
 // src/commands/create.ts
 var CREATE_HELP = `Usage: mavonengine create [name] [options]
 
@@ -1642,8 +1904,8 @@ Options:
   -h, --help         Show this help
 `;
 var MAX_SETUP_OUTPUT = 64 * 1024;
-function parseCreateArgs(args, cwd = process5.cwd(), env = process5.env) {
-  const { values, positionals } = parseArgs3({
+function parseCreateArgs(args, cwd = process6.cwd(), env = process6.env) {
+  const { values, positionals } = parseArgs4({
     args,
     options: DEV_FLAGS,
     strict: true,
@@ -1664,7 +1926,7 @@ function checkProjectName(name) {
     throw new UsageError(`invalid project name '${name}'`);
 }
 async function promptProjectName() {
-  const rl = createInterface({ input: process5.stdin, output: process5.stdout });
+  const rl = createInterface({ input: process6.stdin, output: process6.stdout });
   try {
     return (await rl.question("Project name: ")).trim();
   } finally {
@@ -1718,18 +1980,18 @@ async function runCreateWithDashboard(projectName, parentDir, dashboard) {
       return 0;
     await work.catch(() => {
     });
-    process5.stderr.write(`mavonengine: stopped creating the project, what was set up so far is in ${projectDirFor(projectName, parentDir)}
+    process6.stderr.write(`mavonengine: stopped creating the project, what was set up so far is in ${projectDirFor(projectName, parentDir)}
 `);
     return 130;
   }
   try {
     const exitCode = await work;
-    process5.stderr.write(`${dev.output()}
+    process6.stderr.write(`${dev.output()}
 mavonengine: the dev script exited with code ${exitCode}
 `);
     return exitCode;
   } catch (err) {
-    process5.stderr.write(output);
+    process6.stderr.write(output);
     throw err;
   }
 }
@@ -1737,16 +1999,16 @@ async function runCreatePlain(projectName, parentDir) {
   const report = {
     step: () => {
     },
-    output: (chunk) => process5.stdout.write(chunk)
+    output: (chunk) => process6.stdout.write(chunk)
   };
   const dir = await createProject({ projectName, parentDir, report });
-  process5.stdout.write(`
+  process6.stdout.write(`
 mavonengine: your project is ready at ${dir}
 `);
   return runDev(dir);
 }
 async function runCreateCommand(options) {
-  const interactive = !!process5.stdout.isTTY && !!process5.stdin.isTTY;
+  const interactive = !!process6.stdout.isTTY && !!process6.stdin.isTTY;
   let projectName = options.projectName;
   if (!projectName) {
     if (!interactive)
@@ -1757,13 +2019,395 @@ async function runCreateCommand(options) {
     checkProjectName(projectName);
   }
   const dir = projectDirFor(projectName, options.cwd);
-  if (existsSync3(dir))
+  if (existsSync5(dir))
     throw new UsageError(`${dir} already exists`);
   if (options.dashboard && interactive)
     return runCreateWithDashboard(projectName, options.cwd, options.dashboard);
   return runCreatePlain(projectName, options.cwd);
 }
 
+// src/commands/install.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
+import { join as join5, resolve as resolve5 } from "path";
+import process7 from "process";
+import { createInterface as createInterface2 } from "readline/promises";
+import { parseArgs as parseArgs5 } from "util";
+var INSTALL_HELP = `Usage: mavonengine install <package...> [options]
+
+Install packages into the MavonEngine project you are in. For each one that is a
+MavonEngine plugin, asks whether to add it to the plugins in ${CONFIG_FILE}, so it
+loads on the client and/or the game server and is built into the release.
+
+Takes anything your package manager does: names, name@version, file: paths, git URLs.
+
+Options:
+  --cwd <dir>        Start looking for the project here (default: current directory)
+  -y, --yes          Add plugins to ${CONFIG_FILE} without asking
+  --no-register      Only install, leave ${CONFIG_FILE} alone
+  -h, --help         Show this help
+`;
+var PACKAGE_SPEC_RE = /^((?:@[\w.-]+\/)?[\w.-]+)(?:@.*)?$/;
+var LOCAL_PATH_RE = /^(?:\.{1,2}(?:[/\\]|$)|[/~]|[a-z]:[/\\])/i;
+var TARGET_LABELS = {
+  client: "client only",
+  server: "server only",
+  both: "client + server"
+};
+function parseInstallArgs(args, cwd = process7.cwd()) {
+  const { values, positionals } = parseArgs5({
+    args,
+    options: {
+      cwd: { type: "string" },
+      yes: { type: "boolean", short: "y", default: false },
+      register: { type: "boolean", default: true },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    strict: true,
+    allowPositionals: true,
+    allowNegative: true
+  });
+  if (values.help)
+    return "help";
+  if (positionals.length === 0)
+    throw new UsageError(`which package? e.g. mavonengine install my-plugin
+
+${INSTALL_HELP}`);
+  return { cwd: resolve5(cwd, values.cwd ?? "."), packages: positionals, yes: values.yes, register: values.register };
+}
+function packageNameFromSpec(spec, root) {
+  const localPath = spec.startsWith("file:") ? spec.slice("file:".length) : LOCAL_PATH_RE.test(spec) ? spec : void 0;
+  if (localPath !== void 0) {
+    const packageJson = join5(resolve5(root, localPath), "package.json");
+    try {
+      return existsSync6(packageJson) ? JSON.parse(readFileSync5(packageJson, "utf8")).name : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  if (spec.includes(":") || spec.endsWith(".tgz"))
+    return void 0;
+  return PACKAGE_SPEC_RE.exec(spec)?.[1];
+}
+function installArgs(pm, packages) {
+  return [pm === "npm" ? "install" : "add", ...packages];
+}
+function dependencyNames(root) {
+  const path = join5(root, "package.json");
+  if (!existsSync6(path))
+    return /* @__PURE__ */ new Map();
+  const pkg = JSON.parse(readFileSync5(path, "utf8"));
+  return new Map(Object.entries({ ...pkg.devDependencies, ...pkg.dependencies }));
+}
+function installedNames(specs, root, before, after) {
+  const names = specs.map((spec) => packageNameFromSpec(spec, root)).filter((name) => !!name);
+  for (const [name, version2] of after) {
+    if (before.get(name) !== version2)
+      names.push(name);
+  }
+  return [...new Set(names)];
+}
+function describePlugin(plugin, engineVersion) {
+  const { manifest } = plugin;
+  const lines = [`${plugin.package}${plugin.version ? `@${plugin.version}` : ""} is a MavonEngine plugin (${TARGET_LABELS[manifest.target]})`];
+  const prefabs = Object.keys(manifest.assets?.prefabs ?? {});
+  if (prefabs.length)
+    lines.push(`  Prefabs: ${prefabs.join(", ")}. Their assets ship in the release once you place them in the editor`);
+  if (manifest.engine)
+    lines.push(`  Made for @mavonengine/core ${manifest.engine}${engineVersion ? `, you have ${engineVersion}` : ""}`);
+  return `${lines.join("\n")}
+`;
+}
+function confirmOnTerminal(question) {
+  const rl = createInterface2({ input: process7.stdin, output: process7.stdout });
+  return rl.question(question).then((answer) => ["", "y", "yes"].includes(answer.trim().toLowerCase())).finally(() => rl.close());
+}
+var terminalIO = {
+  run: (command, args, cwd) => runCommand(command, args, cwd, {
+    report: { step: () => {
+    }, output: (chunk) => process7.stdout.write(chunk) }
+  }),
+  confirm: confirmOnTerminal,
+  get interactive() {
+    return !!process7.stdin.isTTY && !!process7.stdout.isTTY;
+  },
+  write: (text) => process7.stdout.write(text)
+};
+async function runInstallCommand(options, io = terminalIO) {
+  const root = findProjectRoot(options.cwd);
+  if (!root)
+    throw new UsageError(`no MavonEngine project found in ${options.cwd} or its parents (looking for a package.json with @mavonengine/core and a dev script)`);
+  const config = readConfig(root);
+  const pm = detectPackageManager(root);
+  const args = installArgs(pm, options.packages);
+  const before = dependencyNames(root);
+  io.write(`mavonengine: running '${pm} ${args.join(" ")}' in ${root}
+`);
+  await io.run(pm, args, root);
+  const engineVersion = installedEngineVersion(root);
+  let failed = false;
+  const names = installedNames(options.packages, root, before, dependencyNames(root));
+  if (names.length === 0)
+    io.write(`
+mavonengine: couldn't tell which packages were installed. If one is a plugin, run 'mavonengine install <its name>' to register it
+`);
+  for (const name of names) {
+    let plugin;
+    try {
+      plugin = readPluginManifest(root, name);
+    } catch (err) {
+      io.write(`
+mavonengine: ${err.message}
+`);
+      failed = true;
+      continue;
+    }
+    if (!plugin) {
+      io.write(`
+${name} is installed. It is not a MavonEngine plugin (no "mavonengine" field in its package.json), so ${CONFIG_FILE} is left alone
+`);
+      continue;
+    }
+    io.write(`
+${describePlugin(plugin, engineVersion)}`);
+    const entry = config.plugins[name];
+    if (entry && entry.enabled !== false) {
+      io.write(`  Already in ${CONFIG_FILE}
+`);
+      continue;
+    }
+    if (!options.register)
+      continue;
+    if (!options.yes && !io.interactive) {
+      io.write(`  Not added to ${CONFIG_FILE}: run with --yes, or add "${name}": { "enabled": true } to its "plugins"
+`);
+      continue;
+    }
+    if (!options.yes && !await io.confirm(`Add ${name} to the plugins in ${CONFIG_FILE}? (Y/n) `)) {
+      io.write(`  Not added. Add "${name}": { "enabled": true } to "plugins" in ${CONFIG_FILE} to use it later
+`);
+      continue;
+    }
+    addPluginToConfig(root, name);
+    io.write(`  Added to ${join5(root, CONFIG_FILE)}
+`);
+    if (plugin.manifest.target !== "client")
+      io.write(`  Restart the game server ('mavonengine dev') to load it there
+`);
+  }
+  return failed ? 1 : 0;
+}
+
+// src/commands/mcp.ts
+import process8 from "process";
+import { parseArgs as parseArgs6 } from "util";
+
+// src/mcp/GameServerClient.ts
+var GameServerError = class extends Error {
+};
+var DEV_UNAVAILABLE = "The dev endpoints are not available: the game server runs with NODE_ENV=production (they are never served there), or it uses a @mavonengine/core release without them";
+var GameServerClient = class {
+  url;
+  clientUrl;
+  base;
+  clientBase;
+  token;
+  timeoutMs;
+  fetchImpl;
+  constructor({ url, clientUrl, token, timeoutMs = 3e3, fetch = globalThis.fetch }) {
+    this.base = new URL(url.endsWith("/") ? url : `${url}/`);
+    this.url = this.base.href;
+    this.clientBase = clientUrl ? new URL(clientUrl.endsWith("/") ? clientUrl : `${clientUrl}/`) : this.base;
+    this.clientUrl = this.clientBase.href;
+    this.token = token;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetch;
+  }
+  health() {
+    return this.get("api/game/health");
+  }
+  metrics() {
+    return this.get("api/game/metrics");
+  }
+  logs(afterId = 0) {
+    return this.get("api/game/logs", { after: String(afterId) }, "The server does not keep logs (metrics.logBufferSize is 0)");
+  }
+  requests(afterId = 0) {
+    return this.get("api/game/requests", { after: String(afterId) }, "The server does not record requests (metrics.requestLogSize is 0)");
+  }
+  scene() {
+    return this.get("api/game/dev/scene", {}, DEV_UNAVAILABLE);
+  }
+  entities(query = {}) {
+    const params = {};
+    if (query.type)
+      params.type = query.type;
+    if (query.near)
+      params.near = `${query.near.x},${query.near.y},${query.near.z}`;
+    for (const key of ["radius", "limit", "offset"]) {
+      if (query[key] !== void 0)
+        params[key] = String(query[key]);
+    }
+    return this.get("api/game/dev/entities", params, DEV_UNAVAILABLE);
+  }
+  entity(id) {
+    return this.get(`api/game/dev/entities/${encodeURIComponent(id)}`, {}, DEV_UNAVAILABLE);
+  }
+  /** The game tabs open in a browser, through the dev bridge */
+  clients() {
+    return this.bridge("__mavonengine/clients", {});
+  }
+  /**
+   * Ask one tab. `clientId` defaults to the only open tab (or the only one not running the editor)
+   */
+  client(query, params = {}, clientId = "auto") {
+    const defined = Object.fromEntries(Object.entries(params).filter(([, v]) => v !== void 0).map(([k, v]) => [k, String(v)]));
+    const timeoutMs = query === "trace" ? Number(params.durationMs ?? 3e3) + 15e3 : query === "screenshot" ? 15e3 : query === "status" ? 1e4 : 8e3;
+    return this.bridge(`__mavonengine/clients/${encodeURIComponent(clientId)}/${query}`, defined, timeoutMs);
+  }
+  async bridge(path, params, timeoutMs = 5e3) {
+    const target = new URL(path, this.clientBase);
+    for (const [key, value] of Object.entries(params))
+      target.searchParams.set(key, value);
+    let res;
+    try {
+      res = await this.fetchImpl(target, {
+        headers: this.token ? { Authorization: `Bearer ${this.token}` } : {},
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (err) {
+      throw new GameServerError(`Can't reach the client dev server at ${this.clientUrl}: ${err.message}. Is it running?`);
+    }
+    const isJson = res.headers.get("content-type")?.includes("application/json");
+    const body = isJson ? await res.json().catch(() => null) : null;
+    if (!isJson || res.status === 404 && !body?.error) {
+      throw new GameServerError(`No dev bridge at ${this.clientUrl}. The game client must be served by Vite in dev with the mavonengine Vite plugin (@mavonengine/core/vite.config). If Vite runs on its own port, pass --client-url, e.g. http://localhost:5173`);
+    }
+    if (res.status === 401 || res.status === 403)
+      throw new GameServerError(`${body?.error ?? "Not allowed"}: pass --token or set MAVONENGINE_METRICS_TOKEN for both the CLI and the dev server`);
+    if (!res.ok)
+      throw new GameServerError(body?.error ?? `Client dev server responded ${res.status} ${res.statusText}`);
+    return body;
+  }
+  async get(path, params = {}, notFound) {
+    const target = new URL(path, this.base);
+    for (const [key, value] of Object.entries(params))
+      target.searchParams.set(key, value);
+    let res;
+    try {
+      res = await this.fetchImpl(target, {
+        headers: this.token ? { Authorization: `Bearer ${this.token}` } : {},
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw new GameServerError(`Can't reach the game server at ${this.url}: ${err.message}. Is it running?`);
+    }
+    if (res.status === 401)
+      throw new GameServerError("Metrics token missing or wrong: pass --token or set MAVONENGINE_METRICS_TOKEN");
+    if (res.status === 403)
+      throw new GameServerError("The game server only answers localhost without a token: pass --token or set MAVONENGINE_METRICS_TOKEN");
+    if (res.status === 404)
+      throw new GameServerError(notFound ?? "Metrics endpoints not found: they are turned off in the server options, or it runs in production without a metrics token");
+    if (res.status === 400)
+      throw new GameServerError(`Bad request: ${(await res.json().catch(() => null))?.error ?? res.statusText}`);
+    if (!res.ok)
+      throw new GameServerError(`Game server responded ${res.status} ${res.statusText}`);
+    return res.json();
+  }
+};
+
+// src/commands/mcp.ts
+var MCP_HELP = `Usage: mavonengine mcp [options]
+
+Model Context Protocol (MCP) server over stdio, for any MCP client and model
+(Claude Code, Cursor, VS Code, Codex, Gemini CLI, Zed, local models, \u2026).
+It lets the assistant read a running game: the game server (status, metrics,
+players, scene, entities, logs, HTTP requests) and the game tabs open in a
+browser (renderer stats, entities, network, console, screenshots), and compare
+an entity on both sides. Every tool is read-only. Server scene and entity tools
+need the game server in development (NODE_ENV is not "production"); client
+tools need the client served by Vite in dev.
+
+Register it in your client as a stdio server with this command:
+  npx -y @mavonengine/cli mcp [options]
+
+Most clients take JSON like this (projects from 'mavonengine create' get it in .mcp.json):
+  { "mcpServers": { "mavonengine": { "command": "npx", "args": ["-y", "@mavonengine/cli", "mcp"] } } }
+
+Options:
+  --host <host>        Server host (default: localhost)
+  --port <port>        Server HTTP port (default: 8050)
+  --url <url>          Server base URL, e.g. http://localhost:8050, overrides --host and --port
+  --client-url <url>   Where Vite serves the client in dev (default: the server URL,
+                       which serves it in the template), e.g. http://localhost:5173
+  --token <token>      Metrics token (or set MAVONENGINE_METRICS_TOKEN)
+  --docs-url <url>     MCP server of the documentation for the docs_* tools
+                       (default: https://mavonengine.com/mcp)
+  --no-docs            Leave out the docs_* tools, e.g. offline
+  -h, --help           Show this help
+`;
+function parseMcpArgs(args, env = process8.env) {
+  const { values } = parseArgs6({
+    args,
+    options: {
+      "host": { type: "string", default: "localhost" },
+      "port": { type: "string", default: "8050" },
+      "url": { type: "string" },
+      "client-url": { type: "string" },
+      "token": { type: "string" },
+      "docs-url": { type: "string" },
+      "docs": { type: "boolean", default: true },
+      "help": { type: "boolean", short: "h", default: false }
+    },
+    strict: true,
+    allowPositionals: false,
+    allowNegative: true
+  });
+  if (values.help)
+    return "help";
+  let url = values.url;
+  if (!url) {
+    const port = Number(values.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+      throw new UsageError("--port must be between 1 and 65535");
+    const host = values.host.includes(":") && !values.host.startsWith("[") ? `[${values.host}]` : values.host;
+    url = `http://${host}:${port}`;
+  }
+  for (const [flag, value] of [["--url", url], ["--client-url", values["client-url"]], ["--docs-url", values["docs-url"]]]) {
+    try {
+      if (value !== void 0)
+        void new URL(value);
+    } catch {
+      throw new UsageError(`Invalid ${flag}: ${value}`);
+    }
+  }
+  return {
+    client: new GameServerClient({ url, clientUrl: values["client-url"], token: values.token ?? env.MAVONENGINE_METRICS_TOKEN }),
+    docsUrl: values.docs ? values["docs-url"] ?? DEFAULT_DOCS_URL : false
+  };
+}
+async function runMcpCommand({ client, docsUrl }) {
+  const [{ StdioServerTransport }, { createMcpServer }, { DocsClient }] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/stdio.js"),
+    import("./server-35RY6IGC.js"),
+    import("./docs-4C7X6FUQ.js")
+  ]);
+  const docs = docsUrl ? new DocsClient(docsUrl) : void 0;
+  const server = createMcpServer(client, docs);
+  const transport = new StdioServerTransport();
+  const closed = new Promise((resolve6) => {
+    transport.onclose = resolve6;
+    process8.stdin.on("end", resolve6);
+  });
+  await server.connect(transport);
+  process8.stderr.write(`mavonengine mcp: reading the game server at ${client.url}
+`);
+  await closed;
+  await server.close().catch(() => {
+  });
+  await docs?.close();
+  return 0;
+}
+
 // src/index.ts
 var HELP = `Usage: mavonengine <command> [options]
 
@@ -1771,6 +2415,9 @@ Commands:
   create       Create a project from the multiplayer template and start it
   dashboard    Live terminal dashboard for a running game server
   dev          Run the project's dev servers (game server and client)
+  install      Install packages and register engine plugins in mavonengine.json
+  build        Build the project for release, with the plugin assets it uses
+  mcp          MCP server so AI assistants (any MCP client) can inspect a running game server
 
 Options:
   -h, --help       Show help
@@ -1781,18 +2428,18 @@ Run 'mavonengine <command> --help' for command options.
 async function main(argv) {
   const [command, ...args] = argv;
   if (!command || command === "-h" || command === "--help" || command === "help") {
-    process6.stdout.write(HELP);
+    process9.stdout.write(HELP);
     return 0;
   }
   if (command === "-v" || command === "--version") {
-    process6.stdout.write(`${version}
+    process9.stdout.write(`${version}
 `);
     return 0;
   }
   if (command === "create") {
     const options = parseCreateArgs(args);
     if (options === "help") {
-      process6.stdout.write(CREATE_HELP);
+      process9.stdout.write(CREATE_HELP);
       return 0;
     }
     return runCreateCommand(options);
@@ -1800,11 +2447,11 @@ async function main(argv) {
   if (command === "dashboard") {
     const options = parseDashboardArgs(args);
     if (options === "help") {
-      process6.stdout.write(DASHBOARD_HELP);
+      process9.stdout.write(DASHBOARD_HELP);
       return 0;
     }
-    if (!process6.stdout.isTTY || !process6.stdin.isTTY) {
-      process6.stderr.write("mavonengine dashboard needs an interactive terminal\n");
+    if (!process9.stdout.isTTY || !process9.stdin.isTTY) {
+      process9.stderr.write("mavonengine dashboard needs an interactive terminal\n");
       return 1;
     }
     await runDashboard(options);
@@ -1813,18 +2460,42 @@ async function main(argv) {
   if (command === "dev") {
     const options = parseDevArgs(args);
     if (options === "help") {
-      process6.stdout.write(DEV_HELP);
+      process9.stdout.write(DEV_HELP);
       return 0;
     }
     return runDevCommand(options);
   }
+  if (command === "install" || command === "i" || command === "add") {
+    const options = parseInstallArgs(args);
+    if (options === "help") {
+      process9.stdout.write(INSTALL_HELP);
+      return 0;
+    }
+    return runInstallCommand(options);
+  }
+  if (command === "mcp") {
+    const options = parseMcpArgs(args);
+    if (options === "help") {
+      process9.stdout.write(MCP_HELP);
+      return 0;
+    }
+    return runMcpCommand(options);
+  }
+  if (command === "build") {
+    const options = parseBuildArgs(args);
+    if (options === "help") {
+      process9.stdout.write(BUILD_HELP);
+      return 0;
+    }
+    return runBuildCommand(options);
+  }
   throw new UsageError(`Unknown command '${command}'
 
 ${HELP}`);
 }
-main(process6.argv.slice(2)).then((code) => process6.exit(code)).catch((err) => {
+main(process9.argv.slice(2)).then((code) => process9.exit(code)).catch((err) => {
   const isUsage = err instanceof UsageError || err.code?.startsWith("ERR_PARSE_ARGS");
-  process6.stderr.write(`mavonengine: ${err.message}
+  process9.stderr.write(`mavonengine: ${err.message}
 `);
-  process6.exit(isUsage ? 2 : 1);
+  process9.exit(isUsage ? 2 : 1);
 });