@deepgram/styles 0.2.12 → 0.2.14

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 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.12",
+  "version": "0.2.14",
   "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": {
+    "deepgram-styles-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"
   }
 }