@evolve.ui/mcp

An MCP server that exposes the Evolve UI design system to AI editors. It indexes components, hooks, utilities and Storybook MDX pages, then answers with the real import statement, prop declaration and file paths — read from the design-system sources the project actually uses, so the answers cannot drift from the library.

What it provides

Tools

| Tool | Purpose | | --- | --- | | get_resource | Resolve one component, hook, utility or MDX page to its import statement, props and file paths. | | install_rules | Install Evolve UI rules into the current project for Cursor or Claude Code. |

get_resource parameters:

| Parameter | Type | Notes | | --- | --- | --- | | name | string | Required. Button, useDebounce, cn, or an MDX page stem such as Tooltip Docs. | | package | string | Optional. core-components, theme-system, basketball-training-ui, professional-brand-ui, or docs to search MDX pages only. Short aliases (core, theme, basketball, professional) are accepted. | | includeTests | boolean | Optional. Adds the spec file path. |

install_rules parameters:

| Parameter | Type | Notes | | --- | --- | --- | | platform | cursor | claude | Defaults to cursor. | | profile | consumer | contributor | Defaults to consumer. contributor also copies the design system's own rules from a resolved checkout. | | force | boolean | Replace the rules this tool owns. Without it, existing files are left untouched. |

Resources

| URI | Contents | | --- | --- | | evolve-ui://available-components | Every export, grouped by package, with categories and whether Storybook docs exist. | | evolve-ui://storybook-docs | Every Storybook MDX page with its path and lookup keys. |

Installation

pnpm add -D @evolve.ui/mcp

In a project that depends on @evolve.ui/core-components (1.1.0+), that is the whole setup: the libraries publish their indexable sources (src/** plus an evolve-ui.entries.json manifest), so the server builds its catalog straight from node_modules. Under npm, a postinstall step also writes the project-local editor config for any detected editor (.cursor/mcp.json, .mcp.json, .vscode/mcp.json) — non-destructively, never in CI, never for transitive or global installs, and never touching your home directory or CLAUDE.md.

pnpm ≥ 10 / modern Yarn: dependency lifecycle scripts do not run by default, so the postinstall is skipped. Run the wizard once instead:

npx evolve-ui-mcp wizard    # detects editors, writes config, installs rules, runs doctor
npx evolve-ui-mcp doctor    # verifies every link in the chain, with a remedy per failure

wizard accepts --yes, --editors cursor,claude-code,vscode, --scope project|user, --skip-rules and --offline; doctor accepts --json and --offline. Set EVOLVE_UI_MCP_NO_POSTINSTALL=1 to disable the postinstall entirely.

Cursor setup

Inside the design-system monorepo

The server detects the monorepo root on its own (it looks for pnpm-workspace.yaml next to shared-configs/core-components), so no path configuration is needed:

{
    "mcpServers": {
        "evolve-ui": {
            "command": "pnpm",
            "args": ["--filter", "@evolve.ui/mcp", "start"]
        }
    }
}

In a consuming application

npx evolve-ui-mcp wizard writes this for you. The equivalent manual config — no paths needed when @evolve.ui/core-components (1.1.0+) is installed:

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

Write the config to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json to enable it everywhere. Restart Cursor afterwards, then ask the agent to call install_rules so it knows when to use the server. To serve a local checkout instead of the installed packages, add "--evolve-ui-root", "/absolute/path/to/evolve-ui" to the args.

Installed mode indexes components, hooks, utilities and props from the published sources. Storybook stories and MDX pages live only in the design-system repository, so storybook-docs reports itself unavailable and categories fall back to Other — npx evolve-ui-mcp doctor names this gap explicitly.

Configuration

CLI flags

| Flag | Purpose | | --- | --- | | --evolve-ui-root <absolute path> | Design-system checkout to index. | | --project-root <absolute path> | Consumer project that rules are installed into and dependency versions are read from. Defaults to the nearest ancestor with a package.json or .git. | | --no-rules-warning | Suppress the "rules are not installed" notice on tool responses. |

A bare positional argument is also accepted as the design-system path.

Environment variables

| Variable | Purpose | | --- | --- | | EVOLVE_UI_PATH | Absolute path of the design-system checkout. Equivalent to --evolve-ui-root. | | EVOLVE_UI_VERSION | Version to serve when no local checkout is available. |

How sources are resolved

1. An explicit absolute path from --evolve-ui-root or EVOLVE_UI_PATH.
2. An auto-detected design-system root above the working directory.
3. Published @evolve.ui/* packages installed under the nearest node_modules (npm, pnpm and Yarn node-modules linkers; Yarn PnP is unsupported — doctor says so explicitly).
4. The version pinned by the project's @evolve.ui/core-components dependency, cached under ~/.evolve-ui-mcp/versions/<version>/.
5. The latest published version, cached in the same place.

If none of these resolve, the server exits with a message naming --evolve-ui-root and EVOLVE_UI_PATH rather than serving an empty catalog silently.

Rules profiles

• consumer — how to use the design system from an application: MCP usage, import and styling patterns, and a theming primer. Installed as .cursor/rules/evolve-ui-*.mdc, or as a marked ## Evolve UI MCP Integration section in CLAUDE.md.
• contributor — the consumer rules plus the design system's own rules, copied live from the resolved checkout. Requires a resolvable checkout; it will not fall back to a stale snapshot.

Existing files are never silently overwritten. force replaces only the files (or the marked CLAUDE.md section) that this tool owns.

Development

pnpm --filter @evolve.ui/mcp build
pnpm --filter @evolve.ui/mcp test
pnpm --filter @evolve.ui/mcp ts-check
pnpm --filter @evolve.ui/mcp lint

Diagnostics are written to stderr, because stdout is the MCP transport.

Licence

MIT