@sakaniui/mcp 0.8.12 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/bin/sakaniui-mcp.mjs +65 -10
- package/data/AGENTS.md +9 -3
- package/data/CHANGELOG.md +37 -0
- package/data/dist/icon-index.json +1 -1
- package/data/dist/manifest.json +142 -5
- package/data/package.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -51,6 +51,27 @@ show 10 tools.
|
|
|
51
51
|
| `check_compatibility` | compare the reference with the version installed in your project |
|
|
52
52
|
| `get_changelog` | release notes for a version, or everything since yours |
|
|
53
53
|
|
|
54
|
+
## Troubleshooting
|
|
55
|
+
|
|
56
|
+
Run this in a terminal first. It checks Node, the data, the tools and your project, and prints a report you can
|
|
57
|
+
paste when asking for help:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx -y @sakaniui/mcp --doctor
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
| Symptom | Fix |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `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"`. |
|
|
66
|
+
| Windows | `npx` is a `.cmd` script: use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@sakaniui/mcp"]`. |
|
|
67
|
+
| 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`. |
|
|
68
|
+
| "Node.js ... is too old" | Install Node 18 or later: https://nodejs.org (check with `node --version`). |
|
|
69
|
+
| 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. |
|
|
70
|
+
| 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. |
|
|
71
|
+
| 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. |
|
|
72
|
+
| Added it but no tools appear | Restart the editor. In Claude Code run `/mcp` and look for `sakaniui` with 10 tools. |
|
|
73
|
+
| `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. |
|
|
74
|
+
|
|
54
75
|
## Matches your version
|
|
55
76
|
|
|
56
77
|
It finds the `@sakaniui/react` installed in your project (the folder it runs in, or `--project <dir>`) and
|
package/bin/sakaniui-mcp.mjs
CHANGED
|
@@ -17,10 +17,21 @@
|
|
|
17
17
|
* manifest era, answers come from this copy but every component is checked against its `since`
|
|
18
18
|
* release and flagged when the project does not have it yet.
|
|
19
19
|
*/
|
|
20
|
-
import fs from '
|
|
21
|
-
import path from '
|
|
22
|
-
import readline from '
|
|
23
|
-
import { fileURLToPath } from '
|
|
20
|
+
import fs from 'fs';
|
|
21
|
+
import path from 'path';
|
|
22
|
+
import readline from 'readline';
|
|
23
|
+
import { fileURLToPath } from 'url';
|
|
24
|
+
|
|
25
|
+
/* ---------- Node version guard ---------- */
|
|
26
|
+
// Tested on Node 16, 18, 20, 22 and 26; 18+ is the supported range. Say so plainly instead of failing later in a way
|
|
27
|
+
// 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).
|
|
28
|
+
const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
|
|
29
|
+
if (NODE_MAJOR < 16) {
|
|
30
|
+
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`);
|
|
31
|
+
process.exit(1);
|
|
32
|
+
}
|
|
33
|
+
// `Object.hasOwn` is Node 16.9+; this works everywhere
|
|
34
|
+
const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
|
|
24
35
|
|
|
25
36
|
const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
26
37
|
|
|
@@ -48,6 +59,21 @@ function findProjectInstall() {
|
|
|
48
59
|
}
|
|
49
60
|
|
|
50
61
|
// inside @sakaniui/react the data sits next to bin/; inside @sakaniui/mcp it is copied into data/
|
|
62
|
+
/* ---------- command line: --version, --help, --doctor ---------- */
|
|
63
|
+
const argvFlag = (...names) => process.argv.slice(2).some((a) => names.includes(a));
|
|
64
|
+
if (argvFlag('--help', '-h')) {
|
|
65
|
+
process.stdout.write(`sakaniui-mcp: the SakaniUI MCP server (read-only). Your editor starts it; there is nothing to type.
|
|
66
|
+
|
|
67
|
+
npx -y @sakaniui/mcp start the server (waits silently for an editor)
|
|
68
|
+
npx -y @sakaniui/mcp --doctor check this machine and print a report (paste it when asking for help)
|
|
69
|
+
npx -y @sakaniui/mcp --version print the version
|
|
70
|
+
npx -y @sakaniui/mcp --project <dir> answer for the @sakaniui/react installed in <dir>
|
|
71
|
+
|
|
72
|
+
Docs: https://www.sakaniui.com/docs/ai
|
|
73
|
+
`);
|
|
74
|
+
process.exit(0);
|
|
75
|
+
}
|
|
76
|
+
|
|
51
77
|
const bundled = loadInstall(fs.existsSync(path.join(ownRoot, 'dist', 'manifest.json')) ? ownRoot : path.join(ownRoot, 'data'));
|
|
52
78
|
if (!bundled || !bundled.manifest) {
|
|
53
79
|
process.stderr.write('sakaniui-mcp: dist/manifest.json not found. Run `npm run build:lib` (or install a published version).\n');
|
|
@@ -442,8 +468,10 @@ function checkCode(source) {
|
|
|
442
468
|
if (imp.def) errors.push({ line: imp.line, message: `${entry} has no default export; use a named import: import { ${imp.def} } from '${entry}';` });
|
|
443
469
|
for (const n of imp.names) {
|
|
444
470
|
if (n.typeOnly) continue;
|
|
445
|
-
const
|
|
446
|
-
const isUtility =
|
|
471
|
+
const util = manifest.utilities?.find((u) => u.name === n.imported);
|
|
472
|
+
const isUtility = !!util;
|
|
473
|
+
// an exact helper name (toast) is not a mis-cased component (Toast)
|
|
474
|
+
const c = isUtility ? undefined : byName.get(n.imported.toLowerCase());
|
|
447
475
|
if (entry === '@sakaniui/react/icons') {
|
|
448
476
|
if (!iconNames.has(n.imported) && !iconOtherExports.has(n.imported)) {
|
|
449
477
|
const hint = searchIcons(n.imported, 3).map((i) => i.name);
|
|
@@ -463,6 +491,7 @@ function checkCode(source) {
|
|
|
463
491
|
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.` });
|
|
464
492
|
}
|
|
465
493
|
if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
|
|
494
|
+
if (util && inInstalled(util) === false) errors.push({ line: imp.line, message: `${util.name} was added in ${util.since}; the project has ${projectVersion}.` });
|
|
466
495
|
}
|
|
467
496
|
}
|
|
468
497
|
|
|
@@ -666,7 +695,7 @@ const tools = {
|
|
|
666
695
|
const g = strArg(args, 'group'); const q = strArg(args, 'query');
|
|
667
696
|
const e = firstError(g, q); if (e) return fail(e.err);
|
|
668
697
|
const groups = manifest.tokens.groups;
|
|
669
|
-
if (g.value && !
|
|
698
|
+
if (g.value && !has(groups, g.value)) return fail(`Unknown token group "${g.value}". Groups: ${Object.keys(groups).join(', ')}`);
|
|
670
699
|
const needle = q.value?.toLowerCase();
|
|
671
700
|
const out = {};
|
|
672
701
|
for (const [name, toks] of Object.entries(groups)) {
|
|
@@ -691,7 +720,7 @@ const tools = {
|
|
|
691
720
|
const errors = [];
|
|
692
721
|
const warnings = [];
|
|
693
722
|
if (inInstalled(c) === false) errors.push(`${c.name} was added in ${c.since}; the project has ${projectVersion}. It does not exist there.`);
|
|
694
|
-
for (const r of c.contract.requiredProps) if (!
|
|
723
|
+
for (const r of c.contract.requiredProps) if (!has(props, r)) errors.push(`Missing required prop "${r}".`);
|
|
695
724
|
for (const [k, v] of Object.entries(props)) {
|
|
696
725
|
const p = known.get(k);
|
|
697
726
|
if (!p) { const u = unknownProp(c, k); if (u) (u.level === 'error' ? errors : warnings).push(u.message); continue; }
|
|
@@ -809,7 +838,7 @@ function handle(msg) {
|
|
|
809
838
|
return reply(id, { result: {
|
|
810
839
|
protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
|
|
811
840
|
capabilities: { tools: { listChanged: false } },
|
|
812
|
-
serverInfo: { name: 'sakaniui', title: 'SakaniUI', version:
|
|
841
|
+
serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: bundled.version }, // the server's own version, not the data's
|
|
813
842
|
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}` : ''}`,
|
|
814
843
|
} });
|
|
815
844
|
}
|
|
@@ -818,7 +847,7 @@ function handle(msg) {
|
|
|
818
847
|
case 'tools/list':
|
|
819
848
|
return reply(id, { result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
|
|
820
849
|
case 'tools/call': {
|
|
821
|
-
const t = typeof params?.name === 'string' &&
|
|
850
|
+
const t = typeof params?.name === 'string' && has(tools, params.name) ? tools[params.name] : null;
|
|
822
851
|
if (!t) return reply(id, { error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
|
|
823
852
|
const args = params.arguments;
|
|
824
853
|
if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return reply(id, { result: fail('Tool arguments must be an object.') });
|
|
@@ -837,6 +866,32 @@ function handle(msg) {
|
|
|
837
866
|
}
|
|
838
867
|
}
|
|
839
868
|
|
|
869
|
+
/* ---------- --version and --doctor (no protocol traffic; print and exit) ---------- */
|
|
870
|
+
if (argvFlag('--version', '-v')) { process.stdout.write(`${bundled.version}\n`); process.exit(0); }
|
|
871
|
+
if (argvFlag('--doctor')) {
|
|
872
|
+
const lines = [];
|
|
873
|
+
const row = (label, value, ok) => lines.push(` ${ok === false ? '✘' : ok === 'warn' ? '!' : ok === true ? '✔' : ' '} ${label.padEnd(20)}${value}`);
|
|
874
|
+
row('server version', bundled.version, true);
|
|
875
|
+
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');
|
|
876
|
+
row('platform', `${process.platform} ${process.arch}`);
|
|
877
|
+
row('working folder', process.cwd());
|
|
878
|
+
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);
|
|
879
|
+
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)');
|
|
880
|
+
const exe = process.platform === 'win32' ? ['npx.cmd', 'npx.exe', 'npx'] : ['npx'];
|
|
881
|
+
const onPath = (process.env.PATH || '').split(path.delimiter).find((d) => d && exe.some((e) => fs.existsSync(path.join(d, e))));
|
|
882
|
+
row('npx on PATH', onPath ? onPath : 'not found on this PATH', !!onPath);
|
|
883
|
+
// exercise the real tools, the same code paths an editor calls
|
|
884
|
+
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) }; } };
|
|
885
|
+
const s1 = probe('search_components', { query: 'dialog' });
|
|
886
|
+
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));
|
|
887
|
+
const s2 = probe('check_code', { code: "import { Button } from '@sakaniui/react';\n<Button variant=\"danger\">x</Button>" });
|
|
888
|
+
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));
|
|
889
|
+
const s3 = probe('get_tokens', { group: 'radius' });
|
|
890
|
+
row('tool: get_tokens', s3.ok ? 'ok' : `FAILED: ${s3.text.slice(0, 120)}`, s3.ok);
|
|
891
|
+
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`);
|
|
892
|
+
process.exit(lines.some((l) => l.includes('✘')) ? 1 : 0);
|
|
893
|
+
}
|
|
894
|
+
|
|
840
895
|
const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
|
|
841
896
|
rl.on('line', (line) => {
|
|
842
897
|
if (!line.trim()) return;
|
package/data/AGENTS.md
CHANGED
|
@@ -78,7 +78,7 @@ import { Button, Card } from '@sakaniui/react';
|
|
|
78
78
|
(`aria-label`, or `label` on `socialLinks`). Status changes use live regions (`Alert`, `Toast`,
|
|
79
79
|
`Spinner`, `EmptyState` are `role="status"`/`alert`). Never remove focus rings.
|
|
80
80
|
7. **Don't fake what the system doesn't do.** `Toast` is presentational — you own queueing and
|
|
81
|
-
positioning. `Menu` is a surface — you own anchoring (pair it with `Popover`). Dragging is a
|
|
81
|
+
positioning (for a ready-made stack, use `Toaster` and `toast()`). `Menu` is a surface — you own anchoring (pair it with `Popover`). Dragging is a
|
|
82
82
|
look, not a behaviour. Check "Behaviour you must supply" in the table below before assuming.
|
|
83
83
|
8. **Compose in slots, don't fork.** Components expose slots (`leading`, `trailing`, `meta`,
|
|
84
84
|
`assignees`, `icon`, `actions`). Fill a slot with other system components rather than copying a
|
|
@@ -153,7 +153,7 @@ CSS of a component into your own file.
|
|
|
153
153
|
Format: **Use for** · **Why it is built this way** · **Not for / instead**.
|
|
154
154
|
|
|
155
155
|
**Looking for a component by another name?** SakaniUI uses its own names. A *dialog* or *alert dialog* is
|
|
156
|
-
`Modal`; a *snackbar* is `Toast
|
|
156
|
+
`Modal`; a *snackbar* is `Toast` (or `Toaster` + `toast()` for a managed stack); a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
|
|
157
157
|
*date picker* is `Calendar`; a *loader* is `Spinner`; a *toggle* is `Switch`; a *banner* is `Announcement`;
|
|
158
158
|
*autocomplete* is `Combobox`. There is no `Dialog`, `AlertDialog`, `Snackbar` or `Navbar`. Each component
|
|
159
159
|
lists its other names under `aliases` in `manifest.json`, and `search_components` understands them.
|
|
@@ -174,6 +174,11 @@ lists its other names under `aliases` in `manifest.json`, and `search_components
|
|
|
174
174
|
- **Toast** — Use for short-lived confirmation or error after an action. *Why:* presentational only;
|
|
175
175
|
queueing and positioning are the app's job, so it fits any notification system. *Not for* anything the user
|
|
176
176
|
must act on — a toast disappears.
|
|
177
|
+
- **Toaster + toast()** — Use for notifications you trigger from code: mount one `<Toaster />`, call
|
|
178
|
+
`toast.success('Saved')` from anywhere. *Why:* it owns queueing, position (6), the 4s timer, the pile that
|
|
179
|
+
spreads on hover and swipe-to-dismiss, so the app does not. `toast.promise` turns one toast from loading
|
|
180
|
+
into success or error. *Not for* anything the user must act on — a toast disappears; a plain static card
|
|
181
|
+
→ `Toast`. Needs `Toaster` mounted once, and `toast()` is a function, not a component.
|
|
177
182
|
- **Badge** — Use for a short status, category or count. *Why:* 6 colours × subtle/solid, no sizes, no
|
|
178
183
|
borders — it is a label, not a control. *Not for* clickable filters → `FilterChip`.
|
|
179
184
|
- **Tooltip** — Use for brief supplementary text on hover/focus. *Why:* pure CSS, so it works with
|
|
@@ -261,7 +266,8 @@ and **tell the user when you are composing** rather than implying a dedicated co
|
|
|
261
266
|
|
|
262
267
|
| Component | You own |
|
|
263
268
|
|---|---|
|
|
264
|
-
| Toast | queueing, positioning, auto-dismiss timing |
|
|
269
|
+
| Toast | queueing, positioning, auto-dismiss timing (or use `Toaster`) |
|
|
270
|
+
| Toaster | mounting it once; it handles the rest |
|
|
265
271
|
| Menu | anchoring/positioning (pair with Popover) |
|
|
266
272
|
| BoardCard `dragging` | drag-and-drop logic and drop targets |
|
|
267
273
|
| BoardColumn `loading` | the skeleton cards inside it |
|
package/data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,43 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@sakaniui/react` are documented here.
|
|
4
4
|
|
|
5
|
+
## 0.9.0
|
|
6
|
+
|
|
7
|
+
- **New: `Toaster` and `toast()`**, a managed toast stack (Sonner-style) built from the new *↳ Sonner* page in Figma.
|
|
8
|
+
Mount one `<Toaster />`, then call `toast()`, `toast.success()`, `.info()`, `.warning()`, `.error()`,
|
|
9
|
+
`.loading()`, `.promise()` and `.dismiss()` from anywhere.
|
|
10
|
+
- New toasts rise in from the edge; older ones pile up behind the newest (lifted 14px, shrunk 5% per level,
|
|
11
|
+
content hidden, three visible). Hover or focus spreads the pile into a list and pauses the 4s timers;
|
|
12
|
+
leaving folds it back. Swipe a toast towards its edge to dismiss it (past 45px, or a quick flick, it flies
|
|
13
|
+
out in 200ms; otherwise it springs back in 400ms). Motion is 400ms `ease`.
|
|
14
|
+
- Options per toast: `description`, `icon`, `action`, `cancel`, `closeButton`, `duration`, `dismissible`,
|
|
15
|
+
`richColors`, `id` (update in place), `onDismiss`, `onAutoClose`. On `Toaster`: `position` (six),
|
|
16
|
+
`richColors`, `closeButton`, `expand`, `visibleToasts`, `duration`, `gap`, `offset`, `mobileOffset`,
|
|
17
|
+
`hotkey` (alt+T focuses the stack; Escape folds it).
|
|
18
|
+
- Light, dark and glass surfaces through the existing tokens; reduced motion keeps the fades only; errors
|
|
19
|
+
are announced assertively.
|
|
20
|
+
- The existing `Toast` is unchanged: it stays the static, presentational card.
|
|
21
|
+
- Agent contract: `Toaster` is in the manifest with recipes (show a toast, a promise toast) and the aliases
|
|
22
|
+
*sonner*, *toast stack*, *toast provider*. (`toaster` now means this component, not `Toast`.)
|
|
23
|
+
|
|
24
|
+
## 0.8.13
|
|
25
|
+
|
|
26
|
+
A user reported the MCP server "didn't work". Reproduced: on a Node older than 16.9 the server connected
|
|
27
|
+
and listed its tools, then **every tool call failed** with `Object.hasOwn is not a function`.
|
|
28
|
+
|
|
29
|
+
- **Fixed: tool calls failing on older Node.** The server no longer uses `Object.hasOwn` (Node 16.9+) or the
|
|
30
|
+
`node:` import prefix, so it works on Node 16 (tested on 16.20) as well as 18, 20, 22 and 26. Node older
|
|
31
|
+
than 16 now stops with a plain message ("Node.js 14.18.0 is too old... needs Node.js 18 or later") instead
|
|
32
|
+
of failing later. 18+ remains the supported range.
|
|
33
|
+
- **New: `npx -y @sakaniui/mcp --doctor`** prints a report (Node version, platform, whether `npx` is on the
|
|
34
|
+
PATH, the reference data, the version found in your project) and exercises three real tools. Also
|
|
35
|
+
`--version` and `--help`.
|
|
36
|
+
- **The build now guards against this**: it fails if the server uses an API newer than Node 16, and it runs a
|
|
37
|
+
real tool call with `Object.hasOwn` removed from the runtime.
|
|
38
|
+
- **Troubleshooting** added to the README, the package README and sakaniui.com/docs/ai (PATH problems in
|
|
39
|
+
desktop editors, Windows, proxies, stale `npx` caches).
|
|
40
|
+
- Correction: the 0.8.12 notes said "250+" aliases; the number is 249.
|
|
41
|
+
|
|
5
42
|
## 0.8.12
|
|
6
43
|
|
|
7
44
|
Found while testing 0.8.11 in Claude Code: after writing correct code, the agent offered to wrap the
|