@sakaniui/mcp 0.8.13 → 0.10.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 CHANGED
@@ -1,8 +1,9 @@
1
1
  # @sakaniui/mcp
2
2
 
3
- A [Model Context Protocol](https://modelcontextprotocol.io) server for [SakaniUI](https://www.sakaniui.com).
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for [SakaniUI](https://www.sakaniui.com),
4
+ the open-source React design system with 1500+ components and variants.
4
5
  It lets an AI assistant (Claude Code, Cursor, Windsurf, Claude Desktop, ...) look the design system up
5
- instead of guessing: components, props, allowed values, tokens and icons, plus a checker for the code it
6
+ instead of guessing: components, props, allowed values, tokens, icons and emoji, plus a checker for the code it
6
7
  writes.
7
8
 
8
9
  Read-only, no dependencies, starts in about a second.
@@ -44,6 +45,7 @@ show 10 tools.
44
45
  | `get_component` | full contract for one: props, types, allowed values, required props, and a type-checked `example` |
45
46
  | `list_components` | browse everything, by kind or category |
46
47
  | `search_icons` | find real icon names by meaning ("delete" gives `IconTrash`) |
48
+ | `search_emoji` | find real emoji names by meaning ("party" gives `EmojiPartyPopper`) |
47
49
  | `check_code` | check a whole snippet: imports, required props, allowed values, icon names, and the field names of object props like table columns (the code is read, never run) |
48
50
  | `check_usage` | check one component's props |
49
51
  | `get_tokens` | the design tokens that exist |
@@ -42,7 +42,7 @@ const readJson = (root, rel) => { try { return JSON.parse(readText(root, rel));
42
42
  function loadInstall(root) {
43
43
  const pkg = readJson(root, 'package.json');
44
44
  if (!pkg || pkg.name !== '@sakaniui/react') return null;
45
- return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), icons: readJson(root, 'dist/icon-index.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
45
+ return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), icons: readJson(root, 'dist/icon-index.json'), emoji: readJson(root, 'dist/emoji-index.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
46
46
  }
47
47
 
48
48
  function findProjectInstall() {
@@ -93,6 +93,7 @@ const manifest = active.manifest;
93
93
  const guide = active.guide || bundled.guide || '';
94
94
  const changelog = active.changelog || bundled.changelog || '';
95
95
  const iconIndex = (active.icons && active.icons.icons) || (bundled.icons && bundled.icons.icons) || [];
96
+ const emojiIndex = (active.emoji && active.emoji.emoji) || (bundled.emoji && bundled.emoji.emoji) || [];
96
97
  const projectVersion = project ? project.version : null;
97
98
 
98
99
  // The HTML attributes React accepts (shipped in the manifest since 0.8.10; older manifests use the fallback list).
@@ -312,6 +313,34 @@ function iconProblem(propName, raw, importedElsewhere = new Set(), localNames =
312
313
  return `"${v}" is not a SakaniUI icon.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''} Use search_icons to find the real name.`;
313
314
  }
314
315
 
316
+ /* ---------- emoji ---------- */
317
+ const emojiNames = new Set(emojiIndex.map((e) => e.name));
318
+ const emojiOtherExports = new Set(((active.emoji && active.emoji.other) || (bundled.emoji && bundled.emoji.other)) || []);
319
+ const EMOJI_SINCE = '0.10.0';
320
+ const emojiWords = (name) => name.replace(/^Emoji/, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Za-z])(\d)/g, '$1 $2').toLowerCase();
321
+
322
+ function searchEmoji(query, limit = 12) {
323
+ const terms = String(query).toLowerCase().replace(/emoji/g, ' ').split(/[^a-z0-9]+/).filter(Boolean);
324
+ if (!terms.length) return [];
325
+ return emojiIndex
326
+ .map((e) => {
327
+ const words = emojiWords(e.name).split(' ');
328
+ let s = 0;
329
+ for (const t of terms) {
330
+ if (words.join(' ') === t) s += 30;
331
+ else if (words[0] === t) s += 12;
332
+ else if (words.includes(t)) s += 8;
333
+ else if (words.some((w) => w.startsWith(t))) s += 4;
334
+ if ((e.category || '').toLowerCase().includes(t)) s += 1;
335
+ }
336
+ return [s - words.length * 0.1, e];
337
+ })
338
+ .filter(([s]) => s > 0.5)
339
+ .sort((a, b) => b[0] - a[0])
340
+ .slice(0, limit)
341
+ .map(([, e]) => e);
342
+ }
343
+
315
344
  // Attributes every component forwards to its root element. A prop outside this list and the contract is worth a warning.
316
345
  const NATIVE_FALLBACK = /^(className|style|id|ref|key|children|role|tabIndex|title|hidden|lang|dir|slot|on[A-Z].*|aria-.*|data-.*|href|target|rel|download|name|type|value|defaultValue|checked|defaultChecked|disabled|required|readOnly|placeholder|htmlFor|form|autoFocus|autoComplete|autoCapitalize|spellCheck|inputMode|pattern|min|max|step|minLength|maxLength|rows|cols|multiple|accept|src|srcSet|alt|width|height|loading|draggable|tabindex|ariaLabel)$/;
317
346
 
@@ -461,15 +490,26 @@ function checkCode(source) {
461
490
  for (const imp of imports) {
462
491
  if (!imp.from.startsWith('@sakaniui/react')) continue;
463
492
  const entry = imp.from;
464
- if (!['@sakaniui/react', '@sakaniui/react/blocks', '@sakaniui/react/icons'].includes(entry)) {
465
- if (imp.names.length) errors.push({ line: imp.line, message: `"${entry}" has no named exports. Import components from @sakaniui/react, blocks from @sakaniui/react/blocks and icons from @sakaniui/react/icons.` });
493
+ if (!['@sakaniui/react', '@sakaniui/react/blocks', '@sakaniui/react/icons', '@sakaniui/react/emoji'].includes(entry)) {
494
+ if (imp.names.length) errors.push({ line: imp.line, message: `"${entry}" has no named exports. Import components from @sakaniui/react, blocks from @sakaniui/react/blocks icons from @sakaniui/react/icons and emoji from @sakaniui/react/emoji.` });
466
495
  continue;
467
496
  }
468
497
  if (imp.def) errors.push({ line: imp.line, message: `${entry} has no default export; use a named import: import { ${imp.def} } from '${entry}';` });
469
498
  for (const n of imp.names) {
470
499
  if (n.typeOnly) continue;
471
- const c = byName.get(n.imported.toLowerCase());
472
- const isUtility = manifest.utilities?.some((u) => u.name === n.imported);
500
+ const util = manifest.utilities?.find((u) => u.name === n.imported);
501
+ const isUtility = !!util;
502
+ // an exact helper name (toast) is not a mis-cased component (Toast)
503
+ const c = isUtility ? undefined : byName.get(n.imported.toLowerCase());
504
+ if (entry === '@sakaniui/react/emoji') {
505
+ if (!emojiNames.has(n.imported) && !emojiOtherExports.has(n.imported)) {
506
+ const hint = searchEmoji(n.imported, 3).map((e) => e.name);
507
+ errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react/emoji.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''} Use search_emoji to find the real name.` });
508
+ } else if (inInstalled({ since: EMOJI_SINCE }) === false) {
509
+ errors.push({ line: imp.line, message: `@sakaniui/react/emoji was added in ${EMOJI_SINCE}; the project has ${projectVersion}.` });
510
+ }
511
+ continue;
512
+ }
473
513
  if (entry === '@sakaniui/react/icons') {
474
514
  if (!iconNames.has(n.imported) && !iconOtherExports.has(n.imported)) {
475
515
  const hint = searchIcons(n.imported, 3).map((i) => i.name);
@@ -489,6 +529,7 @@ function checkCode(source) {
489
529
  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.` });
490
530
  }
491
531
  if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
532
+ if (util && inInstalled(util) === false) errors.push({ line: imp.line, message: `${util.name} was added in ${util.since}; the project has ${projectVersion}.` });
492
533
  }
493
534
  }
494
535
 
@@ -784,8 +825,20 @@ const tools = {
784
825
  return text({ import: "import { IconName } from '@sakaniui/react/icons';", usage: 'icon={IconName} (the component, not <IconName />)', icons: hits });
785
826
  },
786
827
  },
828
+ search_emoji: {
829
+ description: 'Find real emoji component names (Fluent Emoji, exported from @sakaniui/react/emoji) by meaning, e.g. "rocket", "party", "thumbs up". Emoji are full colour and rendered as elements (<EmojiRocket />), not passed to icon props. Only names returned here exist.',
830
+ inputSchema: { type: 'object', properties: { query: { type: 'string' }, limit: { type: 'number' } }, required: ['query'] },
831
+ run(args) {
832
+ const q = strArg(args, 'query', { required: true }); if (q.err) return fail(q.err);
833
+ if (!emojiIndex.length) return fail('The emoji index is not available in this install (emoji arrived in 0.10.0).');
834
+ const limit = Number.isInteger(args.limit) ? Math.min(Math.max(args.limit, 1), 30) : 12;
835
+ const hits = searchEmoji(q.value, limit).map((e) => { const o = { name: e.name, label: e.label, char: e.char, category: e.category }; if (e.tones) o.tones = true; return o; });
836
+ if (!hits.length) return text(`No emoji matches "${q.value}". Try a simpler word (e.g. "party" rather than "celebration").`);
837
+ return text({ import: "import { EmojiName } from '@sakaniui/react/emoji';", usage: '<EmojiName size={24} /> (an element, not an icon prop). Where tones is true: tone="light" | "medium-light" | "medium" | "medium-dark" | "dark".', emoji: hits });
838
+ },
839
+ },
787
840
  check_code: {
788
- description: 'Check a JSX/TSX snippet you wrote: imports from @sakaniui/react (and /blocks, /icons) must exist, every SakaniUI element must have its required props, prop values must be allowed, and icon props must be real icon components passed as components. The code is only read, never run. Run it on every snippet before you answer.',
841
+ description: 'Check a JSX/TSX snippet you wrote: imports from @sakaniui/react (and /blocks, /icons, /emoji) must exist, every SakaniUI element must have its required props, prop values must be allowed, and icon props must be real icon components passed as components. The code is only read, never run. Run it on every snippet before you answer.',
789
842
  inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The snippet, including its import lines.' } }, required: ['code'] },
790
843
  run(args) {
791
844
  const code = args.code;
@@ -836,7 +889,7 @@ function handle(msg) {
836
889
  protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
837
890
  capabilities: { tools: { listChanged: false } },
838
891
  serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: bundled.version }, // the server's own version, not the data's
839
- 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}` : ''}`,
892
+ 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 and emoji names with search_emoji (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}` : ''}`,
840
893
  } });
841
894
  }
842
895
  case 'ping':
package/data/AGENTS.md CHANGED
@@ -16,7 +16,7 @@ import manifest from '@sakaniui/react/manifest.json';
16
16
  const button = manifest.components.find((c) => c.name === 'Button'); // props[], contract.requiredProps
17
17
  ```
18
18
  Editors can query the same data through the bundled MCP server
19
- (`npx -y @sakaniui/mcp`): `search_components`, `get_component`, `search_icons`,
19
+ (`npx -y @sakaniui/mcp`): `search_components`, `get_component`, `search_icons`, `search_emoji`,
20
20
  `check_code`, `check_usage`, `get_tokens`, `get_guide`, `check_compatibility`, `get_changelog`.
21
21
 
22
22
  **Object props have a shape.** A prop such as `columns`, `items`, `options`, `plans` or `data` takes an array
@@ -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
@@ -148,12 +148,27 @@ CSS of a component into your own file.
148
148
  - Component props that take an icon (`icon`, `leftIcon` ...) take the component itself, typed
149
149
  `IconComponent`; Sakani, Lucide and Tabler React icons all fit.
150
150
 
151
+ ## 4d. Emoji
152
+
153
+ - Full-colour emoji (Fluent Emoji, Flat) live in `@sakaniui/react/emoji`, one component per emoji:
154
+ `EmojiRocket`, `EmojiPartyPopper`, `EmojiWavingHand` (1,594 emoji; names are `Emoji` + PascalCase of the
155
+ Unicode name, so find them with `search_emoji` instead of guessing). Each is tree-shaken on its own.
156
+ - They are pictures, not icons: render them as elements (`<EmojiRocket />`), never pass them to an `icon`
157
+ prop, and do not expect `currentColor` (they keep their own colours). Use an icon for UI chrome and an
158
+ emoji for expression: reactions, empty states, celebration, user-chosen labels.
159
+ - 311 people and hand emoji take `tone`: `<EmojiWavingHand tone="medium-dark" />` (`light`, `medium-light`,
160
+ `medium`, `medium-dark`, `dark`). Emoji with tones weigh more (about 16 kB) because all six tones ship in
161
+ the module; the others are about 2 kB.
162
+ - Props: `size` (default 24; `'1em'` follows the text), `tone`, `title`. Without `title` the emoji is
163
+ decorative (`aria-hidden`); add `title` when it carries meaning alone. `emojiCatalog` lists every emoji
164
+ with its label, Unicode character and category, for pickers and search.
165
+
151
166
  ## 5. Component guide — what it's for, why it behaves that way, when not to use it
152
167
 
153
168
  Format: **Use for** · **Why it is built this way** · **Not for / instead**.
154
169
 
155
170
  **Looking for a component by another name?** SakaniUI uses its own names. A *dialog* or *alert dialog* is
156
- `Modal`; a *snackbar* is `Toast`; a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
171
+ `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
172
  *date picker* is `Calendar`; a *loader* is `Spinner`; a *toggle* is `Switch`; a *banner* is `Announcement`;
158
173
  *autocomplete* is `Combobox`. There is no `Dialog`, `AlertDialog`, `Snackbar` or `Navbar`. Each component
159
174
  lists its other names under `aliases` in `manifest.json`, and `search_components` understands them.
@@ -174,6 +189,11 @@ lists its other names under `aliases` in `manifest.json`, and `search_components
174
189
  - **Toast** — Use for short-lived confirmation or error after an action. *Why:* presentational only;
175
190
  queueing and positioning are the app's job, so it fits any notification system. *Not for* anything the user
176
191
  must act on — a toast disappears.
192
+ - **Toaster + toast()** — Use for notifications you trigger from code: mount one `<Toaster />`, call
193
+ `toast.success('Saved')` from anywhere. *Why:* it owns queueing, position (6), the 4s timer, the pile that
194
+ spreads on hover and swipe-to-dismiss, so the app does not. `toast.promise` turns one toast from loading
195
+ into success or error. *Not for* anything the user must act on — a toast disappears; a plain static card
196
+ → `Toast`. Needs `Toaster` mounted once, and `toast()` is a function, not a component.
177
197
  - **Badge** — Use for a short status, category or count. *Why:* 6 colours × subtle/solid, no sizes, no
178
198
  borders — it is a label, not a control. *Not for* clickable filters → `FilterChip`.
179
199
  - **Tooltip** — Use for brief supplementary text on hover/focus. *Why:* pure CSS, so it works with
@@ -261,7 +281,8 @@ and **tell the user when you are composing** rather than implying a dedicated co
261
281
 
262
282
  | Component | You own |
263
283
  |---|---|
264
- | Toast | queueing, positioning, auto-dismiss timing |
284
+ | Toast | queueing, positioning, auto-dismiss timing (or use `Toaster`) |
285
+ | Toaster | mounting it once; it handles the rest |
265
286
  | Menu | anchoring/positioning (pair with Popover) |
266
287
  | BoardCard `dragging` | drag-and-drop logic and drop targets |
267
288
  | BoardColumn `loading` | the skeleton cards inside it |
package/data/CHANGELOG.md CHANGED
@@ -2,6 +2,41 @@
2
2
 
3
3
  All notable changes to `@sakaniui/react` are documented here.
4
4
 
5
+ ## 0.10.0
6
+
7
+ - **New: `@sakaniui/react/emoji`**, 1,594 full-colour emoji (Fluent Emoji, Flat style, by Microsoft, MIT), built
8
+ from the new *↳ Emoji* page in Figma. One component per emoji, tree-shaken on its own:
9
+ `<EmojiRocket />`, `<EmojiPartyPopper size={32} />`.
10
+ - 311 people and hand emoji take a skin tone: `<EmojiWavingHand tone="medium-dark" />`
11
+ (`light`, `medium-light`, `medium`, `medium-dark`, `dark`).
12
+ - Props: `size` (default 24, `'1em'` follows the text), `tone`, `title` (without it the emoji is decorative).
13
+ - `emojiCatalog`, `emojiCategories` and `emojiNames` list every emoji with its label, Unicode character and
14
+ category, for pickers and search; `createEmoji` builds one from your own artwork.
15
+ - The docs *Icons* page is now *Icons & emoji*, with a searchable emoji gallery (category, skin tone, copy
16
+ JSX or the character).
17
+ - Agent contract: the MCP server has a new `search_emoji` tool, `check_code` validates imports from
18
+ `@sakaniui/react/emoji`, and `emoji-index.json` ships next to `icon-index.json`.
19
+ - Licence notice for Fluent Emoji added to `THIRD_PARTY_NOTICES.md`.
20
+
21
+ ## 0.9.0
22
+
23
+ - **New: `Toaster` and `toast()`**, a managed toast stack (Sonner-style) built from the new *↳ Sonner* page in Figma.
24
+ Mount one `<Toaster />`, then call `toast()`, `toast.success()`, `.info()`, `.warning()`, `.error()`,
25
+ `.loading()`, `.promise()` and `.dismiss()` from anywhere.
26
+ - New toasts rise in from the edge; older ones pile up behind the newest (lifted 14px, shrunk 5% per level,
27
+ content hidden, three visible). Hover or focus spreads the pile into a list and pauses the 4s timers;
28
+ leaving folds it back. Swipe a toast towards its edge to dismiss it (past 45px, or a quick flick, it flies
29
+ out in 200ms; otherwise it springs back in 400ms). Motion is 400ms `ease`.
30
+ - Options per toast: `description`, `icon`, `action`, `cancel`, `closeButton`, `duration`, `dismissible`,
31
+ `richColors`, `id` (update in place), `onDismiss`, `onAutoClose`. On `Toaster`: `position` (six),
32
+ `richColors`, `closeButton`, `expand`, `visibleToasts`, `duration`, `gap`, `offset`, `mobileOffset`,
33
+ `hotkey` (alt+T focuses the stack; Escape folds it).
34
+ - Light, dark and glass surfaces through the existing tokens; reduced motion keeps the fades only; errors
35
+ are announced assertively.
36
+ - The existing `Toast` is unchanged: it stays the static, presentational card.
37
+ - Agent contract: `Toaster` is in the manifest with recipes (show a toast, a promise toast) and the aliases
38
+ *sonner*, *toast stack*, *toast provider*. (`toaster` now means this component, not `Toast`.)
39
+
5
40
  ## 0.8.13
6
41
 
7
42
  A user reported the MCP server "didn't work". Reproduced: on a Node older than 16.9 the server connected