@epilot/volt-ui-mcp 0.1.3 → 0.3.0

package/tools.js

@@ -0,0 +1,226 @@
+/**
+ * Single source of truth for MCP tool metadata (name, description, params).
+ *
+ * Both transports — the stdio bin (index.js) and the remote HTTP route
+ * (docs/app/api/[transport]/route.ts) — build their tool schemas from these
+ * specs, so descriptions and parameter docs can't drift between them. Handler
+ * wiring (which query function each tool calls) stays in each transport.
+ *
+ * Descriptions are the ONLY thing an agent uses to pick a tool, and they load
+ * into context on every turn — so they lead with WHEN to use each tool,
+ * disambiguate siblings, and teach the drill-down workflow (browse → narrow →
+ * resolve). Keep them high-signal and lean.
+ */
+
+// One server version, used by BOTH transports' serverInfo so they can't diverge.
+export const SERVER_VERSION = "0.3.0"
+
+// Every tool is a pure, side-effect-free registry lookup — declare it so clients
+// can treat calls as safe/cacheable.
+export const READ_ONLY_ANNOTATIONS = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  openWorldHint: false,
+}
+
+export const TOOL_SPECS = [
+  {
+    name: "list_components",
+    description:
+      "List Volt UI components (names + summaries). Use to browse what exists; use search_components to find by keyword/intent, then get_component for full details.",
+    params: [
+      {
+        name: "query",
+        type: "string",
+        optional: true,
+        description: "Optional keyword filter (component name or description).",
+      },
+    ],
+  },
+  {
+    name: "get_component",
+    description:
+      'Get a Volt UI component: props, composition requirements (required provider/ancestors/parts) and runtime constraints where applicable, and — for most components — one fully-wired example with the correct import. Pass include="examples,tokens" for the full example set and recommended token families.',
+    params: [
+      {
+        name: "name",
+        type: "string",
+        description: "Component name (e.g. Button, Accordion).",
+      },
+      {
+        name: "include",
+        type: "string",
+        optional: true,
+        description:
+          'Optional CSV of extra detail: "examples", "tokens", or "all". Defaults to a lean response.',
+      },
+    ],
+  },
+  {
+    name: "search_components",
+    description:
+      'Search components by name, description, prop names, or intent aliases (e.g. "info banner" → Callout, "side panel" → Drawer). Returns summaries; drill in with get_component.',
+    params: [
+      {
+        name: "query",
+        type: "string",
+        description:
+          'Search term — keyword or intent phrase (e.g. "info banner").',
+      },
+    ],
+  },
+  {
+    name: "list_tokens",
+    description:
+      'Browse the design-token taxonomy. With NO arguments, returns the category index (groups: spacing, palette, semantic, utility, other) with counts — cheap, no token dump. Pass group= to drill into one category\'s tokens (e.g. group="spacing"), or use search_tokens / get_token to narrow large color groups. Note: theme (light/dark) applies to palette tokens; other groups are global.',
+    params: [
+      {
+        name: "query",
+        type: "string",
+        optional: true,
+        description:
+          "Optional keyword/intent filter; when set, returns matching tokens instead of the category index.",
+      },
+      {
+        name: "theme",
+        type: "string",
+        optional: true,
+        description:
+          "Optional theme filter; applies to palette tokens (light/dark). Other groups are global, so theme+non-palette group returns empty.",
+      },
+      {
+        name: "group",
+        type: "string",
+        optional: true,
+        description:
+          "Category to drill into — one of: spacing, palette, semantic, utility, other. Returns that category's tokens.",
+      },
+      {
+        name: "limit",
+        type: "number",
+        optional: true,
+        description: "Max tokens per page (default 200, max 500).",
+      },
+      {
+        name: "offset",
+        type: "number",
+        optional: true,
+        description: "Pagination offset (default 0).",
+      },
+    ],
+  },
+  {
+    name: "get_token",
+    description:
+      "Resolve one design token by exact name (e.g. --volt-accent-9 or --spacing-group-2) to its value(s) across light/dark/global themes, plus intent metadata (utility + usage) for non-color tokens.",
+    params: [
+      {
+        name: "name",
+        type: "string",
+        description:
+          "Exact token name (e.g. --volt-accent-a3 or --spacing-group-2).",
+      },
+    ],
+  },
+  {
+    name: "search_tokens",
+    description:
+      'Find design tokens by name, value, or intent (e.g. "gap", "spacing", "accent"). Use when you know what you want; call list_tokens with no args to browse categories first.',
+    params: [
+      {
+        name: "query",
+        type: "string",
+        description:
+          'Search term — name, value, or intent (e.g. "gap", "accent").',
+      },
+    ],
+  },
+  {
+    name: "list_guidelines",
+    description:
+      "List Volt UI design guidelines (color/token usage, spacing, theming, ux-writing/tone, typography). Returns an index; use get_guideline for the full text.",
+    params: [
+      {
+        name: "query",
+        type: "string",
+        optional: true,
+        description: "Optional filter for guideline slug, title, or headings.",
+      },
+    ],
+  },
+  {
+    name: "get_guideline",
+    description:
+      "Get the full text of a Volt UI design guideline by slug (e.g. color, spacing, theming, ux-writing, font).",
+    params: [
+      {
+        name: "slug",
+        type: "string",
+        description: "Guideline slug (e.g. color, ux-writing).",
+      },
+    ],
+  },
+]
+
+/** Builds a JSON-Schema tool definition (stdio bin / ListTools) from a spec. */
+export function toJsonSchema(spec) {
+  const properties = {}
+  const required = []
+  for (const param of spec.params) {
+    properties[param.name] = {
+      type: param.type,
+      description: param.description,
+    }
+    if (!param.optional) {
+      required.push(param.name)
+    }
+  }
+  const inputSchema = {
+    type: "object",
+    properties,
+    additionalProperties: false,
+  }
+  if (required.length > 0) {
+    inputSchema.required = required
+  }
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema,
+    annotations: READ_ONLY_ANNOTATIONS,
+  }
+}
+
+// Single dispatch shared by BOTH transports so the handler wiring can't drift
+// (a one-sided tool addition would otherwise crash one transport silently).
+export function callTool(queries, name, args) {
+  const a = args || {}
+  const str = (v) => (typeof v === "string" ? v : "")
+  const num = (v) => (typeof v === "number" ? v : undefined)
+  switch (name) {
+    case "list_components":
+      return queries.listComponents(str(a.query))
+    case "get_component":
+      return queries.getComponent(str(a.name), str(a.include))
+    case "search_components":
+      return queries.searchComponents(str(a.query))
+    case "list_tokens":
+      return queries.listTokens({
+        query: str(a.query),
+        theme: str(a.theme),
+        group: str(a.group),
+        limit: num(a.limit),
+        offset: num(a.offset),
+      })
+    case "get_token":
+      return queries.getToken(str(a.name))
+    case "search_tokens":
+      return queries.searchTokens(str(a.query))
+    case "list_guidelines":
+      return queries.listGuidelines(str(a.query))
+    case "get_guideline":
+      return queries.getGuideline(str(a.slug))
+    default:
+      return { error: `Unknown tool: ${name}` }
+  }
+}