@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 +4 -2
- package/bin/sakaniui-mcp.mjs +55 -5
- package/data/AGENTS.md +16 -1
- package/data/CHANGELOG.md +24 -0
- package/data/dist/emoji-index.json +1 -0
- package/data/dist/icon-index.json +1 -1
- package/data/dist/manifest.json +5 -4
- package/data/package.json +1 -1
- package/package.json +1 -1
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
|
|
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 |
|
package/bin/sakaniui-mcp.mjs
CHANGED
|
@@ -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
|
|
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.
|