@deepgram/styles 0.2.13 → 0.2.15

package/README.md

@@ -292,6 +292,67 @@ Auto-generated custom elements with Shadow DOM, built from the same YAML source.
 
 ---
 
+## MCP Server (AI Agent Integration)
+
+The package includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI coding agents direct access to the design system — component names, BEM classes, rendered HTML examples, and design tokens.
+
+### Setup
+
+Install the package, then configure your AI tool:
+
+**Claude Code** (CLI or `.mcp.json`):
+
+```bash
+claude mcp add deepgram-styles --scope project -- npx -y -p @deepgram/styles mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`.cursor/mcp.json`), or **Windsurf** (`.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "deepgram-styles": {
+      "command": "npx",
+      "args": ["-y", "-p", "@deepgram/styles", "mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all components with metadata, tags, and counts. Filter by category. |
+| `get_component` | Full details for a component: BEM classes, variants, rendered HTML examples. |
+| `get_design_tokens` | Design tokens (colors, spacing, fonts, shadows, border-radius). |
+| `search_components` | Keyword search across names, titles, tags, and descriptions. |
+
+### Custom YAML
+
+To point the server at a custom design system YAML:
+
+```json
+{
+  "mcpServers": {
+    "deepgram-styles": {
+      "command": "npx",
+      "args": ["-y", "-p", "@deepgram/styles", "mcp", "--yaml", "./path/to/design-system.yaml"]
+    }
+  }
+}
+```
+
+### Testing
+
+Use the MCP Inspector to test interactively:
+
+```bash
+npx @modelcontextprotocol/inspector npx -y -p @deepgram/styles mcp
+```
+
+---
+
 ## Package Exports
 
 | Import | Description |
@@ -303,6 +364,7 @@ Auto-generated custom elements with Shadow DOM, built from the same YAML source.
 | `@deepgram/styles/react` | Typed React components |
 | `@deepgram/styles/utils` | Theme utility functions |
 | `@deepgram/styles/design-system` | Raw YAML design tokens |
+| `@deepgram/styles/mcp` | MCP server for AI agent integration |
 | `@deepgram/styles/logo/*` | 12 SVG logo variants |
 
 ---

package/design-system.yaml

@@ -660,6 +660,13 @@ categories:
           web-components:
             name: Web Components
             description: Framework-agnostic custom elements
+      integrations:
+        name: Integrations
+        icon: fa-plug
+        subsections:
+          mcp-server:
+            name: MCP Server
+            description: Give AI agents access to the design system
 components:
   btn:
     metadata:

package/dist/mcp/server.d.ts

@@ -0,0 +1,12 @@
+#!/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 -p @deepgram/styles mcp        # uses bundled design-system.yaml
+ *   node dist/mcp/server.js --yaml /path/to/design-system.yaml
+ */
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,477 @@
+#!/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 -p @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";
+// ---------------------------------------------------------------------------
+// Type guard
+// ---------------------------------------------------------------------------
+function isUseRefNode(node) {
+    return (typeof node === "object" &&
+        node !== null &&
+        "$ref" in node &&
+        typeof node.$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) {
+    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, level = 1) {
+    const spaces = "  ".repeat(level);
+    return code
+        .split("\n")
+        .map((line) => (line ? spaces + line : line))
+        .join("\n");
+}
+function astToHTML(node, depth = 0) {
+    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) {
+    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, component) {
+    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, node) {
+    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, ref) {
+    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 = [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 = {};
+    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;
+    if (ref.children) {
+        resolvedChildren = ref.children.map((child) => {
+            if (typeof child === "string")
+                return child;
+            return resolveNode(ds, child);
+        });
+    }
+    const result = { tag, props: mergedProps };
+    if (resolvedChildren)
+        result.children = resolvedChildren;
+    if (ref.text)
+        result.text = ref.text;
+    return result;
+}
+function resolvePathSegment(ds, component, componentKey, blockClass, pathSegment) {
+    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}`],
+    };
+}
+function collectAllExamples(component) {
+    const results = [];
+    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, name) {
+    const classes = new Set();
+    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.elements) {
+        for (const eKey of Object.keys(component.elements)) {
+            classes.add(`${blockClass}__${eKey}`);
+        }
+    }
+    return [...classes].sort();
+}
+// ---------------------------------------------------------------------------
+// Load YAML
+// ---------------------------------------------------------------------------
+function loadDesignSystem(yamlPath) {
+    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();
+    return resolveComponentRefs(ds);
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+function createServer(ds) {
+    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",
+                    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",
+                        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),
+        }));
+        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",
+                    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;
+            if (!(key in tokens)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Token group "${group}" not found. Available groups: ${Object.keys(tokens).join(", ")}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ [key]: tokens[key] }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    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",
+                    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() {
+    // Parse --yaml flag
+    let yamlPath;
+    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);
+});

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@deepgram/styles",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Tailwind-based design system and styles library for Deepgram design system and demos",
   "author": "Deepgram",
   "license": "ISC",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/deepgram/dx-design.git",
@@ -19,6 +20,9 @@
     "ui-components",
     "frontend"
   ],
+  "bin": {
+    "mcp": "dist/mcp/server.js"
+  },
   "main": "dist/deepgram.css",
   "style": "dist/deepgram.css",
   "files": [
@@ -96,14 +100,19 @@
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js",
+      "default": "./dist/mcp/server.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "tailwindcss": "^4.0.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "tailwindcss": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "tailwindcss": {
@@ -112,5 +121,10 @@
     "react": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "yaml": "^2.8.1",
+    "zod": "^4.3.6"
   }
 }

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 -p @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);
+});