@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.46 → 0.1.2-dev.47

package/cli/src/mcp.mjs

@@ -1,7 +1,6 @@
-// muscat-pk mcp — an MCP (Model Context Protocol) server that gives an AI
-// coding agent (Claude Code, Codex, ...) grounded knowledge of the Muscat
-// plugin UI surface, instead of it guessing prop names or grepping
-// node_modules for @rainbow-robotics/plugin-ui and @repo/rb-components:
+// 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.
@@ -42,11 +41,9 @@ const DESIGN_TOKENS_CSS = existsSync(SHIPPED_DESIGN_TOKENS)
 
 let typesCache = null;
 
-// Resolves @rainbow-robotics/plugin-ui/react's bundled, self-contained
-// dist/react.d.ts (see plugin-ui/build-dist.mjs — rb-components' own types are
-// inlined into it, so this single file is enough; no need to resolve
-// @repo/rb-components separately, which wouldn't exist in an external install
-// anyway).
+// 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;
 
@@ -113,9 +110,7 @@ function findStorySource(name) {
 /* README search                                                              */
 /* -------------------------------------------------------------------------- */
 
-// Splits the plugin-author README on headings and keyword-scores each
-// section — good enough for short-query lookups ("save form data", "toast",
-// "manifest ui") without pulling in a real search dependency.
+// Split the README on headings and keyword-score each section.
 function searchReadme(query) {
   if (!existsSync(TEMPLATE_README)) return [];
   const text = readFileSync(TEMPLATE_README, "utf8");
@@ -200,9 +195,8 @@ function pythonCmd() {
   return null;
 }
 
-// Runs a short introspection script against the INSTALLED rainbow.rb_sdk. It's
-// the plugin's own backend dependency (requirements.txt / `muscat-pk sdk`), so
-// in a real plugin env it's importable; otherwise we return a clear hint.
+// 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) {
@@ -478,20 +472,66 @@ print(json.dumps(out))
       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. Requires rainbow-rb-sdk to be pip-installed.",
-      inputSchema: { name: z.string().describe('e.g. "PluginProgramContext"') },
+        "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 }) => {
+    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(name)}
+name = ${JSON.stringify(className)}
+method = ${JSON.stringify(methodName ?? null)}
 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
+        for attr, nested_name in re.findall(r"self\\.(\\w+)\\s*=\\s*(\\w+)\\(", src):
+            nested = 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"
@@ -508,12 +548,17 @@ print(json.dumps(res))
 `);
       if (error) return { isError: true, content: [{ type: "text", text: error }] };
       if (data.__missing__) {
-        return {
-          isError: true,
-          content: [
-            { type: "text", text: `No "${name}" in rainbow.rb_sdk. Call list_rb_sdk for valid names.` },
-          ],
-        };
+        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, "");

package/cli/src/pluginDevServer.mjs

@@ -46,12 +46,11 @@ import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
 import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
 import App from ${entry};
 
-// HMR only hands the new module to the accept callback — it does NOT rebind the
-// static \`App\` import above. So we track the latest component at MODULE scope.
-// Without this, navigating away and back (a fresh mount() call on this cached
-// bootstrap module) would render the STALE component captured at first import;
-// only a hard refresh fixed it. \`activeRender\` points at the currently-mounted
-// root so live edits re-render it in place.
+// HMR passes the new module to the accept callback but doesn't rebind the
+// static \`App\` import, so we track the latest at module scope. Without this,
+// navigating away and back (a fresh mount() on this cached module) renders the
+// stale App from first import. \`activeRender\` points at the mounted root so
+// live edits re-render in place.
 let latestApp = App;
 let activeRender = null;
 if (import.meta.hot) {

package/cli/src/util.mjs

@@ -40,12 +40,9 @@ export function venvPython(venvDir) {
 }
 
 /**
- * Create/refresh a LOCAL `.venv` with the plugin's requirements.txt installed —
- * purely so an editor/linter (pylint, pyright, mypy, ...) can resolve imports.
- * Docker remains the actual execution environment for `dev`/`dev:back`; this
- * never affects it. Uses `uv` if available (fast, pins Python 3.12 — matches
- * the robot), else falls back to the detected system Python.
- * Returns true if the venv is ready with deps installed.
+ * Create/refresh a local `.venv` with requirements.txt installed, for the
+ * editor/linter only (the backend actually runs in Docker). Uses `uv` if
+ * present, else the system Python. Returns true if the venv is ready.
  */
 export function ensureIdeVenv(root) {
   const venvDir = resolve(root, ".venv");

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1783623695483,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}
+{"generatedAt":1783624567446,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.46",
+  "version": "0.1.2-dev.47",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,8 +53,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "0.1.2-dev.46",
-    "@rainbow-robotics/preview-host": "0.1.2-dev.46",
+    "@rainbow-robotics/plugin-ui": "0.1.2-dev.47",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.47",
     "postcss": "^8.5.8",
     "socket.io": "^4.8.1",
     "typescript": "^5.8.0",