@sakaniui/react 0.8.11 → 0.8.13

package/AGENTS.md

@@ -152,6 +152,12 @@ CSS of a component into your own file.
 
 Format: **Use for** · **Why it is built this way** · **Not for / instead**.
 
+**Looking for a component by another name?** SakaniUI uses its own names. A *dialog* or *alert dialog* is
+`Modal`; a *snackbar* is `Toast`; a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
+*date picker* is `Calendar`; a *loader* is `Spinner`; a *toggle* is `Switch`; a *banner* is `Announcement`;
+*autocomplete* is `Combobox`. There is no `Dialog`, `AlertDialog`, `Snackbar` or `Navbar`. Each component
+lists its other names under `aliases` in `manifest.json`, and `search_components` understands them.
+
 ### Actions
 - **Button** — Use for any action that does something. *Why:* 5 variants × 3 sizes mirror Figma 1:1;
   `loading` disables interaction so double-submits can't happen. *Not for* navigation → `Link`; icon-only →

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 0.8.13
+
+A user reported the MCP server "didn't work". Reproduced: on a Node older than 16.9 the server connected
+and listed its tools, then **every tool call failed** with `Object.hasOwn is not a function`.
+
+- **Fixed: tool calls failing on older Node.** The server no longer uses `Object.hasOwn` (Node 16.9+) or the
+  `node:` import prefix, so it works on Node 16 (tested on 16.20) as well as 18, 20, 22 and 26. Node older
+  than 16 now stops with a plain message ("Node.js 14.18.0 is too old... needs Node.js 18 or later") instead
+  of failing later. 18+ remains the supported range.
+- **New: `npx -y @sakaniui/mcp --doctor`** prints a report (Node version, platform, whether `npx` is on the
+  PATH, the reference data, the version found in your project) and exercises three real tools. Also
+  `--version` and `--help`.
+- **The build now guards against this**: it fails if the server uses an API newer than Node 16, and it runs a
+  real tool call with `Object.hasOwn` removed from the runtime.
+- **Troubleshooting** added to the README, the package README and sakaniui.com/docs/ai (PATH problems in
+  desktop editors, Windows, proxies, stale `npx` caches).
+- Correction: the 0.8.12 notes said "250+" aliases; the number is 249.
+
+## 0.8.12
+
+Found while testing 0.8.11 in Claude Code: after writing correct code, the agent offered to wrap the
+delete button in "SakaniUI's Dialog/AlertDialog". Neither exists; the component is `Modal`. It named it
+from memory without looking it up.
+
+- **`aliases` in `manifest.json`**: the other names people use for a component, 250+ across 61 components
+  (dialog, alert dialog -> `Modal`; snackbar -> `Toast`; navbar, app bar -> `TopBar`; date picker ->
+  `Calendar`; loader -> `Spinner`; toggle -> `Switch`; autocomplete -> `Combobox`; dropzone ->
+  `FileUpload`; pricing table -> `PricingTableBlock`; ...). Hand-written; the build checks every one
+  points at a real component and never shadows a real name.
+- **MCP:** `search_components` ranks by alias ("dialog" finds `Modal` first; a plain exact name such as
+  "button" always wins). `get_component`, `check_usage` and `check_code` now say what the name is here:
+  *"Dialog is not exported by @sakaniui/react. In SakaniUI that is `Modal` (Confirmation dialog)."*
+- `AGENTS.md` lists the most common renamings.
+
 ## 0.8.11
 
 Found by asking Claude Code, with the published 0.8.10 MCP server, to add a delete button to a table row:

package/README.md

@@ -155,6 +155,27 @@ Tools: `search_components`, `get_component` (with a type-checked `example`), `se
   an export that is not described, a prop that is not declared, an example that does not type-check, an
   icon name that does not exist, a token that is not defined, or anything that looks like a private reference.
 
+### Troubleshooting the MCP server
+
+Run this in a terminal first. It checks Node, the data, the tools and your project, and prints a report you can
+paste when asking for help:
+
+```bash
+npx -y @sakaniui/mcp --doctor
+```
+
+| Symptom | Fix |
+|---|---|
+| `spawn npx ENOENT`, or the editor cannot start it | Desktop editors often start with a smaller `PATH` than your terminal (common with nvm and Homebrew). Use the full path: run `which npx` (macOS/Linux) or `where npx` (Windows) and put that in `"command"`, e.g. `"/opt/homebrew/bin/npx"`. |
+| Windows | `npx` is a `.cmd` script: use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@sakaniui/mcp"]`. |
+| Connects, but tool calls fail (before 0.8.13) | Node older than 16.9. Update Node (18 or later is supported), or use `@sakaniui/mcp@latest`. |
+| "Node.js ... is too old" | Install Node 18 or later: https://nodejs.org (check with `node --version`). |
+| Times out on the first start | The first run downloads about 200 kB. Run `npx -y @sakaniui/mcp --version` once in a terminal to warm the cache, then restart the editor. |
+| Behind a company proxy or private npm registry | The machine must reach `registry.npmjs.org` (check `npm config get registry`) and `@sakaniui/*` packages must be allowed. |
+| Odd `npx` errors, or an old version keeps running | Delete the `_npx` folder inside your npm cache (find it with `npm config get cache`), then restart the editor. |
+| Added it but no tools appear | Restart the editor. In Claude Code run `/mcp` and look for `sakaniui` with 10 tools. |
+| `Failed to connect` after typing the command by hand | Check the package name for a full-width `＠` or stray characters; copy the command from here instead. |
+
 ## Glass & liquid glass
 
 Glass is built into the theme system, not added component by component. Next to light/dark, SakaniUI has a second axis — **Surface** — with three modes: **Solid** (the default), **Glass** (frosted translucency) and **Liquid** (Apple-style liquid glass: the backdrop *bends* at the edges like a lens, with a faint color fringe, rim light and depth). Components read a small set of `--surface-*` tokens, so switching an area from Solid to Glass or Liquid re-themes everything inside it at once — in the Figma file (variable modes and effect styles) and in code. Solid stays pixel-identical to before.

package/bin/sakaniui-mcp.mjs

@@ -17,10 +17,21 @@
  * manifest era, answers come from this copy but every component is checked against its `since`
  * release and flagged when the project does not have it yet.
  */
-import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline';
-import { fileURLToPath } from 'node:url';
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+
+/* ---------- Node version guard ---------- */
+// Tested on Node 16, 18, 20, 22 and 26; 18+ is the supported range. Say so plainly instead of failing later in a way
+// that looks like the server is broken (before 0.8.13 a Node older than 16.9 connected, listed its tools, then failed every call).
+const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
+if (NODE_MAJOR < 16) {
+  process.stderr.write(`sakaniui-mcp: Node.js ${process.versions.node} is too old. SakaniUI's MCP server needs Node.js 18 or later (https://nodejs.org). Run \`node --version\` to check.\n`);
+  process.exit(1);
+}
+// `Object.hasOwn` is Node 16.9+; this works everywhere
+const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
 
 const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -48,6 +59,21 @@ function findProjectInstall() {
 }
 
 // inside @sakaniui/react the data sits next to bin/; inside @sakaniui/mcp it is copied into data/
+/* ---------- command line: --version, --help, --doctor ---------- */
+const argvFlag = (...names) => process.argv.slice(2).some((a) => names.includes(a));
+if (argvFlag('--help', '-h')) {
+  process.stdout.write(`sakaniui-mcp: the SakaniUI MCP server (read-only). Your editor starts it; there is nothing to type.
+
+  npx -y @sakaniui/mcp                 start the server (waits silently for an editor)
+  npx -y @sakaniui/mcp --doctor        check this machine and print a report (paste it when asking for help)
+  npx -y @sakaniui/mcp --version       print the version
+  npx -y @sakaniui/mcp --project <dir> answer for the @sakaniui/react installed in <dir>
+
+Docs: https://www.sakaniui.com/docs/ai
+`);
+  process.exit(0);
+}
+
 const bundled = loadInstall(fs.existsSync(path.join(ownRoot, 'dist', 'manifest.json')) ? ownRoot : path.join(ownRoot, 'data'));
 if (!bundled || !bundled.manifest) {
   process.stderr.write('sakaniui-mcp: dist/manifest.json not found. Run `npm run build:lib` (or install a published version).\n');
@@ -121,6 +147,22 @@ function propTooNew(c, p, value, installed = projectVersion) {
 
 /* ---------- helpers ---------- */
 const byName = new Map(manifest.components.map((c) => [c.name.toLowerCase(), c]));
+// Common names for components ("Dialog" -> Modal). Only used when a name is not found, and to rank search results.
+const norm = (x) => String(x).toLowerCase().replace(/[^a-z0-9]/g, '');
+const aliasIndex = new Map(); // normalized alias -> components
+for (const c of manifest.components) for (const a of c.aliases || []) { const k = norm(a); if (!aliasIndex.has(k)) aliasIndex.set(k, []); aliasIndex.get(k).push(c); }
+/** The real component(s) for a name that does not exist: "Dialog" -> [Modal]. */
+function byAlias(name) {
+  const k = norm(name);
+  const exact = aliasIndex.get(k) || aliasIndex.get(k.replace(/s$/, '')) || [];
+  return [...new Set(exact)].slice(0, 4);
+}
+const aliasHint = (name) => {
+  const hits = byAlias(name);
+  if (!hits.length) return '';
+  return ` ${hits.length === 1 ? `In SakaniUI that is \`${hits[0].name}\` (${hits[0].summary.replace(/\.$/, '')})` : `In SakaniUI that could be ${hits.map((h) => `\`${h.name}\``).join(' or ')}`}.`;
+};
+
 const brief = (c) => {
   const out = { name: c.name, kind: c.kind, category: c.category, import: c.import, since: c.since, summary: c.summary, requiredProps: c.contract.requiredProps };
   if (inInstalled(c) === false) out.availableInInstalled = false;
@@ -150,9 +192,19 @@ const verArg = (args, key) => {
 };
 const firstError = (...rs) => rs.find((r) => r.err);
 
-function score(c, terms) {
+function score(c, terms, phrase = '') {
   const hay = `${c.name} ${c.category ?? ''} ${c.summary} ${c.props.map((p) => p.name).join(' ')}`.toLowerCase();
   let s = 0;
+  // an alias is the name people use for this component: "dialog" finds Modal, "snackbar" finds Toast
+  const p = norm(phrase);
+  let aliasWords = 0;
+  for (const a of c.aliases || []) {
+    const na = norm(a);
+    if (na === p || na + 's' === p || na === p + 's') s += 60;
+    else if (na.length >= 4 && p.includes(na)) s += 25;
+    else if (!aliasWords && terms.length && a.toLowerCase().split(/[^a-z0-9]+/).some((w) => w.length >= 3 && terms.includes(w))) { s += 6; aliasWords = 1; } // loosely related: counts once
+  }
+  if (p && norm(c.name) === p) s += 100; // the real name always wins
   for (const t of terms) {
     if (c.name.toLowerCase() === t) s += 20;
     else if (c.name.toLowerCase().includes(t)) s += 8;
@@ -434,7 +486,7 @@ function checkCode(source) {
       if (!c && !isUtility) {
         if (TYPE_LIKE.test(n.imported)) continue; // most likely a type export
         const near = closest(n.imported);
-        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
+        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${aliasHint(n.imported)}${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
       }
       if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
     }
@@ -578,7 +630,7 @@ const tools = {
       const terms = q.value.toLowerCase().split(/\s+/).filter(Boolean);
       const hits = manifest.components
         .filter((c) => !k.value || c.kind === k.value)
-        .map((c) => [score(c, terms), c])
+        .map((c) => [score(c, terms, q.value), c])
         .filter(([s]) => s > 0)
         .sort((a, b) => b[0] - a[0])
         .slice(0, limit)
@@ -594,7 +646,7 @@ const tools = {
     run(args) {
       const n = strArg(args, 'name', { required: true }); if (n.err) return fail(n.err);
       const c = byName.get(n.value.toLowerCase());
-      if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}? Use search_components.`);
+      if (!c) return fail(`No component named "${n.value}".${aliasHint(n.value)} ${closest(n.value).length ? `Did you mean: ${closest(n.value).join(', ')}? ` : ''}Use search_components.`.replace(/\s+/g, ' '));
       const out = { ...c, note: 'Native HTML attributes (className, style, aria-*, event handlers) are also accepted on the root element.' };
       if (c.props.some((p) => p.shape)) out.shapeNote = 'A prop with a `shape` takes an object (or an array of objects) with exactly those fields; `required` fields must be present. In a generic shape, `keyof T & string` means the value must be a field of your own data type.';
       if (c.recipes && c.recipes.length) out.recipeNote = 'See `recipes`: patterns the types alone do not teach, compiled against this release.';
@@ -640,7 +692,7 @@ const tools = {
       const g = strArg(args, 'group'); const q = strArg(args, 'query');
       const e = firstError(g, q); if (e) return fail(e.err);
       const groups = manifest.tokens.groups;
-      if (g.value && !Object.hasOwn(groups, g.value)) return fail(`Unknown token group "${g.value}". Groups: ${Object.keys(groups).join(', ')}`);
+      if (g.value && !has(groups, g.value)) return fail(`Unknown token group "${g.value}". Groups: ${Object.keys(groups).join(', ')}`);
       const needle = q.value?.toLowerCase();
       const out = {};
       for (const [name, toks] of Object.entries(groups)) {
@@ -660,12 +712,12 @@ const tools = {
       if (typeof props !== 'object' || Array.isArray(props)) return fail('"props" must be an object of prop name -> value.');
       if (Object.keys(props).length > 200) return fail('"props" has too many entries (max 200).');
       const c = byName.get(n.value.toLowerCase());
-      if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}?`);
+      if (!c) return fail(`No component named "${n.value}".${aliasHint(n.value)} ${closest(n.value).length ? `Did you mean: ${closest(n.value).join(', ')}?` : ''}`.replace(/\s+/g, ' ').trim());
       const known = new Map(c.props.map((p) => [p.name, p]));
       const errors = [];
       const warnings = [];
       if (inInstalled(c) === false) errors.push(`${c.name} was added in ${c.since}; the project has ${projectVersion}. It does not exist there.`);
-      for (const r of c.contract.requiredProps) if (!Object.hasOwn(props, r)) errors.push(`Missing required prop "${r}".`);
+      for (const r of c.contract.requiredProps) if (!has(props, r)) errors.push(`Missing required prop "${r}".`);
       for (const [k, v] of Object.entries(props)) {
         const p = known.get(k);
         if (!p) { const u = unknownProp(c, k); if (u) (u.level === 'error' ? errors : warnings).push(u.message); continue; }
@@ -783,8 +835,8 @@ function handle(msg) {
         return reply(id, { result: {
           protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
           capabilities: { tools: { listChanged: false } },
-          serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: refVersion },
-          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
+          serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: bundled.version }, // the server's own version, not the data's
+          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); search by the name you would normally use (dialog, snackbar, navbar, date picker) and it maps to the real component; run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
         } });
       }
       case 'ping':
@@ -792,7 +844,7 @@ function handle(msg) {
       case 'tools/list':
         return reply(id, { result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
       case 'tools/call': {
-        const t = typeof params?.name === 'string' && Object.hasOwn(tools, params.name) ? tools[params.name] : null;
+        const t = typeof params?.name === 'string' && has(tools, params.name) ? tools[params.name] : null;
         if (!t) return reply(id, { error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
         const args = params.arguments;
         if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return reply(id, { result: fail('Tool arguments must be an object.') });
@@ -811,6 +863,32 @@ function handle(msg) {
   }
 }
 
+/* ---------- --version and --doctor (no protocol traffic; print and exit) ---------- */
+if (argvFlag('--version', '-v')) { process.stdout.write(`${bundled.version}\n`); process.exit(0); }
+if (argvFlag('--doctor')) {
+  const lines = [];
+  const row = (label, value, ok) => lines.push(`  ${ok === false ? '✘' : ok === 'warn' ? '!' : ok === true ? '✔' : ' '} ${label.padEnd(20)}${value}`);
+  row('server version', bundled.version, true);
+  row('Node.js', NODE_MAJOR >= 18 ? `${process.version}` : `${process.version} (18+ is supported; 16 works but is end-of-life, please update)`, NODE_MAJOR >= 18 ? true : 'warn');
+  row('platform', `${process.platform} ${process.arch}`);
+  row('working folder', process.cwd());
+  row('reference data', `${manifest.components.length} components and blocks, ${Object.values(manifest.tokens.groups).reduce((a, g) => a + Object.keys(g).length, 0)} tokens, ${iconIndex.length} icons, describing @sakaniui/react ${refVersion} (${answeringFromProject ? "taken from your project's install" : 'bundled with this package'})`, manifest.components.length > 100 && iconIndex.length > 1000);
+  row('your project', project ? `@sakaniui/react ${project.version} at ${project.root}` : 'no @sakaniui/react found from this folder (fine for a quick check; run it from your project folder, or pass --project <dir>, to answer for your version)');
+  const exe = process.platform === 'win32' ? ['npx.cmd', 'npx.exe', 'npx'] : ['npx'];
+  const onPath = (process.env.PATH || '').split(path.delimiter).find((d) => d && exe.some((e) => fs.existsSync(path.join(d, e))));
+  row('npx on PATH', onPath ? onPath : 'not found on this PATH', !!onPath);
+  // exercise the real tools, the same code paths an editor calls
+  const probe = (name, args) => { try { const r = tools[name].run(args); return r.isError ? { ok: false, text: r.content[0].text } : { ok: true, text: r.content[0].text }; } catch (e) { return { ok: false, text: String(e && e.message || e) }; } };
+  const s1 = probe('search_components', { query: 'dialog' });
+  row('tool: search', s1.ok && /Modal/.test(s1.text) ? 'search_components("dialog") finds Modal' : `FAILED: ${s1.text.slice(0, 120)}`, s1.ok && /Modal/.test(s1.text));
+  const s2 = probe('check_code', { code: "import { Button } from '@sakaniui/react';\n<Button variant=\"danger\">x</Button>" });
+  row('tool: check_code', s2.ok && /not allowed/.test(s2.text) ? 'catches a wrong prop value' : `FAILED: ${s2.text.slice(0, 120)}`, s2.ok && /not allowed/.test(s2.text));
+  const s3 = probe('get_tokens', { group: 'radius' });
+  row('tool: get_tokens', s3.ok ? 'ok' : `FAILED: ${s3.text.slice(0, 120)}`, s3.ok);
+  process.stdout.write(`SakaniUI MCP doctor\n${lines.join('\n')}\n\nIf your editor still cannot start it: the editor may use a different PATH than this terminal\n(common with nvm and with desktop apps; on Windows use "cmd" with args ["/c","npx","-y","@sakaniui/mcp"]).\nPaste this report when asking for help: https://github.com/samzydd/Sakaniui/issues\n`);
+  process.exit(lines.some((l) => l.includes('✘')) ? 1 : 0);
+}
+
 const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
 rl.on('line', (line) => {
   if (!line.trim()) return;