@rainbow-robotics/muscat-plugin-kit 1.1.5 → 1.2.1

package/README.md

@@ -119,6 +119,54 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 | `muscat-pk version` | Print the installed CLI version (`-v` / `--version` also work) |
 | `muscat-pk completion [shell]` | Print a shell completion script (`bash` / `zsh` / `fish` / `powershell`; defaults to `$SHELL`) |
 
+### Update policy
+
+`muscat-pk` can be installed globally (npm `-g` or the S3 binary) and/or per
+plugin project (`node_modules`). Two rules keep those from drifting apart:
+
+**The project's local install wins.** When you run `muscat-pk` inside a plugin
+project that has its own install, the CLI hands off to that copy. So the CLI,
+the `vite` preset your `vite.config.ts` imports, and the `preview-host` that
+`dev:ui` launches are always the single version the project pinned — a global
+CLI that is newer or older than the project can't half-apply itself.
+
+**`update` only touches what you're in.**
+
+| Where you run it | What it updates |
+|---|---|
+| Inside a project with a local install | that project's `muscat-plugin-kit` + `plugin-ui` only |
+| Same, with `--global` | the above, plus the global CLI |
+| Anywhere else | the global CLI (and local deps if you're in a project) |
+
+```bash
+muscat-pk update            # this project only
+muscat-pk update --global   # this project + the global CLI
+muscat-pk update dev        # follow the dev channel instead of latest
+muscat-pk version           # which version is actually running here
+```
+
+`dev:ui` also prints a one-line notice when a newer version is published. It is
+skipped by `MUSCAT_PK_NO_UPDATE_CHECK=1` and fails silently offline.
+
+### Offline / air-gapped use
+
+Docker images are only built when they are missing. `docker build` contacts the
+registry to resolve the base image tag on every run — even when every layer is
+cached — so rebuilding an image you already have would break `dev` with no
+network. Once an image exists locally, `muscat-pk` skips the build entirely.
+
+Move images to a machine with no internet:
+
+```bash
+# on a machine with network
+docker save muscat-pk-python-dev muscat-pk-bridge | gzip > muscat-pk-images.tar.gz
+
+# on the offline machine
+gunzip -c muscat-pk-images.tar.gz | docker load
+```
+
+Force a rebuild with `MUSCAT_PK_REBUILD_IMAGE=1`.
+
 ### Shell completion
 
 | OS / shell | Command |
@@ -130,6 +178,57 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 
 Windows `cmd.exe` has no completion mechanism to hook into — use PowerShell, Git Bash, or WSL.
 
+## Backend port policy
+
+A plugin backend that opens a TCP listener must declare every such port in
+`manifest.json`:
+
+```json
+{ "ports": [28600, 28601] }
+```
+
+| Rule | Enforced by |
+|---|---|
+| Ports must be within `28600-28999` | `muscat-pk build` / `dev` (manifest validation) |
+| Reserved robot/industrial ports are rejected | same — `502`, `2222`, `4840`, `5170-5179`, `8000-8999`, `10000`, `30004`, `34964`, `44818`, `50000-50005`, `50051` |
+| **Every listening port must be declared** | `dev` / `dev:back` runtime monitor — stops the backend on the first undeclared port |
+| No two enabled plugins may claim the same port | the robot, at install time (HTTP 409) |
+
+The runtime monitor is strict on purpose: an undeclared port outside the plugin
+range is invisible to both the monitor and the robot's conflict check, so it
+would only surface as a collision after deployment.
+
+`muscat-pk`'s own dev plumbing (the Socket.IO bridge on `10000`, the Zenoh dev
+peer port) is excluded from the check — it isn't the plugin's traffic.
+
+Declared ports are published to `127.0.0.1` on macOS and Windows so you can
+reach the backend from the host; native Linux uses host networking, where they
+already are.
+
+## Variables (pyfm)
+
+Variables the plugin wants to expose to pyfm programs must be pre-declared in
+`manifest.json` — the Muscat UI lists only declared variables in its variable
+picker:
+
+```json
+{
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘 (0~1)", "en": "Gripper force (0–1)" } },
+    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
+  ]
+}
+```
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | must start with `RBP_`, then letters/digits/underscore; unique per plugin |
+| `type` | yes | `"number"` \| `"string"` \| `"array"` |
+| `init` | yes | initial value, must match `type` |
+| `description` | no | string or i18n object (`en` required in object form). Without it the UI shows the variable with no explanation — write one. |
+
+Validated by `muscat-pk build` / `dev` alongside the rest of the manifest.
+
 ## IDE support (Python)
 
 `muscat-pk new` creates a `.venv` at the project root with `requirements.txt` installed. The real backend still runs in a Docker container — this `.venv` exists purely for editor linting (pylint/pyright).

package/cli/README.md

@@ -37,7 +37,17 @@ If a plugin backend opens a TCP server, declare it in `manifest.json`:
 `ports` is optional and accepts only `number[]`; ranges or objects are not
 accepted. External plugin backend ports are reserved for `28600-28999`.
 `muscat-pk dev` and `muscat-pk dev:back` validate the manifest before start and
-stop the backend if it opens an undeclared managed TCP listen port.
+then watch the container: **any listening TCP port that is not declared stops
+the backend**, whatever its number. Since a port outside `28600-28999` cannot be
+declared, it cannot be opened either — otherwise it would slip past both this
+check and the robot's install-time conflict check.
+
+The kit's own dev ports (Socket.IO bridge `10000`, the Zenoh dev peer port) are
+excluded from that check.
+
+Declared ports are published to `127.0.0.1` so the host can reach the backend on
+macOS/Windows; native Linux dev containers use host networking and already have
+them. A declared port that is already busy on the host is skipped with a warning.
 
 Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
 `8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,
@@ -229,4 +239,25 @@ offline.
 - `RB_REGISTRY` — registry base URL (default `https://registry.npmjs.org`).
 - `MUSCAT_PK_NO_UPDATE_CHECK=1` — skip the check.
 
+## Local vs global install
+
+If the plugin project has its own `muscat-plugin-kit` in `node_modules`, the CLI
+delegates to it — so the CLI, the `vite` preset, and `preview-host` are always
+the one version the project pinned, no matter which `muscat-pk` you typed.
+
+`muscat-pk update` follows the same rule: run from a project's local install it
+updates only that project; add `--global` to also update the machine-wide CLI.
+`muscat-pk version` prints whichever copy actually ran.
+
+## Docker images
+
+Images are built only when missing, because `docker build` resolves the base
+image tag over the network on every run — even with all layers cached — which
+would break `dev` offline. Pre-seed an air-gapped machine with
+`docker save … | gzip` + `docker load`, or force a rebuild with
+`MUSCAT_PK_REBUILD_IMAGE=1`.
+
+On Linux the dev containers run as the invoking user (`--user`), so build output
+under `dist/` and `cpp/build-*` is not left root-owned.
+
 Full spec: [`docs/plugin-system/CREATE-CLI.md`](../../docs/plugin-system/CREATE-CLI.md).

package/cli/bin/muscat-pk.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
 // Subcommands: new, build, dev, dev:ui, dev:back, storybook, mcp, update, uninstall, sdk, version.
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { color, kitVersion, log, resolveLocalCliBin } from "../src/util.mjs";
@@ -24,15 +25,39 @@ import { runCompletion } from "../src/completion.mjs";
 // 실행 중인 게 글로벌/바이너리인데 cwd 상위에 로컬 설치가 있으면 그쪽으로 넘긴다.
 // vite preset / preview-host / manifest 검증이 항상 프로젝트가 고정한 버전과
 // 맞아야 해서다 (버전이 안 맞으면 "module not found" 류 에러로 터진다).
+function readVersion(binPath) {
+  try {
+    return JSON.parse(readFileSync(resolve(binPath, "../../../package.json"), "utf8")).version;
+  } catch {
+    return "";
+  }
+}
+
+const isBinaryMode = typeof Bun !== "undefined";
+
 (function delegateToLocalInstall() {
   try {
     const localBin = resolveLocalCliBin();
     if (!localBin) return;
-    if (realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
-    const r = spawnSync(process.execPath, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    // 바이너리는 node_modules 안의 mjs일 수 없으니 자기 자신 비교 생략.
+    // (import.meta.url이 /$bunfs/ 가상 경로라 realpath가 throw하기도 한다.)
+    if (!isBinaryMode && realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
+    // Say so — otherwise an outdated local copy silently answers instead, and
+    // its missing/renamed subcommands look like the CLI is broken.
+    const localVersion = readVersion(localBin);
+    console.error(
+      color.dim(`[muscat-pk] using this project's local install${localVersion ? ` (v${localVersion})` : ""}: ${localBin}`),
+    );
+    // Bun 바이너리의 execPath는 스크립트 인자를 실행하지 않으니 PATH의 node로 넘긴다.
+    const runtime = isBinaryMode ? "node" : process.execPath;
+    const r = spawnSync(runtime, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    if (r.error) {
+      log.warn(`Failed to run local install via ${runtime} (${r.error.code}); continuing with this binary.`);
+      return;
+    }
     process.exit(r.status ?? 0);
   } catch {
-    // Bun 단일 바이너리 등 realpath가 안 통하는 환경 — 그냥 지금 프로세스로 계속.
+    // realpath 실패 등 — 그냥 지금 프로세스로 계속.
   }
 })();
 
@@ -55,7 +80,7 @@ function formatHelp() {
     commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),
-    commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents`),
+    commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents ${color.dim(`(${option("--install")} codex: register in ~/.codex/config.toml)`)}`),
     commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")} and ${color.magenta("@rainbow-robotics/plugin-ui")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
     commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
     commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
@@ -84,7 +109,9 @@ async function main() {
       case "storybook":
         return await runStorybook(args);
       case "mcp": {
-        const { runMcp } = await import("../src/mcp.mjs");
+        const { runMcp, installMcp } = await import("../src/mcp.mjs");
+        if (args[0] === "--install" || args[0] === "install")
+          return installMcp(args[1]);
         return await runMcp(args);
       }
       case "update":

package/cli/src/dev.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
 import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
-import { assertManifestPorts } from "./manifest.mjs";
+import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
   ensureDocker,
@@ -111,6 +111,7 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
 
 export async function runDev(args = []) {
   const root = findPluginRoot();
+  assertManifestVariables(root);
   const portRanges = assertManifestPorts(root);
   if (portRanges.length > 0) {
     log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);

package/cli/src/devBack.mjs

@@ -10,9 +10,9 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
+import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
 import { ensureRemoteZenohEnv, usesHostNetwork } from "./zenohDev.mjs";
-import { assertManifestPorts, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import { assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
   portEnvFlags,
@@ -147,7 +147,7 @@ async function runPython(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting Python dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags,
+    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags, ...realtimeFlags(),
       // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
       // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
       ...hostGatewayFlags,
@@ -445,11 +445,11 @@ async function runRos2(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
   log.step("pip install + colcon build --symlink-install (once)…");
@@ -526,11 +526,11 @@ async function runCpp(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting C++ dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {
     log.step("cmake build…");
@@ -585,6 +585,7 @@ function warnManifest(root) {
 
 export async function runDevBack(args = []) {
   const root = findPluginRoot();
+  assertManifestVariables(root);
   warnManifest(root);
   const portRanges = assertManifestPorts(root);
   if (portRanges.length > 0 && process.env.MUSCAT_PK_PORTS_PRECHECKED !== "1")

package/cli/src/manifest.mjs

@@ -15,6 +15,9 @@ const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
 const ROS_CLIENTS = ["rclpy", "rclcpp"];
 const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
 const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
+const VARIABLE_TYPES = ["number", "string", "array"];
+const VARIABLE_NAME_PREFIX = "RBP_";
+const VARIABLE_NAME_RE = /^RBP_[A-Za-z0-9_]+$/;
 
 function validateI18nLabel(value, field, errors) {
   if (value === undefined || value === null) {
@@ -110,6 +113,44 @@ function validateCommandInfo(info, prefix, errors) {
     errors.push(`${prefix}.commandInfo.childrenCommand must be a string`);
 }
 
+// variables: pyfm에 노출할 변수 선언. 없으면 UI가 사용 가능한 변수를 보여줄 수 없다.
+function validateVariables(variables, errors) {
+  if (variables === undefined || variables === null) return;
+  if (!Array.isArray(variables)) {
+    errors.push(`"variables" must be an array`);
+    return;
+  }
+  const names = variables.map((v) => v?.name).filter(Boolean);
+  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
+  if (duplicates.length > 0)
+    errors.push(`variables: "name" must be unique (duplicates: ${[...new Set(duplicates)].map((n) => `"${n}"`).join(", ")})`);
+
+  variables.forEach((v, i) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+      errors.push(`variables[${i}] must be an object ({ name, type, init, description? })`);
+      return;
+    }
+    if (typeof v.name !== "string" || v.name.length === 0)
+      errors.push(`variables[${i}].name is required`);
+    else if (!v.name.startsWith(VARIABLE_NAME_PREFIX))
+      errors.push(`variables[${i}].name: "${v.name}" must start with "${VARIABLE_NAME_PREFIX}" (e.g. "${VARIABLE_NAME_PREFIX}${v.name}")`);
+    else if (!VARIABLE_NAME_RE.test(v.name))
+      errors.push(`variables[${i}].name: "${v.name}" is not a valid identifier (after "${VARIABLE_NAME_PREFIX}": letters, digits, underscore only, at least one character)`);
+    if (!VARIABLE_TYPES.includes(v.type))
+      errors.push(`variables[${i}].type must be one of ${VARIABLE_TYPES.map((t) => `"${t}"`).join(" | ")}`);
+    if (v.init === undefined)
+      errors.push(`variables[${i}].init is required (initial value)`);
+    else if (v.type === "number" && typeof v.init !== "number")
+      errors.push(`variables[${i}].init must be a number when type is "number"`);
+    else if (v.type === "string" && typeof v.init !== "string")
+      errors.push(`variables[${i}].init must be a string when type is "string"`);
+    else if (v.type === "array" && !Array.isArray(v.init))
+      errors.push(`variables[${i}].init must be an array when type is "array"`);
+    if (v.description !== undefined && v.description !== null)
+      validateI18nLabel(v.description, `variables[${i}].description`, errors);
+  });
+}
+
 function validateContributes(contributes, errors) {
   if (!Array.isArray(contributes) || contributes.length === 0) {
     errors.push("contributes is required and must be a non-empty array");
@@ -183,6 +224,7 @@ export function validateManifest(manifest) {
   validatePorts(manifest.ports, errors);
   validateRuntime(manifest.runtime, errors);
   validateContributes(manifest.contributes, errors);
+  validateVariables(manifest.variables, errors);
 
   return errors;
 }
@@ -202,6 +244,18 @@ export function assertManifest(root) {
   return manifest;
 }
 
+export function assertManifestVariables(root) {
+  const manifest = readManifest(root);
+  if (manifest === null)
+    throw new Error("manifest.json parse failed — check JSON syntax");
+  if (Object.keys(manifest).length === 0)
+    return;
+  const errors = [];
+  validateVariables(manifest.variables, errors);
+  if (errors.length > 0)
+    throw new Error(`manifest.json variable errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+}
+
 export function assertManifestPorts(root) {
   const manifest = readManifest(root);
   if (manifest === null)

package/cli/src/mcp.mjs

@@ -22,8 +22,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import ts from "typescript";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
@@ -111,10 +112,28 @@ function findStorySource(name) {
 /* -------------------------------------------------------------------------- */
 
 // Split the README on headings and keyword-score each section.
+// Headings inside fenced code blocks (```…```) don't count — a column-0
+// Python comment would otherwise start a bogus section.
+function splitSections(text) {
+  const sections = [];
+  let current = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    if (!inFence && /^#{1,4} /.test(line) && current.length) {
+      sections.push(current.join("\n"));
+      current = [];
+    }
+    current.push(line);
+  }
+  if (current.length) sections.push(current.join("\n"));
+  return sections;
+}
+
 function searchReadme(query) {
   if (!existsSync(TEMPLATE_README)) return [];
   const text = readFileSync(TEMPLATE_README, "utf8");
-  const sections = text.split(/\n(?=#{1,4} )/);
+  const sections = splitSections(text);
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
 
   return sections
@@ -243,6 +262,39 @@ ${script}
   return { data };
 }
 
+/* -------------------------------------------------------------------------- */
+/* client registration — `muscat-pk mcp --install <client>`                    */
+/* -------------------------------------------------------------------------- */
+
+// Claude Code needs no install step: `muscat-pk new` scaffolds a project-level
+// .mcp.json. Codex only reads the global ~/.codex/config.toml, so we append
+// the server block there (idempotent).
+export function installMcp(target) {
+  if (target !== "codex") {
+    throw new Error(
+      `Unknown --install target ${JSON.stringify(target ?? "")} — supported: "codex". ` +
+        "(Claude Code works out of the box via the scaffolded .mcp.json.)",
+    );
+  }
+  const cfgDir = join(homedir(), ".codex");
+  const cfgPath = join(cfgDir, "config.toml");
+  const existing = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : "";
+  if (/^\s*\[mcp_servers\.muscat\]/m.test(existing)) {
+    console.log(`Codex already has the muscat MCP server registered (${cfgPath}) — nothing to do.`);
+    return;
+  }
+  // ponytail: Windows Codex spawns without a shell, so it needs the .cmd shim.
+  const command = process.platform === "win32" ? "muscat-pk.cmd" : "muscat-pk";
+  mkdirSync(cfgDir, { recursive: true });
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  appendFileSync(
+    cfgPath,
+    `${sep}[mcp_servers.muscat]\ncommand = "${command}"\nargs = ["mcp"]\n`,
+  );
+  console.log(`Registered the muscat MCP server for Codex → ${cfgPath}`);
+  console.log("Restart Codex (or start a new session) to pick it up.");
+}
+
 /* -------------------------------------------------------------------------- */
 /* server                                                                      */
 /* -------------------------------------------------------------------------- */
@@ -348,7 +400,10 @@ export async function runMcp() {
       description:
         "Search the Muscat plugin-author README for how to use useRb(), rb.pub/sub/action/serve, " +
         "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
-        "host), manifest.json, contribution points, and backend runtimes (Python/C++/ROS2). IMPORTANT: " +
+        "host), manifest.json (including the \"variables\" declaration for the pyfm variable picker — " +
+        "names require the RBP_ prefix), program variables & executor state (ctx.get_variable/" +
+        "set_variable/executor_state/check_stop), contribution points, and backend runtimes " +
+        "(Python/C++/ROS2). IMPORTANT: " +
         "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
         "writing py/main.py. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
         "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",

package/cli/src/new.mjs

@@ -65,6 +65,9 @@ function printNewSuccess({ targetName, type, pm }) {
   log.info(`  ${color.cyan("muscat-pk dev")}      ${color.dim("# preview in mini-Muscat + back end")}`);
   log.info(`  ${color.cyan("muscat-pk build")}    ${color.dim("# build + distributable ZIP")}`);
   log.info("");
+  log.info(color.dim("AI assistant? Claude Code reads the scaffolded .mcp.json;"));
+  log.info(color.dim(`Codex users run ${color.cyan("muscat-pk mcp --install codex")} once.`));
+  log.info("");
 }
 
 // Build the manifest runtime object for a given type choice + plugin slug.

package/cli/src/ports.mjs

@@ -28,9 +28,9 @@ function reservedPortReason(port) {
   return `${range.name} (${range.from}-${range.to})`;
 }
 
-function isPluginManagedPort(port) {
-  return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
-}
+// function isPluginManagedPort(port) {
+//   return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
+// }
 
 function isInt(value) {
   return Number.isInteger(value);