@mavonengine/cli 0.0.1 → 0.0.2

package/README.md

@@ -6,7 +6,7 @@ Requires Node 24 or newer.
 
 ```sh
 npm install -D @mavonengine/cli
-npx mavonengine --help
+npx @mavonengine/cli --help
 ```
 
 ## `mavonengine create`
@@ -30,15 +30,17 @@ Asks for a name if none is given. While the template downloads and `npm install`
 
 ## `mavonengine dev`
 
-Runs the `dev` script of the MavonEngine project you are in and shows the [dashboard](#mavonengine-dashboard) for it. For the multiplayer template that starts the game server and the client together.
+Runs the dev script of the MavonEngine project you are in and shows the [dashboard](#mavonengine-dashboard) for it. For the multiplayer template that starts the game server and the client together.
+
+It runs the project's `dev:server` script, or `dev` when there is none. So `dev` can be `mavonengine dev` itself, as in the multiplayer template, and `npm run dev` brings up the dashboard. A `dev` script that would start `mavonengine dev` again, without a `dev:server` next to it, is refused instead of looping.
 
 While the game server starts, a startup screen shows the latest output of the dev script; the dashboard takes over as soon as the server answers. Once the server is up, the game it serves opens in your default browser (not over SSH, and only if the server answers `/` with a page); `--no-open` turns that off, and `o` opens it again any time. Quitting the dashboard (`q` or Ctrl-C) stops the dev script and everything it started. If the dev script exits on its own, the dashboard closes and its output is printed.
 
 ```sh
-npx mavonengine dev
+npx @mavonengine/cli dev
 
 # From somewhere else
-npx mavonengine dev --cwd path/to/my-game
+npx @mavonengine/cli dev --cwd path/to/my-game
 ```
 
 The project root is the nearest `package.json`, from the current directory upwards, that depends on `@mavonengine/core` and has a `dev` script, so it also works from inside `client/` or `server/`. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn` or `bun`, default `npm`). Without an interactive terminal, or with `--no-dashboard`, the dev script's output goes straight to the terminal instead. Ctrl-C stops everything, and the command exits with the dev script's exit code.
@@ -52,21 +54,66 @@ The project root is the nearest `package.json`, from the current directory upwar
 | `--transparent` | | Let a transparent terminal background show through |
 | `--no-open` | | Don't open the game in the browser once the server is up |
 
+## `mavonengine install`
+
+Installs packages into the project you are in, with its package manager. For each one that is a MavonEngine [plugin](#writing-a-plugin), it shows where the plugin runs (client, server or both) and which prefabs it brings, and asks whether to add it to the `plugins` in `mavonengine.json`. Registered plugins load on the client and/or the game server and are built into the release.
+
+```sh
+npx @mavonengine/cli install my-custom-plugin
+
+# Anything your package manager takes
+npx @mavonengine/cli install @acme/forest@^2 file:../my-plugin --yes
+```
+
+`mavonengine.json` sits in the project root, next to `package.json`, and is created if it doesn't exist:
+
+```json
+{
+  "plugins": {
+    "my-custom-plugin": { "enabled": true, "prefabs": ["Tree"], "options": { "density": 2 } }
+  }
+}
+```
+
+- `enabled`: set to `false` to turn a plugin off without uninstalling it.
+- `prefabs`: the plugin prefabs the project uses. The editor adds a prefab here when you place it, and you can edit the list by hand. Only the assets of these prefabs (plus the plugin's shared assets) go into the release.
+- `options`: passed to the plugin as `ctx.options`.
+
+The client reloads when the plugins in `mavonengine.json` change. Restart the game server to load a new server plugin. Without an interactive terminal it only installs, unless `--yes` is given.
+
+| Option | Default | |
+| --- | --- | --- |
+| `--cwd <dir>` | current directory | Where to start looking for the project |
+| `-y`, `--yes` | | Add plugins to `mavonengine.json` without asking |
+| `--no-register` | | Only install |
+
+## `mavonengine build`
+
+Runs the project's `build` script, then lists what each plugin put into the release. Plugin assets are copied into the client's output under `plugins/<package>/`. Only the shared ones and those of the prefabs in `mavonengine.json` are copied. The client skips loading the others, so a release never requests a file it doesn't contain.
+
+```sh
+npx @mavonengine/cli build
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `--cwd <dir>` | current directory | Where to start looking for the project |
+
 ## `mavonengine dashboard`
 
-A live terminal dashboard for a running game server, built with [hqtui](https://github.com/profullstack/hqtui).
+A live terminal dashboard for a running game server, built with [hqtui](https://github.com/profullstack/hqtui). For the same dashboard in a browser, behind a login, see the [`@mavonengine/http-monitoring`](https://github.com/MavonEngine/Core/tree/main/packages/plugins/http-monitoring) plugin.
 
 It shows CPU, network bandwidth, tick timings against the tick budget, world/physics/memory stats, the connected players, the server's recent log output and the HTTP requests it received. It reads them from the server's `GET /api/game/metrics`, `GET /api/game/logs` and `GET /api/game/requests` endpoints, which need a `@mavonengine/core` release that includes them.
 
 ```sh
 # Local server on the default HTTP port (8050)
-npx mavonengine dashboard
+npx @mavonengine/cli dashboard
 
 # Remote server with a metrics token
-MAVONENGINE_METRICS_TOKEN=secret npx mavonengine dashboard --host game.example.com --port 8050
+MAVONENGINE_METRICS_TOKEN=secret npx @mavonengine/cli dashboard --host game.example.com --port 8050
 
 # No server needed: simulated data
-npx mavonengine dashboard --sim
+npx @mavonengine/cli dashboard --sim
 ```
 
 | Option | Default | |
@@ -105,3 +152,152 @@ const server = new MyServer(logger, physicsWorld, {
 - With `NODE_ENV=production` and no token, the endpoint is turned off.
 - Set `metrics.enabled: false` to turn it off everywhere.
 - The logs endpoint follows the same rules. It serves whatever passes your logger's level.
+
+## `mavonengine mcp`
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, so an AI coding assistant can look at your running game: the game server, and the game tabs open in a browser. It works with any MCP client and any model: Claude Code, Cursor, VS Code, Codex, Gemini CLI, Zed, or a local model behind an MCP-capable client.
+
+Projects made with `mavonengine create` get a `.mcp.json` that registers it. Elsewhere, add it to your client as a stdio server; most clients take this JSON:
+
+```json
+{
+  "mcpServers": {
+    "mavonengine": { "command": "npx", "args": ["-y", "@mavonengine/cli", "mcp"] }
+  }
+}
+```
+
+Game server tools:
+
+| Tool | |
+| --- | --- |
+| `server_status` | Uptime, tick time against its budget, CPU, bandwidth, memory, player / entity / physics counts |
+| `server_metrics` | The full metrics snapshot, optionally with its per-second history |
+| `list_players` | Connected players with position and connection details |
+| `get_scene` | The active scene: file, hot reload, unsaved changes, settings and objects (dev only) |
+| `list_entities` | Entities in the world, filtered by type and distance to a point (dev only) |
+| `get_entity` | One entity with the state it sends to clients (dev only) |
+| `recent_logs` | Server log lines, filtered by level and text |
+| `recent_requests` | HTTP requests the server answered, filtered by path and status |
+
+Client tools, for the game tabs open while Vite serves the client in dev:
+
+| Tool | |
+| --- | --- |
+| `list_clients` | Open tabs: page, editor or player, the player's id on the server, visibility, FPS |
+| `client_status` | Draw calls and triangles of one frame, GPU geometries / textures / programs, JS heap, canvas, camera |
+| `client_entities` / `client_entity` | The tab's world, in the same shape as the server's, with its local player marked |
+| `client_scene` | The scene loaded in the tab, and which objects the client built |
+| `client_network` | Connection, ping, and inputs sent but not yet acknowledged by the server |
+| `client_logs` | Console output, uncaught errors and unhandled rejections, filtered by level and text |
+| `client_screenshot` | What the tab renders, as an image (the WebGL canvas, without HTML UI) |
+| `client_trace` | Records a few seconds of the tab and analyses it: frame times, render CPU vs GPU, composer passes, ticks, WebGL work per frame, the bottleneck, and the worst hitches with their causes. Saves a flame chart trace file |
+| `compare_entity` | One entity on the server next to a tab's copy: position / rotation / scale deltas and differing fields |
+
+Documentation tools, passed through to the MCP server of [mavonengine.com](https://mavonengine.com) (`https://mavonengine.com/mcp`), so answers come from the current docs:
+
+| Tool | |
+| --- | --- |
+| `docs_list_pages` | Every docs page with its path, title, description and category |
+| `docs_get_page` | One docs page as Markdown, by path (e.g. `/networking/state-sync`) |
+
+They connect to the site the first time one is used, so the other tools also work offline. `--docs-url` points them at another docs server, `--no-docs` leaves them out.
+
+Client tools take a `clientId` from `list_clients`. Without one they ask the only open tab, or the only one not running the editor.
+
+Every tool is read-only. It takes `--host`, `--port`, `--url` and `--token` like the dashboard, where `--url` is the server's base URL (`http://localhost:8050`). When Vite serves the client on its own port instead of through the game server, pass `--client-url`, e.g. `http://localhost:5173`.
+
+The server scene and entity tools read `GET /api/game/dev/*` on the game server. Those routes are only registered when `NODE_ENV` is not `production`: a metrics token does not turn them on there. Otherwise they follow the [server access](#server-access) rules of the metrics endpoint.
+
+The client tools go through the dev bridge of the Vite plugin in `@mavonengine/core/vite.config` (Vite 8). In dev it adds a small module to the page that answers over Vite's hot-reload WebSocket, and serves `GET /__mavonengine/clients` to localhost, or with `MAVONENGINE_METRICS_TOKEN` as bearer token when that is set for the dev server. Builds never include it. Turn it off with `mavonEnginePlugins({ devBridge: false })`.
+
+`client_trace` patches the tab only while it records and puts everything back afterwards. It times every frame and composer pass, counts the WebGL calls on the context, keeps slow single calls (shader compiles, texture uploads, `readPixels` / `getError` stalls), long animation frames with the scripts that ran, and your own `performance.measure()` spans. GPU time per frame needs `EXT_disjoint_timer_query_webgl2` (Chrome and Edge on most GPUs; the three-perf panel pauses while tracing since it uses the same queries). JS call stacks come from the [JS Self-Profiling API](https://wicg.github.io/js-self-profiling/) in Chromium browsers: the Vite plugin serves dev pages with `Document-Policy: js-profiling` for it, so reload tabs opened before you updated. The trace file is [Chrome Trace Event](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU) JSON with tracks for frames, passes, GPU time, ticks, JS samples and slow WebGL calls: open it in [Perfetto](https://ui.perfetto.dev), `chrome://tracing` or [speedscope](https://www.speedscope.app). Keep the tab in the foreground while it records, browsers throttle hidden tabs.
+
+To let `compare_entity` match your own player with the server's, set `game.localPlayer` to the entity the tab controls, or give it `isLocalPlayer = true`: the server keys players by socket id, which the client often doesn't.
+
+## Writing a plugin
+
+A plugin is an npm package with a `mavonengine` field in its `package.json`:
+
+```json
+{
+  "name": "my-custom-plugin",
+  "type": "module",
+  "mavonengine": {
+    "target": "both",
+    "client": "./dist/client.js",
+    "server": "./dist/server.js",
+    "engine": "^0.0.22",
+    "assets": {
+      "dir": "./assets",
+      "shared": ["textures/bark.png"],
+      "prefabs": {
+        "Tree": ["models/tree.glb"],
+        "Rock": ["models/rock.glb"]
+      }
+    }
+  }
+}
+```
+
+- `target`: `client`, `server` or `both`. The matching entries are required.
+- `assets`: paths relative to `dir` (default `assets`). They are served at `/plugins/<package>/<path>`: all of them in dev, and only the shared ones and those of used prefabs in a release.
+
+Each entry default-exports the plugin. Every hook gets the plugin's context last, which carries `package`, `options`, `game` and `logger`.
+
+```ts
+// client.ts
+import { defineClientPlugin } from '@mavonengine/core/Plugins/types'
+
+export default defineClientPlugin({
+  assets: ctx => [{ name: 'tree', type: 'gltfModel', path: ctx.assetUrl('models/tree.glb') }],
+  setup(ctx) {
+    ctx.registerPrefab({
+      name: 'Tree',
+      spawn: position => ({ object: new Tree(position) }),
+    })
+  },
+  update(delta, ctx) {},
+  // Dev only, when the editor boots
+  editor(ctx) {
+    ctx.editor.on('objectSelected', () => {})
+  },
+})
+```
+
+```ts
+// server.ts
+import { defineServerPlugin } from '@mavonengine/core/Plugins/types'
+
+export default defineServerPlugin({
+  setup(ctx) {},
+  // Runs after the server's own onHttp routes, before the game client
+  http(app, ctx) {
+    app.get('/api/my-plugin/status', (_req, res) => res.json({ ok: true }))
+  },
+  onConnection(channel, client, ctx) {},
+  onDisconnect(channel, ctx) {},
+  tick(delta, ctx) {},
+  destroy(ctx) {},
+})
+```
+
+A hook that throws is logged and turned off for that plugin, and the game keeps running.
+
+Projects made with `mavonengine create` are already set up for plugins. To set up an existing project:
+
+```ts
+// client: Game.usePlugins() before new Game()
+import Game from '@mavonengine/core/Game'
+import plugins from 'virtual:mavonengine/plugins'
+
+Game.usePlugins(plugins)
+```
+
+```ts
+// server: the directory with mavonengine.json
+const server = new MyServer(logger, physicsWorld, { plugins: { root: projectRoot } })
+await server.start()
+```
+
+The client's Vite config needs to extend `@mavonengine/core/vite.config`, which provides `virtual:mavonengine/plugins`, serves plugin assets in dev and copies them into the release.

package/dist/chunk-OSCNM66O.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_DOCS_URL,
+  version
+} from "./chunk-TNN4S5K4.js";
+
+// src/mcp/docs.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { z as z2 } from "zod";
+
+// src/mcp/result.ts
+import { z } from "zod";
+var READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var LOG_LEVELS = ["error", "warn", "info", "http", "verbose", "debug", "silly"];
+var vec3 = z.object({ x: z.number(), y: z.number(), z: z.number() });
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+async function run(body) {
+  try {
+    return json(await body());
+  } catch (err) {
+    return { isError: true, content: [{ type: "text", text: err.message }] };
+  }
+}
+
+// src/mcp/docs.ts
+var REQUEST_TIMEOUT_MS = 15e3;
+var DocsClient = class {
+  constructor(url = DEFAULT_DOCS_URL, connect = connectHttp) {
+    this.url = url;
+    this.connect = connect;
+  }
+  url;
+  connect;
+  client;
+  async call(tool, args = {}) {
+    this.client ??= this.connect(this.url);
+    try {
+      const client = await this.client;
+      return await client.callTool({ name: tool, arguments: args }, void 0, { timeout: REQUEST_TIMEOUT_MS });
+    } catch (err) {
+      const failed = this.client;
+      this.client = void 0;
+      void failed.then((client) => client.close()).catch(() => {
+      });
+      throw new Error(`Could not read the MavonEngine docs at ${this.url}: ${err.message}`);
+    }
+  }
+  async close() {
+    const client = this.client;
+    this.client = void 0;
+    await client?.then((c) => c.close()).catch(() => {
+    });
+  }
+};
+async function connectHttp(url) {
+  const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+  const client = new Client({ name: "mavonengine-cli", version });
+  await client.connect(new StreamableHTTPClientTransport(new URL(url)));
+  return client;
+}
+function registerDocsTools(server, docs) {
+  const forward = async (tool, args) => {
+    try {
+      return await docs.call(tool, args);
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: err.message }] };
+    }
+  };
+  server.registerTool("docs_list_pages", {
+    title: "List MavonEngine docs pages",
+    description: "Every page of the MavonEngine documentation (mavonengine.com) with its path, title, description and category. Use it to find the page about an engine concept or API, then read it with docs_get_page.",
+    annotations: { ...READ_ONLY, openWorldHint: true }
+  }, () => forward("list-pages"));
+  server.registerTool("docs_get_page", {
+    title: "Read a MavonEngine docs page",
+    description: "One page of the MavonEngine documentation as Markdown, by its path from docs_list_pages (e.g. /networking/state-sync).",
+    inputSchema: { path: z2.string().min(1).describe("Page path, e.g. /getting-started/installation") },
+    annotations: { ...READ_ONLY, openWorldHint: true }
+  }, ({ path }) => forward("get-page", { path }));
+}
+
+export {
+  READ_ONLY,
+  LOG_LEVELS,
+  vec3,
+  run,
+  DocsClient,
+  registerDocsTools
+};

package/dist/chunk-TNN4S5K4.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+// package.json
+var version = "0.0.2";
+
+// src/mcp/config.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+var DEFAULT_DOCS_URL = "https://mavonengine.com/mcp";
+var MCP_SERVER_NAME = "mavonengine";
+var MCP_CONFIG_FILE = ".mcp.json";
+function mcpServerEntry() {
+  return {
+    command: "npx",
+    args: ["-y", "@mavonengine/cli", "mcp"]
+  };
+}
+function writeMcpConfig(dir) {
+  const file = join(dir, MCP_CONFIG_FILE);
+  let config = {};
+  if (existsSync(file)) {
+    try {
+      config = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      return false;
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config))
+      return false;
+  }
+  const servers = config.mcpServers && typeof config.mcpServers === "object" ? config.mcpServers : {};
+  if (MCP_SERVER_NAME in servers)
+    return false;
+  config.mcpServers = { ...servers, [MCP_SERVER_NAME]: mcpServerEntry() };
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}
+`);
+  return true;
+}
+
+export {
+  version,
+  DEFAULT_DOCS_URL,
+  MCP_CONFIG_FILE,
+  writeMcpConfig
+};

package/dist/docs-4C7X6FUQ.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  DocsClient,
+  registerDocsTools
+} from "./chunk-OSCNM66O.js";
+import {
+  DEFAULT_DOCS_URL
+} from "./chunk-TNN4S5K4.js";
+export {
+  DEFAULT_DOCS_URL,
+  DocsClient,
+  registerDocsTools
+};