@deepgram/styles 0.2.12 → 0.2.14

package/src/mcp/server.ts

@@ -0,0 +1,724 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for @deepgram/styles
+ *
+ * Exposes the design system (tokens, components, examples) as MCP tools
+ * so AI agents can query BEM classes, rendered HTML examples, and tokens.
+ *
+ * Usage:
+ *   npx deepgram-styles-mcp            # uses bundled design-system.yaml
+ *   node dist/mcp/server.js --yaml /path/to/design-system.yaml
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Inline types (subset of tools/yaml-pipeline/src/schema/types.ts)
+// ---------------------------------------------------------------------------
+
+interface CSSRule {
+  apply?: string;
+  properties?: Record<string, string>;
+}
+
+type CSSRuleMap = Record<string, CSSRule>;
+
+interface StyleState {
+  apply?: string;
+  properties?: Record<string, string>;
+}
+
+interface ComponentStyles extends StyleState {
+  hover?: StyleState;
+  focus?: StyleState;
+  "focus-visible"?: StyleState;
+  "focus-within"?: StyleState;
+  active?: StyleState;
+  disabled?: StyleState;
+  checked?: StyleState;
+  "first-child"?: StyleState;
+  "last-child"?: StyleState;
+  media?: Record<string, StyleState>;
+}
+
+interface VariantNode {
+  title?: string;
+  description?: string;
+  styles?: ComponentStyles;
+  css?: CSSRuleMap;
+  media?: Record<string, CSSRuleMap>;
+  examples?: ComponentExample[];
+}
+
+interface ComponentNode {
+  $ref?: string;
+  tag?: string;
+  styles?: ComponentStyles;
+  variants?: Record<string, VariantNode>;
+  components?: Record<string, ComponentNode>;
+  css?: CSSRuleMap;
+  media?: Record<string, CSSRuleMap>;
+  examples?: ComponentExample[];
+  "default-props"?: Record<string, string>;
+  "class-props"?: Record<string, string>;
+  polymorphic?: boolean;
+}
+
+interface ASTNode {
+  tag: string;
+  props?: Record<string, string | boolean | number>;
+  children?: (ASTNode | UseRefNode | string)[];
+  text?: string;
+}
+
+interface UseRefNode {
+  $ref: string;
+  props?: Record<string, string | boolean | number>;
+  children?: (ASTNode | UseRefNode | string)[];
+  text?: string;
+}
+
+interface ComponentExample {
+  title: string;
+  description?: string;
+  ast: ASTNode | UseRefNode;
+}
+
+interface ComponentMetadata {
+  title: string;
+  description?: string;
+  category: string;
+  section: string;
+  subsection: string;
+  tags?: string[];
+}
+
+interface ComponentDefinition extends ComponentNode {
+  metadata: ComponentMetadata;
+  tag?: string;
+  variables?: Record<string, string>;
+  examples: ComponentExample[];
+}
+
+interface ColorToken {
+  value: string;
+  variable?: string;
+  fallback?: string;
+}
+
+interface FontToken {
+  family: string[];
+  "tailwind-key": string;
+}
+
+interface DesignTokens {
+  variables: Record<string, string>;
+  colors: {
+    brand: Record<string, ColorToken>;
+    background: Record<string, string>;
+    border: Record<string, string>;
+    text: Record<string, string>;
+    status: Record<string, string>;
+    gradient: Record<string, string>;
+  };
+  fonts: Record<string, FontToken>;
+  spacing: Record<string, string>;
+  "border-radius": Record<string, string>;
+  shadows: Record<string, string>;
+}
+
+interface DesignSystem {
+  version: string;
+  tokens: DesignTokens;
+  components: Record<string, ComponentDefinition>;
+}
+
+// ---------------------------------------------------------------------------
+// Type guard
+// ---------------------------------------------------------------------------
+
+function isUseRefNode(node: unknown): node is UseRefNode {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    "$ref" in node &&
+    typeof (node as UseRefNode).$ref === "string" &&
+    !("tag" in node)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline AST → HTML renderer (from generators/html.ts)
+// ---------------------------------------------------------------------------
+
+const SELF_CLOSING = new Set(["img", "br", "hr", "input", "meta", "link"]);
+
+function formatHTMLProps(
+  props: Record<string, string | boolean | number>
+): string {
+  return Object.entries(props)
+    .map(([key, value]) => {
+      if (typeof value === "boolean") return value ? key : "";
+      const attrName = key === "className" ? "class" : key;
+      return `${attrName}="${value}"`;
+    })
+    .filter(Boolean)
+    .join(" ");
+}
+
+function indentStr(code: string, level = 1): string {
+  const spaces = "  ".repeat(level);
+  return code
+    .split("\n")
+    .map((line) => (line ? spaces + line : line))
+    .join("\n");
+}
+
+function astToHTML(node: ASTNode, depth = 0): string {
+  const { tag, props = {}, children = [], text } = node;
+  const propsStr =
+    Object.keys(props).length > 0 ? " " + formatHTMLProps(props) : "";
+
+  if (SELF_CLOSING.has(tag) && !text && children.length === 0) {
+    return `<${tag}${propsStr} />`;
+  }
+
+  if (text) {
+    return `<${tag}${propsStr}>${text}</${tag}>`;
+  }
+
+  if (children.length > 0) {
+    const childrenStr = children
+      .map((child) => {
+        if (typeof child === "string") return child;
+        if ("tag" in child) return astToHTML(child, depth + 1);
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+
+    if (
+      children.length > 1 ||
+      (children[0] && typeof children[0] !== "string")
+    ) {
+      return `<${tag}${propsStr}>\n${indentStr(childrenStr, 1)}\n</${tag}>`;
+    }
+    return `<${tag}${propsStr}>${childrenStr}</${tag}>`;
+  }
+
+  return `<${tag}${propsStr}></${tag}>`;
+}
+
+// ---------------------------------------------------------------------------
+// Inline $ref resolver (from parser/resolve-refs.ts)
+// ---------------------------------------------------------------------------
+
+function resolveComponentRefs(ds: DesignSystem): DesignSystem {
+  const resolved = { ...ds, components: { ...ds.components } };
+  for (const [key, component] of Object.entries(resolved.components)) {
+    resolved.components[key] = resolveComponentExamples(ds, component);
+  }
+  return resolved;
+}
+
+function resolveComponentExamples(
+  ds: DesignSystem,
+  component: ComponentDefinition
+): ComponentDefinition {
+  const result = { ...component };
+
+  if (result.examples) {
+    result.examples = result.examples.map((ex) => ({
+      ...ex,
+      ast: resolveNode(ds, ex.ast),
+    }));
+  }
+
+  if (result.variants) {
+    result.variants = { ...result.variants };
+    for (const [vKey, variant] of Object.entries(result.variants)) {
+      if (variant.examples) {
+        result.variants[vKey] = {
+          ...variant,
+          examples: variant.examples.map((ex) => ({
+            ...ex,
+            ast: resolveNode(ds, ex.ast),
+          })),
+        };
+      }
+    }
+  }
+
+  if (result.components) {
+    result.components = { ...result.components };
+    for (const [cKey, child] of Object.entries(result.components)) {
+      if (child.examples) {
+        result.components[cKey] = {
+          ...child,
+          examples: child.examples.map((ex) => ({
+            ...ex,
+            ast: resolveNode(ds, ex.ast),
+          })),
+        };
+      }
+    }
+  }
+
+  return result;
+}
+
+function resolveNode(ds: DesignSystem, node: ASTNode | UseRefNode): ASTNode {
+  if (isUseRefNode(node)) {
+    return resolveUseRef(ds, node);
+  }
+
+  if (!node.children) return node;
+
+  const resolvedChildren = node.children.map((child) => {
+    if (typeof child === "string") return child;
+    return resolveNode(ds, child);
+  });
+
+  return { ...node, children: resolvedChildren };
+}
+
+function resolveUseRef(ds: DesignSystem, ref: UseRefNode): ASTNode {
+  const segments = ref.$ref.split("/");
+  const componentKey = segments[0];
+
+  const component = ds.components[componentKey];
+  if (!component) {
+    return { tag: "div", props: { class: `dg-${componentKey}` }, text: `[unresolved: ${ref.$ref}]` };
+  }
+
+  const blockClass = `dg-${componentKey}`;
+  let tag = component.tag ?? "div";
+  const classes: string[] = [blockClass];
+
+  if (segments.length > 1) {
+    const pathSegment = segments.slice(1).join("/");
+    const resolved = resolvePathSegment(
+      ds,
+      component,
+      componentKey,
+      blockClass,
+      pathSegment
+    );
+    tag = resolved.tag;
+    classes.length = 0;
+    classes.push(...resolved.classes);
+  }
+
+  const mergedProps: Record<string, string | boolean | number> = {};
+  if (classes.length > 0) {
+    mergedProps.class = classes.join(" ");
+  }
+  if (ref.props) {
+    for (const [key, value] of Object.entries(ref.props)) {
+      if (key === "class" && typeof value === "string") {
+        mergedProps.class = mergedProps.class
+          ? `${mergedProps.class} ${value}`
+          : value;
+      } else {
+        mergedProps[key] = value;
+      }
+    }
+  }
+
+  let resolvedChildren: (ASTNode | string)[] | undefined;
+  if (ref.children) {
+    resolvedChildren = ref.children.map((child) => {
+      if (typeof child === "string") return child;
+      return resolveNode(ds, child);
+    });
+  }
+
+  const result: ASTNode = { tag, props: mergedProps };
+  if (resolvedChildren) result.children = resolvedChildren;
+  if (ref.text) result.text = ref.text;
+
+  return result;
+}
+
+interface ResolvedPath {
+  tag: string;
+  classes: string[];
+}
+
+function resolvePathSegment(
+  ds: DesignSystem,
+  component: ComponentDefinition,
+  componentKey: string,
+  blockClass: string,
+  pathSegment: string
+): ResolvedPath {
+  const parts = pathSegment.split("+");
+
+  if (parts.length > 1) {
+    for (const part of parts) {
+      if (!component.variants?.[part]) {
+        return {
+          tag: component.tag ?? "div",
+          classes: [blockClass, ...parts.map((p) => `${blockClass}--${p}`)],
+        };
+      }
+    }
+    return {
+      tag: component.tag ?? "div",
+      classes: [blockClass, ...parts.map((p) => `${blockClass}--${p}`)],
+    };
+  }
+
+  const name = parts[0];
+
+  if (component.variants?.[name]) {
+    return {
+      tag: component.tag ?? "div",
+      classes: [blockClass, `${blockClass}--${name}`],
+    };
+  }
+
+  if (component.components?.[name]) {
+    const child = component.components[name];
+    const elementClass = `dg-${componentKey}__${name}`;
+
+    if (child.$ref) {
+      const refComponent = ds.components[child.$ref];
+      return {
+        tag: child.tag ?? refComponent?.tag ?? "div",
+        classes: [`dg-${child.$ref}`, elementClass],
+      };
+    }
+
+    return { tag: child.tag ?? "div", classes: [elementClass] };
+  }
+
+  // Graceful fallback for unknown segments
+  return {
+    tag: component.tag ?? "div",
+    classes: [blockClass, `${blockClass}--${name}`],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Inline example collector (from generators/collect-examples.ts)
+// ---------------------------------------------------------------------------
+
+interface CollectedExample {
+  example: ComponentExample;
+  variantKey?: string;
+}
+
+function collectAllExamples(
+  component: ComponentDefinition
+): CollectedExample[] {
+  const results: CollectedExample[] = [];
+
+  for (const example of component.examples) {
+    results.push({ example });
+  }
+
+  if (component.variants) {
+    for (const [vKey, variant] of Object.entries(component.variants)) {
+      if (variant.examples) {
+        for (const example of variant.examples) {
+          results.push({ example, variantKey: vKey });
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// CSS class extractor
+// ---------------------------------------------------------------------------
+
+function extractBEMClasses(component: ComponentDefinition, name: string): string[] {
+  const classes = new Set<string>();
+  const blockClass = `dg-${name}`;
+  classes.add(blockClass);
+
+  // From css rules
+  if (component.css) {
+    for (const selector of Object.keys(component.css)) {
+      const matches = selector.match(/\.dg-[\w-]+(?:__[\w-]+)?(?:--[\w-]+)?/g);
+      if (matches) matches.forEach((m) => classes.add(m.replace(/^\./, "")));
+    }
+  }
+
+  // From variants
+  if (component.variants) {
+    for (const vKey of Object.keys(component.variants)) {
+      classes.add(`${blockClass}--${vKey}`);
+      const variant = component.variants[vKey];
+      if (variant.css) {
+        for (const selector of Object.keys(variant.css)) {
+          const matches = selector.match(/\.dg-[\w-]+(?:__[\w-]+)?(?:--[\w-]+)?/g);
+          if (matches) matches.forEach((m) => classes.add(m.replace(/^\./, "")));
+        }
+      }
+    }
+  }
+
+  // From elements/components
+  if (component.components) {
+    for (const cKey of Object.keys(component.components)) {
+      classes.add(`${blockClass}__${cKey}`);
+    }
+  }
+
+  // From elements (legacy css-based)
+  if ((component as any).elements) {
+    for (const eKey of Object.keys((component as any).elements)) {
+      classes.add(`${blockClass}__${eKey}`);
+    }
+  }
+
+  return [...classes].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Load YAML
+// ---------------------------------------------------------------------------
+
+function loadDesignSystem(yamlPath?: string): DesignSystem {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const resolvedPath = yamlPath
+    ? resolve(yamlPath)
+    : resolve(__dirname, "..", "..", "design-system.yaml");
+
+  const raw = readFileSync(resolvedPath, "utf-8");
+  const doc = parseDocument(raw);
+  const ds = doc.toJSON() as DesignSystem;
+
+  return resolveComponentRefs(ds);
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+function createServer(ds: DesignSystem): McpServer {
+  const server = new McpServer({
+    name: "deepgram-styles",
+    version: ds.version ?? "0.0.0",
+  });
+
+  // ---- list_components ----
+  server.tool(
+    "list_components",
+    "List all components in the Deepgram design system. Returns component names, titles, categories, tags, and counts of variants and examples. Use the optional category filter to narrow results.",
+    { category: z.string().optional().describe("Filter by category (e.g. 'application-ui', 'marketing', 'documentation')") },
+    async ({ category }) => {
+      const entries = Object.entries(ds.components)
+        .filter(([, comp]) => !category || comp.metadata.category === category)
+        .map(([name, comp]) => ({
+          name,
+          title: comp.metadata.title,
+          category: comp.metadata.category,
+          section: comp.metadata.section,
+          subsection: comp.metadata.subsection,
+          tags: comp.metadata.tags ?? [],
+          variantCount: comp.variants ? Object.keys(comp.variants).length : 0,
+          exampleCount: collectAllExamples(comp).length,
+        }));
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(entries, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // ---- get_component ----
+  server.tool(
+    "get_component",
+    "Get full details for a specific Deepgram design system component. Returns BEM CSS classes, variant names, and rendered HTML examples you can copy-paste. Use list_components first to discover available component names.",
+    { name: z.string().describe("Component key (e.g. 'btn', 'card', 'alert')") },
+    async ({ name }) => {
+      const component = ds.components[name];
+      if (!component) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Component "${name}" not found. Use list_components to see available components.`,
+            },
+          ],
+        };
+      }
+
+      const bemClasses = extractBEMClasses(component, name);
+      const variants = component.variants
+        ? Object.entries(component.variants).map(([vKey, v]) => ({
+            name: vKey,
+            class: `dg-${name}--${vKey}`,
+            title: v.title,
+            description: v.description,
+          }))
+        : [];
+
+      const examples = collectAllExamples(component).map(
+        ({ example, variantKey }) => ({
+          title: example.title,
+          description: example.description,
+          variant: variantKey,
+          html: astToHTML(example.ast as ASTNode),
+        })
+      );
+
+      const result = {
+        name,
+        title: component.metadata.title,
+        description: component.metadata.description,
+        category: component.metadata.category,
+        section: component.metadata.section,
+        subsection: component.metadata.subsection,
+        tags: component.metadata.tags ?? [],
+        tag: component.tag ?? "div",
+        bemClasses,
+        variants,
+        examples,
+      };
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // ---- get_design_tokens ----
+  server.tool(
+    "get_design_tokens",
+    "Get design tokens (colors, spacing, fonts, shadows, border-radius, CSS variables) from the Deepgram design system. Tokens define the visual language — use these values instead of hardcoded colors or sizes.",
+    { group: z.string().optional().describe("Token group to return: 'colors', 'spacing', 'fonts', 'shadows', 'border-radius', 'variables'. Omit for all.") },
+    async ({ group }) => {
+      const tokens = ds.tokens;
+
+      if (group) {
+        const key = group as keyof DesignTokens;
+        if (!(key in tokens)) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Token group "${group}" not found. Available groups: ${Object.keys(tokens).join(", ")}`,
+              },
+            ],
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ [key]: tokens[key] }, null, 2),
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(tokens, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // ---- search_components ----
+  server.tool(
+    "search_components",
+    "Search for Deepgram design system components by keyword. Matches against component name, title, tags, description, category, section, and subsection. Returns matching components with metadata.",
+    { query: z.string().describe("Search keyword (e.g. 'button', 'navigation', 'form', 'card')") },
+    async ({ query }) => {
+      const q = query.toLowerCase();
+
+      const matches = Object.entries(ds.components)
+        .filter(([name, comp]) => {
+          const searchable = [
+            name,
+            comp.metadata.title,
+            comp.metadata.description ?? "",
+            comp.metadata.category,
+            comp.metadata.section,
+            comp.metadata.subsection,
+            ...(comp.metadata.tags ?? []),
+          ]
+            .join(" ")
+            .toLowerCase();
+          return searchable.includes(q);
+        })
+        .map(([name, comp]) => ({
+          name,
+          title: comp.metadata.title,
+          category: comp.metadata.category,
+          section: comp.metadata.section,
+          tags: comp.metadata.tags ?? [],
+          description: comp.metadata.description,
+          variantCount: comp.variants ? Object.keys(comp.variants).length : 0,
+          exampleCount: collectAllExamples(comp).length,
+        }));
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              matches.length > 0
+                ? JSON.stringify(matches, null, 2)
+                : `No components found matching "${query}". Try list_components to see all available components.`,
+          },
+        ],
+      };
+    }
+  );
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  // Parse --yaml flag
+  let yamlPath: string | undefined;
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--yaml" && args[i + 1]) {
+      yamlPath = args[i + 1];
+      i++;
+    }
+  }
+
+  const ds = loadDesignSystem(yamlPath);
+  const server = createServer(ds);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});