@mavonengine/cli 0.0.1 → 0.0.3

package/dist/server-NNL4IMYV.js

@@ -0,0 +1,925 @@
+#!/usr/bin/env node
+import {
+  fetchPluginReadme,
+  fetchPluginRegistry
+} from "./chunk-ZEMFSSJP.js";
+import {
+  LOG_LEVELS,
+  READ_ONLY,
+  registerDocsTools,
+  run,
+  vec3
+} from "./chunk-NIBSLCCZ.js";
+import {
+  version
+} from "./chunk-XPKCYSMN.js";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z as z4 } from "zod";
+
+// src/mcp/clientTools.ts
+import { mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+import { z } from "zod";
+
+// src/mcp/trace.ts
+var REFRESH_RATES = [30, 50, 60, 75, 90, 100, 120, 144, 165, 180, 240, 360];
+var GC_DROP_BYTES = 1024 * 1024;
+var MB = 1024 * 1024;
+var VITE_DEPS_RE = /^\/node_modules\/\.vite\/deps\//;
+var LEADING_SLASH_RE = /^\//;
+var round = (n, digits = 2) => Math.round(n * 10 ** digits) / 10 ** digits;
+function percentile(values, p) {
+  if (!values.length)
+    return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p / 100 * sorted.length) - 1))];
+}
+function stats(values) {
+  if (!values.length)
+    return null;
+  const sum2 = values.reduce((a, b) => a + b, 0);
+  return { avg: round(sum2 / values.length), p50: round(percentile(values, 50)), p95: round(percentile(values, 95)), p99: round(percentile(values, 99)), max: round(Math.max(...values)) };
+}
+function refreshRate(intervals) {
+  if (intervals.length < 5)
+    return null;
+  const hz = 1e3 / percentile(intervals, 20);
+  return REFRESH_RATES.reduce((best, rate) => Math.abs(rate - hz) < Math.abs(best - hz) ? rate : best);
+}
+function frameLabel(profile, frameId) {
+  const frame = profile.frames[frameId];
+  if (!frame)
+    return { name: "(unknown)", location: null };
+  const resource = frame.resourceId !== void 0 ? profile.resources[frame.resourceId] : void 0;
+  let file = null;
+  if (resource) {
+    try {
+      const url = new URL(resource);
+      file = url.pathname.replace(VITE_DEPS_RE, "deps/").replace(LEADING_SLASH_RE, "");
+    } catch {
+      file = resource;
+    }
+  }
+  return {
+    name: frame.name || "(anonymous)",
+    location: file ? `${file}${frame.line !== void 0 ? `:${frame.line}` : ""}${frame.column !== void 0 ? `:${frame.column}` : ""}` : null
+  };
+}
+function stackFrames(profile, stackId) {
+  const frames = [];
+  const seen = /* @__PURE__ */ new Set();
+  let id = stackId;
+  while (id !== void 0 && !seen.has(id)) {
+    seen.add(id);
+    const stack = profile.stacks[id];
+    if (!stack)
+      break;
+    frames.push(stack.frameId);
+    id = stack.parentId;
+  }
+  return frames.reverse();
+}
+function weightedSamples(profile) {
+  return profile.samples.map((sample, i) => {
+    const next = profile.samples[i + 1];
+    const weight = next ? Math.min(next.timestamp - sample.timestamp, profile.sampleIntervalMs * 4) : profile.sampleIntervalMs;
+    return { ...sample, weight: Math.max(0, weight) };
+  });
+}
+function hotFunctions(profile, limit = 15, from = -Infinity, to = Infinity) {
+  const byKey = /* @__PURE__ */ new Map();
+  let busyMs = 0;
+  let idleMs = 0;
+  for (const sample of weightedSamples(profile)) {
+    if (sample.timestamp < from || sample.timestamp > to)
+      continue;
+    const frames = stackFrames(profile, sample.stackId);
+    if (!frames.length) {
+      idleMs += sample.weight;
+      continue;
+    }
+    busyMs += sample.weight;
+    const keys = frames.map((frameId) => {
+      const label = frameLabel(profile, frameId);
+      const key = `${label.name}@${label.location}`;
+      if (!byKey.has(key))
+        byKey.set(key, { ...label, selfMs: 0, totalMs: 0, selfPercent: 0 });
+      return key;
+    });
+    for (const key of new Set(keys))
+      byKey.get(key).totalMs += sample.weight;
+    byKey.get(keys.at(-1)).selfMs += sample.weight;
+  }
+  const functions = [...byKey.values()].sort((a, b) => b.selfMs - a.selfMs).slice(0, limit).map((fn) => ({ ...fn, selfMs: round(fn.selfMs, 1), totalMs: round(fn.totalMs, 1), selfPercent: busyMs ? round(fn.selfMs / busyMs * 100, 1) : 0 }));
+  return { busyMs: round(busyMs, 1), idleMs: round(idleMs, 1), functions };
+}
+var sum = (values) => values.reduce((a, b) => a + b, 0);
+var mean = (values) => values.length ? sum(values) / values.length : 0;
+function overlaps(span, from, to) {
+  return span.start < to && span.start + span.duration > from;
+}
+function hitchCauses(capture, index, budgetMs) {
+  const frame = capture.frames[index];
+  const previous = capture.frames[index - 1];
+  const from = previous ? previous.start : frame.start - (frame.interval ?? 0);
+  const to = frame.start + frame.cpu;
+  const causes = [];
+  const gl = [previous?.gl, frame.gl].filter(Boolean);
+  const compileMs = sum(gl.map((g) => g.shaderCompileMs));
+  const compiles = sum(gl.map((g) => g.shaderCompiles));
+  if (compileMs >= 1)
+    causes.push(`Shader compilation: ${round(compileMs, 1)}ms${compiles ? ` linking ${compiles} program${compiles === 1 ? "" : "s"}` : ""} (a material or light setup rendered for the first time)`);
+  const uploadMs = sum(gl.map((g) => g.textureUploadMs));
+  if (uploadMs >= 1)
+    causes.push(`Texture uploads: ${round(uploadMs, 1)}ms for ${sum(gl.map((g) => g.textureUploads))} upload(s)`);
+  const bufferBytes = sum(gl.map((g) => g.bufferUploadBytes));
+  if (bufferBytes >= MB)
+    causes.push(`Buffer uploads: ${round(bufferBytes / MB, 1)}MB of geometry/attributes`);
+  const syncMs = sum(gl.map((g) => g.syncMs));
+  if (syncMs >= 1)
+    causes.push(`GPU sync stalls: ${round(syncMs, 1)}ms in readPixels/getError/finish/clientWaitSync`);
+  if (frame.cpu > budgetMs)
+    causes.push(`Render CPU time ${round(frame.cpu, 1)}ms (${frame.calls} draw calls)`);
+  if (frame.gpu !== null && frame.gpu > budgetMs)
+    causes.push(`GPU time ${round(frame.gpu, 1)}ms`);
+  for (const tick of capture.ticks) {
+    if (overlaps(tick, from, to) && tick.duration >= Math.max(4, budgetMs / 3)) {
+      const parts = [tick.physics !== null && `physics ${round(tick.physics, 1)}ms`, tick.world !== null && `world.update ${round(tick.world, 1)}ms`].filter(Boolean);
+      causes.push(`Game tick took ${round(tick.duration, 1)}ms${parts.length ? ` (${parts.join(", ")})` : ""}`);
+    }
+  }
+  if (previous?.heap != null && frame.heap != null && previous.heap - frame.heap >= GC_DROP_BYTES)
+    causes.push(`Garbage collection likely: JS heap dropped ${round((previous.heap - frame.heap) / MB, 1)}MB`);
+  const scripts = capture.spans.filter((s) => s.category === "script" && overlaps(s, from, to) && s.duration >= 2).sort((a, b) => b.duration - a.duration).slice(0, 3);
+  for (const script of scripts) {
+    const detail = script.detail ?? {};
+    causes.push(`Script ${script.name} ran ${round(script.duration, 1)}ms${detail.invoker ? ` (${String(detail.invoker)})` : ""}${detail.source ? ` at ${String(detail.source)}` : ""}${detail.forcedStyleAndLayout ? `, forced layout ${String(detail.forcedStyleAndLayout)}ms` : ""}`);
+  }
+  const measures = capture.spans.filter((s) => s.category === "measure" && overlaps(s, from, to) && s.duration >= 1);
+  for (const measure of measures.sort((a, b) => b.duration - a.duration).slice(0, 3))
+    causes.push(`performance.measure "${measure.name}" ${round(measure.duration, 1)}ms`);
+  if (capture.profile) {
+    const { functions } = hotFunctions(capture.profile, 3, from, to);
+    const hot = functions.filter((fn) => fn.selfMs >= capture.profile.sampleIntervalMs);
+    if (hot.length)
+      causes.push(`Hot JS in this frame: ${hot.map((fn) => `${fn.name} ${fn.selfMs}ms${fn.location ? ` (${fn.location})` : ""}`).join(", ")}`);
+  }
+  if (!causes.length)
+    causes.push("No cause recorded in the tab: the browser or OS held the frame back (another tab, compositor, GPU process, power saving), or work outside the game loop");
+  return causes;
+}
+function analyzeTrace(capture, { maxHitches = 10 } = {}) {
+  const frames = capture.frames;
+  const intervals = frames.map((f) => f.interval).filter((n) => n !== null);
+  const display = refreshRate(intervals);
+  const maxFps = capture.maxFps ?? 0;
+  const capped = maxFps > 0 && (display === null || maxFps < display * 1.05);
+  const hz = capped ? maxFps : display;
+  const budgetMs = hz ? 1e3 / hz : null;
+  const medianInterval = percentile(intervals, 50);
+  const gpuTimes = frames.map((f) => f.gpu).filter((n) => n !== null);
+  const cpuTimes = frames.map((f) => f.cpu);
+  const notes = [];
+  const findings = [];
+  if (!capture.visible)
+    notes.push("The tab was in the background: browsers throttle or stop rendering hidden tabs, so bring it to the front and trace again");
+  if (frames.length < 2)
+    notes.push("Fewer than two frames rendered while tracing: the tab is hidden, frozen or stuck before its first frame");
+  if (capped)
+    notes.push(`Rendering is capped at renderer.maxFps = ${maxFps}: frame times are measured against ${round(1e3 / maxFps, 1)}ms. Set it to 0 to see how fast the game can render`);
+  if (!capture.gpuTiming.enabled || capture.gpuTiming.note)
+    notes.push(`GPU timing: ${capture.gpuTiming.enabled ? "on" : "off"}${capture.gpuTiming.note ? `, ${capture.gpuTiming.note}` : ""}`);
+  if (!capture.jsProfile.enabled)
+    notes.push(`JS sampling: off, ${capture.jsProfile.note ?? "not available"}`);
+  const ticks = capture.ticks;
+  const tickStats = ticks.length ? {
+    ...stats(ticks.map((t) => t.duration)),
+    count: ticks.length,
+    physics: stats(ticks.map((t) => t.physics).filter((n) => n !== null)),
+    world: stats(ticks.map((t) => t.world).filter((n) => n !== null))
+  } : null;
+  const passes = capture.passes.map((name, i) => {
+    const times = frames.map((f) => f.passes[i]?.[1]).filter((n) => n !== void 0);
+    return { name, avgMs: round(mean(times)), maxMs: round(times.length ? Math.max(...times) : 0) };
+  });
+  const steady = frames.length > 1 ? frames.slice(1) : frames;
+  const avg = (pick) => round(mean(steady.map(pick)), 1);
+  const perFrame = {
+    drawCalls: avg((f) => f.calls),
+    triangles: Math.round(mean(steady.map((f) => f.triangles))),
+    glDraws: avg((f) => f.gl.draws),
+    instancedDraws: avg((f) => f.gl.instancedDraws),
+    programSwitches: avg((f) => f.gl.programSwitches),
+    textureBinds: avg((f) => f.gl.textureBinds),
+    framebufferBinds: avg((f) => f.gl.framebufferBinds),
+    vertexArrayBinds: avg((f) => f.gl.vertexArrayBinds),
+    uniformCalls: avg((f) => f.gl.uniformCalls),
+    bufferUploads: avg((f) => f.gl.bufferUploads),
+    bufferUploadKB: round(mean(steady.map((f) => f.gl.bufferUploadBytes)) / 1024, 1),
+    textureUploads: avg((f) => f.gl.textureUploads)
+  };
+  const totalOf = (pick) => sum(frames.map((f) => pick(f.gl)));
+  const totals = {
+    shaderCompiles: totalOf((g) => g.shaderCompiles),
+    shaderCompileMs: round(totalOf((g) => g.shaderCompileMs), 1),
+    textureUploads: totalOf((g) => g.textureUploads),
+    textureUploadMs: round(totalOf((g) => g.textureUploadMs), 1),
+    bufferUploadMB: round(totalOf((g) => g.bufferUploadBytes) / MB),
+    syncCalls: totalOf((g) => g.syncCalls),
+    syncMs: round(totalOf((g) => g.syncMs), 1)
+  };
+  const js = capture.profile ? hotFunctions(capture.profile, 15) : null;
+  const busyPercent = js && js.busyMs + js.idleMs > 0 ? round(js.busyMs / (js.busyMs + js.idleMs) * 100, 1) : null;
+  const cpuP50 = percentile(cpuTimes, 50);
+  const gpuP50 = gpuTimes.length ? percentile(gpuTimes, 50) : null;
+  const tickPerFrame = ticks.length && frames.length ? sum(ticks.map((t) => t.duration)) / frames.length : 0;
+  let bottleneck;
+  if (!budgetMs || frames.length < 5) {
+    bottleneck = { verdict: "unknown", reason: "Too few frames to tell" };
+  } else if (medianInterval <= budgetMs * 1.15 && (capped || hz >= 60 || Math.max(cpuP50 + tickPerFrame, gpuP50 ?? 0) < medianInterval * 0.6)) {
+    const used = Math.max(cpuP50 + tickPerFrame, gpuP50 ?? 0);
+    bottleneck = { verdict: "smooth", reason: `Frames keep up with ${capped ? `renderer.maxFps = ${maxFps}` : `the ${hz}Hz display`}: a typical frame uses ${round(used, 1)}ms of the ${round(budgetMs, 1)}ms budget (render CPU ${round(cpuP50, 1)}ms${gpuP50 !== null ? `, GPU ${round(gpuP50, 1)}ms` : ""}, game ticks ~${round(tickPerFrame, 1)}ms per frame)` };
+  } else if (gpuP50 !== null && gpuP50 >= medianInterval * 0.75 && gpuP50 > cpuP50 + tickPerFrame) {
+    bottleneck = { verdict: "gpu-bound", reason: `The GPU needs ${round(gpuP50, 1)}ms per frame against frames every ${round(medianInterval, 1)}ms, while render CPU time is ${round(cpuP50, 1)}ms` };
+  } else if (cpuP50 >= medianInterval * 0.6) {
+    bottleneck = { verdict: "cpu-render-bound", reason: `Renderer.update takes ${round(cpuP50, 1)}ms of each ${round(medianInterval, 1)}ms frame on the CPU, submitting ${perFrame.drawCalls} draw calls` };
+  } else if (tickPerFrame >= medianInterval * 0.4) {
+    bottleneck = { verdict: "cpu-game-logic-bound", reason: `Game ticks take ~${round(tickPerFrame, 1)}ms per rendered frame (tick p50 ${tickStats?.p50}ms at ${ticks.length} ticks)` };
+  } else if (busyPercent !== null && busyPercent >= 70) {
+    bottleneck = { verdict: "main-thread-busy", reason: `The main thread is busy ${busyPercent}% of the time outside what the render and tick account for: see js.hotFunctions` };
+  } else {
+    bottleneck = { verdict: "unknown", reason: `Frames take ${round(medianInterval, 1)}ms against a ${round(budgetMs, 1)}ms budget, but neither render CPU (${round(cpuP50, 1)}ms), GPU (${gpuP50 !== null ? `${round(gpuP50, 1)}ms` : "not measured"}) nor ticks explain it` };
+  }
+  const thresholdMs = round(Math.max(medianInterval * 1.5, medianInterval + 4));
+  const late = frames.map((frame, index) => ({ frame, index })).filter(({ frame }) => frame.interval !== null && frame.interval > thresholdMs);
+  const worst = [...late].sort((a, b) => b.frame.interval - a.frame.interval).slice(0, maxHitches).map(({ frame, index }) => ({
+    frame: index,
+    at: round(frame.start, 1),
+    intervalMs: round(frame.interval, 1),
+    cpuMs: round(frame.cpu, 1),
+    gpuMs: frame.gpu === null ? null : round(frame.gpu, 1),
+    causes: hitchCauses(capture, index, budgetMs ?? medianInterval)
+  }));
+  if (totals.shaderCompiles > 0)
+    findings.push(`${totals.shaderCompiles} shader program(s) were linked while playing (${totals.shaderCompileMs}ms on the main thread). Compile materials up front with renderer.compileAsync(scene, camera) after loading, and avoid changing defines / light counts at runtime`);
+  if (perFrame.drawCalls > 1e3)
+    findings.push(`${perFrame.drawCalls} draw calls per frame is a lot for WebGL: merge static meshes, use InstancedMesh / BatchedMesh for repeated objects, and share materials`);
+  else if (perFrame.drawCalls > 300 && bottleneck.verdict === "cpu-render-bound")
+    findings.push(`${perFrame.drawCalls} draw calls per frame drive the render CPU time: instancing or merging would cut it`);
+  if (perFrame.programSwitches > 100)
+    findings.push(`${perFrame.programSwitches} shader program switches per frame: fewer distinct materials, or the same material on more meshes, lets three.js sort and batch`);
+  if (perFrame.textureUploads >= 1)
+    findings.push(`${perFrame.textureUploads} texture upload(s) every frame: a texture (often a canvas, video or DataTexture) has needsUpdate set each frame`);
+  if (perFrame.bufferUploadKB >= 256)
+    findings.push(`${perFrame.bufferUploadKB}KB of buffer data uploaded per frame: geometry attributes are updated every frame (needsUpdate / updateRanges), consider updating only the ranges that change`);
+  if (totals.syncCalls > frames.length && totals.syncMs >= 1)
+    findings.push(`${totals.syncCalls} GPU sync calls (${totals.syncMs}ms): readPixels / getError stall the pipeline. renderer.debug.checkShaderErrors = true calls getError after compiles, and picking with readPixels each frame stalls too`);
+  if (bottleneck.verdict === "gpu-bound") {
+    findings.push(`GPU-bound at ${capture.canvas.width}x${capture.canvas.height} (pixel ratio ${capture.canvas.pixelRatio}): lower the pixel ratio (cap it at 1.5\u20132), shadow map size or shadow-casting lights, and look at the most expensive passes`);
+    const heavyPasses = passes.filter((p) => p.name !== "RenderPass" && p.name !== "OutputPass");
+    if (heavyPasses.length)
+      findings.push(`Post-processing passes cost GPU fill rate on every pixel: ${heavyPasses.map((p) => p.name).join(", ")}`);
+  }
+  if (tickStats && budgetMs && tickStats.p95 > budgetMs / 2)
+    findings.push(`Game ticks are slow (p95 ${tickStats.p95}ms${tickStats.physics ? `, physics p95 ${tickStats.physics.p95}ms` : ""}${tickStats.world ? `, world.update p95 ${tickStats.world.p95}ms` : ""}) and block rendering when they run`);
+  const gcHitches = worst.filter((h) => h.causes.some((c) => c.startsWith("Garbage collection"))).length;
+  if (gcHitches >= 2)
+    findings.push(`${gcHitches} hitches line up with garbage collection: reuse Vector3 / Matrix4 / arrays in update loops instead of allocating each frame`);
+  if (late.length && budgetMs)
+    findings.push(`${late.length} of ${frames.length} frames came late (over ${thresholdMs}ms), ${round(late.length / frames.length * 100, 1)}%`);
+  const measureMap = /* @__PURE__ */ new Map();
+  for (const span of capture.spans.filter((s) => s.category === "measure"))
+    measureMap.set(span.name, [...measureMap.get(span.name) ?? [], span.duration]);
+  const measures = Array.from(measureMap, ([name, durations]) => ({ name, count: durations.length, avgMs: round(mean(durations)), maxMs: round(Math.max(...durations)) })).sort((a, b) => b.avgMs * b.count - a.avgMs * a.count).slice(0, 20);
+  return {
+    durationMs: capture.durationMs,
+    frames: frames.length,
+    fps: round(frames.length / (capture.durationMs / 1e3), 1),
+    refreshRate: hz,
+    maxFps,
+    budgetMs: budgetMs && round(budgetMs),
+    frameInterval: stats(intervals),
+    renderCpu: stats(cpuTimes),
+    gpu: stats(gpuTimes),
+    tick: tickStats,
+    passes,
+    perFrame,
+    totals,
+    bottleneck,
+    hitches: { count: late.length, thresholdMs, worst },
+    js: js && { mainThreadBusyPercent: busyPercent ?? 0, hotFunctions: js.functions },
+    longAnimationFrames: capture.spans.filter((s) => s.category === "long-animation-frame" || s.category === "long-task").length,
+    measures,
+    findings,
+    notes
+  };
+}
+var PID = 1;
+var TRACKS = { frames: 1, passes: 2, gpu: 3, ticks: 4, js: 5, gl: 6, browser: 7 };
+var TRACK_NAMES = {
+  [TRACKS.frames]: "Frames (render CPU)",
+  [TRACKS.passes]: "Composer passes",
+  [TRACKS.gpu]: "GPU time per frame (duration, not GPU clock)",
+  [TRACKS.ticks]: "Game ticks",
+  [TRACKS.js]: "JS samples",
+  [TRACKS.gl]: "Slow WebGL calls",
+  [TRACKS.browser]: "Long animation frames, scripts, measures"
+};
+var us = (ms) => Math.round(ms * 1e3);
+function profileEvents(profile) {
+  const events = [];
+  const open = [];
+  const close = (depth, at) => {
+    while (open.length > depth) {
+      const { frameId, start } = open.pop();
+      const label = frameLabel(profile, frameId);
+      events.push({ name: label.name, cat: "js", ph: "X", ts: us(start), dur: Math.max(1, us(at - start)), pid: PID, tid: TRACKS.js, args: label.location ? { location: label.location } : void 0 });
+    }
+  };
+  const samples = weightedSamples(profile);
+  for (const sample of samples) {
+    const frames = stackFrames(profile, sample.stackId);
+    let common = 0;
+    while (common < open.length && common < frames.length && open[common].frameId === frames[common])
+      common++;
+    close(common, sample.timestamp);
+    for (let i = common; i < frames.length; i++)
+      open.push({ frameId: frames[i], start: sample.timestamp });
+  }
+  const last = samples.at(-1);
+  close(0, last ? last.timestamp + last.weight : 0);
+  return events;
+}
+function spanEvent(span) {
+  return {
+    name: span.name,
+    cat: span.category,
+    ph: "X",
+    ts: us(span.start),
+    dur: Math.max(1, us(span.duration)),
+    pid: PID,
+    tid: span.category === "gl" ? TRACKS.gl : TRACKS.browser,
+    args: span.detail
+  };
+}
+function toTraceEvents(capture, label = "MavonEngine game tab") {
+  const events = [
+    { name: "process_name", ph: "M", ts: 0, pid: PID, tid: 0, args: { name: label } },
+    ...Object.entries(TRACK_NAMES).flatMap(([tid, name]) => [
+      { name: "thread_name", ph: "M", ts: 0, pid: PID, tid: Number(tid), args: { name } },
+      { name: "thread_sort_index", ph: "M", ts: 0, pid: PID, tid: Number(tid), args: { sort_index: Number(tid) } }
+    ])
+  ];
+  capture.frames.forEach((frame, index) => {
+    events.push({
+      name: `Frame ${index}`,
+      cat: "frame",
+      ph: "X",
+      ts: us(frame.start),
+      dur: Math.max(1, us(frame.cpu)),
+      pid: PID,
+      tid: TRACKS.frames,
+      args: { intervalMs: frame.interval, cpuMs: frame.cpu, gpuMs: frame.gpu, drawCalls: frame.calls, triangles: frame.triangles, gl: frame.gl }
+    });
+    frame.passes.forEach((pass, i) => {
+      const [start, duration] = pass ?? [];
+      if (start !== void 0 && duration !== void 0)
+        events.push({ name: capture.passes[i] ?? `Pass ${i}`, cat: "pass", ph: "X", ts: us(start), dur: Math.max(1, us(duration)), pid: PID, tid: TRACKS.passes });
+    });
+    if (frame.gpu !== null)
+      events.push({ name: `GPU frame ${index}`, cat: "gpu", ph: "X", ts: us(frame.start), dur: Math.max(1, us(frame.gpu)), pid: PID, tid: TRACKS.gpu });
+    const counters = { drawCalls: frame.calls, glDraws: frame.gl.draws };
+    if (frame.interval)
+      counters.fps = round(1e3 / frame.interval, 1);
+    events.push({ name: "Frame", ph: "C", ts: us(frame.start), pid: PID, tid: 0, args: counters });
+    if (frame.heap !== null)
+      events.push({ name: "JS heap (MB)", ph: "C", ts: us(frame.start), pid: PID, tid: 0, args: { used: round(frame.heap / MB) } });
+  });
+  for (const tick of capture.ticks) {
+    events.push({ name: "tick", cat: "tick", ph: "X", ts: us(tick.start), dur: Math.max(1, us(tick.duration)), pid: PID, tid: TRACKS.ticks, args: { physicsMs: tick.physics, worldMs: tick.world } });
+  }
+  events.push(...capture.spans.map(spanEvent));
+  if (capture.profile)
+    events.push(...profileEvents(capture.profile));
+  return {
+    traceEvents: events,
+    displayTimeUnit: "ms",
+    metadata: {
+      source: "mavonengine mcp client_trace",
+      startedAt: new Date(capture.startedAt).toISOString(),
+      userAgent: capture.userAgent,
+      canvas: capture.canvas,
+      gpuTiming: capture.gpuTiming,
+      jsProfile: capture.jsProfile
+    }
+  };
+}
+
+// src/mcp/clientTools.ts
+var CLIENT_LOG_LEVELS = ["error", "warn", "info", "log", "debug"];
+var SEVERITY = { error: 0, warn: 1, info: 2, log: 2, debug: 3 };
+var clientId = z.string().optional().describe("Tab id from list_clients. Default: the only open tab, or the only one not running the editor");
+function delta(a, b) {
+  const d = { x: b.x - a.x, y: b.y - a.y, z: b.z - a.z };
+  return { ...d, length: Math.hypot(d.x, d.y, d.z) };
+}
+function compareEntities(id, server, client) {
+  if (!server || !client) {
+    return {
+      id,
+      server,
+      client,
+      note: !server && !client ? "Neither side has this entity" : !server ? "Only the client has it: it may be client-only, or the server removed it and the client did not get SV_REMOVE_ENTITY" : "Only the server has it: it may be out of this client's sync distance, not sent yet, or the client failed to create it"
+    };
+  }
+  const serverFields = server.serialized ?? {};
+  const clientFields = client.serialized ?? {};
+  const differentFields = [.../* @__PURE__ */ new Set([...Object.keys(serverFields), ...Object.keys(clientFields)])].filter((field) => !["id", "position", "rotation", "scale"].includes(field)).filter((field) => JSON.stringify(serverFields[field]) !== JSON.stringify(clientFields[field])).map((field) => ({ field, server: serverFields[field], client: clientFields[field] }));
+  const { serialized: _s, ...serverSummary } = server;
+  const { serialized: _c, ...clientSummary } = client;
+  return {
+    id,
+    clientId: client.id === id ? void 0 : client.id,
+    positionDelta: delta(server.position, client.position),
+    rotationDelta: delta(server.rotation, client.rotation),
+    scaleDelta: delta(server.scale, client.scale),
+    differentFields,
+    server: serverSummary,
+    client: clientSummary,
+    note: "Client state of remote entities is interpolated and the local player is predicted, so small deltas are expected while moving"
+  };
+}
+function defaultTracePath(clientId3, at = /* @__PURE__ */ new Date()) {
+  const stamp = at.toISOString().replace(/[:.]/g, "-");
+  return join(tmpdir(), "mavonengine-traces", `trace-${clientId3}-${stamp}.json`);
+}
+function registerClientTools(server, client) {
+  server.registerTool("list_clients", {
+    title: "Open game tabs",
+    description: "Browser tabs running the game client in dev, connected through the dev bridge: id, page, whether it runs the editor, its player id on the server (playerId), visibility, focus and FPS. The other client_* tools take one of these ids.",
+    annotations: READ_ONLY
+  }, () => run(async () => {
+    const { clients } = await client.clients();
+    return { devServer: client.clientUrl, clients, ...clients.length ? {} : { note: "No game tab is open. Open the game in a browser" } };
+  }));
+  server.registerTool("client_status", {
+    title: "Client status",
+    description: "One tab's rendering and state: FPS, draw calls / triangles / points / lines of one frame, GPU geometries / textures / shader programs, JS heap, canvas size, camera, entity count, active scene, resource loading.",
+    inputSchema: { clientId },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3 }) => run(() => client.client("status", {}, clientId3)));
+  server.registerTool("client_entities", {
+    title: "Entities on a client",
+    description: "Entities in a tab's world, in the same shape as list_entities on the server, plus `localPlayer` for the entity the tab controls. Filter by type and/or distance to a point (nearest first).",
+    inputSchema: {
+      clientId,
+      type: z.string().optional().describe("Entity class / networked type name, or scene object type, case-insensitive"),
+      near: vec3.optional(),
+      radius: z.number().nonnegative().optional(),
+      limit: z.number().int().min(1).max(500).default(50),
+      offset: z.number().int().min(0).default(0)
+    },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3, near, ...query }) => run(() => client.client("entities", { ...query, near: near && `${near.x},${near.y},${near.z}` }, clientId3)));
+  server.registerTool("client_entity", {
+    title: "One entity on a client",
+    description: "One entity in a tab's world with its serialized state. The server id of the tab's own player finds its local player.",
+    inputSchema: { id: z.string().min(1), clientId },
+    annotations: READ_ONLY
+  }, ({ id, clientId: clientId3 }) => run(async () => {
+    const { entity } = await client.client("entity", { id }, clientId3);
+    if (!entity)
+      throw new Error(`The client has no entity with id "${id}". client_entities shows its ids`);
+    return entity;
+  }));
+  server.registerTool("client_scene", {
+    title: "Scene on a client",
+    description: "The scene loaded in a tab, in the same shape as get_scene: objects with `built` telling whether the client built them.",
+    inputSchema: { clientId, includeObjects: z.boolean().default(true) },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3, includeObjects }) => run(async () => {
+    const { scene } = await client.client("scene", {}, clientId3);
+    if (!scene)
+      return { scene: null, note: "No scene is loaded in this tab. The client opens one with game.openScene(name)" };
+    if (includeObjects)
+      return scene;
+    const { objects, ...summary } = scene;
+    return { ...summary, objectCount: objects?.length ?? 0 };
+  }));
+  server.registerTool("client_network", {
+    title: "Client network state",
+    description: "A tab's connection to the game server: connected, player id, ping, editor mode, inputs sent but not yet acknowledged (pendingCommands, replayed for prediction) and the next input sequence id.",
+    inputSchema: { clientId },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3 }) => run(() => client.client("network", {}, clientId3)));
+  server.registerTool("client_logs", {
+    title: "Client console",
+    description: "A tab's console output, uncaught errors and unhandled promise rejections since it loaded (the last 500), oldest first. Pass the returned latestId as afterId later to get only newer lines.",
+    inputSchema: {
+      clientId,
+      level: z.enum(CLIENT_LOG_LEVELS).optional().describe("Only this level and more severe ones, e.g. warn includes error"),
+      contains: z.string().optional().describe("Only lines containing this text, case-insensitive"),
+      afterId: z.number().int().min(0).default(0),
+      limit: z.number().int().min(1).max(500).default(100).describe("Newest lines kept when more match")
+    },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3, level, contains, afterId, limit }) => run(async () => {
+    const { entries = [], latestId = 0 } = await client.client("logs", { after: afterId }, clientId3);
+    const maxSeverity = level ? SEVERITY[level] : Infinity;
+    const needle = contains?.toLowerCase();
+    const matches = entries.filter((entry) => (SEVERITY[entry.level] ?? 2) <= maxSeverity && (!needle || entry.message.toLowerCase().includes(needle)));
+    return {
+      latestId,
+      matched: matches.length,
+      entries: matches.slice(-limit).map(({ timestamp, ...entry }) => ({ ...entry, time: new Date(timestamp).toISOString() }))
+    };
+  }));
+  server.registerTool("client_screenshot", {
+    title: "Client screenshot",
+    description: "What a tab renders right now, as an image. Only the WebGL canvas: HTML UI drawn over it is not included.",
+    inputSchema: {
+      clientId,
+      maxWidth: z.number().int().min(64).max(4096).default(1024).describe("Scaled down to this width"),
+      format: z.enum(["jpeg", "png"]).default("jpeg")
+    },
+    annotations: READ_ONLY
+  }, async ({ clientId: clientId3, maxWidth, format }) => {
+    try {
+      const shot = await client.client("screenshot", { maxWidth, format }, clientId3);
+      return {
+        content: [
+          { type: "image", data: shot.data, mimeType: shot.mimeType },
+          { type: "text", text: `${shot.width}x${shot.height} ${shot.mimeType}` }
+        ]
+      };
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: err.message }] };
+    }
+  });
+  server.registerTool("client_trace", {
+    title: "Trace client rendering",
+    description: "Record a tab for a few seconds and analyse its performance: frame time distribution, render CPU vs GPU time per frame, time per composer pass, game tick time (physics, world.update), WebGL work per frame (draw calls, program / texture / framebuffer switches, uniform calls, uploads), the bottleneck, and the worst hitches with their likely causes (shader compiles, texture uploads, GPU syncs, GC, slow ticks, long scripts, hot JS functions). JS sampling uses the browser's JS Self-Profiling API (Chromium) and GPU time EXT_disjoint_timer_query_webgl2. Also saves a Chrome Trace Event file to open as a flame chart in https://ui.perfetto.dev or chrome://tracing. Keep the tab in the foreground while it records.",
+    inputSchema: {
+      clientId,
+      durationMs: z.number().int().min(500).max(15e3).default(3e3).describe("How long to record"),
+      jsProfile: z.boolean().default(true).describe("Sample JS call stacks"),
+      sampleIntervalMs: z.number().int().min(1).max(100).default(10).describe("JS sampling interval, the browser may round it up"),
+      gpu: z.boolean().default(true).describe("Time each frame on the GPU"),
+      maxHitches: z.number().int().min(0).max(50).default(10).describe("Worst late frames to explain"),
+      savePath: z.string().optional().describe("Where to write the trace file. Default: a file in the system temp directory"),
+      save: z.boolean().default(true).describe("Write the trace file")
+    },
+    annotations: { ...READ_ONLY, idempotentHint: false }
+  }, ({ clientId: clientId3, durationMs, jsProfile, sampleIntervalMs, gpu, maxHitches, savePath, save }) => run(async () => {
+    const capture = await client.client("trace", { durationMs, jsProfile: String(jsProfile), sampleIntervalMs, gpu: String(gpu) }, clientId3);
+    const analysis = analyzeTrace(capture, { maxHitches });
+    let traceFile;
+    if (save) {
+      traceFile = savePath ? resolve(savePath) : defaultTracePath(clientId3 ?? "auto");
+      await mkdir(dirname(traceFile), { recursive: true });
+      await writeFile(traceFile, JSON.stringify(toTraceEvents(capture)));
+    }
+    return {
+      ...analysis,
+      traceFile,
+      traceFileNote: traceFile ? "Chrome Trace Event JSON: drag it into https://ui.perfetto.dev (or chrome://tracing, or speedscope.app) for the flame chart" : void 0
+    };
+  }));
+  server.registerTool("compare_entity", {
+    title: "Compare an entity on server and client",
+    description: "One entity as the server has it next to a tab's copy: position / rotation / scale deltas and the serialized fields that differ. For the tab's own player pass its server id (playerId from list_clients). Needs the server in development too.",
+    inputSchema: { id: z.string().min(1).describe("Entity id on the server"), clientId },
+    annotations: READ_ONLY
+  }, ({ id, clientId: clientId3 }) => run(async () => {
+    const [onServer, onClient] = await Promise.all([client.entity(id), client.client("entity", { id }, clientId3)]);
+    return compareEntities(id, onServer.entity, onClient.entity);
+  }));
+}
+
+// src/mcp/networkTools.ts
+import { z as z2 } from "zod";
+var clientId2 = z2.string().optional().describe("Tab id from list_clients. Default: the only open tab, or the only one not running the editor");
+var packetFilters = {
+  kind: z2.enum(["packet", "event"]).optional().describe("packet: messages on the wire. event: connect, disconnect, sync_enter, sync_leave, dropped, state_gap\u2026"),
+  direction: z2.enum(["in", "out"]).optional().describe("Seen from the side that recorded it: out was sent, in was received"),
+  type: z2.string().optional().describe("Message or event name, e.g. sv_state or command. Several separated by commas"),
+  afterId: z2.number().int().min(0).default(0),
+  limit: z2.number().int().min(1).max(2e3).default(50).describe("Newest records kept when more match")
+};
+function withTime({ timestamp, ...record }) {
+  return { ...record, time: new Date(timestamp).toISOString() };
+}
+function listing(list) {
+  return {
+    latestId: list.latestId,
+    matched: list.matched,
+    records: list.records.map(withTime),
+    ...list.enabled === false ? { note: "Nothing is being recorded on this side" } : {}
+  };
+}
+function mergeTimeline(server, client) {
+  return [
+    ...server.map((record) => ({ side: "server", ...record })),
+    ...client.map((record) => ({ side: "client", ...record }))
+  ].sort((a, b) => a.timestamp - b.timestamp || (a.side === b.side ? a.id - b.id : a.side === "server" ? -1 : 1));
+}
+function registerNetworkTools(server, client) {
+  server.registerTool("network_packets", {
+    title: "Packets on the server",
+    description: "Packets the game server sent and received and its network events, oldest first: time, direction, message name, client (peer), size in bytes, server tick, input sequence id and a few facts about the payload (entity count, ack, command). The server keeps the last 2000. Pass the returned latestId as afterId to get only newer ones; network_packet shows a payload. Development only.",
+    inputSchema: { ...packetFilters, peer: z2.string().optional().describe("Only one client: its player id (list_players, or playerId from list_clients)") },
+    annotations: READ_ONLY
+  }, ({ afterId, ...query }) => run(async () => listing(await client.packets({ ...query, after: afterId }))));
+  server.registerTool("network_packet", {
+    title: "One packet on the server",
+    description: "One record from network_packets with its payload, as it was serialized for the wire. Payloads of old records are dropped to bound memory (hasPayload false). Development only.",
+    inputSchema: { id: z2.number().int().min(1) },
+    annotations: READ_ONLY
+  }, ({ id }) => run(async () => {
+    const { record } = await client.packet(id);
+    if (!record)
+      throw new Error(`No record ${id}: it is older than the 2000 the server keeps, or was never recorded`);
+    return withTime(record);
+  }));
+  server.registerTool("network_sync", {
+    title: "State sync",
+    description: "Who is sent what: the current server tick, the sync distance, each player with the entities in its last state update (tracked), its last acknowledged input and the size of that update; and each synced entity with how many players track it (trackedBy, 0 means no player is in range), whether it changed since it was last synced and the tick it was last sent in. For entities that do not show up or stop updating on a client. Development only.",
+    inputSchema: {
+      player: z2.string().optional().describe("Only this player, and the entities with `tracked` telling whether it is sent them"),
+      includeEntities: z2.boolean().default(true)
+    },
+    annotations: READ_ONLY
+  }, ({ player, includeEntities }) => run(async () => {
+    const sync = await client.sync();
+    const { entities = [], players = [], ...rest } = sync;
+    if (!player)
+      return includeEntities ? sync : { ...rest, players, entityCount: entities.length };
+    const one = players.find((p) => p.id === player);
+    if (!one)
+      throw new Error(`No player "${player}". Players: ${players.map((p) => p.id).join(", ") || "none"}`);
+    const tracked = new Set(one.tracked);
+    return {
+      ...rest,
+      player: one,
+      ...includeEntities ? { entities: entities.map((entity) => ({ ...entity, tracked: tracked.has(entity.id) })) } : { entityCount: entities.length }
+    };
+  }));
+  server.registerTool("client_packets", {
+    title: "Packets on a client",
+    description: "Packets a tab sent and received and its network events (connect, disconnect, state_gap for lost state updates, state_out_of_order), in the same shape as network_packets. Recorded since the tab loaded, the last 2000.",
+    inputSchema: { clientId: clientId2, ...packetFilters },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3, afterId, ...query }) => run(async () => listing(await client.client("packets", { ...query, after: afterId }, clientId3))));
+  server.registerTool("client_packet", {
+    title: "One packet on a client",
+    description: "One record from client_packets with its payload.",
+    inputSchema: { id: z2.number().int().min(1), clientId: clientId2 },
+    annotations: READ_ONLY
+  }, ({ id, clientId: clientId3 }) => run(async () => {
+    const { record } = await client.client("packet", { id }, clientId3);
+    if (!record)
+      throw new Error(`No record ${id}: it is older than the 2000 the tab keeps, or was never recorded`);
+    return withTime(record);
+  }));
+  server.registerTool("network_timeline", {
+    title: "Network timeline of one client",
+    description: "What happened between the server and one tab, in order of time: the server's records for that client and the tab's own, merged, each marked with its side. Shows a packet leaving one side and arriving on the other (or not), inputs against the state updates that acknowledge them, and events like sync_enter / sync_leave, dropped and state_gap. Needs the server in development too.",
+    inputSchema: {
+      clientId: clientId2,
+      sinceMs: z2.number().int().min(100).max(6e5).default(5e3).describe("How far back to look"),
+      includePings: z2.boolean().default(false).describe("Keep ping / pong, one pair per second"),
+      eventsOnly: z2.boolean().default(false).describe("Leave the packets out"),
+      limit: z2.number().int().min(1).max(2e3).default(200).describe("Newest entries kept when more match")
+    },
+    annotations: READ_ONLY
+  }, ({ clientId: clientId3, sinceMs, includePings, eventsOnly, limit }) => run(async () => {
+    const { network } = await client.client("network", {}, clientId3);
+    if (!network?.playerId)
+      throw new Error("This tab is not connected to the game server, so the server has no records for it");
+    const kind = eventsOnly ? "event" : void 0;
+    const [onServer, onClient] = await Promise.all([
+      client.packets({ peer: network.playerId, kind, limit: 2e3 }),
+      client.client("packets", { kind, limit: 2e3 }, clientId3)
+    ]);
+    const from = Date.now() - sinceMs;
+    const entries = mergeTimeline(onServer.records, onClient.records).filter((record) => record.timestamp >= from && (includePings || record.type !== "ping" && record.type !== "pong"));
+    return {
+      playerId: network.playerId,
+      pingMs: network.pingMs,
+      matched: entries.length,
+      entries: entries.slice(-limit).map(withTime),
+      note: "Times are each side's own clock. On one machine they line up; otherwise shift one side by the clock difference"
+    };
+  }));
+}
+
+// src/mcp/pluginTools.ts
+import { z as z3 } from "zod";
+var installCommand = (pkg) => `npx @mavonengine/cli install ${pkg}`;
+async function installedPlugins(client) {
+  const [{ plugins = [] }, routes] = await Promise.all([
+    client.plugins(),
+    // An older server lists its plugins but not its routes: the plugins are still worth showing
+    client.routes().then((result) => result.routes ?? [], () => null)
+  ]);
+  return plugins.map((plugin) => ({
+    ...plugin,
+    endpoints: routes ? routes.filter((route) => route.source === "plugin" && route.plugin === plugin.package).map(({ method, path, devOnly, summary }) => ({ method, path, devOnly, summary })) : null
+  }));
+}
+function registerPluginTools(server, client, list) {
+  server.registerTool("list_plugins", {
+    title: "Plugins of the project",
+    description: "The engine plugins in the project's mavonengine.json: version, whether each is enabled and runs on this server, where it runs (client, server or both), its prefabs and the HTTP endpoints it registered. A problem is reported for a plugin that is missing or invalid. See available_plugins for plugins the project could add.",
+    annotations: READ_ONLY
+  }, () => run(async () => ({ plugins: await installedPlugins(client) })));
+  if (!list)
+    return;
+  const registry = () => fetchPluginRegistry({ url: list.url, fetch: list.fetch });
+  server.registerTool("available_plugins", {
+    title: "Plugins that can be installed",
+    description: "The official MavonEngine plugins: what each does, where it runs, the engine versions it supports and the command that installs it. Says which ones the project already has. Check this before building something a plugin already does, such as chat or a monitoring dashboard, and read plugin_readme before suggesting one. Installing is for the user to do: this server is read-only.",
+    annotations: { ...READ_ONLY, openWorldHint: true }
+  }, () => run(async () => {
+    const [{ url, plugins }, installed] = await Promise.all([
+      registry(),
+      // Whether the project has them is extra: the list is worth showing without a running server
+      installedPlugins(client).then((found) => new Map(found.map((plugin) => [plugin.package, plugin])), () => null)
+    ]);
+    return {
+      source: url,
+      projectPlugins: installed ? "known" : "unknown: the game server could not be asked",
+      plugins: plugins.map((plugin) => ({
+        package: plugin.package,
+        name: plugin.name,
+        description: plugin.description,
+        runsOn: plugin.target,
+        engine: plugin.engine,
+        homepage: plugin.homepage,
+        hasReadme: !!plugin.readme,
+        inProject: installed ? installed.has(plugin.package) : null,
+        install: installCommand(plugin.package)
+      }))
+    };
+  }));
+  server.registerTool("plugin_readme", {
+    title: "Read a plugin's readme",
+    description: "The README of an official MavonEngine plugin as Markdown, by its package name from available_plugins: what it does, its options for mavonengine.json, how a game hooks into it and its limits.",
+    inputSchema: { package: z3.string().describe("npm package of the plugin, e.g. @mavonengine/chat") },
+    annotations: { ...READ_ONLY, openWorldHint: true }
+  }, async ({ package: pkg }) => {
+    try {
+      const { plugins } = await registry();
+      const plugin = plugins.find((candidate) => candidate.package === pkg);
+      if (!plugin)
+        throw new Error(`${pkg} is not on the list of plugins. It has: ${plugins.map((candidate) => candidate.package).join(", ") || "nothing"}`);
+      return { content: [{ type: "text", text: await fetchPluginReadme(plugin, { fetch: list.fetch }) }] };
+    } catch (err) {
+      return { isError: true, content: [{ type: "text", text: err.message }] };
+    }
+  });
+}
+
+// src/mcp/server.ts
+var INSTRUCTIONS = `Reads the live state of a running MavonEngine game: the game server (health, performance, players, scene,
+entities, logs, HTTP requests) and, in development, the game tabs open in a browser (renderer stats, the client's world,
+network state, console logs, screenshots). Every tool is read-only.
+Server scene / entity tools need the server in development (NODE_ENV is not "production"); client tools need the client
+served by Vite in dev. Start with server_status and list_clients. Use type / near filters rather than paging through a world.
+compare_entity shows one entity on both sides, for prediction, interpolation and sync bugs.
+network_packets / client_packets list the packets each side sent and received, network_timeline merges both sides for one
+client, and network_sync tells which entities each player is sent: use them when something does not arrive or arrives late.
+client_trace records a few seconds of a tab for frame drops, stutter and slow rendering: the bottleneck, hitches with
+their causes, hot JS functions, WebGL load, and a trace file for flame charts.
+list_plugins shows the plugins the project has, available_plugins the official ones it could add and plugin_readme how
+one is set up and used: look there before building something a plugin already does, like chat.
+docs_list_pages / docs_get_page read the MavonEngine documentation: check it before guessing how an engine API works.`;
+function summarize(metrics) {
+  const { cpu, bandwidth, tick, players, ...rest } = metrics ?? {};
+  return {
+    ...rest,
+    players: Array.isArray(players) ? players.length : 0,
+    cpu: cpu && { current: cpu.current, avg1s: cpu.avg1s, avg10s: cpu.avg10s, avg60s: cpu.avg60s },
+    bandwidth: bandwidth && { sentPerSecond: bandwidth.sentPerSecond, receivedPerSecond: bandwidth.receivedPerSecond },
+    tick: tick && { budgetMs: tick.budgetMs, latest: tick.latest }
+  };
+}
+function levelOf(level) {
+  return level.toLowerCase().replace(/[^a-z]/g, "");
+}
+function createMcpServer(client, docs, pluginList) {
+  const server = new McpServer({ name: "mavonengine", version }, { instructions: INSTRUCTIONS });
+  server.registerTool("server_status", {
+    title: "Game server status",
+    description: "Health and current performance of the game server: uptime, tick rate and tick time against its budget, CPU, bandwidth, memory, player and entity counts, physics bodies, latency simulation. History is left out, see server_metrics.",
+    annotations: READ_ONLY
+  }, () => run(async () => ({ server: client.url, ...summarize(await client.metrics()) })));
+  server.registerTool("server_metrics", {
+    title: "Full metrics snapshot",
+    description: "The full metrics snapshot. With includeHistory, also the last ~60 samples of CPU, bandwidth and tick timings, to spot spikes.",
+    inputSchema: { includeHistory: z4.boolean().default(false).describe("Include the per-sample history arrays") },
+    annotations: READ_ONLY
+  }, ({ includeHistory }) => run(async () => {
+    const metrics = await client.metrics();
+    if (includeHistory)
+      return metrics;
+    const { cpu, bandwidth, tick } = metrics ?? {};
+    const { history: _cpu, ...cpuNow } = cpu ?? {};
+    const { history: _bandwidth, ...bandwidthNow } = bandwidth ?? {};
+    const { history: _tick, ...tickNow } = tick ?? {};
+    return { ...metrics, cpu: cpuNow, bandwidth: bandwidthNow, tick: tickNow };
+  }));
+  server.registerTool("list_players", {
+    title: "Connected players",
+    description: "Connected players: id, display name, position, last processed input sequence, tracked entities, time connected, and connection details (address, round trip time, bytes sent and received).",
+    annotations: READ_ONLY
+  }, () => run(async () => (await client.metrics())?.players ?? []));
+  server.registerTool("get_scene", {
+    title: "Active scene",
+    description: "The scene loaded on the server: name, file, whether it hot-reloads, unsaved changes, settings, and its objects with type, transform, props, the plugin that registered the type and whether the server built it (false for client-only types). Development only.",
+    inputSchema: { includeObjects: z4.boolean().default(true).describe("Include the scene objects, not just the summary") },
+    annotations: READ_ONLY
+  }, ({ includeObjects }) => run(async () => {
+    const { scene } = await client.scene();
+    if (!scene)
+      return { scene: null, note: "No scene is loaded. The server opens one with server.openScene(name)" };
+    if (includeObjects)
+      return scene;
+    const { objects, ...summary } = scene;
+    return { ...summary, objectCount: objects?.length ?? 0 };
+  }));
+  server.registerTool("list_entities", {
+    title: "Entities in the world",
+    description: "Entities in the server world: id, type, position, rotation, scale, whether networked or a player, and the scene object it was built from. Filter by type and/or distance to a point (results are then nearest first). Returns the total match count. Development only.",
+    inputSchema: {
+      type: z4.string().optional().describe("Entity class / networked type name, or scene object type, case-insensitive"),
+      near: vec3.optional().describe("Only entities around this point, nearest first"),
+      radius: z4.number().nonnegative().optional().describe("Max distance from `near`"),
+      limit: z4.number().int().min(1).max(500).default(50),
+      offset: z4.number().int().min(0).default(0)
+    },
+    annotations: READ_ONLY
+  }, (query) => run(() => client.entities(query)));
+  server.registerTool("get_entity", {
+    title: "One entity",
+    description: "One entity by id, with the state it sends to clients (its serialize() output). Development only.",
+    inputSchema: { id: z4.string().min(1) },
+    annotations: READ_ONLY
+  }, ({ id }) => run(async () => {
+    const { entity } = await client.entity(id);
+    if (!entity)
+      throw new Error(`No entity with id "${id}" in the world. list_entities shows the ids`);
+    return entity;
+  }));
+  server.registerTool("recent_logs", {
+    title: "Server logs",
+    description: "Recent game server log lines, oldest first. The server keeps the last 500 by default. Pass the returned latestId as afterId later to get only newer lines.",
+    inputSchema: {
+      level: z4.enum(LOG_LEVELS).optional().describe("Only this level and more severe ones, e.g. warn includes error"),
+      contains: z4.string().optional().describe("Only lines containing this text, case-insensitive"),
+      afterId: z4.number().int().min(0).default(0),
+      limit: z4.number().int().min(1).max(500).default(100).describe("Newest lines kept when more match")
+    },
+    annotations: READ_ONLY
+  }, ({ level, contains, afterId, limit }) => run(async () => {
+    const { entries = [], latestId = 0 } = await client.logs(afterId);
+    const maxSeverity = level ? LOG_LEVELS.indexOf(level) : Infinity;
+    const needle = contains?.toLowerCase();
+    const matches = entries.filter((entry) => {
+      const severity = LOG_LEVELS.indexOf(levelOf(entry.level));
+      return (severity === -1 || severity <= maxSeverity) && (!needle || entry.message.toLowerCase().includes(needle));
+    });
+    return {
+      latestId,
+      matched: matches.length,
+      entries: matches.slice(-limit).map(({ timestamp, ...entry }) => ({ ...entry, time: new Date(timestamp).toISOString() }))
+    };
+  }));
+  server.registerTool("recent_requests", {
+    title: "HTTP requests",
+    description: "Recent HTTP requests the game server answered: method, path, status, duration, bytes, address. Pass the returned latestId as afterId later to get only newer ones.",
+    inputSchema: {
+      pathContains: z4.string().optional(),
+      minStatus: z4.number().int().optional().describe("e.g. 400 for errors only"),
+      afterId: z4.number().int().min(0).default(0),
+      limit: z4.number().int().min(1).max(500).default(50).describe("Newest requests kept when more match")
+    },
+    annotations: READ_ONLY
+  }, ({ pathContains, minStatus, afterId, limit }) => run(async () => {
+    const { entries = [], latestId = 0 } = await client.requests(afterId);
+    const matches = entries.filter((entry) => (!pathContains || entry.path.includes(pathContains)) && (minStatus === void 0 || (entry.status ?? 0) >= minStatus));
+    return { latestId, matched: matches.length, entries: matches.slice(-limit) };
+  }));
+  registerClientTools(server, client);
+  registerNetworkTools(server, client);
+  registerPluginTools(server, client, pluginList);
+  if (docs)
+    registerDocsTools(server, docs);
+  return server;
+}
+export {
+  createMcpServer
+};