# @corva/ui MCP Server MCP (Model Context Protocol) server that exposes `@corva/ui` component library documentation to AI coding agents. Setup supports Claude Code, Cursor, and Codex CLI. ## Table of Contents - [Overview](#overview) - [Available Tools](#available-tools) - [Usage](#usage) - [Available Prompts](#available-prompts) - [Setup](#setup) - [Quick Setup](#quick-setup) - [Local Setup (Recommended)](#local-setup-recommended) - [Monorepo Setup](#monorepo-setup) - [Global Installation (Rare)](#global-installation-rare) - [Verifying It Works](#verifying-it-works) - [Telemetry and Privacy](#telemetry-and-privacy) - [FAQ](#faq) ## Overview ### Available Tools - `search_corva_ui` - Search components, hooks, utils by name or description. When the requested `category` (`v2` or `v1`) has no match, the response surfaces a labeled fallback block from the other version so a single search still discovers a candidate. - `get_component_docs` - Get detailed component documentation with props and examples - `get_hook_docs` - Get hook documentation - `get_theme_docs` - Get theme/styling documentation - `list_corva_ui` - List all available items by category - `get_constants_docs` - Get constants documentation (values, namespaces, usage) - `get_client_docs` - Get API client documentation (methods, endpoints) - `get_diagnostics` - Get MCP server health metrics (memory, uptime, request stats, telemetry status) - `submit_feedback` - Send feedback about `@corva/ui` or this MCP server to the maintainers (docs gaps, wrong/missing props, search misses). The assistant can also call this on its own when it hits a gap. ### Usage No special keywords required. The AI automatically uses these tools when you ask about: - **Components**: "What's the Button component?", "How do I use Tooltip?" - **Hooks**: "How does useSubscriptions work?" - **Theme**: "What colors are in the palette?" - **Browsing**: "List all v2 components" Mentioning `@corva/ui`, component names, or asking about the design system triggers the MCP automatically. ### Available Prompts MCP prompts are surfaced as slash commands in clients that support them. In Claude Code they appear under `/mcp__corva-ui__`. - `figma_to_code` — Translate a Figma node into React components that follow `@corva/ui` conventions. Orchestrates the Figma Dev Mode MCP (for design context and Code Connect mappings) and the `@corva/ui` MCP tools above (for component, icon, theme, and hook lookups). **Argument** (optional; the assistant asks if missing): - `input` — Freeform request. Paste the full Figma node URL (e.g. `https://www.figma.com/design//...?node-id=`) together with any extra context: target path or directory in the app, an existing file to extend, naming preferences, edge cases. The assistant extracts the URL itself. > A single freeform argument is intentional: Claude Code's MCP-prompt bridge splits positional string arguments on > whitespace, so a multi-arg schema would only capture the first token of each. **Example invocation** (Claude Code): ``` /mcp__corva-ui__figma_to_code https://www.figma.com/design/ABC/Sample?node-id=1-2 create under src/apps/drilling/RigStatusCard.tsx ``` **Prerequisite:** the Figma Dev Mode MCP must be enabled in the same client session so the prompt can call `mcp__figma__get_design_context`. Enable it via Figma Desktop → Preferences → Enable Dev Mode MCP Server, then restart your client. **Scope:** primarily consumer mode — app repos that depend on `@corva/ui` and import from its entry points. Authoring mode (inside the `@corva/ui` repo itself) is auto-detected from `package.json` and adjusts output conventions. - `feedback` — Send feedback about `@corva/ui` or this MCP server to the maintainers. The prompt collects your message (and an optional sentiment / which component the feedback is about) and submits it via the `submit_feedback` tool. **Argument** (optional; the assistant asks if missing): - `input` — Your feedback. Optionally mention a sentiment (positive / negative / neutral) and which component, hook, or tool it is about. **Example invocation** (Claude Code): ``` /mcp__corva-ui__feedback the Button docs are missing the `variant` prop ``` - `healthcheck` — Check the health of this MCP server: uptime, memory usage, request statistics, telemetry status, and project identity. Runs the `get_diagnostics` tool and presents the report. **Takes no arguments.** **Example invocation** (Claude Code): ``` /mcp__corva-ui__healthcheck ``` ## Setup > **Just generated a fresh project with the latest `create-corva-app`?** MCP is already configured for Claude Code, > Cursor, and Codex CLI in the generated project — skip the setup steps below and jump > to [Verifying It Works](#verifying-it-works). Older projects scaffolded before MCP was added to the template still > need the setup below. > **Minimum Version:** The MCP server is available starting from `@corva/ui` version **3.44.0**. ### Quick Setup Run from your project root: ```bash npx -p @corva/ui corva-ui-mcp-setup ``` This creates `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.codex/config.toml` (Codex CLI) automatically. Restart your IDE or reload MCP servers afterward. > If any of these files already exist, the setup command **extends** them — your existing MCP server entries are > preserved, and only the `corva-ui` entry is added or updated. > **Monorepo:** Run the setup command from the monorepo root, not from individual > `apps/*` directories. See [Monorepo Setup](#monorepo-setup) for details. ### Local Setup (Recommended) **This is the recommended approach.** Add the MCP config to your project and it just works — no global installs, no PATH issues, always in sync with your project's `@corva/ui` version. | IDE | Config File | |-------------|----------------------| | Claude Code | `.mcp.json` | | Cursor | `.cursor/mcp.json` | | Codex CLI | `.codex/config.toml` | > These configs reference `npx -p @corva/ui corva-ui-mcp` (no machine-specific paths), so they're safe to commit if your > team wants project-wide MCP support. #### Claude Code 1. Create `.mcp.json` in your project root: ```json { "mcpServers": { "corva-ui": { "command": "npx", "args": [ "-p", "@corva/ui", "corva-ui-mcp" ] } } } ``` 2. Restart Claude Code or run `/mcp` to reload servers 3. Verify: Ask Claude "search corva-ui for Button" - it should use the MCP tool > **Native Windows note:** `npx` is a `.cmd` shim, and several MCP clients on native Windows (Claude Code; some Codex > CLI builds) fail to spawn it directly with `ENOENT` or `spawn npx`. If you hit that, wrap with `cmd /c`: > > ```json > { "command": "cmd", "args": ["/c", "npx", "--yes", "--package", "@corva/ui", "corva-ui-mcp"] } > ``` > > `--yes` skips npx's first-run "Need to install …?" prompt, which an MCP server start-up has no way to answer > interactively. (`--package` is the long form of `-p`; in npm proper `-p` aliases `--parseable`, so the long > form is clearer.) Cursor on Windows generally accepts plain `"command": "npx"` — try that first, only switch to the > `cmd /c` form if it fails. WSL users (with the client also running in WSL) don't hit this — plain `npx` works. #### Cursor 1. Create `.cursor/mcp.json` in your project root: ```json { "mcpServers": { "corva-ui": { "command": "npx", "args": [ "-p", "@corva/ui", "corva-ui-mcp" ] } } } ``` 2. Restart Cursor or use Command Palette → "MCP: Restart Servers" 3. **Note:** MCP is disabled by default in Cursor. Enable it in **Cursor Settings → Features → MCP** before restarting. 4. Verify: In Composer, ask about a @corva/ui component #### OpenAI Codex CLI 1. Create `.codex/config.toml` in your project root: ```toml [mcp_servers.corva_ui] command = "npx" args = ["-p", "@corva/ui", "corva-ui-mcp"] ``` 2. Restart Codex CLI or start a new session 3. Verify: Ask about a @corva/ui component #### Troubleshooting: Direct Path (Last Resort) If `npx` doesn't work in your environment (e.g., restricted shell, corporate proxy blocking npm registry), you can reference the module directly: ```json { "mcpServers": { "corva-ui": { "command": "node", "args": [ "node_modules/@corva/ui/mcp-server/server.mjs" ] } } } ``` **Trade-offs:** - Path may break if @corva/ui changes internal structure - Won't work with monorepo hoisting (yarn/pnpm workspaces) - Config isn't portable across different project structures --- ### Monorepo Setup Use the same per-IDE configs from [Local Setup](#local-setup-recommended), but place them in the **monorepo root**. For monorepos, place MCP config files (`.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`) in the **monorepo root** — just like other shared configs (e.g., DC app configs placed at repo root). Do **not** place them separately in each `apps/*` directory. > **Cursor-specific note:** If you open each app in a separate Cursor window, the monorepo-root MCP configs won't be > detected. To fix this, add the parent monorepo folder to the Cursor workspace: **File → Add Folder to Workspace**, > then select the monorepo root. --- ### Global Installation (Rare) Use this **only** if you need `@corva/ui` docs in projects that don't have `@corva/ui` as a dependency (e.g., backend repos, scratch projects). For all other cases, prefer the [local setup](#local-setup-recommended) above. **Trade-offs vs local setup:** - You must manually run `npm i -g @corva/ui` to get documentation updates - nvm users need absolute paths (PATH isn't inherited by MCP clients) - Documentation version may drift from what your project actually uses | IDE | Config File | |-------------|------------------------| | Claude Code | `~/.claude.json` | | Cursor | `~/.cursor/mcp.json` | | Codex CLI | `~/.codex/config.toml` | > These are user-level configs — they apply to all projects on your machine. Do not commit them. #### Step 1: Install Globally ```bash npm i -g @corva/ui ``` > Required for the with-nvm setups below — they reference the binary by an absolute path (macOS / Linux), > source `nvm.sh` to put it on PATH (Windows + WSL), or point Node at `mcp-server/server.mjs` directly > (nvm-windows). Optional for the "without nvm" setups: those use `npx --yes --package @corva/ui`, which runs > a matching local dependency when present or installs into npm's cache otherwise — `npx` does not honour the > global install. If you need a strictly pinned version regardless of cache state (or are working offline / behind > a registry-blocking proxy), use the [Troubleshooting: Direct Node Path](#troubleshooting-direct-node-path) form > below. #### Claude Code (with nvm) MCP clients can't find nvm-managed binaries due to PATH issues ([reference](https://github.com/modelcontextprotocol/servers/issues/64)). Use full paths. ##### macOS / Linux 1. Find your paths: ```bash nvm which current # e.g., /Users/you/.nvm/versions/node/v22.12.0/bin/node which corva-ui-mcp # e.g., /Users/you/.nvm/versions/node/v22.12.0/bin/corva-ui-mcp ``` 2. Add the `mcpServers` entry to your `~/.claude.json` (create the file if it doesn't exist, or merge into existing config): ```json { "mcpServers": { "corva-ui": { "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/node", "args": [ "/Users/you/.nvm/versions/node/v22.12.0/bin/corva-ui-mcp" ] } } } ``` ##### Windows + WSL Node lives inside WSL, so where you point the MCP config depends on where the *MCP client* runs: - **Client also runs inside WSL** (e.g. you launch `claude` from a WSL shell): follow the macOS / Linux instructions above unchanged. WSL is Linux for this purpose. - **Client is the native Windows app** (Claude Code installed on Windows, Node only in WSL): wrap with `wsl.exe`. The most reliable shape is to source `nvm.sh` explicitly so the spawned shell finds your Node and the global bin, regardless of how your `.bashrc` is structured: ```json { "mcpServers": { "corva-ui": { "command": "wsl.exe", "args": [ "-e", "bash", "-lc", ". \"$HOME/.nvm/nvm.sh\" && exec corva-ui-mcp" ] } } } ``` Notes for this config: - `wsl.exe` with no `-d` uses your default distro. If your dev environment lives in a non-default distro, add `-d ` (run `wsl.exe -l -v` to list them). - First MCP-server start may be slow if WSL is cold (the VM has to boot). If your client times out, restart the client once WSL is warm. - Simpler shapes like `["--", "corva-ui-mcp"]` or `["--", "bash", "-lc", "corva-ui-mcp"]` *can* work, but they're fragile: WSL's non-interactive shell may not source `nvm.sh`, so `corva-ui-mcp` won't be on PATH. Prefer the explicit-source form above unless you've verified the simpler one works on your setup. - If you'd rather avoid `wsl.exe` from the Windows-side client, install Node natively on Windows and follow [Native Windows (nvm-windows)](#native-windows-nvm-windows) below — keep WSL for everything else and run the MCP server off the native Node. ##### Native Windows (nvm-windows) `nvm which` doesn't exist on `nvm-windows`. Find the active Node bin path and the global npm prefix: ```cmd :: cmd where node npm prefix -g ``` ```powershell # PowerShell — bare `where` is an alias for Where-Object, so use where.exe (or Get-Command): where.exe node npm prefix -g ``` `where node` typically returns the `NVM_SYMLINK` path (default `C:\Program Files\nodejs\node.exe`) rather than the per-version path. Either path works in the MCP config. `npm prefix -g` returns the directory holding global executables and `node_modules\` — on a default `nvm-windows` setup that's `%APPDATA%\nvm\v`, but it can differ if you've customized the npm prefix or installed `nvm-windows` to a non-default root. Then in `~/.claude.json` (use forward slashes, or escape backslashes — both are valid JSON; substitute the prefix you got from `npm prefix -g`): ```json { "mcpServers": { "corva-ui": { "command": "C:/Program Files/nodejs/node.exe", "args": [ "C:/Users/you/AppData/Roaming/nvm/v22.12.0/node_modules/@corva/ui/mcp-server/server.mjs" ] } } } ``` The script path is `mcp-server/server.mjs` (the `bin` entry from `@corva/ui` `package.json`), **not** the `dist/` build path. Pointing `command` directly at `corva-ui-mcp.cmd` is technically possible but unreliable as an MCP `command` value across clients; the explicit `node.exe` + `.mjs` form mirrors the macOS / Linux example and is the recommended shape. #### Claude Code (without nvm) Add the `mcpServers` entry to your `~/.claude.json` (merge into existing config): ```json { "mcpServers": { "corva-ui": { "command": "npx", "args": [ "--yes", "--package", "@corva/ui", "corva-ui-mcp" ] } } } ``` > **Windows:** `npx` is a `.cmd` shim — see the [Native Windows note](#claude-code) under Local Setup for the > `cmd /c` workaround. WSL users running the native-Windows client should follow the `wsl.exe` config from > [Claude Code Windows + WSL](#windows--wsl) instead. #### Cursor (with nvm) Use the same path-discovery and JSON-shape rules as [Claude Code (with nvm)](#claude-code-with-nvm) above, but write the config to `~/.cursor/mcp.json`. ##### macOS / Linux 1. Find your paths (same as Claude Code above) 2. Add to `~/.cursor/mcp.json` (create the file if it doesn't exist, or merge into existing config): ```json { "mcpServers": { "corva-ui": { "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/node", "args": [ "/Users/you/.nvm/versions/node/v22.12.0/bin/corva-ui-mcp" ] } } } ``` ##### Windows + WSL If Cursor runs inside WSL, follow the macOS / Linux instructions above. If Cursor is the native Windows app and Node lives in WSL, write to `~/.cursor/mcp.json`: ```json { "mcpServers": { "corva-ui": { "command": "wsl.exe", "args": [ "-e", "bash", "-lc", ". \"$HOME/.nvm/nvm.sh\" && exec corva-ui-mcp" ] } } } ``` See the [Claude Code Windows + WSL notes](#windows--wsl) above for distro selection (`-d `), cold-start caveats, and why the explicit `nvm.sh` source is preferred over simpler shapes. ##### Native Windows (nvm-windows) Find your paths with `where.exe node` and `npm prefix -g` as described in the [Claude Code native-Windows section](#native-windows-nvm-windows), then write to `~/.cursor/mcp.json`: ```json { "mcpServers": { "corva-ui": { "command": "C:/Program Files/nodejs/node.exe", "args": [ "C:/Users/you/AppData/Roaming/nvm/v22.12.0/node_modules/@corva/ui/mcp-server/server.mjs" ] } } } ``` > **Note:** MCP is disabled by default in Cursor. Enable it in **Cursor Settings → Features → MCP** before restarting. #### Cursor (without nvm) Add to `~/.cursor/mcp.json` (merge into existing config): ```json { "mcpServers": { "corva-ui": { "command": "npx", "args": [ "--yes", "--package", "@corva/ui", "corva-ui-mcp" ] } } } ``` > **Windows:** `npx` is a `.cmd` shim. Cursor on Windows usually accepts plain `npx` — if it fails, use the > `cmd /c` workaround from the [Native Windows note](#claude-code) under Local Setup. WSL users running > native-Windows Cursor should follow the `wsl.exe` config from [Cursor Windows + WSL](#windows--wsl-1) instead. > **Note:** MCP is disabled by default in Cursor. Enable it in **Cursor Settings → Features → MCP** before restarting. #### Troubleshooting: Direct Node Path If `npx` isn't viable (offline, corporate proxy blocking the registry, or you need a strictly pinned version regardless of npm cache state), point Node directly at the global install's `server.mjs`. This shape requires Step 1 above and works for any IDE — drop it into `~/.claude.json`, `~/.cursor/mcp.json`, or `~/.codex/config.toml`. Find your global install's path with `npm prefix -g`, then substitute it below: ```json { "mcpServers": { "corva-ui": { "command": "node", "args": [ "/lib/node_modules/@corva/ui/mcp-server/server.mjs" ] } } } ``` Native-Windows substitution (default nodejs.org installer): `command` becomes `"C:/Program Files/nodejs/node.exe"`, `args` becomes `["C:/Users/you/AppData/Roaming/npm/node_modules/@corva/ui/mcp-server/server.mjs"]`. nvm-windows users should use the [Native Windows (nvm-windows)](#native-windows-nvm-windows) shape above instead — its `%APPDATA%\nvm\v\node_modules` path is the same direct-Node form. ## Verifying It Works Ask your AI agent a question about a `@corva/ui` component (e.g., "How do I use the Button component from @corva/ui?") — it should call one of the MCP tools and return real documentation. For server health (uptime, memory, request stats, telemetry status), run the healthcheck slash command in Claude Code: ``` /mcp__corva-ui__healthcheck ``` This runs the `get_diagnostics` tool under the hood. Clients without slash-command support can call the `get_diagnostics` tool directly instead. If the AI doesn't pick up the MCP tools, restart your IDE / reload MCP servers, and confirm the config file is at the location listed in the [Local Setup](#local-setup-recommended) table for your IDE. ## Telemetry and Privacy The MCP server may collect anonymous usage telemetry — tool name, arguments, results, latency, and MCP client name/version — when a telemetry endpoint is configured at build time. No hostnames, usernames, IP addresses, or other direct machine/user identifiers are collected. **Tool arguments and results are exported in full, without redaction or truncation.** Span payloads may therefore contain content from your queries (file paths, source snippets, component names, or other text you sent to the tool) alongside the documentation responses. This includes anything you send via the `feedback` prompt / `submit_feedback` tool — the free-text message is recorded verbatim and is intended for the `@corva/ui` maintainers. To check whether telemetry is currently active for your install, run `/mcp__corva-ui__healthcheck` (or call the `get_diagnostics` tool directly) — it reports the resolved telemetry status. Telemetry is fully disabled when no valid endpoint is configured. ## FAQ ### Does this affect my application bundle or runtime? No. The MCP server adds ~2 MB to the published `@corva/ui` npm package (bundled server, setup CLI, and pre-generated documentation data). These files live in `dist/mcp-server/` and are only used when running the CLI binaries ( `corva-ui-mcp`, `corva-ui-mcp-setup`). Consuming app bundlers resolve imports from the library's ESM/CJS entry points, which don't reference MCP files — so they are never included in application bundles or executed at runtime.