@cobwds/mcp-server 1.19.3

package/dist/tools/token-tools.js

@@ -0,0 +1,207 @@
+/**
+ * Token Tools
+ *
+ * MCP tools for working with COBWDS design tokens.
+ *
+ * Tools:
+ * - find_tokens: Search or browse tokens (discovery)
+ * - get_token: Get full details for a specific token (deep dive)
+ * - get_token_graph: Get token dependency graph
+ */
+import { z } from "zod";
+import { getCSSTokens, getCSSTokenByVariable, buildTokenGraph, getRecommendedTokens, getPrimitiveTokens, getAlternativeTokens, } from "../lib/token-parser.js";
+// ============================================================================
+// Shared Constants
+// ============================================================================
+const CATEGORY_ENUM = [
+    "color",
+    "font",
+    "space",
+    "size",
+    "radius",
+    "shadow",
+    "border",
+    "form",
+    "gutter",
+    "icon",
+];
+const TOKEN_TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerTokenTools(server) {
+    // -------------------------------------------------------------------------
+    // find_tokens - Search or browse tokens (discovery)
+    // -------------------------------------------------------------------------
+    server.tool("find_tokens", "Search or browse COBWDS design tokens. Omit query to list all. Returns CSS variable names for use with var().", {
+        query: z
+            .string()
+            .optional()
+            .describe("Free-text search across token names and descriptions. Omit to list all."),
+        category: z.enum(CATEGORY_ENUM).optional().describe("Filter by category"),
+        include: z
+            .enum(["recommended", "primitive", "all"])
+            .default("recommended")
+            .describe("'recommended' (default) excludes color primitives; 'primitive' returns only primitives; 'all' returns everything"),
+    }, TOKEN_TOOL_ANNOTATIONS, async ({ query, category, include }) => {
+        // Pick token set based on include value
+        let tokens;
+        if (include === "primitive") {
+            tokens = getPrimitiveTokens();
+        }
+        else if (include === "all") {
+            tokens = getCSSTokens();
+        }
+        else {
+            tokens = getRecommendedTokens();
+        }
+        // Apply category filter
+        if (category) {
+            tokens = tokens.filter((t) => t.category.toLowerCase() === category.toLowerCase());
+        }
+        // Apply query filter (case-insensitive match on cssVariable or description)
+        if (query) {
+            const lowerQuery = query.toLowerCase();
+            tokens = tokens.filter((t) => t.cssVariable.toLowerCase().includes(lowerQuery) ||
+                t.description?.toLowerCase().includes(lowerQuery));
+        }
+        const results = tokens.map((t) => ({
+            cssVariable: t.cssVariable,
+            description: t.description,
+            category: t.category,
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ count: results.length, results }, null, 2),
+                },
+            ],
+        };
+    });
+    // -------------------------------------------------------------------------
+    // get_token - Get full details for a specific token (deep dive)
+    // -------------------------------------------------------------------------
+    server.tool("get_token", "Get full details for a specific design token including resolved values and alternatives.", {
+        token: z
+            .string()
+            .describe('CSS variable name (e.g., "--cob-color-text" or "color-text")'),
+    }, TOKEN_TOOL_ANNOTATIONS, async ({ token }) => {
+        const tokenInfo = getCSSTokenByVariable(token);
+        if (!tokenInfo) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Token not found: ${token}`,
+                            suggestion: "Use find_tokens to search for available tokens",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const alternatives = getAlternativeTokens(tokenInfo);
+        const result = {
+            cssVariable: tokenInfo.cssVariable,
+            cssValue: tokenInfo.cssValue,
+            resolvedValue: tokenInfo.resolvedValue,
+            description: tokenInfo.description,
+            category: tokenInfo.category,
+            layer: tokenInfo.layer,
+            alternatives,
+            resourceUri: "cobwds://tokens",
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    // -------------------------------------------------------------------------
+    // get_token_graph - Token dependency graph
+    // -------------------------------------------------------------------------
+    server.tool("get_token_graph", "Get the token dependency graph showing which tokens reference which and which are used by which", {
+        filter: z
+            .enum(["all", "aliases-only", "primitives-only", "most-used"])
+            .default("all")
+            .describe("Filter the graph to specific token types"),
+        category: z
+            .enum(CATEGORY_ENUM)
+            .optional()
+            .describe("Filter to a specific category"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe("Maximum number of tokens to return (default: 20)"),
+    }, TOKEN_TOOL_ANNOTATIONS, async ({ filter, category, limit }) => {
+        const graph = buildTokenGraph();
+        const tokens = getCSSTokens();
+        // Build lookup for categories
+        const tokenCategories = new Map();
+        for (const t of tokens) {
+            tokenCategories.set(t.cssVariable, t.category);
+        }
+        const allNodes = Array.from(graph.values());
+        let nodes = allNodes;
+        // Apply category filter
+        if (category) {
+            nodes = nodes.filter((n) => tokenCategories.get(n.cssVariable) === category);
+        }
+        // Apply type filter
+        if (filter === "aliases-only") {
+            nodes = nodes.filter((n) => n.referencesVariable);
+        }
+        else if (filter === "primitives-only") {
+            nodes = nodes.filter((n) => !n.referencesVariable);
+        }
+        else if (filter === "most-used") {
+            nodes = nodes.filter((n) => n.usedBy.length > 0);
+            nodes.sort((a, b) => b.usedBy.length - a.usedBy.length);
+        }
+        // Apply limit
+        nodes = nodes.slice(0, limit);
+        const stats = {
+            totalTokens: allNodes.length,
+            aliasTokens: allNodes.filter((n) => n.referencesVariable).length,
+            primitiveTokens: allNodes.filter((n) => !n.referencesVariable).length,
+            mostUsed: allNodes
+                .filter((n) => n.usedBy.length > 0)
+                .sort((a, b) => b.usedBy.length - a.usedBy.length)
+                .slice(0, 5)
+                .map((n) => ({
+                cssVariable: n.cssVariable,
+                usedByCount: n.usedBy.length,
+            })),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        filter,
+                        category: category || "all",
+                        nodes: nodes.map((n) => ({
+                            cssVariable: n.cssVariable,
+                            referencesVariable: n.referencesVariable,
+                            usedBy: n.usedBy.length > 0 ? n.usedBy : undefined,
+                        })),
+                        stats,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/utility-tools.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility Tools
+ *
+ * MCP tools for COBWDS utility classes.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerUtilityTools(server: McpServer): void;
+//# sourceMappingURL=utility-tools.d.ts.map

package/dist/tools/utility-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility-tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmPzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}

package/dist/tools/utility-tools.js

@@ -0,0 +1,293 @@
+/**
+ * Utility Tools
+ *
+ * MCP tools for COBWDS utility classes.
+ */
+import { z } from "zod";
+const UTILITY_DOCS = {
+    grid: `## Grid System
+
+COBWDS provides a 12-column responsive grid system.
+
+### Structure
+\`\`\`html
+<div class="cob-grid-container">
+  <div class="cob-grid-row">
+    <div class="cob-grid-col-6">Half width</div>
+    <div class="cob-grid-col-6">Half width</div>
+  </div>
+</div>
+\`\`\`
+
+### Column Classes
+- \`cob-grid-col-[1-12]\` - Fixed column widths (1-12 columns)
+- \`cob-grid-col\` - Equal width columns (auto-distributes)
+- \`cob-grid-col-auto\` - Column sized to content
+- \`cob-grid-col-fill\` - Column fills remaining space
+
+### Gap Classes
+- \`cob-grid-gap-0\` - No gap
+- \`cob-grid-gap-2px\` - 2px gap
+- \`cob-grid-gap-50\` - 4px gap (0.25rem)
+- \`cob-grid-gap-100\` - 8px gap (0.5rem)
+- \`cob-grid-gap-150\` - 12px gap (0.75rem)
+- \`cob-grid-gap-200\` - 16px gap (1rem)
+- \`cob-grid-gap-250\` - 20px gap (1.25rem)
+- \`cob-grid-gap-300\` - 24px gap (1.5rem)
+- \`cob-grid-gap-400\` - 32px gap (2rem)
+- \`cob-grid-gap-500\` - 40px gap (2.5rem)
+- \`cob-grid-gap-600\` - 48px gap (3rem)
+- \`cob-grid-gap-700\` - 56px gap (3.5rem)
+- \`cob-grid-gap-800\` - 64px gap (4rem)
+- \`cob-grid-gap-1200\` - 96px gap (6rem)
+
+### Offset Classes
+- \`cob-grid-offset-[1-12]\` - Offset column by 1-12 columns
+
+### Example: Form with Sidebar
+\`\`\`html
+<div class="cob-grid-container">
+  <div class="cob-grid-row">
+    <div class="cob-grid-col-12 cob-desktop:cob-grid-col-4">
+      <!-- Sidebar content (stepper, navigation) -->
+    </div>
+    <div class="cob-grid-col-12 cob-desktop:cob-grid-col-8">
+      <!-- Main content (form) -->
+    </div>
+  </div>
+</div>
+\`\`\``,
+    flex: `## Flexbox Utilities
+
+### Display
+- \`cob-display-flex\` - Sets display: flex
+
+### Direction
+- \`cob-flex-row\` - Row direction (default)
+- \`cob-flex-column\` - Column direction
+
+### Wrapping
+- \`cob-flex-wrap\` - Allow items to wrap
+- \`cob-flex-no-wrap\` - Prevent wrapping
+
+### Alignment (Cross Axis)
+- \`cob-flex-align-start\` - Align items to start
+- \`cob-flex-align-center\` - Align items to center
+- \`cob-flex-align-end\` - Align items to end
+- \`cob-flex-align-stretch\` - Stretch items to fill
+
+### Justification (Main Axis)
+- \`cob-flex-justify-start\` - Justify to start
+- \`cob-flex-justify-center\` - Justify to center
+- \`cob-flex-justify-end\` - Justify to end
+
+### Flex Sizing
+- \`cob-flex-[1-12]\` - Flex grow/shrink values
+- \`cob-flex-auto\` - flex: auto (grow and shrink)
+- \`cob-flex-fill\` - Fill available space
+
+### Example: Button Group
+\`\`\`html
+<div class="cob-display-flex cob-flex-justify-end cob-flex-gap-200">
+  <cob-button label="Cancel" variant="outline"></cob-button>
+  <cob-button label="Submit"></cob-button>
+</div>
+\`\`\``,
+    spacing: `## Spacing Utilities
+
+Pattern: \`cob-{property}-{direction}-{value}\`
+
+### Properties
+- \`margin\` - External spacing
+- \`padding\` - Internal spacing
+
+### Directions
+- \`t\` - Top
+- \`r\` - Right
+- \`b\` - Bottom
+- \`l\` - Left
+- \`x\` - Horizontal (left + right)
+- \`y\` - Vertical (top + bottom)
+- (none) - All sides
+
+### Values
+- \`0\` - 0
+- \`1px\` - 1px
+- \`2px\` - 2px
+- \`50\` - var(--cob-space-50) = 0.125rem (2px)
+- \`100\` - var(--cob-space-100) = 0.25rem (4px)
+- \`150\` - var(--cob-space-150) = 0.375rem (6px)
+- \`200\` - var(--cob-space-200) = 0.5rem (8px)
+- \`250\` - var(--cob-space-250) = 0.625rem (10px)
+- \`300\` - var(--cob-space-300) = 0.75rem (12px)
+- \`400\` - var(--cob-space-400) = 1rem (16px)
+- \`500\` - var(--cob-space-500) = 1.25rem (20px)
+- \`600\` - var(--cob-space-600) = 1.5rem (24px)
+- \`700\` - var(--cob-space-700) = 2rem (32px)
+- \`800\` - var(--cob-space-800) = 2.5rem (40px)
+- \`1200\` - var(--cob-space-1200) = 4rem (64px)
+
+### Examples
+\`\`\`html
+<!-- Add bottom margin to an alert -->
+<cob-alert class="cob-margin-b-300">...</cob-alert>
+
+<!-- Add padding to a container -->
+<div class="cob-padding-400">...</div>
+
+<!-- Horizontal margin -->
+<div class="cob-margin-x-200">...</div>
+\`\`\``,
+    display: `## Display Utilities
+
+- \`cob-display-none\` - Hide element
+- \`cob-display-block\` - Block display
+- \`cob-display-inline\` - Inline display
+- \`cob-display-inline-block\` - Inline-block display
+- \`cob-display-flex\` - Flex display
+
+### Example: Hide on Mobile
+\`\`\`html
+<div class="cob-display-none cob-tablet:cob-display-block">
+  Only visible on tablet and larger
+</div>
+\`\`\``,
+    opacity: `## Opacity Utilities
+
+- \`cob-opacity-0\` - Fully transparent
+- \`cob-opacity-25\` - 25% opacity
+- \`cob-opacity-50\` - 50% opacity
+- \`cob-opacity-75\` - 75% opacity
+- \`cob-opacity-100\` - Fully opaque`,
+    zindex: `## Z-Index Utilities
+
+- \`cob-z-0\` - z-index: 0
+- \`cob-z-10\` - z-index: 10
+- \`cob-z-20\` - z-index: 20
+- \`cob-z-30\` - z-index: 30
+- \`cob-z-40\` - z-index: 40
+- \`cob-z-50\` - z-index: 50
+- \`cob-z-auto\` - z-index: auto`,
+    typography: `## Typography Utilities
+
+### Text Alignment
+- \`cob-text-left\` - Left align text
+- \`cob-text-center\` - Center align text
+- \`cob-text-right\` - Right align text
+
+### Font Weight
+- \`cob-font-normal\` - Normal weight
+- \`cob-font-medium\` - Medium weight
+- \`cob-font-semibold\` - Semibold weight
+- \`cob-font-bold\` - Bold weight
+
+### Text Transform
+- \`cob-text-uppercase\` - Uppercase text
+- \`cob-text-lowercase\` - Lowercase text
+- \`cob-text-capitalize\` - Capitalize text`,
+    responsive: `## Responsive Breakpoints
+
+COBWDS utility classes support responsive prefixes.
+
+### Breakpoints
+- (no prefix) - All screen sizes (mobile-first)
+- \`cob-mobile-lg:\` - 30em (480px) and up
+- \`cob-tablet:\` - 40em (640px) and up
+- \`cob-desktop:\` - 64em (1024px) and up
+
+### Pattern
+\`cob-{breakpoint}:cob-{class}\`
+
+### Examples
+\`\`\`html
+<!-- Full width on mobile, half on tablet, third on desktop -->
+<div class="cob-grid-col-12 cob-tablet:cob-grid-col-6 cob-desktop:cob-grid-col-4">
+  Responsive column
+</div>
+
+<!-- Stack on mobile, row on tablet -->
+<div class="cob-display-flex cob-flex-column cob-tablet:cob-flex-row">
+  Responsive flex direction
+</div>
+
+<!-- Hide on mobile, show on desktop -->
+<div class="cob-display-none cob-desktop:cob-display-block">
+  Desktop only content
+</div>
+\`\`\``,
+    componentSpacing: `## Component Spacing
+
+When adding spacing around COBWDS components, use utility classes rather than wrapper elements.
+
+### Examples
+\`\`\`html
+<!-- Add bottom margin to an alert -->
+<cob-alert class="cob-margin-b-300" type="info">
+  This alert has bottom margin.
+</cob-alert>
+
+<!-- Add top margin to a button -->
+<cob-button class="cob-margin-t-400" label="Submit"></cob-button>
+
+<!-- Stack form fields with consistent spacing -->
+<cob-textinput class="cob-margin-b-300" label="First Name"></cob-textinput>
+<cob-textinput class="cob-margin-b-300" label="Last Name"></cob-textinput>
+<cob-textinput class="cob-margin-b-400" label="Email"></cob-textinput>
+<cob-button label="Submit"></cob-button>
+\`\`\``,
+};
+export function registerUtilityTools(server) {
+    // get_utility_classes - Comprehensive utility class reference
+    server.tool("get_utility_classes", "Get COBWDS utility class reference for layout, spacing, and styling", {
+        category: z
+            .enum([
+            "grid",
+            "flex",
+            "spacing",
+            "display",
+            "opacity",
+            "zindex",
+            "typography",
+            "responsive",
+            "all",
+        ])
+            .optional()
+            .describe("Category of utility classes to retrieve. Defaults to 'all'."),
+    }, async ({ category = "all" }) => {
+        let content;
+        if (category === "all") {
+            content = `# COBWDS Utility Classes
+
+${UTILITY_DOCS.grid}
+
+${UTILITY_DOCS.flex}
+
+${UTILITY_DOCS.spacing}
+
+${UTILITY_DOCS.display}
+
+${UTILITY_DOCS.opacity}
+
+${UTILITY_DOCS.zindex}
+
+${UTILITY_DOCS.typography}
+
+${UTILITY_DOCS.responsive}
+
+${UTILITY_DOCS.componentSpacing}`;
+        }
+        else {
+            content =
+                UTILITY_DOCS[category] ||
+                    `Unknown category: ${category}`;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: content,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/validation-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation Tools
+ *
+ * MCP tools for validating COBWDS component usage.
+ *
+ * Tools:
+ * - validate_component_api: Validate prop/attribute usage
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerValidationTools(server: McpServer): void;
+//# sourceMappingURL=validation-tools.d.ts.map

package/dist/tools/validation-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-tools.d.ts","sourceRoot":"","sources":["../../src/tools/validation-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAgE/D"}

package/dist/tools/validation-tools.js

@@ -0,0 +1,60 @@
+/**
+ * Validation Tools
+ *
+ * MCP tools for validating COBWDS component usage.
+ *
+ * Tools:
+ * - validate_component_api: Validate prop/attribute usage
+ */
+import { z } from "zod";
+import { getComponent } from "../lib/cem-parser.js";
+export function registerValidationTools(server) {
+    // validate_component_api - Validate prop/attribute usage
+    server.tool("validate_component_api", "Validate that the provided attributes/properties are valid for a given COBWDS component", {
+        tagName: z
+            .string()
+            .describe("The tag name of the component (e.g., 'cob-button')"),
+        attributes: z
+            .record(z.string())
+            .describe("Object of attribute names and values to validate"),
+    }, async ({ tagName, attributes }) => {
+        const component = getComponent(tagName);
+        if (!component) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component "${tagName}" not found.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const validAttributes = new Set(component.attributes?.map((a) => a.name) || []);
+        const validProperties = new Set(component.members
+            ?.filter((m) => m.kind === "field")
+            .map((m) => m.name) || []);
+        const errors = [];
+        const warnings = [];
+        for (const attr of Object.keys(attributes)) {
+            if (!validAttributes.has(attr) && !validProperties.has(attr)) {
+                errors.push(`Unknown attribute/property: "${attr}"`);
+            }
+        }
+        const result = {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            validAttributes: Array.from(validAttributes),
+            validProperties: Array.from(validProperties),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@cobwds/mcp-server",
+  "version": "1.19.3",
+  "description": "MCP server for the City of Boston Web Design System. Exposes components, tokens, and documentation to AI assistants.",
+  "type": "module",
+  "bin": {
+    "cobwds-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "data/"
+  ],
+  "scripts": {
+    "copy-data": "mkdir -p data/cem data/tokens && cp ../../custom-elements.json data/cem/ && cp ../tokens/src/tokens.json data/tokens/ && cp ../tokens/dist/tokens.css data/tokens/",
+    "build": "npm run copy-data && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "inspect": "npx -y @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25"
+  },
+  "devDependencies": {
+    "@cobwds/styles": "^1.19.3",
+    "@cobwds/tokens": "^1.19.3",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "city-of-boston",
+    "design-system",
+    "web-components",
+    "ai-assistant"
+  ],
+  "author": "City of Boston Web Design System Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CityOfBoston/nywds-poc.git",
+    "directory": "packages/mcp-server"
+  },
+  "sideEffects": false
+}