AI & MCP

The manifest

sakaniui.com/manifest.json (also shipped as @sakaniui/react/manifest.json) lists every exported component and block with its import path, props, types, allowed values, defaults and required props, plus every design token. It is generated from the TypeScript source on each build, so it always matches the installed version. If a prop, value or token is not in it, it does not exist.

requiresAccessibleName is true when a required prop (an aria-label or alt text) is the only thing that names the control. An assistant must not drop it.

The MCP server

@sakaniui/mcp is a small Model Context Protocol server. It is its own package (about 200 kB, no dependencies), so it starts in a couple of seconds and does not install the component library. It runs locally and answers for the version installed in your project. Add it to your editor's MCP config (Cursor, Windsurf, Claude Desktop, ...):

In Claude Code:

On Windows, npx is a .cmd script, so launch it through cmd /c: use "command": "cmd", "args": ["/c", "npx", "-y", "@sakaniui/mcp"], or in Claude Code claude mcp add sakaniui -- cmd /c npx -y @sakaniui/mcp. It needs Node.js 18 or later. To check it is connected, open your editor's MCP list (/mcp in Claude Code): sakaniui should show 10 tools.

Tools

• search_components: find a component or block by what you need, in the words you would normally use: “dialog” finds Modal, “snackbar” finds Toast, “date picker” finds Calendar. A name that does not exist gets the real one back, not a guess.
• get_component: the full contract for one component: every prop, the fields of object props (shape), a ready-to-paste example that is type-checked against the release, and recipes for patterns the types alone do not teach.
• search_icons: finds real icon names by meaning (“delete” gives IconTrash), so an assistant never guesses one.
• search_emoji: finds real emoji names by meaning (“party” gives EmojiPartyPopper), rendered as elements from @sakaniui/react/emoji.
• check_code: checks a whole snippet before it is shown to you: imports, required props, allowed values, icon props passed as icon={IconTrash}, and the field names inside inline object props such as table columns. The code is read as text, never run.
• list_components: browse everything, filtered by kind or category.
• get_tokens: the design tokens that exist, filtered by group.
• check_usage: validates the props you are about to use: missing required props, values outside an enum, props that do not exist.
• get_guide: sections of the AGENTS.md guide, such as “When nothing fits”.
• check_compatibility: compares the version the reference describes with the one installed in your project, and lists the components your version does not have yet.
• get_changelog: the release notes for a version, or for every release since the one you have.

It matches your version

npx may fetch a newer release than the one your project uses, so the server finds the @sakaniui/react installed in your project (from the folder it runs in, or --project <dir>) and answers for that version. Every component carries since, the first release that contained it, so a component your version does not have is flagged availableInInstalled: false and check_usage rejects it, instead of an assistant suggesting something that is not there yet.

It is read-only

The server reads five fixed files from an install (package.json, the manifest, the icon index, AGENTS.md and CHANGELOG.md). It writes nothing, runs nothing, opens no network connection and takes no file paths, and every tool is marked read-only. Every tool argument is type- and length-checked.

It is checked against the build

The build fails, and so does npm publish, if the manifest disagrees with the library: an export that is not described, a prop that is not in the type definitions, an example that does not type-check, an icon name that does not exist, a token that is not defined in tokens.css, or anything that looks like a private reference.

The guide

The manifest says what exists; AGENTS.md says why and when not to use it. Read it at /llms-full.txt, or index everything from /llms.txt.

The skill

The MCP server answers questions; a skill is what makes an assistant ask them. It is one short file, SKILL.md, that your assistant loads when you ask for an interface in a project that uses SakaniUI. The format is the open Agent Skills standard, so it is not tied to one product: Claude Code, Cursor and other skills-compatible agents read the same file. It does not repeat any component facts, so it cannot go stale. It tells the assistant to check your installed version, import both stylesheets, look components, icons and emoji up instead of guessing, style with tokens, and run check_code before answering, and it points at the server, the manifest and AGENTS.md as the sources of truth.

Install it for one project (Claude Code and the Claude app read .claude/skills/, and Cursor documents that it reads that folder too; use ~/.claude/skills/ to have it in every project). Other tools keep skills in their own folder, so copy the same sakaniui folder to wherever your tool looks:

mkdir -p .claude/skills/sakaniui
curl -fsSL https://raw.githubusercontent.com/samzydd/Sakaniui/main/skills/sakaniui/SKILL.md \
  -o .claude/skills/sakaniui/SKILL.md

From 0.10.1 it also ships inside the package, so it versions with the library:

mkdir -p .claude/skills
cp -r node_modules/@sakaniui/react/skills/sakaniui .claude/skills/

It is optional. The server and AGENTS.md work without it; the skill only saves you from having to say “use SakaniUI’s tools” in every prompt.

Troubleshooting

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:

• 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 and Linux) or where npx (Windows) and put that in "command", for example /opt/homebrew/bin/npx.
• Windows. npx is a .cmd script, so launch it through cmd /c:

• It connects, but tool calls fail. Node older than 16.9 (fixed in 0.8.13). Node 18 or later is supported; check with node --version and update from nodejs.org.
• 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 (see 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) and 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 other stray characters; copy the command from this page instead.

Still stuck? Open an issue at github.com/samzydd/Sakaniui/issues and paste the output of --doctor, your editor, and your operating system.