@nysds/mcp-server 1.0.0 → 1.14.0

package/dist/lib/token-parser.js

@@ -0,0 +1,458 @@
+/**
+ * Design Token Parser
+ *
+ * Reads and parses NYSDS design tokens with a CSS-centric approach.
+ * Returns data aligned with tokens.css output (not JSON internals).
+ *
+ * Key transformations:
+ * - Token paths are converted to CSS variable names
+ * - Alias references become var() expressions
+ * - Layer prefixes (primitive, applied) are stripped
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// ESM path resolution
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ============================================================================
+// Token Data Cache
+// ============================================================================
+let cachedLegacyTokens = null;
+let cachedCSSTokens = null;
+let cachedTokenGraph = null;
+let cachedRawTokens = null;
+// ============================================================================
+// Path Resolution
+// ============================================================================
+/**
+ * Get the path to tokens.json file
+ * Uses ESM-compatible path resolution with fallbacks for different contexts
+ */
+export function getTokensPath() {
+    // Fallback paths for different execution contexts
+    const possiblePaths = [
+        // From lib/ directory (normal execution)
+        resolve(__dirname, "../../../../tokens/src/tokens.json"),
+        // From mcp-server package root
+        resolve(__dirname, "../../../tokens/src/tokens.json"),
+        // From monorepo root
+        resolve(__dirname, "../../../../../packages/tokens/src/tokens.json"),
+        // Direct path from monorepo root
+        resolve(process.cwd(), "packages/tokens/src/tokens.json"),
+        // From mcp-server package
+        resolve(process.cwd(), "../tokens/src/tokens.json"),
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    return null;
+}
+/**
+ * Get the path to tokens.css file
+ */
+export function getTokensCSSPath() {
+    const possiblePaths = [
+        resolve(__dirname, "../../../../tokens/dist/tokens.css"),
+        resolve(__dirname, "../../../tokens/dist/tokens.css"),
+        resolve(__dirname, "../../../../../packages/tokens/dist/tokens.css"),
+        resolve(process.cwd(), "packages/tokens/dist/tokens.css"),
+        resolve(process.cwd(), "../tokens/dist/tokens.css"),
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    return null;
+}
+// ============================================================================
+// CSS Variable Transformation
+// ============================================================================
+/**
+ * Transform a JSON token path to CSS variable name
+ *
+ * Examples:
+ * - "primitive.color.neutral.900" → "--nys-color-neutral-900"
+ * - "applied.color.text.default" → "--nys-color-text"
+ * - "color.theme.default" → "--nys-color-theme"
+ * - "font.size.md" → "--nys-font-size-md"
+ */
+export function toCSSVariable(jsonPath) {
+    let name = "--nys-" +
+        jsonPath
+            // Strip layer prefixes
+            .replace(/^(primitive|applied|appearance|theme)\./, "")
+            // Dots to hyphens
+            .replace(/\./g, "-");
+    // Strip trailing -default suffix
+    name = name.replace(/-default$/, "");
+    return name;
+}
+/**
+ * Convert an alias reference to CSS var() syntax
+ *
+ * Examples:
+ * - "{primitive.color.neutral.900}" → "var(--nys-color-neutral-900)"
+ * - "{font.size.md}" → "var(--nys-font-size-md)"
+ */
+export function aliasToVarRef(aliasValue) {
+    // Extract the path from {path.to.token}
+    const match = aliasValue.match(/^\{(.+)\}$/);
+    if (!match) {
+        return { cssValue: aliasValue, referencesVariable: "" };
+    }
+    const referencesVariable = toCSSVariable(match[1]);
+    const cssValue = `var(${referencesVariable})`;
+    return { cssValue, referencesVariable };
+}
+/**
+ * Determine the category from a JSON path
+ */
+function getCategoryFromPath(jsonPath) {
+    const parts = jsonPath.split(".");
+    // Skip layer prefix if present
+    const startIndex = ["primitive", "applied", "appearance", "theme"].includes(parts[0])
+        ? 1
+        : 0;
+    return parts[startIndex] || "unknown";
+}
+/**
+ * Determine the layer from a JSON path
+ *
+ * Layers:
+ * - primitive: Raw values (colors, sizes, fonts, spacing, etc.)
+ * - applied: Semantic tokens that reference primitives (includes color.theme.* defaults)
+ * - theme: Agency theme overrides
+ * - appearance: Light/dark mode variations
+ */
+function getLayerFromPath(jsonPath) {
+    const parts = jsonPath.split(".");
+    // Check for explicit layer prefixes
+    if (["primitive", "applied", "appearance", "theme"].includes(parts[0])) {
+        return parts[0];
+    }
+    // color.theme.* tokens are applied semantic tokens (agency themes override these)
+    if (parts[0] === "color" && parts[1] === "theme") {
+        return "applied";
+    }
+    // Non-prefixed categories (space, size, font, radius, etc.) contain raw values
+    // so they are classified as "primitive"
+    return "primitive";
+}
+// ============================================================================
+// Token Parsing
+// ============================================================================
+/**
+ * Load raw token data from tokens.json
+ */
+function loadRawTokens() {
+    if (cachedRawTokens) {
+        return cachedRawTokens;
+    }
+    const tokensPath = getTokensPath();
+    if (!tokensPath) {
+        console.error("Warning: No tokens file found");
+        return null;
+    }
+    try {
+        const content = readFileSync(tokensPath, "utf-8");
+        cachedRawTokens = JSON.parse(content);
+        return cachedRawTokens;
+    }
+    catch (error) {
+        console.error("Warning: Could not parse tokens file:", error);
+        return null;
+    }
+}
+/**
+ * Parse tokens recursively into CSS-centric format
+ */
+function parseCSSTokens(obj, prefix = "", resolvedValues = new Map()) {
+    const tokens = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith("$"))
+            continue; // Skip meta properties
+        const jsonPath = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === "object" &&
+            value !== null &&
+            "$value" in value) {
+            // This is a token
+            const tokenObj = value;
+            const rawValue = tokenObj.$value;
+            const description = tokenObj.$description;
+            const cssVariable = toCSSVariable(jsonPath);
+            const category = getCategoryFromPath(jsonPath);
+            const layer = getLayerFromPath(jsonPath);
+            let cssValue;
+            let referencesVariable;
+            let resolvedValue;
+            // Handle different value types
+            if (typeof rawValue === "string" && rawValue.startsWith("{")) {
+                // Alias reference
+                const aliasResult = aliasToVarRef(rawValue);
+                cssValue = aliasResult.cssValue;
+                referencesVariable = aliasResult.referencesVariable;
+                // Try to resolve the value
+                resolvedValue = resolvedValues.get(referencesVariable);
+            }
+            else if (Array.isArray(rawValue)) {
+                // Complex value (like shadows) - format as string
+                cssValue = JSON.stringify(rawValue);
+                resolvedValue = cssValue;
+            }
+            else if (typeof rawValue === "object" && rawValue !== null) {
+                // Object value (like single shadow)
+                cssValue = JSON.stringify(rawValue);
+                resolvedValue = cssValue;
+            }
+            else {
+                // Direct value
+                cssValue = String(rawValue);
+                resolvedValue = cssValue;
+            }
+            // Store resolved value for other tokens to reference
+            if (resolvedValue) {
+                resolvedValues.set(cssVariable, resolvedValue);
+            }
+            tokens.push({
+                cssVariable,
+                cssValue,
+                referencesVariable,
+                resolvedValue,
+                description,
+                category,
+                layer,
+                jsonPath,
+            });
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Recurse into nested group
+            tokens.push(...parseCSSTokens(value, jsonPath, resolvedValues));
+        }
+    }
+    return tokens;
+}
+/**
+ * Resolve all alias values to their final resolved values
+ */
+function resolveAllValues(tokens) {
+    const byVariable = new Map();
+    for (const token of tokens) {
+        byVariable.set(token.cssVariable, token);
+    }
+    // Iterate to resolve nested aliases (max 10 levels to prevent infinite loops)
+    for (let i = 0; i < 10; i++) {
+        let changed = false;
+        for (const token of tokens) {
+            if (token.referencesVariable && !token.resolvedValue) {
+                const referenced = byVariable.get(token.referencesVariable);
+                if (referenced?.resolvedValue) {
+                    token.resolvedValue = referenced.resolvedValue;
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+}
+// ============================================================================
+// Token Graph
+// ============================================================================
+/**
+ * Build a dependency graph of tokens
+ * Shows which tokens reference which, and which tokens are used by which
+ */
+export function buildTokenGraph() {
+    if (cachedTokenGraph) {
+        return cachedTokenGraph;
+    }
+    const tokens = getCSSTokens();
+    const graph = new Map();
+    // Initialize all nodes
+    for (const token of tokens) {
+        graph.set(token.cssVariable, {
+            cssVariable: token.cssVariable,
+            referencesVariable: token.referencesVariable,
+            usedBy: [],
+        });
+    }
+    // Build usedBy relationships
+    for (const token of tokens) {
+        if (token.referencesVariable) {
+            const referenced = graph.get(token.referencesVariable);
+            if (referenced) {
+                referenced.usedBy.push(token.cssVariable);
+            }
+        }
+    }
+    cachedTokenGraph = graph;
+    return graph;
+}
+// ============================================================================
+// Public API - CSS-Centric
+// ============================================================================
+/**
+ * Get all tokens in CSS-centric format
+ */
+export function getCSSTokens() {
+    if (cachedCSSTokens) {
+        return cachedCSSTokens;
+    }
+    const rawTokens = loadRawTokens();
+    if (!rawTokens) {
+        cachedCSSTokens = [];
+        return cachedCSSTokens;
+    }
+    cachedCSSTokens = parseCSSTokens(rawTokens);
+    resolveAllValues(cachedCSSTokens);
+    return cachedCSSTokens;
+}
+/**
+ * Get CSS tokens filtered by category
+ */
+export function getCSSTokensByCategory(category) {
+    const tokens = getCSSTokens();
+    return tokens.filter((t) => t.category.toLowerCase() === category.toLowerCase());
+}
+/**
+ * Get CSS tokens filtered by layer
+ */
+export function getCSSTokensByLayer(layer) {
+    const tokens = getCSSTokens();
+    return tokens.filter((t) => t.layer.toLowerCase() === layer.toLowerCase());
+}
+/**
+ * Search CSS tokens by variable name, value, or description
+ */
+export function searchCSSTokens(query) {
+    const tokens = getCSSTokens();
+    const lowerQuery = query.toLowerCase();
+    return tokens.filter((t) => t.cssVariable.toLowerCase().includes(lowerQuery) ||
+        t.cssValue.toLowerCase().includes(lowerQuery) ||
+        t.resolvedValue?.toLowerCase().includes(lowerQuery) ||
+        t.description?.toLowerCase().includes(lowerQuery));
+}
+/**
+ * Get a single token by CSS variable name
+ */
+export function getCSSTokenByVariable(variableName) {
+    const tokens = getCSSTokens();
+    // Normalize: accept with or without -- prefix
+    const normalized = variableName.startsWith("--")
+        ? variableName
+        : `--nys-${variableName}`;
+    return tokens.find((t) => t.cssVariable === normalized);
+}
+/**
+ * Get all unique categories
+ */
+export function getCSSTokenCategories() {
+    const tokens = getCSSTokens();
+    const counts = new Map();
+    for (const token of tokens) {
+        counts.set(token.category, (counts.get(token.category) || 0) + 1);
+    }
+    return Array.from(counts.entries())
+        .map(([category, count]) => ({ category, count }))
+        .sort((a, b) => a.category.localeCompare(b.category));
+}
+/**
+ * Get raw tokens.css content
+ */
+export function getTokensCSS() {
+    const cssPath = getTokensCSSPath();
+    if (!cssPath) {
+        return null;
+    }
+    try {
+        return readFileSync(cssPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Public API - Legacy (Backward Compatible)
+// ============================================================================
+/**
+ * Parse DTCG format tokens recursively (legacy format)
+ */
+function parseDTCGTokens(obj, prefix = "", category = "") {
+    const tokens = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith("$"))
+            continue; // Skip meta properties
+        const name = prefix ? `${prefix}.${key}` : key;
+        const currentCategory = category || key;
+        if (typeof value === "object" &&
+            value !== null &&
+            "$value" in value) {
+            // This is a token
+            const tokenObj = value;
+            tokens.push({
+                name,
+                value: String(tokenObj.$value),
+                category: currentCategory,
+                description: tokenObj.$description,
+            });
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Recurse into nested group
+            tokens.push(...parseDTCGTokens(value, name, currentCategory));
+        }
+    }
+    return tokens;
+}
+/**
+ * Load all design tokens (legacy format)
+ */
+export function getAllTokens() {
+    if (cachedLegacyTokens) {
+        return cachedLegacyTokens;
+    }
+    const rawTokens = loadRawTokens();
+    if (!rawTokens) {
+        cachedLegacyTokens = [];
+        return cachedLegacyTokens;
+    }
+    cachedLegacyTokens = parseDTCGTokens(rawTokens);
+    return cachedLegacyTokens;
+}
+/**
+ * Get tokens filtered by category (legacy format)
+ */
+export function getTokensByCategory(category) {
+    const tokens = getAllTokens();
+    return tokens.filter((t) => t.category.toLowerCase() === category.toLowerCase());
+}
+/**
+ * Search tokens by name or value (legacy format)
+ */
+export function searchTokens(query) {
+    const tokens = getAllTokens();
+    const lowerQuery = query.toLowerCase();
+    return tokens.filter((t) => t.name.toLowerCase().includes(lowerQuery) ||
+        t.value.toLowerCase().includes(lowerQuery) ||
+        t.description?.toLowerCase().includes(lowerQuery));
+}
+/**
+ * Get available token categories (legacy format)
+ */
+export function getTokenCategories() {
+    const tokens = getAllTokens();
+    const categories = new Set(tokens.map((t) => t.category));
+    return Array.from(categories).sort();
+}
+/**
+ * Clear all cached tokens (useful for testing)
+ */
+export function clearTokenCache() {
+    cachedLegacyTokens = null;
+    cachedCSSTokens = null;
+    cachedTokenGraph = null;
+    cachedRawTokens = null;
+}

package/dist/prompts/nysds-mode.d.ts

@@ -0,0 +1,8 @@
+/**
+ * NYSDS Mode Prompt
+ *
+ * Activates NYSDS-aware coding assistance.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;
+//# sourceMappingURL=nysds-mode.d.ts.map

package/dist/prompts/nysds-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nysds-mode.d.ts","sourceRoot":"","sources":["../../src/prompts/nysds-mode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAkDvD"}

package/dist/prompts/nysds-mode.js

@@ -0,0 +1,51 @@
+/**
+ * NYSDS Mode Prompt
+ *
+ * Activates NYSDS-aware coding assistance.
+ */
+export function registerPrompts(server) {
+    server.prompt("nysds_mode", "Activates NYSDS-aware coding assistance with knowledge of components, tokens, and best practices", {}, async () => {
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `You are now in NYSDS (New York State Design System) mode. You have access to comprehensive knowledge about NYSDS web components and design tokens.
+
+## Your Capabilities
+
+1. **Component Knowledge**: You can list, search, and provide detailed documentation for all NYSDS web components using the available tools.
+
+2. **Design Tokens**: You can access and explain NYSDS design tokens for colors, spacing, typography, and more.
+
+3. **Code Generation**: When generating code that uses UI components, prefer NYSDS components over generic HTML or other libraries.
+
+4. **Validation**: You can validate component usage to ensure correct attribute and property usage.
+
+5. **Framework Integration**: You can provide setup guides for various frameworks (React, Angular, Vue, .NET, Drupal).
+
+## Best Practices
+
+- Always use semantic NYSDS components (e.g., \`<nys-button>\` instead of \`<button>\`)
+- Use NYSDS design tokens via CSS custom properties for consistent styling
+- Follow accessibility guidelines built into NYSDS components
+- Reference the official documentation at https://designsystem.ny.gov/
+
+## Available Tools
+
+- \`list_components\`: See all available components
+- \`get_component_docs\`: Get detailed docs for a specific component
+- \`find_components\`: Search for components by functionality
+- \`get_design_tokens\`: Access design token values
+- \`validate_component_api\`: Validate component usage
+- \`setup_framework\`: Get framework-specific setup guides
+- \`get_usage_guide\`: General installation and usage guide
+
+When helping with UI development for New York State projects, prioritize NYSDS components and patterns.`,
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/resources/components.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Component Resources
+ *
+ * MCP resources for NYSDS component documentation.
+ *
+ * P0 Resources:
+ * - nysds://components - Component overview list
+ * - nysds://component/{tag} - Individual component docs
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerComponentResources(server: McpServer): void;
+//# sourceMappingURL=components.d.ts.map

package/dist/resources/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/resources/components.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiElE"}

package/dist/resources/components.js

@@ -0,0 +1,62 @@
+/**
+ * Component Resources
+ *
+ * MCP resources for NYSDS component documentation.
+ *
+ * P0 Resources:
+ * - nysds://components - Component overview list
+ * - nysds://component/{tag} - Individual component docs
+ */
+import { getAllComponents, getComponent } from "../lib/cem-parser.js";
+export function registerComponentResources(server) {
+    // nysds://components - Component overview list
+    server.resource("components", "nysds://components", {
+        description: "List of all NYSDS web components with summaries",
+        mimeType: "application/json",
+    }, async () => {
+        const components = getAllComponents();
+        const list = components.map((c) => ({
+            tagName: c.tagName,
+            name: c.name,
+            summary: c.summary || c.description?.split("\n")[0] || "No description",
+        }));
+        return {
+            contents: [
+                {
+                    uri: "nysds://components",
+                    mimeType: "application/json",
+                    text: JSON.stringify(list, null, 2),
+                },
+            ],
+        };
+    });
+    // nysds://component/{tag} - Individual component docs
+    server.resource("component", "nysds://component/{tag}", {
+        description: "Full documentation for a specific NYSDS component",
+        mimeType: "application/json",
+    }, async (uri) => {
+        // Extract tag from URI: nysds://component/nys-button -> nys-button
+        const tag = uri.pathname.split("/").pop() || "";
+        const component = getComponent(tag);
+        if (!component) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "text/plain",
+                        text: `Component "${tag}" not found`,
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(component, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/resources/guides.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Guide Resources
+ *
+ * MCP resources for NYSDS installation and usage guides.
+ *
+ * P0 Resources:
+ * - nysds://installation - Installation guide
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGuideResources(server: McpServer): void;
+//# sourceMappingURL=guides.d.ts.map

package/dist/resources/guides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guides.d.ts","sourceRoot":"","sources":["../../src/resources/guides.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6E9D"}

package/dist/resources/guides.js

@@ -0,0 +1,80 @@
+/**
+ * Guide Resources
+ *
+ * MCP resources for NYSDS installation and usage guides.
+ *
+ * P0 Resources:
+ * - nysds://installation - Installation guide
+ */
+export function registerGuideResources(server) {
+    // nysds://installation - Installation guide
+    server.resource("installation", "nysds://installation", {
+        description: "NYSDS installation and setup guide",
+        mimeType: "text/markdown",
+    }, async () => {
+        const guide = `# NYSDS Installation Guide
+
+## Quick Start
+
+Install the NYSDS components package:
+
+\`\`\`bash
+npm install @nysds/components
+\`\`\`
+
+## Import Components
+
+### Option 1: Import All Components
+
+\`\`\`javascript
+import '@nysds/components';
+\`\`\`
+
+### Option 2: Import Individual Components
+
+\`\`\`javascript
+import '@nysds/components/nys-button';
+import '@nysds/components/nys-alert';
+\`\`\`
+
+## Include Styles
+
+Import the base CSS for design tokens:
+
+\`\`\`css
+@import '@nysds/components/dist/styles.css';
+\`\`\`
+
+## Usage
+
+Once imported, use components as HTML elements:
+
+\`\`\`html
+<nys-button label="Submit" variant="primary"></nys-button>
+<nys-alert type="success">Operation completed successfully!</nys-alert>
+\`\`\`
+
+## Framework Integration
+
+For framework-specific setup (React, Angular, Vue, etc.), use the \`setup_framework\` tool.
+
+## Browser Support
+
+NYSDS components support all modern browsers (Chrome, Firefox, Safari, Edge).
+
+## Resources
+
+- Documentation: https://designsystem.ny.gov/
+- GitHub: https://github.com/ITS-HCD/nysds
+`;
+        return {
+            contents: [
+                {
+                    uri: "nysds://installation",
+                    mimeType: "text/markdown",
+                    text: guide,
+                },
+            ],
+        };
+    });
+}