@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/mcp.mjs

@@ -1,1071 +1,1071 @@
-// muscat-pk mcp — an MCP (Model Context Protocol) server exposing the Muscat
-// plugin UI/SDK surface to an AI coding agent (Claude Code, Codex, ...) so it
-// looks things up instead of guessing. Tools:
-//
-//   Frontend UI (@rainbow-robotics/plugin-ui/react, via dist/react.d.ts):
-//   - list_components        every exported component/hook/type.
-//   - get_component_props    the real TypeScript type for one export.
-//   - get_component_example  a real Storybook story (working code, not a guess).
-//
-//   Design system (rb-styles rb-token.css):
-//   - list_design_tokens     Tailwind classes to use (bg-bg-*, text-fg-*, typo-*, ...).
-//   - search_design_tokens   find a token by name or hex value.
-//
-//   Plugin SDK docs + Python backend:
-//   - search_rb_sdk          search the plugin-author README (useRb(), rb.*, manifest, runtimes).
-//   - list_rb_sdk            classes/functions of the installed rainbow.rb_sdk
-//                            (lang: "python" | "cpp" — cpp reads the headers of the
-//                            rainbow-rb-sdk-dev apt package out of the cpp dev image).
-//   - get_rb_sdk_api         signature + docstring for an rb_sdk class/function.
-//
-// Add to an MCP client config, e.g. Claude Code's .mcp.json:
-//   { "mcpServers": { "muscat": { "command": "muscat-pk", "args": ["mcp"] } } }
-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 {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  statSync,
-  writeFileSync,
-} 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";
-import { PYTHON_DEV_IMAGE } from "./python.mjs";
-import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
-import { CPP_DEV_IMAGE } from "./cpp.mjs";
-import { NATIVE_TO_RB, SERVER_INSTRUCTIONS } from "./ai-rules.mjs";
-
-const TEMPLATE_READMES = { python: "common/README.md", cpp: "readme-cpp/README.md" };
-// Design tokens: prefer the shipped copy, fall back to the monorepo source.
-const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
-  ? SHIPPED_DESIGN_TOKENS
-  : resolve(kitRoot, "../..", "packages/rb-styles/css/output/rb-token.css");
-
-/* -------------------------------------------------------------------------- */
-/* react.d.ts introspection — component/hook list + prop types                */
-/* -------------------------------------------------------------------------- */
-
-// plugin-ui/react's dist/react.d.ts. It's self-contained (rb-components types
-// are inlined at build — see plugin-ui/build-dist.mjs), so this one file is
-// enough even in an external install.
-async function reactDtsPath() {
-  const entryUrl = await import.meta.resolve("@rainbow-robotics/plugin-ui/react");
-  const dtsPath = fileURLToPath(entryUrl).replace(/\.js$/, ".d.ts");
-  if (!existsSync(dtsPath)) {
-    throw new Error(
-      `plugin-ui type declarations not found at ${dtsPath} — reinstall or rebuild @rainbow-robotics/plugin-ui.`,
-    );
-  }
-  return dtsPath;
-}
-
-function loadReactTypes(dtsPath) {
-  // Without moduleResolution the `import ... from "react"` inside react.d.ts
-  // never resolves and every React-derived type collapses to `any`.
-  const program = ts.createProgram([dtsPath], {
-    target: ts.ScriptTarget.ES2022,
-    module: ts.ModuleKind.ESNext,
-    moduleResolution: ts.ModuleResolutionKind.Bundler,
-    skipLibCheck: true,
-  });
-  const sourceFile = program.getSourceFile(dtsPath);
-  const checker = program.getTypeChecker();
-  const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
-  const exports = moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : [];
-  return { checker, sourceFile, exports };
-}
-
-// The barrel's trailing `export { A, B, ... }` produces Alias symbols whose
-// OWN flags don't reflect value-vs-type — resolve to the real declaration first.
-function resolveExport(checker, symbol) {
-  return symbol.flags & ts.SymbolFlags.Alias
-    ? checker.getAliasedSymbol(symbol)
-    : symbol;
-}
-
-function exportKind(checker, symbol) {
-  const resolved = resolveExport(checker, symbol);
-  return resolved.flags & ts.SymbolFlags.Value ? "value" : "type";
-}
-
-// typeToString alone often prints an opaque alias (`ForwardRefExoticComponent<PropsType$s>`).
-// The first call signature works for plain components and forwardRef alike; its
-// first parameter is the props object.
-function ownProps(checker, type, sourceFile) {
-  const [signature] = type.getCallSignatures?.() ?? [];
-  const param = signature?.getParameters?.()[0];
-  if (!param) return [];
-  const declaration = param.valueDeclaration ?? param.declarations?.[0];
-  if (!declaration) return [];
-  const propsType = checker.getTypeOfSymbolAtLocation(param, declaration);
-
-  return checker
-    .getPropertiesOfType(propsType)
-    // Without this, ~220 inherited React DOM attributes bury the component's own API.
-    // Own = declared in react.d.ts itself (rb-components types are inlined there). Not a
-    // "node_modules" path test: in a plugin project react.d.ts itself lives in node_modules.
-    .filter((prop) => (prop.declarations ?? []).some((d) => d.getSourceFile() === sourceFile))
-    .map((prop) => {
-      const d = prop.valueDeclaration ?? prop.declarations[0];
-      const optional = prop.flags & ts.SymbolFlags.Optional ? "?" : "";
-      return `${prop.getName()}${optional}: ${checker.typeToString(
-        checker.getTypeOfSymbolAtLocation(prop, d),
-      )}`;
-    });
-}
-
-// Kept out of the tool handler so every export can be precomputed and cached.
-function propsText(checker, sourceFile, name, symbol) {
-  const resolved = resolveExport(checker, symbol);
-  const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0] ?? sourceFile;
-  const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
-  const signature = checker.typeToString(
-    type,
-    undefined,
-    ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.MultilineObjectLiterals,
-  );
-
-  const props = ownProps(checker, type, sourceFile);
-  if (props.length) {
-    // Keep the signature line: RBSlider's value/min/max come from Radix and the
-    // own-props filter drops them.
-    return `# ${name} — own props\n${props.sort().join("\n")}\n\nfull type: ${signature}`;
-  }
-  // No own props means either a Radix wrapper or unresolved React types. The two
-  // look identical, so name the second case explicitly.
-  if (/<any>/.test(signature)) {
-    return (
-      `# ${name} — prop types could not be resolved\n${signature}\n\n` +
-      "React's types didn't resolve, so this collapsed to `any`. Install `@types/react` " +
-      "in this project (`npm i -D @types/react`) and retry for the real props."
-    );
-  }
-  return (
-    `# ${name} — full type (no plugin-ui-specific props; it forwards a third-party ` +
-    `component's props)\n${signature}`
-  );
-}
-
-// Rendering every export up front is what makes the result cacheable: once the
-// text exists no TypeChecker is needed.
-function buildUiIndex(dtsPath) {
-  const { checker, sourceFile, exports } = loadReactTypes(dtsPath);
-  const props = {};
-  for (const symbol of exports) {
-    props[symbol.getName()] = propsText(checker, sourceFile, symbol.getName(), symbol);
-  }
-  return {
-    components: exports
-      .map((sym) => `${sym.getName()} (${exportKind(checker, sym)})`)
-      .sort()
-      .join("\n"),
-    props,
-  };
-}
-
-// ts.createProgram pulls in ~1100 source files (~1.5s) and an MCP server is a fresh
-// process per session. The key covers the .d.ts identity and the kit version.
-const UI_INDEX_CACHE_DIR = join(homedir(), ".cache", "muscat-pk");
-const UI_INDEX_CACHE = join(UI_INDEX_CACHE_DIR, "ui-index.json");
-const UI_INDEX_FORMAT = 2;
-
-let uiIndexCache = null;
-
-async function loadUiIndex() {
-  if (uiIndexCache) return uiIndexCache;
-  const dtsPath = await reactDtsPath();
-  const { mtimeMs, size } = statSync(dtsPath);
-  // Bump UI_INDEX_FORMAT when the rendered text changes, so dev builds (same version) rebuild too.
-  const key = `${UI_INDEX_FORMAT}|${dtsPath}|${mtimeMs}|${size}|${kitVersion()}`;
-
-  try {
-    const cached = JSON.parse(readFileSync(UI_INDEX_CACHE, "utf8"));
-    // A half-written file still parses as JSON, so check the shape too.
-    if (
-      cached.key === key &&
-      typeof cached.components === "string" &&
-      cached.props &&
-      typeof cached.props === "object"
-    ) {
-      return (uiIndexCache = cached);
-    }
-  } catch {
-    /* absent, unreadable or corrupt — rebuild below */
-  }
-
-  uiIndexCache = { key, ...buildUiIndex(dtsPath) };
-  try {
-    mkdirSync(UI_INDEX_CACHE_DIR, { recursive: true });
-    // rename is atomic, so a concurrent server never reads a half-written file.
-    const tmp = `${UI_INDEX_CACHE}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(uiIndexCache));
-    renameSync(tmp, UI_INDEX_CACHE);
-  } catch {
-    /* read-only fs / sandbox: the cache is an optimisation, never a requirement */
-  }
-  return uiIndexCache;
-}
-
-/* -------------------------------------------------------------------------- */
-/* Storybook story source lookup                                              */
-/* -------------------------------------------------------------------------- */
-
-// Case-insensitive recursive search for `${name}.stories.tsx` under the
-// staged story sources (see storybook.mjs's buildStorybook()).
-function findStorySource(name) {
-  if (!existsSync(SHIPPED_STORIES_SRC)) return null;
-  const target = `${name.toLowerCase()}.stories.tsx`;
-  const stack = [SHIPPED_STORIES_SRC];
-  while (stack.length) {
-    const dir = stack.pop();
-    for (const entry of readdirSync(dir)) {
-      const full = join(dir, entry);
-      if (statSync(full).isDirectory()) {
-        stack.push(full);
-        continue;
-      }
-      if (entry.toLowerCase() === target) return readFileSync(full, "utf8");
-    }
-  }
-  return null;
-}
-
-// Stories are written against the monorepo (@repo/rb-components…). Point those imports at the
-// package a plugin actually has, and flag names plugin-ui does not re-export.
-function rewriteStoryImports(source, exportNames) {
-  const exported = new Set(exportNames);
-  const missing = new Set();
-  const text = source.replace(
-    /import\s+(type\s+)?\{([^}]*)\}\s*from\s*["']@repo\/rb-components[^"']*["'];?/g,
-    (_, typeOnly = "", names) => {
-      const list = names.split(",").map((n) => n.trim()).filter(Boolean);
-      for (const n of list) if (!exported.has(n.replace(/^type\s+/, "").split(/\s+as\s+/)[0])) missing.add(n);
-      return `import ${typeOnly}{ ${list.join(", ")} } from "@rainbow-robotics/plugin-ui/react";`;
-    },
-  );
-  const notes = [
-    "// Storybook story source. In a plugin, import components from \"@rainbow-robotics/plugin-ui/react\"",
-    "// (rewritten below); @storybook/* imports, Meta/StoryObj and play() are Storybook-only.",
-    ...(missing.size ? [`// Not exported by plugin-ui, do not use in a plugin: ${[...missing].join(", ")}`] : []),
-  ];
-  return `${notes.join("\n")}\n\n${text}`;
-}
-
-const editDistance = (a, b) => {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    let prev = row[0]++;
-    for (let j = 1; j <= b.length; j++) {
-      const cur = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
-      prev = cur;
-    }
-  }
-  return row[b.length];
-};
-
-// "RBSelect" → RBSelectBox, RBSelectOption, …; "select" (a native element) → its plugin-ui replacement.
-function suggestExports(name, exportNames) {
-  const q = name.toLowerCase().replace(/[<>]/g, "");
-  const native = NATIVE_TO_RB.filter(([el]) => el.split(/[\s/=]+/).includes(q)).map(([, rb]) => rb);
-  const bare = q.replace(/^rb/, "");
-  const close = exportNames
-    .map((n) => {
-      const lower = n.toLowerCase();
-      const score = lower.includes(q) || (bare.length > 2 && lower.includes(bare)) ? 0 : editDistance(q, lower);
-      return { n, score };
-    })
-    .filter((x) => x.score <= 3)
-    .sort((a, b) => a.score - b.score || a.n.length - b.n.length)
-    .slice(0, 6)
-    .map((x) => x.n);
-  return [...native, ...close];
-}
-
-function unknownExportText(name, exportNames, what) {
-  const hints = suggestExports(name, exportNames);
-  return (
-    `No ${what} named "${name}" in @rainbow-robotics/plugin-ui/react.` +
-    (hints.length ? ` Did you mean: ${hints.join(", ")}?` : "") +
-    " Call list_components for valid names. Do not fall back to a native HTML element."
-  );
-}
-
-/* -------------------------------------------------------------------------- */
-/* README search                                                              */
-/* -------------------------------------------------------------------------- */
-
-// 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;
-}
-
-// Standalone binaries have no templates/ on disk.
-async function readTemplateReadme(rel) {
-  const onDisk = join(kitRoot, "cli/templates", rel);
-  if (existsSync(onDisk)) return readFileSync(onDisk, "utf8");
-  try {
-    const { TEMPLATES } = await import("./templates-embedded.mjs");
-    return TEMPLATES[rel] ? Buffer.from(TEMPLATES[rel], "base64").toString("utf8") : "";
-  } catch {
-    return "";
-  }
-}
-
-async function searchReadme(query, lang) {
-  const langs = lang ? [lang] : ["python", "cpp"];
-  const seen = new Set();
-  const sections = [];
-  for (const l of langs) {
-    for (const section of splitSections(await readTemplateReadme(TEMPLATE_READMES[l]))) {
-      if (seen.has(section)) continue; // UI/manifest sections are shared by both READMEs
-      seen.add(section);
-      sections.push(langs.length > 1 && l === "cpp" ? `[C++ backend]\n${section}` : section);
-    }
-  }
-  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-
-  return sections
-    .map((section) => {
-      const lower = section.toLowerCase();
-      const score = terms.reduce((n, term) => n + (lower.includes(term) ? 1 : 0), 0);
-      return { section: section.trim(), score };
-    })
-    .filter((x) => x.score > 0)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, 5)
-    .map((x) => x.section);
-}
-
-/* -------------------------------------------------------------------------- */
-/* Design tokens — parsed from rb-styles' generated rb-token.css              */
-/* -------------------------------------------------------------------------- */
-
-// A color var `--color-<name>` becomes Tailwind utilities `bg-<name>`,
-// `text-<name>`, `border-<name>`, `fill-<name>`. The design system's naming
-// already encodes intent (bg-/fg-/border-/fill-), so we surface the idiomatic
-// class per group.
-const COLOR_CLASS_HINT = {
-  bg: (n) => `bg-${n}`, // --color-bg-default → bg-bg-default
-  fg: (n) => `text-${n}`, // --color-fg-subtle → text-fg-subtle
-  border: (n) => `border-${n}`,
-  fill: (n) => `fill-${n}`,
-};
-
-let tokensCache = null;
-
-function loadDesignTokens() {
-  if (tokensCache) return tokensCache;
-  if (!existsSync(DESIGN_TOKENS_CSS)) {
-    throw new Error(
-      `design token CSS not found at ${DESIGN_TOKENS_CSS} — rebuild via "muscat-pk storybook --rebuild" (monorepo) or reinstall.`,
-    );
-  }
-  const css = readFileSync(DESIGN_TOKENS_CSS, "utf8");
-
-  // @theme { --name: value; ... }  → { group, name, value, class? }
-  const vars = [];
-  for (const [, rawName, value] of css.matchAll(
-    /^\s*(--[a-z0-9-]+)\s*:\s*([^;]+);/gim,
-  )) {
-    const name = rawName.replace(/^--/, "");
-    const m = name.match(/^color-(bg|fg|border|fill)-(.+)$/);
-    const token = { name, value: value.trim() };
-    if (m) {
-      token.group = `color-${m[1]}`;
-      token.class = COLOR_CLASS_HINT[m[1]](`${m[1]}-${m[2]}`);
-    } else {
-      token.group = name.split("-").slice(0, 2).join("-");
-    }
-    vars.push(token);
-  }
-
-  // @utility typo-… → composite typography classes used directly in className.
-  const typo = [
-    ...new Set(
-      [...css.matchAll(/@utility\s+(typo-[a-z0-9-]+)\s*\{/g)].map((m) => m[1]),
-    ),
-  ].sort();
-
-  tokensCache = { vars, typo };
-  return tokensCache;
-}
-
-/* -------------------------------------------------------------------------- */
-/* rainbow-rb-sdk (Python) introspection                                      */
-/* -------------------------------------------------------------------------- */
-
-function pythonCmd() {
-  // Prefer the current plugin's own .venv — that's where `muscat-pk new` /
-  // ensureIdeVenv() installs rainbow-rb-sdk from requirements.txt. The AI
-  // agent's cwd is usually the plugin dir mcp was launched from.
-  try {
-    const py = venvPython(resolve(findPluginRoot(), ".venv"));
-    if (existsSync(py)) return py;
-  } catch {
-    /* not inside a plugin project — fall through to PATH lookup */
-  }
-  for (const c of ["python3", "python"]) {
-    const r = spawnSync(c, ["--version"], { encoding: "utf8" });
-    if (r.status === 0) return c;
-  }
-  return null;
-}
-
-// Run an introspection script against the installed rainbow.rb_sdk (a plugin's
-// backend dependency). Returns a clear hint if it isn't importable.
-function introspectRbSdk(script) {
-  const py = pythonCmd();
-  const probe = `
-import json, importlib
-try:
-    importlib.import_module("rainbow.rb_sdk")
-except Exception as e:
-    print(json.dumps({"__notinstalled__": str(e)})); raise SystemExit(0)
-${script}
-`;
-  if (!py) {
-    return introspectInDocker(probe) ?? { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
-  }
-  const r = spawnSync(py, ["-c", probe], { encoding: "utf8", maxBuffer: 8 << 20 });
-  if (r.status !== 0) {
-    return { error: `python introspection failed: ${(r.stderr || "").trim().slice(0, 500)}` };
-  }
-  const local = parseProbe(r);
-  return local.error && local.notInstalled ? introspectInDocker(probe) ?? local : local;
-}
-
-// No macOS wheels: import the plugin's pinned SDK inside the python dev image (cached).
-function introspectInDocker(probe) {
-  if (spawnSync("docker", ["image", "inspect", PYTHON_DEV_IMAGE], { encoding: "utf8" }).status !== 0) return null;
-  let ver = "";
-  try {
-    const req = readFileSync(join(findPluginRoot(), "requirements.txt"), "utf8");
-    ver = req.match(/^rainbow-rb-sdk==(\S+)/m)?.[1] ?? "";
-  } catch {
-    /* not a python plugin — latest */
-  }
-  // ponytail: "latest" cache is never refreshed; delete ~/.cache/... rb-sdk-py/latest to update.
-  const cache = join(UI_INDEX_CACHE_DIR, "rb-sdk-py", ver || "latest");
-  mkdirSync(cache, { recursive: true });
-  const pkg = ver ? `rainbow-rb-sdk==${ver}` : "rainbow-rb-sdk";
-  const script =
-    `[ -f /c/.ok ] || { pip3 install -q --break-system-packages --target /c '${pkg}' >&2 && touch /c/.ok; } && ` +
-    `PYTHONPATH=/c python3 -c "$PROBE"`;
-  const r = spawnSync("docker", ["run", "--rm", "-v", `${cache}:/c`, "-e", "PROBE", PYTHON_DEV_IMAGE, "bash", "-c", script], {
-    encoding: "utf8",
-    maxBuffer: 8 << 20,
-    env: { ...process.env, PROBE: probe },
-  });
-  if (r.status !== 0) return { error: `python introspection (docker) failed: ${(r.stderr || "").trim().slice(-500)}` };
-  return parseProbe(r);
-}
-
-function parseProbe(r) {
-  // Importing rainbow.rb_sdk has side effects that print to stdout (e.g. the
-  // Zenoh client logs its connection endpoints), ahead of our own final
-  // print(json.dumps(...)) — so parse the last line, not the whole output.
-  const lines = r.stdout.trim().split("\n");
-  let data;
-  try {
-    data = JSON.parse(lines[lines.length - 1]);
-  } catch {
-    return { error: `unexpected introspection output: ${r.stdout.slice(0, 300)}` };
-  }
-  if (data && data.__notinstalled__) {
-    return {
-      notInstalled: true,
-      error:
-        "rainbow-rb-sdk is not installed in this environment. Install it with `pip install rainbow-rb-sdk` " +
-        "(it's already in a plugin's requirements.txt), then retry.",
-    };
-  }
-  return { data };
-}
-
-/* -------------------------------------------------------------------------- */
-/* rainbow-rb-sdk-dev (C++) headers — copied out of the cpp dev image           */
-/* -------------------------------------------------------------------------- */
-
-const CPP_INCLUDE_CACHE = join(UI_INDEX_CACHE_DIR, "rb-sdk-include");
-// Headers we don't want to surface: third-party vendored code, pybind glue,
-// flatbuffers-generated schemas, and the industrial comm stacks.
-const CPP_SKIP = /^(vendor|binding|rb_comm_source)\/|_generated\.h$/;
-
-// The apt package is only installed inside the muscat-pk-cpp-dev image, so
-// copy /usr/include/rainbow/rb_sdk out once per image build (cache key =
-// image id) with `docker cp` — no host tar needed.
-function cppIncludeDir() {
-  const insp = spawnSync("docker", ["image", "inspect", "-f", "{{.Id}}", CPP_DEV_IMAGE], { encoding: "utf8" });
-  if (insp.error) return { error: "Docker not found — the C++ SDK headers live in the muscat-pk cpp dev image." };
-  if (insp.status !== 0) {
-    return {
-      error:
-        `Docker image ${CPP_DEV_IMAGE} not built yet. Run \`muscat-pk dev:back\` (or \`muscat-pk build\`) once ` +
-        "in a cpp / rclcpp plugin to build it, then retry.",
-    };
-  }
-  const dir = join(CPP_INCLUDE_CACHE, insp.stdout.trim().replace(/^sha256:/, "").slice(0, 12));
-  const out = join(dir, "rb_sdk");
-  if (existsSync(out)) return { dir: out };
-  mkdirSync(dir, { recursive: true });
-  const ctr = spawnSync("docker", ["create", CPP_DEV_IMAGE], { encoding: "utf8" });
-  if (ctr.status !== 0) return { error: `docker create failed: ${(ctr.stderr || "").trim().slice(0, 300)}` };
-  const id = ctr.stdout.trim();
-  const cp = spawnSync("docker", ["cp", `${id}:/usr/include/rainbow/rb_sdk`, dir], { encoding: "utf8" });
-  spawnSync("docker", ["rm", "-f", id], { encoding: "utf8" });
-  if (cp.status !== 0 || !existsSync(out)) {
-    return { error: `docker cp failed: ${(cp.stderr || "").trim().slice(0, 300)}` };
-  }
-  return { dir: out };
-}
-
-function cppHeaders(root) {
-  const files = [];
-  const walk = (d, rel) => {
-    for (const name of readdirSync(d)) {
-      const r = rel ? `${rel}/${name}` : name;
-      if (CPP_SKIP.test(r)) continue;
-      const full = join(d, name);
-      if (statSync(full).isDirectory()) walk(full, r);
-      else if (/\.hpp$/.test(name)) files.push(r);
-    }
-  };
-  walk(root, "");
-  return files.sort();
-}
-
-// "class Foo {" / "class Foo : public Bar {" — not forward declarations.
-const CLASS_RE = /^\s*(?:class|struct)\s+(?:[A-Z][A-Z0-9_]*_API\s+)?(\w+)\b(?![^\n]*;\s*$)/; // skip export macros (RB_SDK_API)
-
-function cppClassesIn(text) {
-  return [...new Set(text.split("\n").map((l) => l.match(CLASS_RE)?.[1]).filter(Boolean))];
-}
-
-// Return the class body (brace-matched) plus the file's leading comment block,
-// which in these headers usually carries a full usage example.
-function cppExtract(text, className, method) {
-  const lines = text.split("\n");
-  const start = lines.findIndex((l) => CLASS_RE.test(l) && l.match(CLASS_RE)[1] === className);
-  if (start < 0) return null;
-  let depth = 0, end = start, seen = false;
-  for (let i = start; i < lines.length; i++) {
-    for (const ch of lines[i]) {
-      if (ch === "{") { depth++; seen = true; }
-      else if (ch === "}") depth--;
-    }
-    if (seen && depth === 0) { end = i; break; }
-  }
-  const body = lines.slice(start, end + 1);
-  if (method) {
-    // Declarations sit at class-member indent (<= 2 spaces) and the name is
-    // not preceded by `.`/`->`/`::` — that skips call sites inside bodies.
-    const re = new RegExp(`^ {0,2}[^(]*(?<![\\w.>:])${method.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\(`);
-    const hits = [];
-    for (let i = 0; i < body.length; i++) {
-      if (!re.test(body[i]) || /^\s*\/\//.test(body[i])) continue;
-      let a = i;
-      while (a > 0 && /^\s*\/\//.test(body[a - 1])) a--;
-      let b = i;
-      while (b < body.length - 1 && !/[{;]/.test(body[b])) b++;
-      hits.push(body.slice(a, b + 1).join("\n"));
-    }
-    return hits.length ? hits.join("\n\n") : null;
-  }
-  const head = [];
-  for (const l of lines) {
-    if (/^\s*\/\//.test(l)) head.push(l);
-    else if (l.trim() === "" || /^#pragma/.test(l)) continue;
-    else break;
-  }
-  return (head.length > 3 ? head.join("\n") + "\n\n" : "") + body.join("\n");
-}
-
-function cppFind(className) {
-  const { dir, error } = cppIncludeDir();
-  if (error) return { error };
-  for (const rel of cppHeaders(dir)) {
-    const text = readFileSync(join(dir, rel), "utf8");
-    if (cppClassesIn(text).includes(className)) return { rel, text };
-  }
-  return { error: `No class "${className}" in the C++ SDK headers. Call list_rb_sdk with lang "cpp" for valid names.` };
-}
-
-/* -------------------------------------------------------------------------- */
-/* 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                                                                      */
-/* -------------------------------------------------------------------------- */
-
-export async function runMcp() {
-  const server = new McpServer(
-    { name: "muscat-plugin-kit", version: kitVersion() },
-    { instructions: SERVER_INSTRUCTIONS },
-  );
-
-  server.registerTool(
-    "list_components",
-    {
-      title: "List Muscat plugin UI components",
-      description:
-        "List every component, hook, and type exported from @rainbow-robotics/plugin-ui/react — " +
-        "the full UI surface available to Muscat plugin authors. Call this first before guessing a " +
-        "component name; plugin UI uses these instead of native <select>/<input>/<button> elements.",
-      inputSchema: {},
-    },
-    async () => {
-      const { components } = await loadUiIndex();
-      return { content: [{ type: "text", text: components }] };
-    },
-  );
-
-  server.registerTool(
-    "get_component_props",
-    {
-      title: "Get a component or hook's real type signature",
-      description:
-        "Get the full TypeScript type for a named export of @rainbow-robotics/plugin-ui/react " +
-        "(e.g. RBSlider, RBLabelButton, useRb, useRbFormData). Use list_components to find valid names.",
-      inputSchema: { name: z.string().describe('Exported name, e.g. "RBSlider"') },
-    },
-    async ({ name }) => {
-      const { props } = await loadUiIndex();
-      if (!Object.hasOwn(props, name)) {
-        return { isError: true, content: [{ type: "text", text: unknownExportText(name, Object.keys(props), "export") }] };
-      }
-      return { content: [{ type: "text", text: props[name] }] };
-    },
-  );
-
-  server.registerTool(
-    "get_component_example",
-    {
-      title: "Get a real Storybook usage example",
-      description:
-        "Get the real Storybook story source for a component (e.g. RBSlider) — actual working " +
-        "props, imports, and layout, not a guessed shape. Prefer this over get_component_props when " +
-        "you just need to know how to use a component, not its full type.",
-      // `component` accepted as an alias — agents often guess it over `name`.
-      inputSchema: {
-        name: z.string().optional().describe('Component name, e.g. "RBSlider"'),
-        component: z.string().optional().describe("Alias for `name`."),
-      },
-    },
-    async ({ name, component }) => {
-      const target = name ?? component;
-      if (!target) {
-        return {
-          isError: true,
-          content: [{ type: "text", text: 'Missing required argument: "name" (component name, e.g. "RBSlider").' }],
-        };
-      }
-      const exportNames = Object.keys((await loadUiIndex()).props);
-      const source = findStorySource(target);
-      if (!source) {
-        // An existing export without a story still has a type; an unknown name gets suggestions.
-        const text = exportNames.includes(target)
-          ? `No Storybook example for "${target}". Call get_component_props for its type, or run "muscat-pk storybook" to browse components live.`
-          : unknownExportText(target, exportNames, "component");
-        return { content: [{ type: "text", text }] };
-      }
-      return { content: [{ type: "text", text: rewriteStoryImports(source, exportNames) }] };
-    },
-  );
-
-  server.registerTool(
-    "search_rb_sdk",
-    {
-      title: "Search the Muscat plugin-author docs",
-      description:
-        "Search the Muscat plugin-author README for how to use useRb(), rb.pub/sub/action/serve, " +
-        "plugin.router (external endpoints: router.on/subscribe/emit exposed over REST/Socket.IO/TCP/" +
-        "MQTT/WebRTC at common/plugin/{plugin_id}/{path}, PluginRouteError, meta.transport/principal), " +
-        "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
-        "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), video streaming (MediaMTX: backend publishes RTSP to " +
-        "127.0.0.1:8554, UI plays WebRTC from :8889), ROS 2 topics (plugin namespace, rb.rosPeers to allow " +
-        "an external PC), contribution points, and backend runtimes " +
-        "(Python/C++/ROS2). Covers BOTH backends: the Python README (py/main.py, rainbow.rb_sdk) and the " +
-        "C++ README (cpp/main.cpp or an rclcpp node: rb_plugin::RBPluginCall serve/subscribe/publish/" +
-        "router(), rb_plugin::PluginProgramContext, RBManipulateSDK, CMake rb_sdk::rb_sdk). Pass lang " +
-        "\"python\" or \"cpp\" to match the plugin's manifest runtime (cpp or ros2+rclcpp → \"cpp\"); " +
-        "omit it to search both. IMPORTANT: " +
-        "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
-        "writing the backend. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
-        "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",
-      inputSchema: {
-        query: z.string().describe('Keywords, e.g. "save form data" or "rb.action"'),
-        lang: z.enum(["python", "cpp"]).optional().describe("Backend language; omit to search both"),
-      },
-    },
-    async ({ query, lang }) => {
-      const sections = await searchReadme(query, lang);
-      if (sections.length === 0) {
-        return { content: [{ type: "text", text: `No matching section found for "${query}".` }] };
-      }
-      return { content: [{ type: "text", text: sections.join("\n\n---\n\n") }] };
-    },
-  );
-
-  /* --- design tokens --- */
-
-  server.registerTool(
-    "list_design_tokens",
-    {
-      title: "List Muscat design tokens (Tailwind classes)",
-      description:
-        "List the design system's tokens as the Tailwind classes to use in a plugin's className: " +
-        "semantic colors (bg-bg-*, text-fg-*, border-border-*, fill-fill-*), typography (typo-*), " +
-        "shadows, radius, spacing. Use these instead of raw hex/px so the plugin matches the host theme " +
-        "(and light/dark). Optionally filter by category.",
-      inputSchema: {
-        category: z
-          .enum(["bg", "fg", "border", "fill", "typography", "shadow", "radius", "spacing", "all"])
-          .optional()
-          .describe('Filter, e.g. "bg", "fg", "typography". Omit for a grouped overview.'),
-      },
-    },
-    async ({ category }) => {
-      const { vars, typo } = loadDesignTokens();
-      const out = [];
-
-      const colorGroups = { bg: [], fg: [], border: [], fill: [] };
-      const other = { shadow: [], radius: [], spacing: [] };
-      for (const t of vars) {
-        const m = t.group?.match(/^color-(bg|fg|border|fill)$/);
-        // Class name only: the value is just an indirection to another CSS var
-        // (var(--color-scale-zinc-200)), and each class is declared twice (light/dark)
-        // with different values — dropping the value lets the Set dedup collapse them.
-        if (m && t.class) colorGroups[m[1]].push(t.class);
-        else if (t.name.startsWith("shadow-")) other.shadow.push(`shadow-${t.name.slice(7)}`);
-        else if (t.name.startsWith("radius-")) other.radius.push(`rounded-${t.name.slice(7)}`);
-        else if (t.name.startsWith("spacing-")) other.spacing.push(t.name);
-      }
-
-      const want = (c) => !category || category === "all" || category === c;
-      const push = (title, items) => {
-        if (items.length) out.push(`## ${title}\n${[...new Set(items)].sort().join("\n")}`);
-      };
-      if (want("bg")) push("Background — bg-bg-*", colorGroups.bg);
-      if (want("fg")) push("Text/foreground — text-fg-*", colorGroups.fg);
-      if (want("border")) push("Border — border-border-*", colorGroups.border);
-      if (want("fill")) push("SVG fill — fill-fill-*", colorGroups.fill);
-      if (want("typography")) push("Typography — typo-* (use directly)", typo);
-      if (want("shadow")) push("Shadow", other.shadow);
-      if (want("radius")) push("Radius", other.radius);
-      if (want("spacing")) push("Spacing scale (p-/m-/gap-/w-/h-)", other.spacing);
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: out.join("\n\n") || `No tokens for category "${category}".`,
-          },
-        ],
-      };
-    },
-  );
-
-  server.registerTool(
-    "search_design_tokens",
-    {
-      title: "Search design tokens by name or value",
-      description:
-        "Find a design token by keyword — e.g. 'danger' (error colors), 'elevated', 'brand', or a hex " +
-        "like '#fb2c36'. Returns the matching Tailwind class + value.",
-      inputSchema: { query: z.string().describe('e.g. "danger", "elevated", "#fb2c36"') },
-    },
-    async ({ query }) => {
-      const { vars, typo } = loadDesignTokens();
-      const q = query.toLowerCase();
-      const hits = vars
-        .filter((t) => t.name.toLowerCase().includes(q) || t.value.toLowerCase().includes(q))
-        .map((t) => `${t.class ?? t.name}   (${t.value})`);
-      const typoHits = typo.filter((c) => c.toLowerCase().includes(q));
-      const all = [...typoHits, ...hits];
-      return {
-        content: [
-          {
-            type: "text",
-            text: all.length ? [...new Set(all)].slice(0, 60).join("\n") : `No token matches "${query}".`,
-          },
-        ],
-      };
-    },
-  );
-
-  /* --- rainbow-rb-sdk (Python backend) --- */
-
-  server.registerTool(
-    "list_rb_sdk",
-    {
-      title: "List rainbow-rb-sdk classes and functions (Python or C++)",
-      description:
-        "List the public classes and functions of the plugin BACKEND SDK. lang \"python\" (default): the " +
-        "installed rainbow.rb_sdk package (RBPluginCall, RBManipulateSDK, RBAmrSDK, PluginProgramContext, " +
-        "...) — call before writing py/main.py; requires rainbow-rb-sdk to be pip-installed. lang \"cpp\": " +
-        "the C++ SDK headers (apt rainbow-rb-sdk-dev: RBManipulateSDK, rb_plugin::PluginProgramContext, " +
-        "...) grouped by header path — call before writing cpp/main.cpp or an rclcpp node; requires the " +
-        "muscat-pk-cpp-dev Docker image (built by `muscat-pk dev:back`). RBPluginCall (UI pub/sub/serve, " +
-        "router) exists in both: Python rainbow.rb_sdk.RBPluginCall, C++ rb_plugin::RBPluginCall " +
-        "(plugin/rb_plugin.hpp).",
-      inputSchema: { lang: z.enum(["python", "cpp"]).optional().describe('Default "python"') },
-    },
-    async ({ lang }) => {
-      if (lang === "cpp") {
-        const { dir, error } = cppIncludeDir();
-        if (error) return { isError: true, content: [{ type: "text", text: error }] };
-        const out = [];
-        for (const rel of cppHeaders(dir)) {
-          const classes = cppClassesIn(readFileSync(join(dir, rel), "utf8"));
-          if (classes.length) out.push(`${rel}: ${classes.join(", ")}`);
-        }
-        return { content: [{ type: "text", text: `#include <rainbow/rb_sdk/...>\n\n${out.join("\n")}` }] };
-      }
-      const { data, error } = introspectRbSdk(`
-import inspect, json
-mod = importlib.import_module("rainbow.rb_sdk")
-out = []
-for name in sorted(getattr(mod, "__all__", None) or dir(mod)):
-    if name.startswith("_"): continue
-    obj = getattr(mod, name)
-    if inspect.isclass(obj): out.append(name + " (class)")
-    elif inspect.isfunction(obj) or inspect.isbuiltin(obj): out.append(name + " (function)")
-print(json.dumps(out))
-`);
-      if (error) return { isError: true, content: [{ type: "text", text: error }] };
-      return { content: [{ type: "text", text: data.join("\n") }] };
-    },
-  );
-
-  server.registerTool(
-    "get_rb_sdk_api",
-    {
-      title: "Get a rainbow-rb-sdk class/function signature + docs (Python or C++)",
-      description:
-        "Get the signature(s) and docstring for a rainbow.rb_sdk class or function (e.g. " +
-        "'PluginProgramContext', 'RBManipulateSDK'). For a class, lists its public methods with " +
-        "signatures. To drill into ONE method of a class (e.g. RBManipulateSDK.call_move_j), pass " +
-        "`method` alongside `name` — do not put both in `name`. lang \"python\" (default) introspects the " +
-        "pip-installed package. lang \"cpp\" returns the class declaration from the C++ SDK header " +
-        "(rainbow-rb-sdk-dev) with its header comment — usually a full usage example — and the " +
-        "#include path; with `method`, just that method's declaration and comment.",
-      inputSchema: {
-        name: z.string().describe('Class or function name, e.g. "RBManipulateSDK"'),
-        method: z.string().optional().describe('Optional: a specific method on that class, e.g. "call_move_j"'),
-        lang: z.enum(["python", "cpp"]).optional().describe('Default "python"'),
-      },
-    },
-    async ({ name, method, lang }) => {
-      // Tolerate a combined "ClassName method_name" in `name` (a common agent
-      // mistake) by splitting it ourselves instead of failing validation.
-      let className = name;
-      let methodName = method;
-      if (!methodName && /\s/.test(name.trim())) {
-        const parts = name.trim().split(/\s+/);
-        if (parts.length === 2) [className, methodName] = parts;
-      }
-
-      if (lang === "cpp") {
-        const cls = className.replace(/^.*::/, "");
-        let { rel, text, error } = cppFind(cls);
-        if (error) return { isError: true, content: [{ type: "text", text: error }] };
-        let body = cppExtract(text, cls, methodName);
-        let owner = cls;
-        if (!body && methodName) {
-          // Like the Python path: most calls live on sub-SDK members
-          // (RBManipulateMoveSDK move; -> sdk.move.call_move_j) or on the base
-          // class — look there before giving up.
-          const decl = cppExtract(text, cls);
-          const cands = [
-            ...[...decl.matchAll(/^\s*(\w+SDK)\s+(\w+);/gm)].map((m) => [m[1], `${cls}.${m[2]}`]),
-            ...[...decl.matchAll(/:\s*public\s+(\w+)/g)].map((m) => [m[1], `${cls} (base ${m[1]})`]),
-          ];
-          for (const [c, label] of cands) {
-            const f = cppFind(c);
-            if (f.error) continue;
-            const b = cppExtract(f.text, c, methodName);
-            if (b) { ({ rel, text } = f); body = b; owner = label; break; }
-          }
-        }
-        if (!body) {
-          return {
-            isError: true,
-            content: [{ type: "text", text: `No method "${methodName}" declared in class "${cls}" (${rel}) or its sub-SDK members / base class. Call get_rb_sdk_api with just \`name\` to see the class.` }],
-          };
-        }
-        const ns = text.match(/^namespace\s+(\w+)\s*\{/m)?.[1];
-        const header =
-          `// #include <rainbow/rb_sdk/${rel}>${ns ? `   (namespace ${ns})` : ""}\n` +
-          `// link: find_package(rb_sdk) + rb_sdk::rb_sdk\n` +
-          (methodName ? `// ${owner}.${methodName}\n` : "") + "\n";
-        return { content: [{ type: "text", text: header + body.slice(0, 60_000) }] };
-      }
-
-      const { data, error } = introspectRbSdk(`
-import inspect, json
-mod = importlib.import_module("rainbow.rb_sdk")
-name = ${JSON.stringify(className)}
-method = ${methodName ? JSON.stringify(methodName) : "None"}
-obj = getattr(mod, name, None)
-if obj is None:
-    print(json.dumps({"__missing__": True})); raise SystemExit(0)
-def sig(o):
-    try: return str(inspect.signature(o))
-    except Exception: return "(...)"
-
-if method:
-    # Direct method on the class itself.
-    fn = getattr(obj, method, None) if inspect.isclass(obj) else None
-    # rb_sdk classes often group calls under a nested namespace set in
-    # __init__ (e.g. RBManipulateSDK().move.call_move_j) — that only exists on
-    # an INSTANCE, which we won't construct (side effects, needs a robot
-    # connection). Best-effort: search the class's own __init__ source text
-    # for self.<attr> = <NestedClass>(...) and check each nested class too.
-    owner = name
-    if fn is None and inspect.isclass(obj):
-        try:
-            src = inspect.getsource(obj.__init__)
-        except Exception:
-            src = ""
-        import re, sys as _sys
-        # The nested sub-SDK classes (e.g. RBManipulateMoveSDK) are imported in
-        # the module that DEFINES obj (rainbow.rb_sdk.manipulate), not in the
-        # rainbow.rb_sdk top-level namespace — resolve names against both.
-        _defmod = _sys.modules.get(getattr(obj, "__module__", ""))
-        for attr, nested_name in re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", src):
-            nested = (
-                (getattr(_defmod, nested_name, None) if _defmod else None)
-                or mod.__dict__.get(nested_name)
-                or globals().get(nested_name)
-            )
-            cand = getattr(nested, method, None) if nested else None
-            if cand:
-                fn = cand
-                owner = f"{name}.{attr} ({nested_name})"
-                break
-    if fn is None:
-        print(json.dumps({"__missing__": True, "__method__": True})); raise SystemExit(0)
-    print(json.dumps({
-        "name": name, "kind": "method", "owner": owner,
-        "signature": method + sig(fn), "doc": inspect.getdoc(fn) or "",
-    }))
-    raise SystemExit(0)
-
-res = {"name": name, "doc": inspect.getdoc(obj) or ""}
-if inspect.isclass(obj):
-    res["kind"] = "class"
-    res["init"] = name + sig(obj.__init__ if "__init__" in dir(obj) else obj)
-    def _methods_of(cls, prefix=""):
-        out = []
-        for m, fn in inspect.getmembers(cls, predicate=inspect.isfunction):
-            if m.startswith("_"): continue
-            out.append({"name": prefix + m, "sig": prefix + m + sig(fn),
-                        "doc": (inspect.getdoc(fn) or "").split("\\n")[0]})
-        return out
-    methods = _methods_of(obj)
-    # Most rb_sdk calls live on nested sub-SDKs assigned in __init__
-    # (e.g. self.move = RBManipulateMoveSDK() -> obj.move.call_move_j). List
-    # those too, name-prefixed, so the API is discoverable without an instance.
-    import re as _re, sys as _sys
-    _defmod = _sys.modules.get(getattr(obj, "__module__", ""))
-    try:
-        _src = inspect.getsource(obj.__init__)
-    except Exception:
-        _src = ""
-    for _attr, _nested_name in _re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", _src):
-        _nested = (getattr(_defmod, _nested_name, None) if _defmod else None) or mod.__dict__.get(_nested_name)
-        if inspect.isclass(_nested):
-            methods.extend(_methods_of(_nested, prefix=_attr + "."))
-    res["methods"] = methods
-else:
-    res["kind"] = "function"
-    res["signature"] = name + sig(obj)
-print(json.dumps(res))
-`);
-      if (error) return { isError: true, content: [{ type: "text", text: error }] };
-      if (data.__missing__) {
-        const text = data.__method__
-          ? `No method "${methodName}" found directly on "${className}" (nor in an obvious nested ` +
-            `namespace set in __init__). Call get_rb_sdk_api with just \`name: "${className}"\` to see ` +
-            `its full method list and constructor first.`
-          : `No "${className}" in rainbow.rb_sdk. Call list_rb_sdk for valid names.`;
-        return { isError: true, content: [{ type: "text", text }] };
-      }
-      if (data.kind === "method") {
-        const lines = [`# ${data.owner}.${data.signature.split("(")[0]}`, data.signature];
-        if (data.doc) lines.push("", data.doc);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      }
-      const lines = [`# ${data.name} (${data.kind})`];
-      if (data.doc) lines.push(data.doc, "");
-      if (data.kind === "class") {
-        lines.push(`constructor: ${data.init}`, "", "methods:");
-        for (const m of data.methods) {
-          lines.push(`  ${m.sig}${m.doc ? `  — ${m.doc}` : ""}`);
-        }
-      } else {
-        lines.push(data.signature);
-      }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
-    },
-  );
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
+// muscat-pk mcp — an MCP (Model Context Protocol) server exposing the Muscat
+// plugin UI/SDK surface to an AI coding agent (Claude Code, Codex, ...) so it
+// looks things up instead of guessing. Tools:
+//
+//   Frontend UI (@rainbow-robotics/plugin-ui/react, via dist/react.d.ts):
+//   - list_components        every exported component/hook/type.
+//   - get_component_props    the real TypeScript type for one export.
+//   - get_component_example  a real Storybook story (working code, not a guess).
+//
+//   Design system (rb-styles rb-token.css):
+//   - list_design_tokens     Tailwind classes to use (bg-bg-*, text-fg-*, typo-*, ...).
+//   - search_design_tokens   find a token by name or hex value.
+//
+//   Plugin SDK docs + Python backend:
+//   - search_rb_sdk          search the plugin-author README (useRb(), rb.*, manifest, runtimes).
+//   - list_rb_sdk            classes/functions of the installed rainbow.rb_sdk
+//                            (lang: "python" | "cpp" — cpp reads the headers of the
+//                            rainbow-rb-sdk-dev apt package out of the cpp dev image).
+//   - get_rb_sdk_api         signature + docstring for an rb_sdk class/function.
+//
+// Add to an MCP client config, e.g. Claude Code's .mcp.json:
+//   { "mcpServers": { "muscat": { "command": "muscat-pk", "args": ["mcp"] } } }
+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 {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} 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";
+import { PYTHON_DEV_IMAGE } from "./python.mjs";
+import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
+import { CPP_DEV_IMAGE } from "./cpp.mjs";
+import { NATIVE_TO_RB, SERVER_INSTRUCTIONS } from "./ai-rules.mjs";
+
+const TEMPLATE_READMES = { python: "common/README.md", cpp: "readme-cpp/README.md" };
+// Design tokens: prefer the shipped copy, fall back to the monorepo source.
+const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
+  ? SHIPPED_DESIGN_TOKENS
+  : resolve(kitRoot, "../..", "packages/rb-styles/css/output/rb-token.css");
+
+/* -------------------------------------------------------------------------- */
+/* react.d.ts introspection — component/hook list + prop types                */
+/* -------------------------------------------------------------------------- */
+
+// plugin-ui/react's dist/react.d.ts. It's self-contained (rb-components types
+// are inlined at build — see plugin-ui/build-dist.mjs), so this one file is
+// enough even in an external install.
+async function reactDtsPath() {
+  const entryUrl = await import.meta.resolve("@rainbow-robotics/plugin-ui/react");
+  const dtsPath = fileURLToPath(entryUrl).replace(/\.js$/, ".d.ts");
+  if (!existsSync(dtsPath)) {
+    throw new Error(
+      `plugin-ui type declarations not found at ${dtsPath} — reinstall or rebuild @rainbow-robotics/plugin-ui.`,
+    );
+  }
+  return dtsPath;
+}
+
+function loadReactTypes(dtsPath) {
+  // Without moduleResolution the `import ... from "react"` inside react.d.ts
+  // never resolves and every React-derived type collapses to `any`.
+  const program = ts.createProgram([dtsPath], {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    skipLibCheck: true,
+  });
+  const sourceFile = program.getSourceFile(dtsPath);
+  const checker = program.getTypeChecker();
+  const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+  const exports = moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : [];
+  return { checker, sourceFile, exports };
+}
+
+// The barrel's trailing `export { A, B, ... }` produces Alias symbols whose
+// OWN flags don't reflect value-vs-type — resolve to the real declaration first.
+function resolveExport(checker, symbol) {
+  return symbol.flags & ts.SymbolFlags.Alias
+    ? checker.getAliasedSymbol(symbol)
+    : symbol;
+}
+
+function exportKind(checker, symbol) {
+  const resolved = resolveExport(checker, symbol);
+  return resolved.flags & ts.SymbolFlags.Value ? "value" : "type";
+}
+
+// typeToString alone often prints an opaque alias (`ForwardRefExoticComponent<PropsType$s>`).
+// The first call signature works for plain components and forwardRef alike; its
+// first parameter is the props object.
+function ownProps(checker, type, sourceFile) {
+  const [signature] = type.getCallSignatures?.() ?? [];
+  const param = signature?.getParameters?.()[0];
+  if (!param) return [];
+  const declaration = param.valueDeclaration ?? param.declarations?.[0];
+  if (!declaration) return [];
+  const propsType = checker.getTypeOfSymbolAtLocation(param, declaration);
+
+  return checker
+    .getPropertiesOfType(propsType)
+    // Without this, ~220 inherited React DOM attributes bury the component's own API.
+    // Own = declared in react.d.ts itself (rb-components types are inlined there). Not a
+    // "node_modules" path test: in a plugin project react.d.ts itself lives in node_modules.
+    .filter((prop) => (prop.declarations ?? []).some((d) => d.getSourceFile() === sourceFile))
+    .map((prop) => {
+      const d = prop.valueDeclaration ?? prop.declarations[0];
+      const optional = prop.flags & ts.SymbolFlags.Optional ? "?" : "";
+      return `${prop.getName()}${optional}: ${checker.typeToString(
+        checker.getTypeOfSymbolAtLocation(prop, d),
+      )}`;
+    });
+}
+
+// Kept out of the tool handler so every export can be precomputed and cached.
+function propsText(checker, sourceFile, name, symbol) {
+  const resolved = resolveExport(checker, symbol);
+  const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0] ?? sourceFile;
+  const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
+  const signature = checker.typeToString(
+    type,
+    undefined,
+    ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.MultilineObjectLiterals,
+  );
+
+  const props = ownProps(checker, type, sourceFile);
+  if (props.length) {
+    // Keep the signature line: RBSlider's value/min/max come from Radix and the
+    // own-props filter drops them.
+    return `# ${name} — own props\n${props.sort().join("\n")}\n\nfull type: ${signature}`;
+  }
+  // No own props means either a Radix wrapper or unresolved React types. The two
+  // look identical, so name the second case explicitly.
+  if (/<any>/.test(signature)) {
+    return (
+      `# ${name} — prop types could not be resolved\n${signature}\n\n` +
+      "React's types didn't resolve, so this collapsed to `any`. Install `@types/react` " +
+      "in this project (`npm i -D @types/react`) and retry for the real props."
+    );
+  }
+  return (
+    `# ${name} — full type (no plugin-ui-specific props; it forwards a third-party ` +
+    `component's props)\n${signature}`
+  );
+}
+
+// Rendering every export up front is what makes the result cacheable: once the
+// text exists no TypeChecker is needed.
+function buildUiIndex(dtsPath) {
+  const { checker, sourceFile, exports } = loadReactTypes(dtsPath);
+  const props = {};
+  for (const symbol of exports) {
+    props[symbol.getName()] = propsText(checker, sourceFile, symbol.getName(), symbol);
+  }
+  return {
+    components: exports
+      .map((sym) => `${sym.getName()} (${exportKind(checker, sym)})`)
+      .sort()
+      .join("\n"),
+    props,
+  };
+}
+
+// ts.createProgram pulls in ~1100 source files (~1.5s) and an MCP server is a fresh
+// process per session. The key covers the .d.ts identity and the kit version.
+const UI_INDEX_CACHE_DIR = join(homedir(), ".cache", "muscat-pk");
+const UI_INDEX_CACHE = join(UI_INDEX_CACHE_DIR, "ui-index.json");
+const UI_INDEX_FORMAT = 2;
+
+let uiIndexCache = null;
+
+async function loadUiIndex() {
+  if (uiIndexCache) return uiIndexCache;
+  const dtsPath = await reactDtsPath();
+  const { mtimeMs, size } = statSync(dtsPath);
+  // Bump UI_INDEX_FORMAT when the rendered text changes, so dev builds (same version) rebuild too.
+  const key = `${UI_INDEX_FORMAT}|${dtsPath}|${mtimeMs}|${size}|${kitVersion()}`;
+
+  try {
+    const cached = JSON.parse(readFileSync(UI_INDEX_CACHE, "utf8"));
+    // A half-written file still parses as JSON, so check the shape too.
+    if (
+      cached.key === key &&
+      typeof cached.components === "string" &&
+      cached.props &&
+      typeof cached.props === "object"
+    ) {
+      return (uiIndexCache = cached);
+    }
+  } catch {
+    /* absent, unreadable or corrupt — rebuild below */
+  }
+
+  uiIndexCache = { key, ...buildUiIndex(dtsPath) };
+  try {
+    mkdirSync(UI_INDEX_CACHE_DIR, { recursive: true });
+    // rename is atomic, so a concurrent server never reads a half-written file.
+    const tmp = `${UI_INDEX_CACHE}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(uiIndexCache));
+    renameSync(tmp, UI_INDEX_CACHE);
+  } catch {
+    /* read-only fs / sandbox: the cache is an optimisation, never a requirement */
+  }
+  return uiIndexCache;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Storybook story source lookup                                              */
+/* -------------------------------------------------------------------------- */
+
+// Case-insensitive recursive search for `${name}.stories.tsx` under the
+// staged story sources (see storybook.mjs's buildStorybook()).
+function findStorySource(name) {
+  if (!existsSync(SHIPPED_STORIES_SRC)) return null;
+  const target = `${name.toLowerCase()}.stories.tsx`;
+  const stack = [SHIPPED_STORIES_SRC];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (entry.toLowerCase() === target) return readFileSync(full, "utf8");
+    }
+  }
+  return null;
+}
+
+// Stories are written against the monorepo (@repo/rb-components…). Point those imports at the
+// package a plugin actually has, and flag names plugin-ui does not re-export.
+function rewriteStoryImports(source, exportNames) {
+  const exported = new Set(exportNames);
+  const missing = new Set();
+  const text = source.replace(
+    /import\s+(type\s+)?\{([^}]*)\}\s*from\s*["']@repo\/rb-components[^"']*["'];?/g,
+    (_, typeOnly = "", names) => {
+      const list = names.split(",").map((n) => n.trim()).filter(Boolean);
+      for (const n of list) if (!exported.has(n.replace(/^type\s+/, "").split(/\s+as\s+/)[0])) missing.add(n);
+      return `import ${typeOnly}{ ${list.join(", ")} } from "@rainbow-robotics/plugin-ui/react";`;
+    },
+  );
+  const notes = [
+    "// Storybook story source. In a plugin, import components from \"@rainbow-robotics/plugin-ui/react\"",
+    "// (rewritten below); @storybook/* imports, Meta/StoryObj and play() are Storybook-only.",
+    ...(missing.size ? [`// Not exported by plugin-ui, do not use in a plugin: ${[...missing].join(", ")}`] : []),
+  ];
+  return `${notes.join("\n")}\n\n${text}`;
+}
+
+const editDistance = (a, b) => {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]++;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[b.length];
+};
+
+// "RBSelect" → RBSelectBox, RBSelectOption, …; "select" (a native element) → its plugin-ui replacement.
+function suggestExports(name, exportNames) {
+  const q = name.toLowerCase().replace(/[<>]/g, "");
+  const native = NATIVE_TO_RB.filter(([el]) => el.split(/[\s/=]+/).includes(q)).map(([, rb]) => rb);
+  const bare = q.replace(/^rb/, "");
+  const close = exportNames
+    .map((n) => {
+      const lower = n.toLowerCase();
+      const score = lower.includes(q) || (bare.length > 2 && lower.includes(bare)) ? 0 : editDistance(q, lower);
+      return { n, score };
+    })
+    .filter((x) => x.score <= 3)
+    .sort((a, b) => a.score - b.score || a.n.length - b.n.length)
+    .slice(0, 6)
+    .map((x) => x.n);
+  return [...native, ...close];
+}
+
+function unknownExportText(name, exportNames, what) {
+  const hints = suggestExports(name, exportNames);
+  return (
+    `No ${what} named "${name}" in @rainbow-robotics/plugin-ui/react.` +
+    (hints.length ? ` Did you mean: ${hints.join(", ")}?` : "") +
+    " Call list_components for valid names. Do not fall back to a native HTML element."
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* README search                                                              */
+/* -------------------------------------------------------------------------- */
+
+// 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;
+}
+
+// Standalone binaries have no templates/ on disk.
+async function readTemplateReadme(rel) {
+  const onDisk = join(kitRoot, "cli/templates", rel);
+  if (existsSync(onDisk)) return readFileSync(onDisk, "utf8");
+  try {
+    const { TEMPLATES } = await import("./templates-embedded.mjs");
+    return TEMPLATES[rel] ? Buffer.from(TEMPLATES[rel], "base64").toString("utf8") : "";
+  } catch {
+    return "";
+  }
+}
+
+async function searchReadme(query, lang) {
+  const langs = lang ? [lang] : ["python", "cpp"];
+  const seen = new Set();
+  const sections = [];
+  for (const l of langs) {
+    for (const section of splitSections(await readTemplateReadme(TEMPLATE_READMES[l]))) {
+      if (seen.has(section)) continue; // UI/manifest sections are shared by both READMEs
+      seen.add(section);
+      sections.push(langs.length > 1 && l === "cpp" ? `[C++ backend]\n${section}` : section);
+    }
+  }
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+  return sections
+    .map((section) => {
+      const lower = section.toLowerCase();
+      const score = terms.reduce((n, term) => n + (lower.includes(term) ? 1 : 0), 0);
+      return { section: section.trim(), score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 5)
+    .map((x) => x.section);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Design tokens — parsed from rb-styles' generated rb-token.css              */
+/* -------------------------------------------------------------------------- */
+
+// A color var `--color-<name>` becomes Tailwind utilities `bg-<name>`,
+// `text-<name>`, `border-<name>`, `fill-<name>`. The design system's naming
+// already encodes intent (bg-/fg-/border-/fill-), so we surface the idiomatic
+// class per group.
+const COLOR_CLASS_HINT = {
+  bg: (n) => `bg-${n}`, // --color-bg-default → bg-bg-default
+  fg: (n) => `text-${n}`, // --color-fg-subtle → text-fg-subtle
+  border: (n) => `border-${n}`,
+  fill: (n) => `fill-${n}`,
+};
+
+let tokensCache = null;
+
+function loadDesignTokens() {
+  if (tokensCache) return tokensCache;
+  if (!existsSync(DESIGN_TOKENS_CSS)) {
+    throw new Error(
+      `design token CSS not found at ${DESIGN_TOKENS_CSS} — rebuild via "muscat-pk storybook --rebuild" (monorepo) or reinstall.`,
+    );
+  }
+  const css = readFileSync(DESIGN_TOKENS_CSS, "utf8");
+
+  // @theme { --name: value; ... }  → { group, name, value, class? }
+  const vars = [];
+  for (const [, rawName, value] of css.matchAll(
+    /^\s*(--[a-z0-9-]+)\s*:\s*([^;]+);/gim,
+  )) {
+    const name = rawName.replace(/^--/, "");
+    const m = name.match(/^color-(bg|fg|border|fill)-(.+)$/);
+    const token = { name, value: value.trim() };
+    if (m) {
+      token.group = `color-${m[1]}`;
+      token.class = COLOR_CLASS_HINT[m[1]](`${m[1]}-${m[2]}`);
+    } else {
+      token.group = name.split("-").slice(0, 2).join("-");
+    }
+    vars.push(token);
+  }
+
+  // @utility typo-… → composite typography classes used directly in className.
+  const typo = [
+    ...new Set(
+      [...css.matchAll(/@utility\s+(typo-[a-z0-9-]+)\s*\{/g)].map((m) => m[1]),
+    ),
+  ].sort();
+
+  tokensCache = { vars, typo };
+  return tokensCache;
+}
+
+/* -------------------------------------------------------------------------- */
+/* rainbow-rb-sdk (Python) introspection                                      */
+/* -------------------------------------------------------------------------- */
+
+function pythonCmd() {
+  // Prefer the current plugin's own .venv — that's where `muscat-pk new` /
+  // ensureIdeVenv() installs rainbow-rb-sdk from requirements.txt. The AI
+  // agent's cwd is usually the plugin dir mcp was launched from.
+  try {
+    const py = venvPython(resolve(findPluginRoot(), ".venv"));
+    if (existsSync(py)) return py;
+  } catch {
+    /* not inside a plugin project — fall through to PATH lookup */
+  }
+  for (const c of ["python3", "python"]) {
+    const r = spawnSync(c, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+// Run an introspection script against the installed rainbow.rb_sdk (a plugin's
+// backend dependency). Returns a clear hint if it isn't importable.
+function introspectRbSdk(script) {
+  const py = pythonCmd();
+  const probe = `
+import json, importlib
+try:
+    importlib.import_module("rainbow.rb_sdk")
+except Exception as e:
+    print(json.dumps({"__notinstalled__": str(e)})); raise SystemExit(0)
+${script}
+`;
+  if (!py) {
+    return introspectInDocker(probe) ?? { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
+  }
+  const r = spawnSync(py, ["-c", probe], { encoding: "utf8", maxBuffer: 8 << 20 });
+  if (r.status !== 0) {
+    return { error: `python introspection failed: ${(r.stderr || "").trim().slice(0, 500)}` };
+  }
+  const local = parseProbe(r);
+  return local.error && local.notInstalled ? introspectInDocker(probe) ?? local : local;
+}
+
+// No macOS wheels: import the plugin's pinned SDK inside the python dev image (cached).
+function introspectInDocker(probe) {
+  if (spawnSync("docker", ["image", "inspect", PYTHON_DEV_IMAGE], { encoding: "utf8" }).status !== 0) return null;
+  let ver = "";
+  try {
+    const req = readFileSync(join(findPluginRoot(), "requirements.txt"), "utf8");
+    ver = req.match(/^rainbow-rb-sdk==(\S+)/m)?.[1] ?? "";
+  } catch {
+    /* not a python plugin — latest */
+  }
+  // ponytail: "latest" cache is never refreshed; delete ~/.cache/... rb-sdk-py/latest to update.
+  const cache = join(UI_INDEX_CACHE_DIR, "rb-sdk-py", ver || "latest");
+  mkdirSync(cache, { recursive: true });
+  const pkg = ver ? `rainbow-rb-sdk==${ver}` : "rainbow-rb-sdk";
+  const script =
+    `[ -f /c/.ok ] || { pip3 install -q --break-system-packages --target /c '${pkg}' >&2 && touch /c/.ok; } && ` +
+    `PYTHONPATH=/c python3 -c "$PROBE"`;
+  const r = spawnSync("docker", ["run", "--rm", "-v", `${cache}:/c`, "-e", "PROBE", PYTHON_DEV_IMAGE, "bash", "-c", script], {
+    encoding: "utf8",
+    maxBuffer: 8 << 20,
+    env: { ...process.env, PROBE: probe },
+  });
+  if (r.status !== 0) return { error: `python introspection (docker) failed: ${(r.stderr || "").trim().slice(-500)}` };
+  return parseProbe(r);
+}
+
+function parseProbe(r) {
+  // Importing rainbow.rb_sdk has side effects that print to stdout (e.g. the
+  // Zenoh client logs its connection endpoints), ahead of our own final
+  // print(json.dumps(...)) — so parse the last line, not the whole output.
+  const lines = r.stdout.trim().split("\n");
+  let data;
+  try {
+    data = JSON.parse(lines[lines.length - 1]);
+  } catch {
+    return { error: `unexpected introspection output: ${r.stdout.slice(0, 300)}` };
+  }
+  if (data && data.__notinstalled__) {
+    return {
+      notInstalled: true,
+      error:
+        "rainbow-rb-sdk is not installed in this environment. Install it with `pip install rainbow-rb-sdk` " +
+        "(it's already in a plugin's requirements.txt), then retry.",
+    };
+  }
+  return { data };
+}
+
+/* -------------------------------------------------------------------------- */
+/* rainbow-rb-sdk-dev (C++) headers — copied out of the cpp dev image           */
+/* -------------------------------------------------------------------------- */
+
+const CPP_INCLUDE_CACHE = join(UI_INDEX_CACHE_DIR, "rb-sdk-include");
+// Headers we don't want to surface: third-party vendored code, pybind glue,
+// flatbuffers-generated schemas, and the industrial comm stacks.
+const CPP_SKIP = /^(vendor|binding|rb_comm_source)\/|_generated\.h$/;
+
+// The apt package is only installed inside the muscat-pk-cpp-dev image, so
+// copy /usr/include/rainbow/rb_sdk out once per image build (cache key =
+// image id) with `docker cp` — no host tar needed.
+function cppIncludeDir() {
+  const insp = spawnSync("docker", ["image", "inspect", "-f", "{{.Id}}", CPP_DEV_IMAGE], { encoding: "utf8" });
+  if (insp.error) return { error: "Docker not found — the C++ SDK headers live in the muscat-pk cpp dev image." };
+  if (insp.status !== 0) {
+    return {
+      error:
+        `Docker image ${CPP_DEV_IMAGE} not built yet. Run \`muscat-pk dev:back\` (or \`muscat-pk build\`) once ` +
+        "in a cpp / rclcpp plugin to build it, then retry.",
+    };
+  }
+  const dir = join(CPP_INCLUDE_CACHE, insp.stdout.trim().replace(/^sha256:/, "").slice(0, 12));
+  const out = join(dir, "rb_sdk");
+  if (existsSync(out)) return { dir: out };
+  mkdirSync(dir, { recursive: true });
+  const ctr = spawnSync("docker", ["create", CPP_DEV_IMAGE], { encoding: "utf8" });
+  if (ctr.status !== 0) return { error: `docker create failed: ${(ctr.stderr || "").trim().slice(0, 300)}` };
+  const id = ctr.stdout.trim();
+  const cp = spawnSync("docker", ["cp", `${id}:/usr/include/rainbow/rb_sdk`, dir], { encoding: "utf8" });
+  spawnSync("docker", ["rm", "-f", id], { encoding: "utf8" });
+  if (cp.status !== 0 || !existsSync(out)) {
+    return { error: `docker cp failed: ${(cp.stderr || "").trim().slice(0, 300)}` };
+  }
+  return { dir: out };
+}
+
+function cppHeaders(root) {
+  const files = [];
+  const walk = (d, rel) => {
+    for (const name of readdirSync(d)) {
+      const r = rel ? `${rel}/${name}` : name;
+      if (CPP_SKIP.test(r)) continue;
+      const full = join(d, name);
+      if (statSync(full).isDirectory()) walk(full, r);
+      else if (/\.hpp$/.test(name)) files.push(r);
+    }
+  };
+  walk(root, "");
+  return files.sort();
+}
+
+// "class Foo {" / "class Foo : public Bar {" — not forward declarations.
+const CLASS_RE = /^\s*(?:class|struct)\s+(?:[A-Z][A-Z0-9_]*_API\s+)?(\w+)\b(?![^\n]*;\s*$)/; // skip export macros (RB_SDK_API)
+
+function cppClassesIn(text) {
+  return [...new Set(text.split("\n").map((l) => l.match(CLASS_RE)?.[1]).filter(Boolean))];
+}
+
+// Return the class body (brace-matched) plus the file's leading comment block,
+// which in these headers usually carries a full usage example.
+function cppExtract(text, className, method) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => CLASS_RE.test(l) && l.match(CLASS_RE)[1] === className);
+  if (start < 0) return null;
+  let depth = 0, end = start, seen = false;
+  for (let i = start; i < lines.length; i++) {
+    for (const ch of lines[i]) {
+      if (ch === "{") { depth++; seen = true; }
+      else if (ch === "}") depth--;
+    }
+    if (seen && depth === 0) { end = i; break; }
+  }
+  const body = lines.slice(start, end + 1);
+  if (method) {
+    // Declarations sit at class-member indent (<= 2 spaces) and the name is
+    // not preceded by `.`/`->`/`::` — that skips call sites inside bodies.
+    const re = new RegExp(`^ {0,2}[^(]*(?<![\\w.>:])${method.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\(`);
+    const hits = [];
+    for (let i = 0; i < body.length; i++) {
+      if (!re.test(body[i]) || /^\s*\/\//.test(body[i])) continue;
+      let a = i;
+      while (a > 0 && /^\s*\/\//.test(body[a - 1])) a--;
+      let b = i;
+      while (b < body.length - 1 && !/[{;]/.test(body[b])) b++;
+      hits.push(body.slice(a, b + 1).join("\n"));
+    }
+    return hits.length ? hits.join("\n\n") : null;
+  }
+  const head = [];
+  for (const l of lines) {
+    if (/^\s*\/\//.test(l)) head.push(l);
+    else if (l.trim() === "" || /^#pragma/.test(l)) continue;
+    else break;
+  }
+  return (head.length > 3 ? head.join("\n") + "\n\n" : "") + body.join("\n");
+}
+
+function cppFind(className) {
+  const { dir, error } = cppIncludeDir();
+  if (error) return { error };
+  for (const rel of cppHeaders(dir)) {
+    const text = readFileSync(join(dir, rel), "utf8");
+    if (cppClassesIn(text).includes(className)) return { rel, text };
+  }
+  return { error: `No class "${className}" in the C++ SDK headers. Call list_rb_sdk with lang "cpp" for valid names.` };
+}
+
+/* -------------------------------------------------------------------------- */
+/* 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                                                                      */
+/* -------------------------------------------------------------------------- */
+
+export async function runMcp() {
+  const server = new McpServer(
+    { name: "muscat-plugin-kit", version: kitVersion() },
+    { instructions: SERVER_INSTRUCTIONS },
+  );
+
+  server.registerTool(
+    "list_components",
+    {
+      title: "List Muscat plugin UI components",
+      description:
+        "List every component, hook, and type exported from @rainbow-robotics/plugin-ui/react — " +
+        "the full UI surface available to Muscat plugin authors. Call this first before guessing a " +
+        "component name; plugin UI uses these instead of native <select>/<input>/<button> elements.",
+      inputSchema: {},
+    },
+    async () => {
+      const { components } = await loadUiIndex();
+      return { content: [{ type: "text", text: components }] };
+    },
+  );
+
+  server.registerTool(
+    "get_component_props",
+    {
+      title: "Get a component or hook's real type signature",
+      description:
+        "Get the full TypeScript type for a named export of @rainbow-robotics/plugin-ui/react " +
+        "(e.g. RBSlider, RBLabelButton, useRb, useRbFormData). Use list_components to find valid names.",
+      inputSchema: { name: z.string().describe('Exported name, e.g. "RBSlider"') },
+    },
+    async ({ name }) => {
+      const { props } = await loadUiIndex();
+      if (!Object.hasOwn(props, name)) {
+        return { isError: true, content: [{ type: "text", text: unknownExportText(name, Object.keys(props), "export") }] };
+      }
+      return { content: [{ type: "text", text: props[name] }] };
+    },
+  );
+
+  server.registerTool(
+    "get_component_example",
+    {
+      title: "Get a real Storybook usage example",
+      description:
+        "Get the real Storybook story source for a component (e.g. RBSlider) — actual working " +
+        "props, imports, and layout, not a guessed shape. Prefer this over get_component_props when " +
+        "you just need to know how to use a component, not its full type.",
+      // `component` accepted as an alias — agents often guess it over `name`.
+      inputSchema: {
+        name: z.string().optional().describe('Component name, e.g. "RBSlider"'),
+        component: z.string().optional().describe("Alias for `name`."),
+      },
+    },
+    async ({ name, component }) => {
+      const target = name ?? component;
+      if (!target) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: 'Missing required argument: "name" (component name, e.g. "RBSlider").' }],
+        };
+      }
+      const exportNames = Object.keys((await loadUiIndex()).props);
+      const source = findStorySource(target);
+      if (!source) {
+        // An existing export without a story still has a type; an unknown name gets suggestions.
+        const text = exportNames.includes(target)
+          ? `No Storybook example for "${target}". Call get_component_props for its type, or run "muscat-pk storybook" to browse components live.`
+          : unknownExportText(target, exportNames, "component");
+        return { content: [{ type: "text", text }] };
+      }
+      return { content: [{ type: "text", text: rewriteStoryImports(source, exportNames) }] };
+    },
+  );
+
+  server.registerTool(
+    "search_rb_sdk",
+    {
+      title: "Search the Muscat plugin-author docs",
+      description:
+        "Search the Muscat plugin-author README for how to use useRb(), rb.pub/sub/action/serve, " +
+        "plugin.router (external endpoints: router.on/subscribe/emit exposed over REST/Socket.IO/TCP/" +
+        "MQTT/WebRTC at common/plugin/{plugin_id}/{path}, PluginRouteError, meta.transport/principal), " +
+        "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
+        "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), video streaming (MediaMTX: backend publishes RTSP to " +
+        "127.0.0.1:8554, UI plays WebRTC from :8889), ROS 2 topics (plugin namespace, rb.rosPeers to allow " +
+        "an external PC), contribution points, and backend runtimes " +
+        "(Python/C++/ROS2). Covers BOTH backends: the Python README (py/main.py, rainbow.rb_sdk) and the " +
+        "C++ README (cpp/main.cpp or an rclcpp node: rb_plugin::RBPluginCall serve/subscribe/publish/" +
+        "router(), rb_plugin::PluginProgramContext, RBManipulateSDK, CMake rb_sdk::rb_sdk). Pass lang " +
+        "\"python\" or \"cpp\" to match the plugin's manifest runtime (cpp or ros2+rclcpp → \"cpp\"); " +
+        "omit it to search both. IMPORTANT: " +
+        "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
+        "writing the backend. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
+        "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",
+      inputSchema: {
+        query: z.string().describe('Keywords, e.g. "save form data" or "rb.action"'),
+        lang: z.enum(["python", "cpp"]).optional().describe("Backend language; omit to search both"),
+      },
+    },
+    async ({ query, lang }) => {
+      const sections = await searchReadme(query, lang);
+      if (sections.length === 0) {
+        return { content: [{ type: "text", text: `No matching section found for "${query}".` }] };
+      }
+      return { content: [{ type: "text", text: sections.join("\n\n---\n\n") }] };
+    },
+  );
+
+  /* --- design tokens --- */
+
+  server.registerTool(
+    "list_design_tokens",
+    {
+      title: "List Muscat design tokens (Tailwind classes)",
+      description:
+        "List the design system's tokens as the Tailwind classes to use in a plugin's className: " +
+        "semantic colors (bg-bg-*, text-fg-*, border-border-*, fill-fill-*), typography (typo-*), " +
+        "shadows, radius, spacing. Use these instead of raw hex/px so the plugin matches the host theme " +
+        "(and light/dark). Optionally filter by category.",
+      inputSchema: {
+        category: z
+          .enum(["bg", "fg", "border", "fill", "typography", "shadow", "radius", "spacing", "all"])
+          .optional()
+          .describe('Filter, e.g. "bg", "fg", "typography". Omit for a grouped overview.'),
+      },
+    },
+    async ({ category }) => {
+      const { vars, typo } = loadDesignTokens();
+      const out = [];
+
+      const colorGroups = { bg: [], fg: [], border: [], fill: [] };
+      const other = { shadow: [], radius: [], spacing: [] };
+      for (const t of vars) {
+        const m = t.group?.match(/^color-(bg|fg|border|fill)$/);
+        // Class name only: the value is just an indirection to another CSS var
+        // (var(--color-scale-zinc-200)), and each class is declared twice (light/dark)
+        // with different values — dropping the value lets the Set dedup collapse them.
+        if (m && t.class) colorGroups[m[1]].push(t.class);
+        else if (t.name.startsWith("shadow-")) other.shadow.push(`shadow-${t.name.slice(7)}`);
+        else if (t.name.startsWith("radius-")) other.radius.push(`rounded-${t.name.slice(7)}`);
+        else if (t.name.startsWith("spacing-")) other.spacing.push(t.name);
+      }
+
+      const want = (c) => !category || category === "all" || category === c;
+      const push = (title, items) => {
+        if (items.length) out.push(`## ${title}\n${[...new Set(items)].sort().join("\n")}`);
+      };
+      if (want("bg")) push("Background — bg-bg-*", colorGroups.bg);
+      if (want("fg")) push("Text/foreground — text-fg-*", colorGroups.fg);
+      if (want("border")) push("Border — border-border-*", colorGroups.border);
+      if (want("fill")) push("SVG fill — fill-fill-*", colorGroups.fill);
+      if (want("typography")) push("Typography — typo-* (use directly)", typo);
+      if (want("shadow")) push("Shadow", other.shadow);
+      if (want("radius")) push("Radius", other.radius);
+      if (want("spacing")) push("Spacing scale (p-/m-/gap-/w-/h-)", other.spacing);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: out.join("\n\n") || `No tokens for category "${category}".`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    "search_design_tokens",
+    {
+      title: "Search design tokens by name or value",
+      description:
+        "Find a design token by keyword — e.g. 'danger' (error colors), 'elevated', 'brand', or a hex " +
+        "like '#fb2c36'. Returns the matching Tailwind class + value.",
+      inputSchema: { query: z.string().describe('e.g. "danger", "elevated", "#fb2c36"') },
+    },
+    async ({ query }) => {
+      const { vars, typo } = loadDesignTokens();
+      const q = query.toLowerCase();
+      const hits = vars
+        .filter((t) => t.name.toLowerCase().includes(q) || t.value.toLowerCase().includes(q))
+        .map((t) => `${t.class ?? t.name}   (${t.value})`);
+      const typoHits = typo.filter((c) => c.toLowerCase().includes(q));
+      const all = [...typoHits, ...hits];
+      return {
+        content: [
+          {
+            type: "text",
+            text: all.length ? [...new Set(all)].slice(0, 60).join("\n") : `No token matches "${query}".`,
+          },
+        ],
+      };
+    },
+  );
+
+  /* --- rainbow-rb-sdk (Python backend) --- */
+
+  server.registerTool(
+    "list_rb_sdk",
+    {
+      title: "List rainbow-rb-sdk classes and functions (Python or C++)",
+      description:
+        "List the public classes and functions of the plugin BACKEND SDK. lang \"python\" (default): the " +
+        "installed rainbow.rb_sdk package (RBPluginCall, RBManipulateSDK, RBAmrSDK, PluginProgramContext, " +
+        "...) — call before writing py/main.py; requires rainbow-rb-sdk to be pip-installed. lang \"cpp\": " +
+        "the C++ SDK headers (apt rainbow-rb-sdk-dev: RBManipulateSDK, rb_plugin::PluginProgramContext, " +
+        "...) grouped by header path — call before writing cpp/main.cpp or an rclcpp node; requires the " +
+        "muscat-pk-cpp-dev Docker image (built by `muscat-pk dev:back`). RBPluginCall (UI pub/sub/serve, " +
+        "router) exists in both: Python rainbow.rb_sdk.RBPluginCall, C++ rb_plugin::RBPluginCall " +
+        "(plugin/rb_plugin.hpp).",
+      inputSchema: { lang: z.enum(["python", "cpp"]).optional().describe('Default "python"') },
+    },
+    async ({ lang }) => {
+      if (lang === "cpp") {
+        const { dir, error } = cppIncludeDir();
+        if (error) return { isError: true, content: [{ type: "text", text: error }] };
+        const out = [];
+        for (const rel of cppHeaders(dir)) {
+          const classes = cppClassesIn(readFileSync(join(dir, rel), "utf8"));
+          if (classes.length) out.push(`${rel}: ${classes.join(", ")}`);
+        }
+        return { content: [{ type: "text", text: `#include <rainbow/rb_sdk/...>\n\n${out.join("\n")}` }] };
+      }
+      const { data, error } = introspectRbSdk(`
+import inspect, json
+mod = importlib.import_module("rainbow.rb_sdk")
+out = []
+for name in sorted(getattr(mod, "__all__", None) or dir(mod)):
+    if name.startswith("_"): continue
+    obj = getattr(mod, name)
+    if inspect.isclass(obj): out.append(name + " (class)")
+    elif inspect.isfunction(obj) or inspect.isbuiltin(obj): out.append(name + " (function)")
+print(json.dumps(out))
+`);
+      if (error) return { isError: true, content: [{ type: "text", text: error }] };
+      return { content: [{ type: "text", text: data.join("\n") }] };
+    },
+  );
+
+  server.registerTool(
+    "get_rb_sdk_api",
+    {
+      title: "Get a rainbow-rb-sdk class/function signature + docs (Python or C++)",
+      description:
+        "Get the signature(s) and docstring for a rainbow.rb_sdk class or function (e.g. " +
+        "'PluginProgramContext', 'RBManipulateSDK'). For a class, lists its public methods with " +
+        "signatures. To drill into ONE method of a class (e.g. RBManipulateSDK.call_move_j), pass " +
+        "`method` alongside `name` — do not put both in `name`. lang \"python\" (default) introspects the " +
+        "pip-installed package. lang \"cpp\" returns the class declaration from the C++ SDK header " +
+        "(rainbow-rb-sdk-dev) with its header comment — usually a full usage example — and the " +
+        "#include path; with `method`, just that method's declaration and comment.",
+      inputSchema: {
+        name: z.string().describe('Class or function name, e.g. "RBManipulateSDK"'),
+        method: z.string().optional().describe('Optional: a specific method on that class, e.g. "call_move_j"'),
+        lang: z.enum(["python", "cpp"]).optional().describe('Default "python"'),
+      },
+    },
+    async ({ name, method, lang }) => {
+      // Tolerate a combined "ClassName method_name" in `name` (a common agent
+      // mistake) by splitting it ourselves instead of failing validation.
+      let className = name;
+      let methodName = method;
+      if (!methodName && /\s/.test(name.trim())) {
+        const parts = name.trim().split(/\s+/);
+        if (parts.length === 2) [className, methodName] = parts;
+      }
+
+      if (lang === "cpp") {
+        const cls = className.replace(/^.*::/, "");
+        let { rel, text, error } = cppFind(cls);
+        if (error) return { isError: true, content: [{ type: "text", text: error }] };
+        let body = cppExtract(text, cls, methodName);
+        let owner = cls;
+        if (!body && methodName) {
+          // Like the Python path: most calls live on sub-SDK members
+          // (RBManipulateMoveSDK move; -> sdk.move.call_move_j) or on the base
+          // class — look there before giving up.
+          const decl = cppExtract(text, cls);
+          const cands = [
+            ...[...decl.matchAll(/^\s*(\w+SDK)\s+(\w+);/gm)].map((m) => [m[1], `${cls}.${m[2]}`]),
+            ...[...decl.matchAll(/:\s*public\s+(\w+)/g)].map((m) => [m[1], `${cls} (base ${m[1]})`]),
+          ];
+          for (const [c, label] of cands) {
+            const f = cppFind(c);
+            if (f.error) continue;
+            const b = cppExtract(f.text, c, methodName);
+            if (b) { ({ rel, text } = f); body = b; owner = label; break; }
+          }
+        }
+        if (!body) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `No method "${methodName}" declared in class "${cls}" (${rel}) or its sub-SDK members / base class. Call get_rb_sdk_api with just \`name\` to see the class.` }],
+          };
+        }
+        const ns = text.match(/^namespace\s+(\w+)\s*\{/m)?.[1];
+        const header =
+          `// #include <rainbow/rb_sdk/${rel}>${ns ? `   (namespace ${ns})` : ""}\n` +
+          `// link: find_package(rb_sdk) + rb_sdk::rb_sdk\n` +
+          (methodName ? `// ${owner}.${methodName}\n` : "") + "\n";
+        return { content: [{ type: "text", text: header + body.slice(0, 60_000) }] };
+      }
+
+      const { data, error } = introspectRbSdk(`
+import inspect, json
+mod = importlib.import_module("rainbow.rb_sdk")
+name = ${JSON.stringify(className)}
+method = ${methodName ? JSON.stringify(methodName) : "None"}
+obj = getattr(mod, name, None)
+if obj is None:
+    print(json.dumps({"__missing__": True})); raise SystemExit(0)
+def sig(o):
+    try: return str(inspect.signature(o))
+    except Exception: return "(...)"
+
+if method:
+    # Direct method on the class itself.
+    fn = getattr(obj, method, None) if inspect.isclass(obj) else None
+    # rb_sdk classes often group calls under a nested namespace set in
+    # __init__ (e.g. RBManipulateSDK().move.call_move_j) — that only exists on
+    # an INSTANCE, which we won't construct (side effects, needs a robot
+    # connection). Best-effort: search the class's own __init__ source text
+    # for self.<attr> = <NestedClass>(...) and check each nested class too.
+    owner = name
+    if fn is None and inspect.isclass(obj):
+        try:
+            src = inspect.getsource(obj.__init__)
+        except Exception:
+            src = ""
+        import re, sys as _sys
+        # The nested sub-SDK classes (e.g. RBManipulateMoveSDK) are imported in
+        # the module that DEFINES obj (rainbow.rb_sdk.manipulate), not in the
+        # rainbow.rb_sdk top-level namespace — resolve names against both.
+        _defmod = _sys.modules.get(getattr(obj, "__module__", ""))
+        for attr, nested_name in re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", src):
+            nested = (
+                (getattr(_defmod, nested_name, None) if _defmod else None)
+                or mod.__dict__.get(nested_name)
+                or globals().get(nested_name)
+            )
+            cand = getattr(nested, method, None) if nested else None
+            if cand:
+                fn = cand
+                owner = f"{name}.{attr} ({nested_name})"
+                break
+    if fn is None:
+        print(json.dumps({"__missing__": True, "__method__": True})); raise SystemExit(0)
+    print(json.dumps({
+        "name": name, "kind": "method", "owner": owner,
+        "signature": method + sig(fn), "doc": inspect.getdoc(fn) or "",
+    }))
+    raise SystemExit(0)
+
+res = {"name": name, "doc": inspect.getdoc(obj) or ""}
+if inspect.isclass(obj):
+    res["kind"] = "class"
+    res["init"] = name + sig(obj.__init__ if "__init__" in dir(obj) else obj)
+    def _methods_of(cls, prefix=""):
+        out = []
+        for m, fn in inspect.getmembers(cls, predicate=inspect.isfunction):
+            if m.startswith("_"): continue
+            out.append({"name": prefix + m, "sig": prefix + m + sig(fn),
+                        "doc": (inspect.getdoc(fn) or "").split("\\n")[0]})
+        return out
+    methods = _methods_of(obj)
+    # Most rb_sdk calls live on nested sub-SDKs assigned in __init__
+    # (e.g. self.move = RBManipulateMoveSDK() -> obj.move.call_move_j). List
+    # those too, name-prefixed, so the API is discoverable without an instance.
+    import re as _re, sys as _sys
+    _defmod = _sys.modules.get(getattr(obj, "__module__", ""))
+    try:
+        _src = inspect.getsource(obj.__init__)
+    except Exception:
+        _src = ""
+    for _attr, _nested_name in _re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", _src):
+        _nested = (getattr(_defmod, _nested_name, None) if _defmod else None) or mod.__dict__.get(_nested_name)
+        if inspect.isclass(_nested):
+            methods.extend(_methods_of(_nested, prefix=_attr + "."))
+    res["methods"] = methods
+else:
+    res["kind"] = "function"
+    res["signature"] = name + sig(obj)
+print(json.dumps(res))
+`);
+      if (error) return { isError: true, content: [{ type: "text", text: error }] };
+      if (data.__missing__) {
+        const text = data.__method__
+          ? `No method "${methodName}" found directly on "${className}" (nor in an obvious nested ` +
+            `namespace set in __init__). Call get_rb_sdk_api with just \`name: "${className}"\` to see ` +
+            `its full method list and constructor first.`
+          : `No "${className}" in rainbow.rb_sdk. Call list_rb_sdk for valid names.`;
+        return { isError: true, content: [{ type: "text", text }] };
+      }
+      if (data.kind === "method") {
+        const lines = [`# ${data.owner}.${data.signature.split("(")[0]}`, data.signature];
+        if (data.doc) lines.push("", data.doc);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+      const lines = [`# ${data.name} (${data.kind})`];
+      if (data.doc) lines.push(data.doc, "");
+      if (data.kind === "class") {
+        lines.push(`constructor: ${data.init}`, "", "methods:");
+        for (const m of data.methods) {
+          lines.push(`  ${m.sig}${m.doc ? `  — ${m.doc}` : ""}`);
+        }
+      } else {
+        lines.push(data.signature);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}