@sakaniui/mcp 0.9.0 → 0.10.1

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,8 +490,8 @@ 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}';` });
@@ -472,6 +501,15 @@ function checkCode(source) {
472
501
  const isUtility = !!util;
473
502
  // an exact helper name (toast) is not a mis-cased component (Toast)
474
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
+ }
475
513
  if (entry === '@sakaniui/react/icons') {
476
514
  if (!iconNames.has(n.imported) && !iconOtherExports.has(n.imported)) {
477
515
  const hint = searchIcons(n.imported, 3).map((i) => i.name);
@@ -787,8 +825,20 @@ const tools = {
787
825
  return text({ import: "import { IconName } from '@sakaniui/react/icons';", usage: 'icon={IconName} (the component, not <IconName />)', icons: hits });
788
826
  },
789
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
+ },
790
840
  check_code: {
791
- 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.',
792
842
  inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The snippet, including its import lines.' } }, required: ['code'] },
793
843
  run(args) {
794
844
  const code = args.code;
@@ -839,7 +889,7 @@ function handle(msg) {
839
889
  protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
840
890
  capabilities: { tools: { listChanged: false } },
841
891
  serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: bundled.version }, // the server's own version, not the data's
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}` : ''}`,
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}` : ''}`,
843
893
  } });
844
894
  }
845
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
@@ -148,6 +148,21 @@ 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**.
package/data/CHANGELOG.md CHANGED
@@ -2,6 +2,30 @@
2
2
 
3
3
  All notable changes to `@sakaniui/react` are documented here.
4
4
 
5
+ ## 0.10.1
6
+
7
+ - **New: an agent skill.** `skills/sakaniui/SKILL.md` ships in the package. It triggers when someone asks an
8
+ agent for UI in a project that uses `@sakaniui/react` and points it at the MCP server, `manifest.json` and
9
+ `AGENTS.md` instead of repeating them, so it cannot go stale. Install it with
10
+ `cp -r node_modules/@sakaniui/react/skills/sakaniui .claude/skills/` (or `~/.claude/skills/` for every project).
11
+ - No component or API changes.
12
+
13
+ ## 0.10.0
14
+
15
+ - **New: `@sakaniui/react/emoji`**, 1,594 full-colour emoji (Fluent Emoji, Flat style, by Microsoft, MIT), built
16
+ from the new *↳ Emoji* page in Figma. One component per emoji, tree-shaken on its own:
17
+ `<EmojiRocket />`, `<EmojiPartyPopper size={32} />`.
18
+ - 311 people and hand emoji take a skin tone: `<EmojiWavingHand tone="medium-dark" />`
19
+ (`light`, `medium-light`, `medium`, `medium-dark`, `dark`).
20
+ - Props: `size` (default 24, `'1em'` follows the text), `tone`, `title` (without it the emoji is decorative).
21
+ - `emojiCatalog`, `emojiCategories` and `emojiNames` list every emoji with its label, Unicode character and
22
+ category, for pickers and search; `createEmoji` builds one from your own artwork.
23
+ - The docs *Icons* page is now *Icons & emoji*, with a searchable emoji gallery (category, skin tone, copy
24
+ JSX or the character).
25
+ - Agent contract: the MCP server has a new `search_emoji` tool, `check_code` validates imports from
26
+ `@sakaniui/react/emoji`, and `emoji-index.json` ships next to `icon-index.json`.
27
+ - Licence notice for Fluent Emoji added to `THIRD_PARTY_NOTICES.md`.
28
+
5
29
  ## 0.9.0
6
30
 
7
31
  - **New: `Toaster` and `toast()`**, a managed toast stack (Sonner-style) built from the new *↳ Sonner* page in Figma.