@epilot/volt-ui-mcp 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# Volt UI MCP Server
+
+Runs a local MCP server that exposes Volt UI components, props, and examples.
+
+## Usage
+
+```json
+{
+  "mcpServers": {
+    "volt-ui-mcp": {
+      "command": "npx",
+      "args": ["-y", "volt-ui-mcp"]
+    }
+  }
+}
+```
+
+## Build the registry
+
+Run this from the repo root before publishing:
+
+```sh
+bun run build:mcp
+```

package/index.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const registryPath = path.join(__dirname, "registry.json")
+
+const registry = loadRegistry(registryPath)
+const server = new Server(
+  {
+    name: "volt-ui-mcp",
+    version: registry.schemaVersion ? `schema-${registry.schemaVersion}` : "0.1.0",
+  },
+  {
+    capabilities: {
+      resources: {},
+      tools: {},
+    },
+  }
+)
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const baseResources = [
+    {
+      uri: "volt-ui://components",
+      name: "Volt UI Components",
+      description: "List of all available Volt UI components.",
+      mimeType: "application/json",
+    },
+    {
+      uri: "volt-ui://blocks",
+      name: "Volt UI Blocks",
+      description: "List of all available Volt UI blocks/examples.",
+      mimeType: "application/json",
+    },
+  ]
+
+  const componentResources = registry.components.map((component) => ({
+    uri: `volt-ui://components/${encodeURIComponent(component.name)}`,
+    name: component.name,
+    description: component.description ?? "",
+    mimeType: "application/json",
+  }))
+
+  const blockResources = registry.blocks.map((block) => ({
+    uri: `volt-ui://blocks/${encodeURIComponent(block.name)}`,
+    name: block.title,
+    description: block.name,
+    mimeType: "application/json",
+  }))
+
+  return {
+    resources: [...baseResources, ...componentResources, ...blockResources],
+  }
+})
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri
+  const response = resolveResource(uri)
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(response, null, 2),
+      },
+    ],
+  }
+})
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "list_components",
+        description: "List all available Volt UI components.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Optional text filter for component name or description.",
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "get_component",
+        description: "Get detailed information about a Volt UI component.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Component name (e.g. Button, DialogContent).",
+            },
+          },
+          required: ["name"],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "search_components",
+        description: "Search components by name, description, or prop names.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Search term.",
+            },
+          },
+          required: ["query"],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "list_blocks",
+        description: "List available Volt UI blocks/examples.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "get_block",
+        description: "Get a specific Volt UI block/example.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Block name (e.g. card-example).",
+            },
+          },
+          required: ["name"],
+          additionalProperties: false,
+        },
+      },
+    ],
+  }
+})
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params
+
+  switch (name) {
+    case "list_components": {
+      const query = typeof args?.query === "string" ? args.query : ""
+      return toolResult(listComponents(query))
+    }
+    case "get_component": {
+      const componentName = typeof args?.name === "string" ? args.name : ""
+      return toolResult(getComponent(componentName))
+    }
+    case "search_components": {
+      const query = typeof args?.query === "string" ? args.query : ""
+      return toolResult(searchComponents(query))
+    }
+    case "list_blocks": {
+      return toolResult(listBlocks())
+    }
+    case "get_block": {
+      const blockName = typeof args?.name === "string" ? args.name : ""
+      return toolResult(getBlock(blockName))
+    }
+    default:
+      return toolResult({ error: `Unknown tool: ${name}` })
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+
+function loadRegistry(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8")
+    return JSON.parse(raw)
+  } catch (error) {
+    return {
+      schemaVersion: 1,
+      components: [],
+      blocks: [],
+      error: String(error),
+    }
+  }
+}
+
+function resolveResource(uri) {
+  if (uri === "volt-ui://components") {
+    return listComponents("")
+  }
+  if (uri === "volt-ui://blocks") {
+    return listBlocks()
+  }
+  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)
+  }
+  return { error: `Unknown resource: ${uri}` }
+}
+
+function listComponents(query) {
+  const q = query.trim().toLowerCase()
+  const components = registry.components.filter((component) => {
+    if (!q) {
+      return true
+    }
+    return (
+      component.name.toLowerCase().includes(q) ||
+      (component.description ?? "").toLowerCase().includes(q)
+    )
+  })
+
+  return {
+    count: components.length,
+    components: components.map((component) => ({
+      name: component.name,
+      title: component.title,
+      description: component.description,
+      docsPath: component.docsPath,
+      docSlug: component.docSlug,
+      documentationUrl: component.documentationUrl,
+      apiReferenceUrl: component.apiReferenceUrl,
+      sourcePaths: component.sourcePaths,
+    })),
+  }
+}
+
+function getComponent(name) {
+  const component = findComponent(name)
+  if (!component) {
+    return { error: `Component not found: ${name}` }
+  }
+  return component
+}
+
+function searchComponents(query) {
+  const q = query.trim().toLowerCase()
+  if (!q) {
+    return { count: 0, components: [] }
+  }
+
+  const components = registry.components.filter((component) => {
+    const haystack = [
+      component.name,
+      component.title,
+      component.description,
+      (component.props || []).map((prop) => prop.name).join(" "),
+    ]
+      .filter(Boolean)
+      .join(" ")
+      .toLowerCase()
+
+    return haystack.includes(q)
+  })
+
+  return {
+    count: components.length,
+    components,
+  }
+}
+
+function listBlocks() {
+  return {
+    count: registry.blocks.length,
+    blocks: registry.blocks.map((block) => ({
+      name: block.name,
+      title: block.title,
+      sourcePath: block.sourcePath,
+    })),
+  }
+}
+
+function getBlock(name) {
+  const block = registry.blocks.find(
+    (entry) => entry.name.toLowerCase() === name.toLowerCase()
+  )
+  if (!block) {
+    return { error: `Block not found: ${name}` }
+  }
+  return block
+}
+
+function findComponent(name) {
+  return registry.components.find(
+    (component) => component.name.toLowerCase() === name.toLowerCase()
+  )
+}
+
+function toolResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@epilot/volt-ui-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "volt-ui-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "registry.json"
+  ],
+  "scripts": {
+    "prepack": "bun ../../scripts/build-mcp-registry.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}