@cobwds/mcp-server 1.19.3

package/dist/lib/token-parser.js

@@ -0,0 +1,431 @@
+/**
+ * Design Token Parser
+ *
+ * Reads and parses COBWDS 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 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() {
+    const possiblePaths = [
+        // Bundled data — works in standalone installs (most reliable)
+        resolve(__dirname, "../../data/tokens/tokens.json"),
+        // 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 = [
+        // Bundled data — works in standalone installs (most reliable)
+        resolve(__dirname, "../../data/tokens/tokens.css"),
+        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;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+const LAYER_PREFIXES = ["primitive", "applied", "appearance", "theme"];
+// ============================================================================
+// CSS Variable Transformation
+// ============================================================================
+/**
+ * Transform a JSON token path to CSS variable name
+ *
+ * Examples:
+ * - "primitive.color.neutral.900" → "--cob-color-neutral-900"
+ * - "applied.color.text.default" → "--cob-color-text"
+ * - "color.theme.default" → "--cob-color-theme"
+ * - "font.size.md" → "--cob-font-size-md"
+ */
+export function toCSSVariable(jsonPath) {
+    let name = "--cob-" +
+        jsonPath
+            // Strip layer prefixes
+            .replace(new RegExp(`^(${LAYER_PREFIXES.join("|")})\\.`), "")
+            // 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(--cob-color-neutral-900)"
+ * - "{font.size.md}" → "var(--cob-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 = LAYER_PREFIXES.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 (LAYER_PREFIXES.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 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
+        : `--cob-${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;
+    }
+}
+/**
+ * Get recommended tokens for everyday use.
+ *
+ * Excludes color primitive tokens (the ~150 palette ramps like neutral-*, red-*,
+ * blue-*) which are low-level raw values. For font tokens, applied aliases
+ * (body-*, h*, ui-*) are sorted before primitives so the most useful tokens
+ * appear first.
+ */
+export function getRecommendedTokens() {
+    const tokens = getCSSTokens();
+    const filtered = tokens.filter((t) => !(t.category === "color" && t.layer === "primitive"));
+    // For font tokens, sort applied before primitive so named aliases surface first
+    filtered.sort((a, b) => {
+        if (a.category === "font" && b.category === "font") {
+            if (a.layer === "applied" && b.layer !== "applied")
+                return -1;
+            if (a.layer !== "applied" && b.layer === "applied")
+                return 1;
+        }
+        return 0;
+    });
+    return filtered;
+}
+/**
+ * Get only primitive (raw value) tokens across all categories.
+ */
+export function getPrimitiveTokens() {
+    const tokens = getCSSTokens();
+    return tokens.filter((t) => t.layer === "primitive");
+}
+/**
+ * Get alternative tokens in the same category that share the same name prefix.
+ *
+ * First looks for child variants (tokens starting with this token's name + "-"):
+ *   --cob-color-text  →  finds --cob-color-text-weak, --cob-color-text-reverse, etc.
+ *
+ * If no children exist, looks for siblings (tokens sharing the same parent prefix):
+ *   --cob-color-text-weak  →  parent: --cob-color-text  →  finds text, text-weaker, etc.
+ *
+ * Returns an array of cssVariable strings (empty if none found).
+ */
+export function getAlternativeTokens(token) {
+    const varName = token.cssVariable;
+    const tokens = getCSSTokens();
+    // Look for child variants: tokens starting with this token's name + "-"
+    const children = tokens.filter((t) => t.category === token.category && t.cssVariable.startsWith(varName + "-"));
+    if (children.length > 0) {
+        return children.map((t) => t.cssVariable);
+    }
+    // No children — look for siblings sharing the same parent prefix
+    const lastDash = varName.lastIndexOf("-");
+    if (lastDash <= 5)
+        return []; // "--cob-" is 6 chars minimum
+    const parent = varName.slice(0, lastDash);
+    return tokens
+        .filter((t) => t.category === token.category &&
+        t.cssVariable !== varName &&
+        (t.cssVariable === parent || t.cssVariable.startsWith(parent + "-")))
+        .map((t) => t.cssVariable);
+}
+/**
+ * Clear all cached tokens (useful for testing)
+ */
+export function clearTokenCache() {
+    cachedCSSTokens = null;
+    cachedTokenGraph = null;
+    cachedRawTokens = null;
+}

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

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

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

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

package/dist/prompts/cobwds-mode.js

@@ -0,0 +1,60 @@
+/**
+ * COBWDS Mode Prompt
+ *
+ * Activates COBWDS-aware coding assistance.
+ */
+export function registerPrompts(server) {
+    server.prompt("cobwds_mode", "Activates COBWDS-aware coding assistance with knowledge of components, tokens, and best practices", {}, async () => {
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `You are now in COBWDS (City of Boston Web Design System) mode. You have access to comprehensive knowledge about COBWDS web components and design tokens.
+
+## Your Capabilities
+
+1. **Component Knowledge**: You can list, search, and provide detailed documentation for all COBWDS web components using the available tools.
+
+2. **Design Tokens**: You can access and explain COBWDS design tokens for colors, spacing, typography, and more.
+
+3. **Code Generation**: When generating code that uses UI components, prefer COBWDS 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, .NET, Drupal, Vanilla JS).
+
+## Best Practices
+
+- Always use semantic COBWDS components (e.g., \`<cob-button>\` instead of \`<button>\`)
+- Use COBWDS design tokens via CSS custom properties for consistent styling
+- Follow accessibility guidelines built into COBWDS components
+- Reference the official documentation at https://cityofboston.github.io/nywds-poc/
+
+## Available Tools
+
+### Components
+- \`find_components\`: Search for components or list all (omit query to list all)
+- \`get_component\`: Get detailed docs for a specific component
+- \`validate_component_api\`: Validate component attribute/property usage
+
+### Design Tokens
+- \`get_tokens\`: Get tokens, categories, or themes (use output parameter)
+- \`find_tokens\`: Search for tokens by name, value, or description
+- \`get_token_info\`: Get details about a specific token with optional context validation
+- \`get_token_graph\`: Explore token dependencies
+
+### Styles & Utilities
+- \`get_utility_classes\`: Grid, flexbox, spacing, and other utility classes
+
+### Guides
+- \`get_guide\`: Get guides for installation, forms, styles, fonts, page structure, or framework setup
+
+When helping with UI development for the City of Boston projects, prioritize COBWDS components and patterns.`,
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/resources/components.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Component Resources
+ *
+ * MCP resources for COBWDS component documentation.
+ *
+ * P0 Resources:
+ * - cobwds://components - Component overview list
+ * - cobwds://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 COBWDS component documentation.
+ *
+ * P0 Resources:
+ * - cobwds://components - Component overview list
+ * - cobwds://component/{tag} - Individual component docs
+ */
+import { getAllComponents, getComponent } from "../lib/cem-parser.js";
+export function registerComponentResources(server) {
+    // cobwds://components - Component overview list
+    server.resource("components", "cobwds://components", {
+        description: "List of all COBWDS 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: "cobwds://components",
+                    mimeType: "application/json",
+                    text: JSON.stringify(list, null, 2),
+                },
+            ],
+        };
+    });
+    // cobwds://component/{tag} - Individual component docs
+    server.resource("component", "cobwds://component/{tag}", {
+        description: "Full documentation for a specific COBWDS component",
+        mimeType: "application/json",
+    }, async (uri) => {
+        // Extract tag from URI: cobwds://component/cob-button -> cob-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 COBWDS installation and usage guides.
+ *
+ * P0 Resources:
+ * - cobwds://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,CAyE9D"}

package/dist/resources/guides.js

@@ -0,0 +1,76 @@
+/**
+ * Guide Resources
+ *
+ * MCP resources for COBWDS installation and usage guides.
+ *
+ * P0 Resources:
+ * - cobwds://installation - Installation guide
+ */
+export function registerGuideResources(server) {
+    // cobwds://installation - Installation guide
+    server.resource("installation", "cobwds://installation", {
+        description: "COBWDS installation and setup guide",
+        mimeType: "text/markdown",
+    }, async () => {
+        const guide = `# COBWDS Installation Guide
+
+## 1. Install packages
+
+\`\`\`bash
+npm install @cobwds/components @cobwds/styles
+\`\`\`
+
+## 2. Load styles
+
+COBWDS components require CSS variables to render correctly. Choose the right stylesheet:
+
+**New project** — includes a CSS reset, typography, and utility/layout classes:
+\`\`\`css
+@import '@cobwds/styles/full';
+\`\`\`
+
+**Existing project** — loads only the CSS variables that style the components:
+\`\`\`css
+@import '@cobwds/styles';
+\`\`\`
+
+## 3. Import and use components
+
+\`\`\`javascript
+import '@cobwds/cob-button';
+import '@cobwds/cob-alert';
+\`\`\`
+
+Or import all components:
+
+\`\`\`javascript
+import '@cobwds/components';
+\`\`\`
+
+Then use them in HTML:
+
+\`\`\`html
+<cob-button label="Submit" variant="filled"></cob-button>
+<cob-alert type="info">This is an informational message.</cob-alert>
+\`\`\`
+
+## Framework Integration
+
+For framework-specific setup, use the \`get_guide\` tool with \`topic: "framework"\` and a \`framework\` parameter (angular, react, dotnet, drupal, or vanilla).
+
+## Resources
+
+- Documentation: https://cityofboston.github.io/nywds-poc/
+- GitHub: https://github.com/CityOfBoston/nywds-poc
+`;
+        return {
+            contents: [
+                {
+                    uri: "cobwds://installation",
+                    mimeType: "text/markdown",
+                    text: guide,
+                },
+            ],
+        };
+    });
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Resources Registration
+ *
+ * Registers all COBWDS resources with the MCP server.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAIzD"}