cozyclay 1.2.0 → 1.5.0

package/LICENSING.md

@@ -0,0 +1,32 @@
+# CozyClay licensing
+
+CozyClay is distributed as a combined work under the GNU Affero General
+Public License, version 3 or later (`AGPL-3.0-or-later`). The complete license
+text is in [`LICENSE`](LICENSE).
+
+If you modify CozyClay and let users interact with that modified version over
+a network, section 13 of the AGPL requires you to offer those users the
+Corresponding Source of the version you run, at no charge. CozyClay keeps that
+offer visible in the Studio footer as **Source code (AGPL)**.
+
+The official build points that link at this repository. Operators deploying a
+modified version must set `VITE_SOURCE_CODE_URL` at build time to a public URL
+containing the complete Corresponding Source for the version they run.
+
+## Earlier contributions
+
+Before 2026-08-21, CozyClay was published under `GPL-3.0-or-later`. Copyright
+in those contributions remains with its respective holders and those portions
+remain available under that license; its text is preserved at
+[`LICENSES/GPL-3.0-or-later.txt`](LICENSES/GPL-3.0-or-later.txt). Section 13 of
+AGPLv3 expressly permits GPLv3 and AGPLv3 code to be combined, with the AGPL
+network-source requirement applying to the combined program.
+
+Contributions submitted on or after 2026-08-21 are accepted under
+`AGPL-3.0-or-later` unless a file clearly says otherwise.
+
+## Third-party material
+
+The AGPL does not replace the licenses of dependencies, fonts, models, model
+weights, or other third-party material. See
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for their separate terms.

package/README.md

@@ -7,18 +7,23 @@
 </p>
 
 <p align="center">
-  <a href="LICENSE"><img alt="License: GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+  Created and maintained by <a href="https://github.com/HaD0Yun">Doyun</a> at <a href="https://github.com/NomaDamas">NomaDamas</a>.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
   <a href="https://www.npmjs.com/package/cozyclay"><img alt="npm" src="https://img.shields.io/npm/v/cozyclay"></a>
   <img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-brightgreen">
-  <a href="https://github.com/HaD0Yun/CozyClay/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/HaD0Yun/CozyClay?style=flat"></a>
+  <a href="https://github.com/NomaDamas/CozyClay/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/NomaDamas/CozyClay?style=flat"></a>
 </p>
 
 <p align="center">
   <a href="https://cozyclay.org/">Demo reel</a> ·
   <a href="#quick-start">Quick start</a> ·
   <a href="#what-you-can-do">Features</a> ·
+  <a href="#ai-control-mcp">AI control</a> ·
   <a href="#controls">Controls</a> ·
-  <a href="https://github.com/HaD0Yun/CozyClay/issues">Issues</a>
+  <a href="https://github.com/NomaDamas/CozyClay/issues">Issues</a>
 </p>
 
 ---
@@ -43,6 +48,7 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 | **Fly the camera** | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, `F` frames — the muscle memory you already have from a 3D editor. |
 | **Undo anything** | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform. |
 | **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to ARDY, then play the result back with sparse IK correction where the generated motion needs fixing. |
+| **Direct it with an AI** | Connect Claude — or any MCP client — and ask for a shot in plain language. It places the cast, frames “a low wide profile”, generates multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control-mcp). |
 
 ## Requirements
 
@@ -61,6 +67,8 @@ bunx cozyclay
 
 That downloads the built studio and opens it at `http://127.0.0.1:5180`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-ardy`.
 
+A global install gives you `cclay`, the same command with less typing. Once a day the launcher checks npm for a newer release and prints a one-line notice after the studio is up; it stays quiet when you're current or offline. `cclay update` installs the latest release, and `--no-update-check` skips the check entirely.
+
 Motion generation stays off until you point it at a machine that can run it:
 
 ```bash
@@ -69,10 +77,40 @@ CCLAY_ARDY_HOST=user@your-gpu-box npx cozyclay
 
 Everything else — staging through camera work and playback — runs without it.
 
+## AI control (MCP)
+
+The studio ships an [MCP](https://modelcontextprotocol.io) server, so an AI assistant can drive it — the same scene, the same viewport, live:
+
+> “Put a detective and a courier in an alley, give me a low wide profile shot,
+> then make her stand up from the chair, sprint, and trip.”
+
+```json
+{
+  "mcpServers": {
+    "cozyclay": {
+      "command": "npx",
+      "args": ["-y", "cozyclay", "mcp"]
+    }
+  }
+}
+```
+
+Drop that into `claude_desktop_config.json` (or any MCP client config) and restart the client. The
+first run automatically installs the MCP SDK's 95-package tree; opening the studio never waits on
+it, so those dependencies are fetched only when you actually want the server.
+
+- **Editor open?** Tool calls move the visible viewport — camera, cast, set, generated motion, prompt blocks on the timeline.
+- **No editor?** Scene and project tools run headless: block scenes, derive film vocabulary
+  (“wide shot · right profile · knee level · 24mm”), render AI video prompts, and write
+  `.cclayproject` files. `capture_frame`, `set_prompt_blocks`, `generate_motion`, and
+  `apply_batch` require the live editor.
+
+Tools, transports and the live-control protocol are documented in [`mcp/README.md`](mcp/README.md).
+
 ### From a clone
 
 ```bash
-git clone https://github.com/HaD0Yun/CozyClay.git
+git clone https://github.com/NomaDamas/CozyClay.git
 cd CozyClay
 npm install
 npm run dev
@@ -123,6 +161,8 @@ See [`tools/ardy/README.md`](tools/ardy/README.md) for details. This workflow is
 | `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
 | `npm run test:lifecycle` | Dev-server process lifecycle |
 | `npm run test:ardy` | ARDY conversion, playback, and IK pipeline |
+| `cd mcp && npm install && npm run verify` | MCP server over real stdio — all 420 framing combinations |
+| `cd mcp && npm run verify:live` | Live-control protocol against a fake editor (same `npm install` first) |
 | `npm run build` | Production build |
 
 Ad-hoc browser QA, while a dev server is available:
@@ -133,12 +173,14 @@ npm run qa:browser -- <qa-script>
 
 ## Contributing
 
-Found something broken, or want a feature? [Open an issue](https://github.com/HaD0Yun/CozyClay/issues) — bug reports with a repro are the most useful thing you can send.
+Found something broken, or want a feature? [Open an issue](https://github.com/NomaDamas/CozyClay/issues) — bug reports with a repro are the most useful thing you can send. Contributions are accepted under `AGPL-3.0-or-later`.
 
 **Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `tools/ardy/out/`, `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
 
+All runtime libraries intentionally live in `devDependencies` because the published npm package ships the prebuilt `dist/`, so `npx cozyclay` must not install the studio's dependency tree.
+
 ## License & credits
 
-GNU General Public License v3.0 or later — see [`LICENSE`](LICENSE). Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+GNU Affero General Public License v3.0 or later — see [`LICENSE`](LICENSE) and the transition details in [`LICENSING.md`](LICENSING.md). Modified network services must offer their users the corresponding source. Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 
 CozyClay can connect to [NVIDIA ARDY](https://github.com/nv-tlabs/ardy) for motion generation. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA.

package/THIRD_PARTY_NOTICES.md

@@ -11,6 +11,16 @@ CozyClay's browser-based 3D studio uses [Three.js](https://threejs.org/) through
 - Source: https://github.com/mrdoob/three.js
 - License text: https://github.com/mrdoob/three.js/blob/dev/LICENSE
 
+## Mediabunny
+
+CozyClay uses [Mediabunny](https://mediabunny.dev/) to mux recorded WebCodecs
+video frames into MP4 files in the browser.
+
+- Copyright (c) 2024-2026 Vanilagy
+- License: MPL-2.0
+- Source: https://github.com/Vanilagy/mediabunny
+- License text: https://github.com/Vanilagy/mediabunny/blob/main/LICENSE
+
 ## NVIDIA ARDY
 
 CozyClay provides an optional bridge and data-conversion workflow for externally installed [ARDY](https://github.com/nv-tlabs/ardy), an interactive human-motion generation project from NVIDIA Research.
@@ -55,6 +65,42 @@ bundled.
 - Source: https://github.com/McGill-NLP/llm2vec
 - License text: https://github.com/McGill-NLP/llm2vec/blob/main/LICENSE
 
+## Fonts
+
+CozyClay bundles subsets of two typefaces. Both are licensed under the SIL Open
+Font License 1.1, which allows them to be redistributed with software as long as
+the copyright notice and the licence travel with the files. The licence texts are
+in `public/fonts/` next to the fonts themselves.
+
+### Inter
+
+- Copyright (c) 2016 The Inter Project Authors
+- License: SIL Open Font License 1.1
+- Source: https://github.com/rsms/inter
+- License text: `public/fonts/Inter-OFL.txt`
+
+### Instrument Serif
+
+- Copyright 2022 The Instrument Serif Project Authors
+- License: SIL Open Font License 1.1
+- Source: https://github.com/Instrument/instrument-serif
+- License text: `public/fonts/InstrumentSerif-OFL.txt`
+
+## Character models
+
+The rigs in `public/models/` are Mixamo characters from Adobe. Adobe permits
+their use in projects but not the distribution of the raw character files, which
+is what shipping them in this repository, the npm package and the hosted site
+amounts to. They are also outside the scope of this repository's AGPL-3.0 grant:
+nothing here relicenses them, and a fork does not acquire the right to
+redistribute them.
+
+They are being replaced with a CC0 rig. Until that lands, treat these two files
+as third-party content that this licence does not cover.
+
+- `x-bot-tpose.fbx`, `y-bot-tpose.fbx` — Adobe Mixamo
+- Terms: https://www.adobe.com/legal/terms.html
+
 ## CozyClay license scope
 
-The CozyClay source code in this repository is licensed under GPL-3.0-or-later. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, or any other third-party component.
+The CozyClay combined work in this repository is distributed under AGPL-3.0-or-later, subject to the transition details in `LICENSING.md`. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, the bundled fonts, the character rigs, or any other third-party component.

package/bin/cozyclay.mjs

@@ -8,24 +8,28 @@
  * `dist/`, so this launcher only has to
  *
  *   - serve those files over loopback,
- *   - forward /ardy to the sidecar on 5181 (the job Vite's dev proxy does),
+ *   - forward /ardy to its dynamically selected sidecar port (the job Vite's dev proxy does),
  *   - keep the sidecar's lifetime tied to this process.
  *
  * It has no dependencies on purpose. A launcher that needs an install step
  * before it can serve a prebuilt app is a launcher that will break.
  */
 import { spawn } from "node:child_process";
+import { startBridge, terminateOwned } from "../tools/process-supervisor.mjs";
 import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { createServer, request as httpRequest } from "node:http";
 import { homedir } from "node:os";
 import { extname, join, normalize, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
+import { runMcp } from "./mcp-runtime.mjs";
+import { openBrowser } from "./open-browser.mjs";
+import { checkForUpdate, runUpdate } from "./update-check.mjs";
 
 const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
 const DIST = join(PKG_ROOT, "dist");
 const BRIDGE = join(PKG_ROOT, "tools", "ardy", "bridge.mjs");
-const BRIDGE_PORT = Number(process.env.COZYCLAY_BRIDGE_PORT ?? 5181);
+let bridgePort = 5181;
 
 const TYPES = {
 	".html": "text/html; charset=utf-8",
@@ -45,7 +49,7 @@ const TYPES = {
 };
 
 function parseArgs(argv) {
-	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true };
+	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true, updateCheck: true };
 	for (let i = 0; i < argv.length; i += 1) {
 		const arg = argv[i];
 		if (arg === "--port" || arg === "-p") opts.port = Number(argv[++i]);
@@ -55,21 +59,29 @@ function parseArgs(argv) {
 		else if (arg === "--no-ardy") opts.ardy = false;
 		else if (arg === "--no-open") opts.open = false;
 		else if (arg === "--no-star") opts.star = false;
+		else if (arg === "--no-update-check") opts.updateCheck = false;
 		else if (arg === "--help" || arg === "-h") opts.help = true;
 		else if (arg === "--version" || arg === "-v") opts.version = true;
 		else {
 			console.error(`cozyclay: unknown option ${arg}`);
 			opts.help = true;
+			opts.invalid = true;
 		}
 	}
-	if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) {
-		console.error("cozyclay: --port must be a port number");
+	if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65534) {
+		console.error("cozyclay: --port must be an integer in 1..65534");
 		opts.help = true;
+		opts.invalid = true;
+	}
+	if (opts.host !== "127.0.0.1") {
+		console.error("cozyclay: --host is restricted to 127.0.0.1");
+		opts.help = true;
+		opts.invalid = true;
 	}
 	return opts;
 }
 
-const REPO_URL = "https://github.com/HaD0Yun/CozyClay";
+const REPO_URL = "https://github.com/NomaDamas/CozyClay";
 const STATE_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay");
 const STATE_FILE = join(STATE_DIR, "state.json");
 // Only worth asking someone who actually used the thing. A prompt three
@@ -79,10 +91,16 @@ const STAR_AFTER_MS = Number(process.env.COZYCLAY_STAR_AFTER_MS ?? 60_000);
 const HELP = `cozyclay - browser-based 3D staging studio
 
   npx cozyclay              start the studio and open it
+  npx cozyclay mcp          run the MCP server (for Claude, Cursor, any MCP client)
+  cclay update              install the latest cozyclay globally (npm install -g)
   npx cozyclay --port 5200  serve on another port
   npx cozyclay --no-ardy    skip the optional motion-generation sidecar
   npx cozyclay --no-open    do not open a browser
   npx cozyclay --no-star    never ask about starring the repo
+  npx cozyclay --no-update-check
+                            do not look for a newer release
+
+cclay is the same command, shorter: a global install gives you both.
 
 Motion generation needs an SSH-reachable NVIDIA machine running ARDY; point
 the sidecar at it with CCLAY_ARDY_HOST. Everything else - staging, posing,
@@ -104,7 +122,7 @@ function serveFile(res, path) {
 // browser code needs no build-time knowledge of how it was launched.
 function proxyToBridge(req, res) {
 	const upstream = httpRequest(
-		{ host: "127.0.0.1", port: BRIDGE_PORT, path: req.url, method: req.method, headers: req.headers },
+		{ host: "127.0.0.1", port: bridgePort, path: req.url, method: req.method, headers: req.headers },
 		(upstreamRes) => {
 			res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
 			upstreamRes.pipe(res);
@@ -138,7 +156,7 @@ function writeState(patch) {
 
 async function starCount() {
 	try {
-		const res = await fetch("https://api.github.com/repos/HaD0Yun/CozyClay", {
+		const res = await fetch("https://api.github.com/repos/NomaDamas/CozyClay", {
 			headers: { accept: "application/vnd.github+json" },
 			signal: AbortSignal.timeout(2500),
 		});
@@ -179,26 +197,42 @@ async function maybeAskForStar(startedAt, opts) {
 	}
 }
 
-function openBrowser(url) {
-	const cmd =
-		process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-	const child = spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
-	child.on("error", () => {
-		/* headless box, no browser: the URL is printed anyway */
-	});
-	child.unref();
+// Read on every launch now, so it must not be able to take the launcher down:
+// the version is cosmetic here, and "0.0.0" just suppresses a bogus notice.
+function readVersion() {
+	try {
+		return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
 }
 
-const opts = parseArgs(process.argv.slice(2));
-if (opts.help) {
-	console.log(HELP);
-	process.exit(0);
+const argv = process.argv.slice(2);
+if (argv[0] === "mcp") {
+	await runMcp(argv.slice(1));
+} else if (argv[0] === "update") {
+	// This branch bypasses parseArgs, so anything trailing would be swallowed
+	// and `cclay update --help` would perform an unrequested global install.
+	if (argv.length > 1) {
+		console.error(`cozyclay: update takes no arguments (got ${argv.slice(1).join(" ")})`);
+		process.exit(1);
+	}
+	runUpdate();
+} else {
+
+const opts = parseArgs(argv);
+	if (opts.help) {
+		console.log(HELP);
+		process.exit(opts.invalid ? 1 : 0);
 }
+const version = readVersion();
 if (opts.version) {
-	const pkg = JSON.parse(await import("node:fs").then((fs) => fs.promises.readFile(join(PKG_ROOT, "package.json"), "utf8")));
-	console.log(pkg.version);
+	console.log(version);
 	process.exit(0);
 }
+// Fired before anything blocking and never awaited on the launch path: the
+// notice is worth a line of output, never a second of startup.
+const updatePending = opts.updateCheck && !process.env.CI && !process.env.COZYCLAY_NO_UPDATE_CHECK ? checkForUpdate(version, STATE_DIR) : null;
 if (!existsSync(join(DIST, "app", "index.html"))) {
 	console.error("cozyclay: this package is missing its build (dist/app/index.html).");
 	console.error("cozyclay: from a clone, run `npm install && npm run build` first.");
@@ -210,16 +244,62 @@ if (!existsSync(join(DIST, "app", "index.html"))) {
 // cannot act on. An unset CCLAY_ARDY_HOST is the normal case, not a fault.
 const ardyHost = process.env.CCLAY_ARDY_HOST?.trim();
 let bridge = null;
+let server = null;
+const startedAt = Date.now();
+let shuttingDown = false;
+async function shutdown(exitCode = 0) {
+	if (shuttingDown) return;
+	shuttingDown = true;
+	if (bridge) await terminateOwned(bridge);
+	if (server?.listening) await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+	try {
+		await maybeAskForStar(startedAt, opts);
+	} catch {
+		/* never let the goodbye prompt hold the process hostage */
+	}
+	process.exit(exitCode);
+}
+process.on("SIGINT", () => shutdown(130));
+process.on("SIGTERM", () => shutdown(143));
+
 if (opts.ardy && ardyHost && existsSync(BRIDGE)) {
-	bridge = spawn(process.execPath, [BRIDGE], { cwd: PKG_ROOT, stdio: "inherit" });
-	bridge.on("error", () => {
-		bridge = null;
-	});
+	try {
+		({ child: bridge, port: bridgePort } = await startBridge({
+			command: process.execPath,
+			args: [BRIDGE],
+			cwd: PKG_ROOT,
+			env: process.env,
+			mainPort: opts.port,
+			onSpawn: (child) => {
+				bridge = child;
+			},
+			onReady: (child) => {
+				child.once("exit", (code, signal) => {
+					if (shuttingDown) return;
+					console.error(`cozyclay: motion generation sidecar exited ${signal ? `from ${signal}` : `with code ${code ?? 0}`}.`);
+					void shutdown(1);
+				});
+				child.once("error", (err) => {
+					if (shuttingDown) return;
+					console.error(`cozyclay: motion generation sidecar failed: ${err.message}`);
+					void shutdown(1);
+				});
+			},
+		}));
+	} catch (err) {
+		console.error(`cozyclay: motion generation sidecar failed: ${err.message}`);
+		console.error("cozyclay: studio did not start; set COZYCLAY_BRIDGE_PORT to an available port or use --no-ardy.");
+		if (bridge) await terminateOwned(bridge);
+		process.exit(1);
+	}
 }
 
-const server = createServer((req, res) => {
+server = createServer((req, res) => {
 	const url = new URL(req.url ?? "/", "http://localhost");
-	if (url.pathname.startsWith("/ardy/")) {
+	// Only the routes the bridge actually owns: /ardy/ is ALSO a public asset
+	// directory (cskel27-rest.json), and those files live in dist/, not behind
+	// the sidecar. Same rule as the Vite dev proxy bypass.
+	if (/^\/ardy\/(health|bases|generate|footage|extract|motions)(\/|$)/.test(url.pathname)) {
 		proxyToBridge(req, res);
 		return;
 	}
@@ -245,37 +325,20 @@ const server = createServer((req, res) => {
 	serveFile(res, target);
 });
 
-const startedAt = Date.now();
-let shuttingDown = false;
-async function shutdown() {
-	if (shuttingDown) process.exit(0);
-	shuttingDown = true;
-	if (bridge) bridge.kill("SIGTERM");
-	server.close();
-	try {
-		await maybeAskForStar(startedAt, opts);
-	} catch {
-		/* never let the goodbye prompt hold the process hostage */
-	}
-	process.exit(0);
-}
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-
 server.on("error", (err) => {
 	if (err && err.code === "EADDRINUSE") {
-		console.error(`cozyclay: port ${opts.port} is taken. Try --port ${opts.port + 1}.`);
-		if (bridge) bridge.kill("SIGTERM");
-		process.exit(1);
+		console.error(`cozyclay: port ${opts.port} is taken. Try --port 5200.`);
+		void shutdown(1);
+		return;
 	}
 	throw err;
 });
 
-server.listen(opts.port, opts.host, () => {
+server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, () => {
 	// The package exists to open the studio, which the site serves from /app/.
 	// Landing on "/" would greet someone who just typed `npx cozyclay` with a
 	// marketing page.
-	const url = `http://${opts.host}:${opts.port}/app/`;
+	const url = `http://127.0.0.1:${opts.port}/app/`;
 	console.log(`CozyClay is running at ${url}`);
 	if (!opts.ardy) console.log("Motion generation: off (--no-ardy).");
 	else if (bridge) console.log(`Motion generation: sidecar running against ${ardyHost}.`);
@@ -285,4 +348,11 @@ server.listen(opts.port, opts.host, () => {
 				"set CCLAY_ARDY_HOST=user@host to turn it on. Everything else works without it.",
 		);
 	if (opts.open) openBrowser(url);
+	void updatePending?.then((latest) => {
+		// `cclay` only exists after a global install, so name the command that
+		// works from an npx run too.
+		if (latest) console.log(`cozyclay ${latest} is available (you have ${version}). Run: npm install -g cozyclay@latest`);
+	});
 });
+
+}

package/bin/mcp-runtime.mjs

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const PACKAGE_VERSION = JSON.parse(await import("node:fs/promises").then((fs) => fs.readFile(join(PKG_ROOT, "package.json"), "utf8"))).version;
+const MCP_RUNTIME_SOURCE = join(PKG_ROOT, "mcp", "runtime");
+const MCP_RUNTIME = process.env.COZYCLAY_MCP_RUNTIME_DIR || join(
+	process.env.XDG_CACHE_HOME || process.env.LOCALAPPDATA || join(homedir(), ".cache"),
+	"cozyclay",
+	"mcp-runtime",
+	PACKAGE_VERSION,
+);
+
+function probeMcpRuntime(runtime = MCP_RUNTIME) {
+	const server = join(runtime, "mcp", "server.mjs");
+	if (!existsSync(server)) throw new Error("MCP server is missing");
+	const runtimeRequire = createRequire(join(runtime, "package.json"));
+	for (const dependency of ["@modelcontextprotocol/sdk/server/mcp.js", "three", "ws", "zod"]) runtimeRequire.resolve(dependency);
+	return server;
+}
+
+function installMcpRuntime() {
+	return new Promise((done) => {
+		const parent = dirname(MCP_RUNTIME);
+		mkdirSync(parent, { recursive: true });
+		try {
+			probeMcpRuntime();
+			done({ code: 0 });
+			return;
+		} catch {
+			// A killed older install can leave an incomplete final directory.
+			// Only complete stagings are ever renamed here, so an invalid final
+			// cache is safe to discard before this attempt begins.
+			rmSync(MCP_RUNTIME, { recursive: true, force: true });
+		}
+		const staging = mkdtempSync(join(parent, `${basename(MCP_RUNTIME)}.install-`));
+		copyFileSync(join(MCP_RUNTIME_SOURCE, "package.json"), join(staging, "package.json"));
+		copyFileSync(join(MCP_RUNTIME_SOURCE, "package-lock.json"), join(staging, "package-lock.json"));
+		cpSync(join(PKG_ROOT, "mcp"), join(staging, "mcp"), { recursive: true });
+		cpSync(join(PKG_ROOT, "src"), join(staging, "src"), { recursive: true });
+
+		const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+		const child = spawn(npm, ["ci", "--no-audit", "--no-fund"], {
+			cwd: staging,
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: process.platform === "win32",
+		});
+		child.stdout.pipe(process.stderr);
+		child.stderr.pipe(process.stderr);
+		child.on("error", (error) => {
+			rmSync(staging, { recursive: true, force: true });
+			done({ code: 1, error });
+		});
+		child.on("exit", (code) => {
+			if (code !== 0) {
+				rmSync(staging, { recursive: true, force: true });
+				done({ code: code ?? 1 });
+				return;
+			}
+			try {
+				probeMcpRuntime(staging);
+				try {
+					probeMcpRuntime();
+					rmSync(staging, { recursive: true, force: true });
+				} catch {
+					try {
+						renameSync(staging, MCP_RUNTIME);
+					} catch (error) {
+						// Another first run can publish its complete staging
+						// directory first. Accept that winner only after the
+						// same full probe; never execute a partial cache.
+						probeMcpRuntime();
+						rmSync(staging, { recursive: true, force: true });
+					}
+				}
+				done({ code: 0 });
+			} catch (error) {
+				rmSync(staging, { recursive: true, force: true });
+				done({ code: 1, error });
+			}
+		});
+	});
+}
+
+export async function runMcp(rest) {
+	if (!existsSync(join(PKG_ROOT, "mcp", "server.mjs")) || !existsSync(join(MCP_RUNTIME_SOURCE, "package-lock.json"))) {
+		console.error("cozyclay: this build does not include the MCP server runtime.");
+		process.exit(1);
+	}
+
+	let server;
+	try {
+		server = probeMcpRuntime();
+	} catch {
+		console.error("cozyclay: installing MCP server dependencies (one-time per CozyClay version)...");
+		const result = await installMcpRuntime();
+		if (result.code !== 0) {
+			console.error(`cozyclay: npm ci failed${result.error ? `: ${result.error.message}` : ` (exit ${result.code})`}. Check your network connection and retry.`);
+			console.error(`cozyclay: the published package was not changed; remove ${JSON.stringify(MCP_RUNTIME)} before retrying a damaged cache.`);
+			process.exit(1);
+		}
+		try {
+			server = probeMcpRuntime();
+		} catch (error) {
+			console.error(`cozyclay: MCP runtime is incomplete after npm ci: ${error.message}`);
+			process.exit(1);
+		}
+	}
+	const child = spawn(process.execPath, [server, ...rest], { stdio: "inherit" });
+	child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+}

package/bin/open-browser.mjs

@@ -0,0 +1,10 @@
+import { spawn } from "node:child_process";
+
+export function openBrowser(url) {
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	const child = spawn(command, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
+	child.on("error", () => {
+		/* headless box, no browser: the URL is printed anyway */
+	});
+	child.unref();
+}