@epilot/volt-ui-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,24 +1,186 @@
 # Volt UI MCP Server
 
-Runs a local MCP server that exposes Volt UI components, props, and examples.
+An MCP (Model Context Protocol) server that exposes Volt UI components, props, documentation, and design tokens to AI assistants.
 
-## Usage
+## Features
+
+- **Component Discovery**: List and search all Volt UI components
+- **Props & Documentation**: Get detailed component props, descriptions, and usage examples
+- **Design Tokens**: Access CSS variables, semantic colors, and theming information
+- **Theme Support**: Light and dark theme token values
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all available Volt UI components |
+| `get_component` | Get detailed information about a specific component |
+| `search_components` | Search components by name, description, or props |
+| `list_tokens` | List design tokens with optional filtering |
+| `get_token` | Get details for a specific design token |
+| `search_tokens` | Search tokens by name or value |
+
+## Setup Instructions
+
+### Claude Desktop
+
+Add the following to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "volt-ui": {
+      "command": "npx",
+      "args": ["-y", "@epilot/volt-ui-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code (VS Code Extension)
+
+Add to your VS Code settings or project's `.vscode/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "volt-ui": {
+      "command": "npx",
+      "args": ["-y", "@epilot/volt-ui-mcp"]
+    }
+  }
+}
+```
+
+Or add to `~/.claude/settings.json` for global access:
+
+```json
+{
+  "mcpServers": {
+    "volt-ui": {
+      "command": "npx",
+      "args": ["-y", "@epilot/volt-ui-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP configuration (`.cursor/mcp.json` in your project or global settings):
 
 ```json
 {
   "mcpServers": {
-    "volt-ui-mcp": {
+    "volt-ui": {
       "command": "npx",
-      "args": ["-y", "volt-ui-mcp"]
+      "args": ["-y", "@epilot/volt-ui-mcp"]
     }
   }
 }
 ```
 
-## Build the registry
+### Windsurf
 
-Run this from the repo root before publishing:
+Add to your Windsurf MCP configuration:
 
-```sh
+```json
+{
+  "mcpServers": {
+    "volt-ui": {
+      "command": "npx",
+      "args": ["-y", "@epilot/volt-ui-mcp"]
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "github.copilot.chat.mcpServers": {
+    "volt-ui": {
+      "command": "npx",
+      "args": ["-y", "@epilot/volt-ui-mcp"]
+    }
+  }
+}
+```
+
+### Local Development (Testing)
+
+For testing during development, point to the local path:
+
+```json
+{
+  "mcpServers": {
+    "volt-ui": {
+      "command": "node",
+      "args": ["/path/to/volt-ui/tools/volt-ui-mcp/index.js"]
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once configured, you can ask your AI assistant questions like:
+
+- "What props does the Button component accept?"
+- "Show me how to use the Dialog component"
+- "What are the available color tokens in Volt UI?"
+- "How do I set up dark mode?"
+- "Search for components with loading states"
+
+## For Maintainers
+
+### Building the Registry
+
+The registry is automatically built during `npm publish` via the `prepack` script. To manually rebuild:
+
+```bash
+# From the volt-ui repo root
 bun run build:mcp
 ```
+
+This parses:
+- Component exports from `src/index.ts`
+- Documentation from `docs/content/docs/components/*.mdx`
+- Design tokens from `src/styles/*.css`
+
+### Publishing
+
+```bash
+cd tools/volt-ui-mcp
+npm publish
+```
+
+The `prepack` script automatically runs `build:mcp` to ensure the registry is up-to-date.
+
+### Versioning
+
+Update the version in `package.json` before publishing:
+
+```bash
+cd tools/volt-ui-mcp
+npm version patch  # or minor, major
+npm publish
+```
+
+## Resources
+
+The server also exposes MCP resources:
+
+| URI | Description |
+|-----|-------------|
+| `volt-ui://components` | List of all components |
+| `volt-ui://tokens` | List of all design tokens |
+| `volt-ui://components/{name}` | Specific component details |
+| `volt-ui://tokens/{name}` | Specific token details |
+

package/index.js

@@ -37,9 +37,9 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
       mimeType: "application/json",
     },
     {
-      uri: "volt-ui://blocks",
-      name: "Volt UI Blocks",
-      description: "List of all available Volt UI blocks/examples.",
+      uri: "volt-ui://tokens",
+      name: "Volt UI Tokens",
+      description: "List of Volt UI design tokens.",
       mimeType: "application/json",
     },
   ]
@@ -51,15 +51,18 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     mimeType: "application/json",
   }))
 
-  const blockResources = registry.blocks.map((block) => ({
-    uri: `volt-ui://blocks/${encodeURIComponent(block.name)}`,
-    name: block.title,
-    description: block.name,
+  const tokenNames = Array.from(
+    new Set((registry.tokens || []).map((token) => token.name))
+  ).sort((a, b) => a.localeCompare(b))
+  const tokenResources = tokenNames.map((name) => ({
+    uri: `volt-ui://tokens/${encodeURIComponent(name)}`,
+    name,
+    description: "Design token",
     mimeType: "application/json",
   }))
 
   return {
-    resources: [...baseResources, ...componentResources, ...blockResources],
+    resources: [...baseResources, ...componentResources, ...tokenResources],
   }
 })
 
@@ -126,29 +129,57 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
       },
       {
-        name: "list_blocks",
-        description: "List available Volt UI blocks/examples.",
+        name: "list_tokens",
+        description: "List Volt UI design tokens.",
         inputSchema: {
           type: "object",
-          properties: {},
+          properties: {
+            query: {
+              type: "string",
+              description: "Optional text filter for token name or value.",
+            },
+            theme: {
+              type: "string",
+              description: "Optional theme filter (light, dark, global).",
+            },
+            group: {
+              type: "string",
+              description: "Optional group filter (palette, semantic, utility).",
+            },
+          },
           additionalProperties: false,
         },
       },
       {
-        name: "get_block",
-        description: "Get a specific Volt UI block/example.",
+        name: "get_token",
+        description: "Get details for a specific Volt UI token.",
         inputSchema: {
           type: "object",
           properties: {
             name: {
               type: "string",
-              description: "Block name (e.g. card-example).",
+              description: "Token name (e.g. --volt-blue-9).",
             },
           },
           required: ["name"],
           additionalProperties: false,
         },
       },
+      {
+        name: "search_tokens",
+        description: "Search tokens by name or value.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Search term.",
+            },
+          },
+          required: ["query"],
+          additionalProperties: false,
+        },
+      },
     ],
   }
 })
@@ -169,12 +200,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const query = typeof args?.query === "string" ? args.query : ""
       return toolResult(searchComponents(query))
     }
-    case "list_blocks": {
-      return toolResult(listBlocks())
+    case "list_tokens": {
+      const query = typeof args?.query === "string" ? args.query : ""
+      const theme = typeof args?.theme === "string" ? args.theme : ""
+      const group = typeof args?.group === "string" ? args.group : ""
+      return toolResult(listTokens({ query, theme, group }))
+    }
+    case "get_token": {
+      const tokenName = typeof args?.name === "string" ? args.name : ""
+      return toolResult(getToken(tokenName))
     }
-    case "get_block": {
-      const blockName = typeof args?.name === "string" ? args.name : ""
-      return toolResult(getBlock(blockName))
+    case "search_tokens": {
+      const query = typeof args?.query === "string" ? args.query : ""
+      return toolResult(searchTokens(query))
     }
     default:
       return toolResult({ error: `Unknown tool: ${name}` })
@@ -192,7 +230,7 @@ function loadRegistry(filePath) {
     return {
       schemaVersion: 1,
       components: [],
-      blocks: [],
+      tokens: [],
       error: String(error),
     }
   }
@@ -202,16 +240,16 @@ function resolveResource(uri) {
   if (uri === "volt-ui://components") {
     return listComponents("")
   }
-  if (uri === "volt-ui://blocks") {
-    return listBlocks()
+  if (uri === "volt-ui://tokens") {
+    return listTokens({})
   }
   if (uri.startsWith("volt-ui://components/")) {
     const name = decodeURIComponent(uri.replace("volt-ui://components/", ""))
     return getComponent(name)
   }
-  if (uri.startsWith("volt-ui://blocks/")) {
-    const name = decodeURIComponent(uri.replace("volt-ui://blocks/", ""))
-    return getBlock(name)
+  if (uri.startsWith("volt-ui://tokens/")) {
+    const name = decodeURIComponent(uri.replace("volt-ui://tokens/", ""))
+    return getToken(name)
   }
   return { error: `Unknown resource: ${uri}` }
 }
@@ -277,25 +315,55 @@ function searchComponents(query) {
   }
 }
 
-function listBlocks() {
+function listTokens({ query = "", theme = "", group = "" }) {
+  const q = query.trim().toLowerCase()
+  const t = theme.trim().toLowerCase()
+  const g = group.trim().toLowerCase()
+  const tokens = (registry.tokens || []).filter((token) => {
+    if (t && token.theme.toLowerCase() !== t) {
+      return false
+    }
+    if (g && token.group.toLowerCase() !== g) {
+      return false
+    }
+    if (!q) {
+      return true
+    }
+    return (
+      token.name.toLowerCase().includes(q) ||
+      token.value.toLowerCase().includes(q)
+    )
+  })
+
   return {
-    count: registry.blocks.length,
-    blocks: registry.blocks.map((block) => ({
-      name: block.name,
-      title: block.title,
-      sourcePath: block.sourcePath,
-    })),
+    count: tokens.length,
+    tokens,
   }
 }
 
-function getBlock(name) {
-  const block = registry.blocks.find(
-    (entry) => entry.name.toLowerCase() === name.toLowerCase()
+function getToken(name) {
+  const target = name.trim().toLowerCase()
+  if (!target) {
+    return { error: "Token name is required." }
+  }
+  const tokens = (registry.tokens || []).filter(
+    (token) => token.name.toLowerCase() === target
   )
-  if (!block) {
-    return { error: `Block not found: ${name}` }
+  if (tokens.length === 0) {
+    return { error: `Token not found: ${name}` }
+  }
+  return {
+    name,
+    tokens,
+  }
+}
+
+function searchTokens(query) {
+  const q = query.trim().toLowerCase()
+  if (!q) {
+    return { count: 0, tokens: [] }
   }
-  return block
+  return listTokens({ query: q })
 }
 
 function findComponent(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/volt-ui-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "bin": {