@epilot/volt-ui-mcp 0.1.4 → 0.3.0

package/index.js

@@ -11,16 +11,20 @@ import {
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js"
 
+import { createQueries, toolResult } from "./lib.js"
+import { TOOL_SPECS, toJsonSchema, callTool, SERVER_VERSION } from "./tools.js"
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const registryPath = path.join(__dirname, "registry.json")
 
-const registry = loadRegistry(registryPath)
+// Fail loud on a missing/empty registry — never serve "0 components" silently.
+const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"))
+const queries = createQueries(registry)
+
 const server = new Server(
   {
     name: "volt-ui-mcp",
-    version: registry.schemaVersion
-      ? `schema-${registry.schemaVersion}`
-      : "0.1.0",
+    version: SERVER_VERSION,
   },
   {
     capabilities: {
@@ -31,358 +35,32 @@ const server = new Server(
 )
 
 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://tokens",
-      name: "Volt UI Tokens",
-      description: "List of Volt UI design tokens.",
-      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 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, ...tokenResources],
-  }
+  return { resources: queries.listResources() }
 })
 
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   const uri = request.params.uri
-  const response = resolveResource(uri)
+  const response = queries.resolveResource(uri)
 
   return {
     contents: [
       {
         uri,
         mimeType: "application/json",
-        text: JSON.stringify(response, null, 2),
+        text: JSON.stringify(response),
       },
     ],
   }
 })
 
 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_tokens",
-        description: "List Volt UI design tokens.",
-        inputSchema: {
-          type: "object",
-          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_token",
-        description: "Get details for a specific Volt UI token.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            name: {
-              type: "string",
-              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,
-        },
-      },
-    ],
-  }
+  return { tools: TOOL_SPECS.map(toJsonSchema) }
 })
 
 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_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 "search_tokens": {
-      const query = typeof args?.query === "string" ? args.query : ""
-      return toolResult(searchTokens(query))
-    }
-    default:
-      return toolResult({ error: `Unknown tool: ${name}` })
-  }
+  return toolResult(callTool(queries, name, args))
 })
 
 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: [],
-      tokens: [],
-      error: String(error),
-    }
-  }
-}
-
-function resolveResource(uri) {
-  if (uri === "volt-ui://components") {
-    return listComponents("")
-  }
-  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://tokens/")) {
-    const name = decodeURIComponent(uri.replace("volt-ui://tokens/", ""))
-    return getToken(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 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: tokens.length,
-    tokens,
-  }
-}
-
-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 (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 listTokens({ query: q })
-}
-
-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/lib.d.ts

@@ -0,0 +1,40 @@
+export const DEFAULT_TOKEN_LIMIT: number
+export const MAX_TOKEN_LIMIT: number
+
+export type ToolResult = {
+  content: Array<{ type: "text"; text: string }>
+  isError?: true
+}
+
+export function toolResult(payload: unknown): ToolResult
+
+export type Queries = {
+  listComponents(query?: string): unknown
+  /** include: CSV of extra detail to add to the lean default — "examples", "tokens", or "all". */
+  getComponent(name: string, include?: string): unknown
+  searchComponents(query: string): unknown
+  listTokens(opts?: {
+    query?: string
+    theme?: string
+    group?: string
+    limit?: number
+    offset?: number
+  }): unknown
+  getToken(name: string): unknown
+  searchTokens(query: string): unknown
+  listGuidelines(query?: string): unknown
+  getGuideline(slug: string): unknown
+  resolveResource(uri: string): unknown
+  listResources(): Array<{
+    uri: string
+    name: string
+    description: string
+    mimeType: string
+  }>
+}
+
+/**
+ * Throws if the registry is missing or has no components (fail loud — an empty
+ * registry must never masquerade as a working server).
+ */
+export function createQueries(registry: unknown): Queries