@corva/ui 3.57.0-4 → 3.57.0-5

package/MCP_README.md

@@ -0,0 +1,515 @@
+# @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)
+- [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
+- `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)
+
+### 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.
+
+## 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 <DistroName>` (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<version>`, 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 <DistroName>`), 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": ["<npm-prefix>/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<version>\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), call the `get_diagnostics` tool. In Claude Code:
+
+```
+Use the get_diagnostics tool from corva-ui MCP
+```
+
+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.
+
+To check whether telemetry is currently active for your install, call the `get_diagnostics` tool — 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.

package/README.md

@@ -32,15 +32,27 @@ with
 public `@corva/ui`
 components - please also update it's `stories.js` file when it's necessary
 
-## AI-Assisted Development
+## AI-Assisted Development (MCP Server)
 
-@corva/ui includes an MCP (Model Context Protocol) server that exposes component library documentation to AI coding
-agents like Claude Code and Cursor. The server provides tools for searching components, viewing documentation, and
-exploring the theme system.
+`@corva/ui` ships an MCP (Model Context Protocol) server that exposes the component library to AI coding agents. Setup
+supports Claude Code, Cursor, and Codex CLI. The server provides tools for searching components and viewing component,
+hook, theme, constants, and API client documentation.
 
-Quick setup: run `npx -p @corva/ui corva-ui-mcp-setup` from your project root to configure MCP automatically.
+> If you just generated a fresh project with the latest `create-corva-app`, MCP is already configured for Claude Code,
+> Cursor, and Codex CLI — you can skip this section. (Older projects scaffolded before MCP was added to the template
+> still need the setup below.)
 
-See [MCP Server documentation](./mcp-server/README.md) for setup instructions and available tools.
+Quick setup (run from your project root):
+
+```bash
+npx -p @corva/ui corva-ui-mcp-setup
+```
+
+If `.mcp.json`, `.cursor/mcp.json`, or `.codex/config.toml` already exists, the command extends it — existing MCP server
+entries are preserved, and only the `corva-ui` entry is added or updated.
+
+See [MCP Docs](./MCP_README.md) for the full list of tools, per-IDE setup (local / monorepo / global), and
+troubleshooting.
 
 ## Figma Code Connect