@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 1.0.1

package/cli/src/mcp.mjs

@@ -0,0 +1,617 @@
+// 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.
+//   - 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 { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
+import { SHIPPED_STORIES_SRC, SHIPPED_DESIGN_TOKENS } from "./storybook.mjs";
+
+const TEMPLATE_README = join(kitRoot, "cli/templates/common/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                */
+/* -------------------------------------------------------------------------- */
+
+let typesCache = null;
+
+// Parse 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 loadReactTypes() {
+  if (typesCache) return typesCache;
+
+  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.`,
+    );
+  }
+
+  const program = ts.createProgram([dtsPath], {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    skipLibCheck: true,
+  });
+  const sourceFile = program.getSourceFile(dtsPath);
+  const checker = program.getTypeChecker();
+  const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+  const exports = moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : [];
+
+  typesCache = { checker, sourceFile, exports };
+  return typesCache;
+}
+
+// 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";
+}
+
+/* -------------------------------------------------------------------------- */
+/* 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;
+}
+
+/* -------------------------------------------------------------------------- */
+/* README search                                                              */
+/* -------------------------------------------------------------------------- */
+
+// Split the README on headings and keyword-score each section.
+function searchReadme(query) {
+  if (!existsSync(TEMPLATE_README)) return [];
+  const text = readFileSync(TEMPLATE_README, "utf8");
+  const sections = text.split(/\n(?=#{1,4} )/);
+  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();
+  if (!py) {
+    return { error: "Python not found on PATH. Install Python 3 to use rb-sdk introspection." };
+  }
+  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}
+`;
+  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)}` };
+  }
+  // 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 {
+      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 };
+}
+
+/* -------------------------------------------------------------------------- */
+/* server                                                                      */
+/* -------------------------------------------------------------------------- */
+
+export async function runMcp() {
+  const server = new McpServer({ name: "muscat-plugin-kit", version: kitVersion() });
+
+  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.",
+      inputSchema: {},
+    },
+    async () => {
+      const { checker, exports } = await loadReactTypes();
+      const lines = exports
+        .map((sym) => `${sym.getName()} (${exportKind(checker, sym)})`)
+        .sort();
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    },
+  );
+
+  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 { checker, sourceFile, exports } = await loadReactTypes();
+      const symbol = exports.find((sym) => sym.getName() === name);
+      if (!symbol) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `No export named "${name}" in @rainbow-robotics/plugin-ui/react. Call list_components for valid names.`,
+            },
+          ],
+        };
+      }
+      const resolved = resolveExport(checker, symbol);
+      const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0] ?? sourceFile;
+      const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
+      const text = checker.typeToString(
+        type,
+        undefined,
+        ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.MultilineObjectLiterals,
+      );
+      return { content: [{ type: "text", text }] };
+    },
+  );
+
+  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 source = findStorySource(target);
+      if (!source) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No Storybook example found for "${target}". Run "muscat-pk storybook" to browse all components live, or use get_component_props for its type.`,
+            },
+          ],
+        };
+      }
+      return { content: [{ type: "text", text: source }] };
+    },
+  );
+
+  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, " +
+        "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
+        "host), manifest.json, contribution points, and backend runtimes (Python/C++/ROS2). IMPORTANT: " +
+        "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
+        "writing py/main.py. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
+        "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",
+      inputSchema: {
+        query: z.string().describe('Keywords, e.g. "save form data" or "rb.action"'),
+      },
+    },
+    async ({ query }) => {
+      const sections = searchReadme(query);
+      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)$/);
+        if (m && t.class) colorGroups[m[1]].push(`${t.class}   (${t.value})`);
+        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 (Python) classes and functions",
+      description:
+        "List the public classes and functions of the installed rainbow.rb_sdk Python package — the " +
+        "plugin BACKEND SDK (RBPluginCall, RBManipulateSDK, RBAmrSDK, PluginProgramContext, ...). Call " +
+        "before writing py/main.py. Requires rainbow-rb-sdk to be pip-installed.",
+      inputSchema: {},
+    },
+    async () => {
+      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",
+      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`. Requires rainbow-rb-sdk to be " +
+        "pip-installed.",
+      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"'),
+      },
+    },
+    async ({ name, method }) => {
+      // 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;
+      }
+
+      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);
+}