VaneUI

@vaneui/mcp

[npm version] [license] [Model Context Protocol]

A Model Context Protocol server that exposes the VaneUI documentation to AI coding agents. Any MCP-aware client (Claude Code, Claude Desktop, Cursor, VS Code, etc.) can read the component docs on demand and search across them with a single tool call, so your agent writes correct VaneUI code without you pasting rules into prompts by hand.

It serves the full component reference, getting-started and customization guides, and a structured prop table for every component, plus two tools: search_docs and get_component_props.

Requirements

• Node.js 24 (the npx command below downloads and runs the server for you).

Quickstart

The server runs over stdio and is published to npm as @vaneui/mcp. Add it to your client with the snippets below; no local clone or build is needed.

Claude Code

claude mcp add vaneui -- npx -y @vaneui/mcp

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "vaneui": {      "command": "npx",      "args": ["-y", "@vaneui/mcp"]    }  }}

Restart Claude Desktop afterward.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{  "mcpServers": {    "vaneui": {      "command": "npx",      "args": ["-y", "@vaneui/mcp"]    }  }}

VS Code

code --add-mcp '{"name":"vaneui","command":"npx","args":["-y","@vaneui/mcp"]}'

Or add to .vscode/mcp.json (note VS Code uses the servers key):

{  "servers": {    "vaneui": {      "command": "npx",      "args": ["-y", "@vaneui/mcp"]    }  }}

Other clients

Any client that accepts a stdio MCP server works. Use npx as the command and -y @vaneui/mcp as the args, following that client's config format.

How to use it

Once the server is connected, just build with VaneUI in natural language. The agent pulls the right docs through the tools automatically:

• "Using VaneUI, build a pricing card with a title, a feature list, and a filled primary button." → the agent reads card, list, and button props and composes them correctly.
• "What's the default appearance and variant of Chip?" → get_component_props returns the prop table (Chip defaults to secondary + outline, not primary).
• "How do I set app-wide defaults for every Button?" → search_docs finds the theme-defaults guide and shows the ThemeProvider themeDefaults pattern.
• "Which VaneUI prop maps to flex-1?" → search_docs finds it in the prop-to-Tailwind mapping.

Verifying it works

After adding the server and restarting your client:

• The client should list a server named vaneui with the tools search_docs and get_component_props (and the vaneui://docs/* resources).
• To smoke-test the server directly, run npx -y @vaneui/mcp in a terminal. It starts and waits on stdio (no output is normal for an MCP stdio server; press Ctrl+C to exit).

Tools

search_docs

Substring or regex search across the full doc corpus.

Returns up to 50 hits, each containing uri, slug, lineNumber, and a short surrounding snippet. Use this before guessing prop names, defaults, or class mappings — the answer is almost always already in the docs.

get_component_props

Returns a component's boolean props as plain text, one line per category, with the default marked *. Props in one category are alternatives. The data comes from @vaneui/ui's ComponentCategories, ComponentKeys, defaultTheme, and PropDescriptions.

The shared layout props (display, gap, justify, border, width and the rest) are the same on most components, so compact output leaves them out: it lists the component's own props, then names the shared categories the component takes and its shared defaults. Call it with slug: "common" once to get those props. full adds a description to every prop and lists the shared props too.

card boolean props. Props in one category are alternatives; * marks the default. Descriptions: call again with detail "full".Size: xs sm md* lg xlAppearance: primary* accent secondary tertiary success danger warning info inheritAppearanceVariant: filled outline* ghost...Shared layout props (get_component_props "common" lists them): Hide, Show, Items, Justify, ...Shared defaults: flex gap column border responsiveSizing

Props that take a value, such as Field's label or Modal's title, are not boolean category props: read them in the component's doc, vaneui://docs/<slug>.

Available resources

Each documentation file is exposed as a resource named vaneui://docs/<slug>, where <slug> is the lowercased source filename minus the .md extension. All resources have mimeType: text/markdown.

Examples:

• vaneui://docs/claude — VaneUI project overview.
• vaneui://docs/component-usage, vaneui://docs/prop-to-tailwind-mapping, vaneui://docs/component-patterns, vaneui://docs/props-and-theme, vaneui://docs/css-conventions, vaneui://docs/testing, vaneui://docs/e2e-testing, vaneui://docs/playground-examples — agent-facing rule files.
• vaneui://docs/installation, vaneui://docs/usage-basics, vaneui://docs/core-concepts — getting-started guides.
• vaneui://docs/theming-overview, vaneui://docs/using-theme-provider, vaneui://docs/theme-defaults, vaneui://docs/theme-and-override, vaneui://docs/extra-classes, vaneui://docs/customizing-styles, vaneui://docs/variant-inheritance, vaneui://docs/css-variables — customization guides.
• vaneui://docs/common-props — shared layout/typography prop reference.
• vaneui://docs/button, vaneui://docs/card, vaneui://docs/modal, ... — one per component.

Development

This section is for contributors and maintainers working on the server itself.

Sources

The doc corpus is bundled from two sibling repos at build time:

• vaneui/ (a checkout of vaneui/vaneui) — API reference and agent-facing rules (CLAUDE.md + .claude/rules/*.md).
• vaneui-web/ (a checkout of vaneui/web) — narrative guides and per-component reference, authored as plain markdown under app/docs/data/**/*.md (one file per component, with frontmatter).

Each .md file goes into resources/ keyed by its basename (filenames are globally unique, so the corpus is flat). Files from vaneui/ are copied verbatim. vaneui-web/ pages are written with their {% include "x.md" %} tags expanded through vaneui-web's own include helper (lib/docs/includes.mjs), so each resource matches the page on vaneui.com. Files and directories whose name starts with _ are partials that pages include, so they get no resource of their own. scripts/sync-component-props.mjs additionally reads each component's componentKey frontmatter and joins it with @vaneui/ui's exported metadata to produce resources/component-props.json. It marks a prop as shared (isCommon) when its category is in vaneui-web/app/docs/commonCategories.ts, the same split the props tables on vaneui.com use.

Building

resources/ is committed to git, so a fresh clone already has everything the server needs to run.

npm installnpm run build       # tsc only — uses the committed resources/npm start           # run the built server over stdio

Point a client at the local build with node /absolute/path/to/vaneui-mcp/dist/server.js as the command.

Testing

npm test compiles src/ and runs the tool tests in test/ with node --test.

Re-syncing the corpus (maintainers)

The sync scripts expect vaneui/ and vaneui-web/ as sibling folders of this repo (resolved as ../vaneui and ../vaneui-web). Override with VANEUI_PATH / VANEUI_WEB_PATH env vars if they live elsewhere. Run npm install in vaneui-web/ first, because its include helper loads @vaneui/md from there. A missing or cyclic include stops the sync.

npm run build:full  # re-sync resources/ from the sibling repos, then tsc

• npm run sync — lenient sync: copies every .md from both sources into resources/ and writes component-props.json. ⚠️ Wipes resources/ first; if a sibling repo is missing you'll get a partial bundle. Prefer build:full.
• npm run sync:strict — strict sync: exits non-zero if any sibling repo is missing or no MD files are found. Used by prepublishOnly.

Adding or updating a doc

1. Edit (or create) the source markdown in vaneui/ or vaneui-web/:
   • Component reference: vaneui-web/app/docs/data/<category>/<slug>.md (with frontmatter).
   • Narrative guide: vaneui-web/app/docs/data/{getting-started,customization,reference}/.
   • Agent rule: vaneui/.claude/rules/<slug>.md.
2. npm run build:full to regenerate resources/ and recompile.
3. Commit the regenerated resources/ alongside the source edit, and restart your MCP client.

src/resources.ts reads the resources directory at startup, so no registry edit is needed when adding a file.

License

MIT