@epilot/volt-ui-mcp 0.1.4 → 0.3.0

package/lib.js

@@ -0,0 +1,499 @@
+/**
+ * Pure query functions over the volt-ui registry.
+ *
+ * Shared by the stdio bin (index.js) and the remote MCP route on the docs app
+ * (docs/app/api/[transport]/route.ts). Transport wiring stays in the consumers —
+ * this module is plain data-in/data-out so both servers answer identically.
+ *
+ * Response-size discipline (remote clients hard-truncate large tool results):
+ * - list/search_components return lean summaries; search_components is capped to
+ *   the top SEARCH_LIMIT matches (the true total stays in `count`)
+ * - list_tokens is topics-first: a bare call returns only the category index;
+ *   token pages (DEFAULT_TOKEN_LIMIT) come back only when drilling into a group
+ */
+
+export const DEFAULT_TOKEN_LIMIT = 200
+export const MAX_TOKEN_LIMIT = 500
+
+// Coerce a tool argument to a string before string ops — tolerant of null,
+// undefined, or a non-string value from a misbehaving client. The transports
+// already coerce, but these query functions are exported and called directly.
+const asText = (value) =>
+  typeof value === "string" ? value : value == null ? "" : String(value)
+
+// decodeURIComponent throws on malformed escapes (e.g. "%ZZ"); fall back to the
+// raw segment so a bad resource URI yields a clean "not found", not a crash.
+const safeDecode = (value) => {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+// One-line descriptions of each token group, surfaced in the list_tokens
+// `groups` index so consumers can see the full token taxonomy (not just colors)
+// and learn how each group is used.
+const GROUP_DESCRIPTIONS = {
+  spacing:
+    "Intent-based gap scale: element (inside a component), group (between items in a group), layout (between groups/sections). Shipped as gap-* and p-* utilities ONLY (not m-/space-); prefix volt- in consumer apps (e.g. volt-gap-group-2).",
+  palette: "Raw color scale steps per hue (1–12 plus alpha aN).",
+  semantic:
+    "Semantic color roles (accent/gray/success/error/warning/info × soft/solid/surface/contrast/…).",
+  utility: "Color utility aliases resolved from the palette.",
+  other:
+    "Uncategorized tokens — discovered from the CSS but not yet assigned a known group; surfaced (never dropped) so they can be classified.",
+}
+
+export function createQueries(registry) {
+  if (
+    !registry ||
+    !Array.isArray(registry.components) ||
+    registry.components.length === 0
+  ) {
+    // Fail loud: an empty/missing registry must never masquerade as a working
+    // server with 0 components (e.g. a file-tracing miss on the host).
+    throw new Error(
+      "volt-ui-mcp: registry is missing or empty — refusing to serve. " +
+        "Regenerate with `bun run build:mcp` from the repo root."
+    )
+  }
+
+  const tokens = registry.tokens || []
+  const guidelines = registry.guidelines || []
+
+  // Category index computed once — exposes which token groups exist (spacing,
+  // palette, semantic, utility, …) so consumers can tell the surface is
+  // complete and discover non-color tokens.
+  const tokenGroups = (() => {
+    const counts = {}
+    for (const token of tokens) {
+      counts[token.group] = (counts[token.group] || 0) + 1
+    }
+    return Object.keys(counts)
+      .sort()
+      .map((group) => ({
+        group,
+        count: counts[group],
+        description: GROUP_DESCRIPTIONS[group] || "",
+      }))
+  })()
+
+  // Lean summary for browse/search results — name/title/description only. The
+  // heavier fields (docs/source paths, urls, props, examples) come from
+  // get_component when the agent drills in.
+  function componentSummary(component) {
+    return {
+      name: component.name,
+      title: component.title,
+      description: component.description,
+    }
+  }
+
+  function findComponent(name) {
+    return registry.components.find(
+      (component) => component.name.toLowerCase() === name.toLowerCase()
+    )
+  }
+
+  function listComponents(query = "") {
+    const q = asText(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(componentSummary),
+    }
+  }
+
+  // Lean default projection. composition/constraints/canonicalExample are
+  // high-signal and default-on (they close the composition-error gap); the
+  // bulky examples[] and recommendedTokens are opt-in via include=. aliases/
+  // useCases are search-only and never returned here.
+  function projectComponent(component, includeSet) {
+    const projected = {
+      name: component.name,
+      title: component.title,
+      description: component.description,
+      docsPath: component.docsPath,
+      docSlug: component.docSlug,
+      documentationUrl: component.documentationUrl,
+      apiReferenceUrl: component.apiReferenceUrl,
+      sourcePaths: component.sourcePaths,
+      props: component.props,
+    }
+    if (component.composition) {
+      projected.composition = component.composition
+    }
+    if (component.constraints) {
+      projected.constraints = component.constraints
+    }
+    if (component.canonicalExample) {
+      projected.canonicalExample = component.canonicalExample
+    }
+    const all = includeSet.has("all")
+    if (all || includeSet.has("examples")) {
+      projected.examples = component.examples
+    }
+    if ((all || includeSet.has("tokens")) && component.recommendedTokens) {
+      projected.recommendedTokens = component.recommendedTokens
+    }
+    return projected
+  }
+
+  function getComponent(name, include = "") {
+    const nameText = asText(name)
+    if (!nameText.trim()) {
+      return { error: "Component name is required." }
+    }
+    const component = findComponent(nameText)
+    if (!component) {
+      return { error: `Component not found: ${nameText}` }
+    }
+    const includeSet = new Set(
+      String(include || "")
+        .split(",")
+        .map((part) => part.trim().toLowerCase())
+        .filter(Boolean)
+    )
+    return projectComponent(component, includeSet)
+  }
+
+  const SEARCH_LIMIT = 25
+
+  function searchComponents(query) {
+    const qFull = asText(query).trim().toLowerCase()
+    if (!qFull) {
+      return { count: 0, returned: 0, hasMore: false, components: [] }
+    }
+    const qWords = qFull.split(/\s+/).filter(Boolean)
+
+    // Tiered scoring so an EXACT name match always beats an incidental intent
+    // substring (the old bug: "button" ranked Tooltip #1 via its useCase text).
+    // Exact alias phrase beats alias substring (so "dropdown" → Select, not
+    // Popover's "dropdown panel"). A final all/any-words tier gives recall for
+    // non-verbatim multi-word intents.
+    const scored = []
+    for (const component of registry.components) {
+      const name = (component.name || "").toLowerCase()
+      const title = (component.title || "").toLowerCase()
+      const description = (component.description || "").toLowerCase()
+      const aliases = (component.aliases || []).map((a) => a.toLowerCase())
+      const useCases = (component.useCases || []).map((u) => u.toLowerCase())
+      const aliasText = aliases.concat(useCases).join(" ")
+      const propNames = (component.props || [])
+        .map((prop) => prop.name)
+        .join(" ")
+        .toLowerCase()
+
+      let score = 0
+      if (name === qFull) {
+        score = 100
+      } else if (name.startsWith(qFull)) {
+        score = 85
+      } else if (aliases.some((a) => a === qFull)) {
+        score = 80
+      } else if (name.includes(qFull)) {
+        score = 70
+      } else if (aliasText.includes(qFull)) {
+        score = 55
+      } else if (title.includes(qFull)) {
+        score = 45
+      } else {
+        const hay = [name, aliasText, title, description, propNames].join(" ")
+        const hits = qWords.filter((w) => hay.includes(w)).length
+        if (qWords.length > 0 && hits === qWords.length) {
+          score = 30 + hits
+        } else if (hits > 0) {
+          score = 10 + hits
+        }
+      }
+      if (score > 0) {
+        scored.push({ component, score })
+      }
+    }
+
+    scored.sort(
+      (a, b) =>
+        b.score - a.score || a.component.name.localeCompare(b.component.name)
+    )
+
+    // Summaries only, capped to the most relevant — full objects blow up remote
+    // clients on broad queries; callers drill in via get_component. `count` is
+    // the true match total so the caller knows results were capped.
+    const page = scored.slice(0, SEARCH_LIMIT)
+    return {
+      count: scored.length,
+      returned: page.length,
+      hasMore: scored.length > page.length,
+      components: page.map((entry) => componentSummary(entry.component)),
+    }
+  }
+
+  function listTokens({
+    query = "",
+    theme = "",
+    group = "",
+    limit = DEFAULT_TOKEN_LIMIT,
+    offset = 0,
+  } = {}) {
+    const q = asText(query).trim().toLowerCase()
+    const t = asText(theme).trim().toLowerCase()
+    const g = asText(group).trim().toLowerCase()
+
+    // Drill-down level 0: with no query and no group, return only the category
+    // index (cheap) so an agent can see the full taxonomy and pick a category
+    // to drill into — instead of receiving a ~200-token color dump.
+    if (!q && !g) {
+      return {
+        mode: "categories",
+        groups: tokenGroups,
+        hint: "Drill in with list_tokens({ group }) for a category's tokens, or search_tokens(<name|intent>) / get_token(<name>) to narrow large color groups.",
+        tokens: [],
+      }
+    }
+
+    const matched = tokens.filter((token) => {
+      if (t && token.theme.toLowerCase() !== t) {
+        return false
+      }
+      if (g && token.group.toLowerCase() !== g) {
+        return false
+      }
+      if (!q) {
+        return true
+      }
+      // Match name/value AND intent metadata (utility/usage) so non-color
+      // tokens are discoverable by intent — e.g. "gap" or "spacing" → the
+      // gap-token scale, "between items" → the group tier.
+      return (
+        token.name.toLowerCase().includes(q) ||
+        token.value.toLowerCase().includes(q) ||
+        (token.utility || "").toLowerCase().includes(q) ||
+        (token.usage || "").toLowerCase().includes(q)
+      )
+    })
+
+    const safeLimit = Math.min(
+      Math.max(1, Number(limit) || DEFAULT_TOKEN_LIMIT),
+      MAX_TOKEN_LIMIT
+    )
+    const safeOffset = Math.max(0, Number(offset) || 0)
+    const page = matched.slice(safeOffset, safeOffset + safeLimit)
+
+    return {
+      count: matched.length,
+      returned: page.length,
+      offset: safeOffset,
+      limit: safeLimit,
+      hasMore: safeOffset + page.length < matched.length,
+      // Always present so consumers can see the full token taxonomy and tell
+      // the surface is complete (not color-only).
+      groups: tokenGroups,
+      tokens: page,
+    }
+  }
+
+  function getToken(name) {
+    const target = asText(name).trim().toLowerCase()
+    if (!target) {
+      return { error: "Token name is required." }
+    }
+    const matches = tokens.filter(
+      (token) => token.name.toLowerCase() === target
+    )
+    if (matches.length === 0) {
+      return { error: `Token not found: ${name}` }
+    }
+    return {
+      name,
+      tokens: matches,
+    }
+  }
+
+  function searchTokens(query) {
+    const qFull = asText(query).trim().toLowerCase()
+    if (!qFull) {
+      return {
+        count: 0,
+        returned: 0,
+        hasMore: false,
+        groups: tokenGroups,
+        tokens: [],
+      }
+    }
+    // Word-tokenized (like search_components): a match is the whole phrase OR
+    // every query word appearing in the token's searchable text, so reworded
+    // multi-word intents ("between groups", "icon to label") still resolve.
+    const qWords = qFull.split(/\s+/).filter(Boolean)
+    const matched = tokens.filter((token) => {
+      const hay = [token.name, token.value, token.utility, token.usage]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase()
+      return hay.includes(qFull) || qWords.every((w) => hay.includes(w))
+    })
+    const page = matched.slice(0, DEFAULT_TOKEN_LIMIT)
+    return {
+      count: matched.length,
+      returned: page.length,
+      hasMore: matched.length > page.length,
+      groups: tokenGroups,
+      tokens: page,
+    }
+  }
+
+  function guidelineSummary(guideline) {
+    return {
+      slug: guideline.slug,
+      title: guideline.title,
+      description: guideline.description,
+      headings: guideline.headings,
+    }
+  }
+
+  function listGuidelines(query = "") {
+    const q = asText(query).trim().toLowerCase()
+    const matched = guidelines.filter((guideline) => {
+      if (!q) {
+        return true
+      }
+      const haystack = [
+        guideline.slug,
+        guideline.title,
+        guideline.description,
+        (guideline.headings || []).join(" "),
+      ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase()
+      return haystack.includes(q)
+    })
+    // Index only (no body) — get_guideline returns the full prose on demand.
+    return {
+      count: matched.length,
+      guidelines: matched.map(guidelineSummary),
+    }
+  }
+
+  function getGuideline(slug) {
+    const target = asText(slug).trim().toLowerCase()
+    if (!target) {
+      return { error: "Guideline slug is required." }
+    }
+    const guideline = guidelines.find(
+      (entry) => entry.slug.toLowerCase() === target
+    )
+    if (!guideline) {
+      return { error: `Guideline not found: ${slug}` }
+    }
+    // Project out the internal sourcePath — consumers get the content, not the
+    // repo layout (consistent with the other tools' projections).
+    return {
+      slug: guideline.slug,
+      title: guideline.title,
+      description: guideline.description,
+      headings: guideline.headings,
+      body: guideline.body,
+    }
+  }
+
+  function resolveResource(uri) {
+    const u = asText(uri)
+    if (u === "volt-ui://components") {
+      return listComponents("")
+    }
+    if (u === "volt-ui://tokens") {
+      return listTokens({})
+    }
+    if (u.startsWith("volt-ui://components/")) {
+      const name = safeDecode(u.replace("volt-ui://components/", ""))
+      // Resources have no include= param, so return full detail (examples +
+      // tokens) — a resource read shouldn't silently drop usage examples.
+      return getComponent(name, "all")
+    }
+    if (u.startsWith("volt-ui://tokens/")) {
+      const name = safeDecode(u.replace("volt-ui://tokens/", ""))
+      return getToken(name)
+    }
+    return { error: `Unknown resource: ${u}` }
+  }
+
+  function listResources() {
+    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(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 [...baseResources, ...componentResources, ...tokenResources]
+  }
+
+  return {
+    listComponents,
+    getComponent,
+    searchComponents,
+    listTokens,
+    getToken,
+    searchTokens,
+    listGuidelines,
+    getGuideline,
+    resolveResource,
+    listResources,
+  }
+}
+
+/**
+ * Compact tool-result envelope (no pretty-printing — size discipline). Sets
+ * isError:true for error-shaped payloads ({error}) so MCP clients surface the
+ * failure instead of silently consuming it as a successful result.
+ */
+export function toolResult(payload) {
+  const isError =
+    payload != null &&
+    typeof payload === "object" &&
+    typeof payload.error === "string"
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload),
+      },
+    ],
+    ...(isError ? { isError: true } : {}),
+  }
+}

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@epilot/volt-ui-mcp",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "bin": {
     "volt-ui-mcp": "./index.js"
   },
+  "exports": {
+    ".": "./index.js",
+    "./lib.js": "./lib.js",
+    "./tools.js": "./tools.js",
+    "./registry.json": "./registry.json"
+  },
   "files": [
     "index.js",
+    "lib.js",
+    "lib.d.ts",
+    "tools.js",
     "registry.json"
   ],
   "scripts": {
-    "prepack": "bun ../react/scripts/build-mcp-registry.ts"
+    "prepack": "bun ../react/scripts/build-mcp-registry.ts",
+    "test": "bun test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"