@nysds/mcp-server 1.18.1 → 1.18.3

package/dist/tools/token-tools.js

@@ -4,312 +4,74 @@
  * MCP tools for working with NYSDS design tokens.
  *
  * Tools:
- * - get_tokens: Get tokens, categories, or themes
- * - find_tokens: Search tokens by CSS variable, value, or description
- * - get_token_info: Get detailed token info with optional context validation
+ * - 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, getCSSTokensByCategory, getCSSTokensByLayer, searchCSSTokens, getCSSTokenByVariable, getCSSTokenCategories, buildTokenGraph, } from "../lib/token-parser.js";
-import { formatResponse } from "../lib/format.js";
-const AGENCY_THEMES = [
-    {
-        id: "default",
-        name: "Default (NY.gov)",
-        description: "Default NY.gov theme for general state sites",
-        primaryColor: "#154973",
-        selectors: [":root", "[data-theme='default']", ".nys-theme-default"],
-    },
-    {
-        id: "admin",
-        name: "Administration",
-        description: "For administrative and regulatory agencies",
-        primaryColor: "#a2350a",
-        selectors: ["[data-theme='admin']", ".nys-theme-admin"],
-    },
-    {
-        id: "business",
-        name: "Business",
-        description: "For commerce and economic development agencies",
-        primaryColor: "#084b52",
-        selectors: ["[data-theme='business']", ".nys-theme-business"],
-    },
-    {
-        id: "environment",
-        name: "Environment",
-        description: "For environmental and conservation agencies",
-        primaryColor: "#233f2b",
-        selectors: ["[data-theme='environment']", ".nys-theme-environment"],
-    },
-    {
-        id: "health",
-        name: "Health",
-        description: "For health and human services agencies",
-        primaryColor: "#43285d",
-        selectors: ["[data-theme='health']", ".nys-theme-health"],
-    },
-    {
-        id: "local",
-        name: "Local Government",
-        description: "For local government entities",
-        primaryColor: "#402217",
-        selectors: ["[data-theme='local']", ".nys-theme-local"],
-    },
-    {
-        id: "safety",
-        name: "Public Safety",
-        description: "For public safety agencies",
-        primaryColor: "#435d6e",
-        selectors: ["[data-theme='safety']", ".nys-theme-safety"],
-    },
-    {
-        id: "transportation",
-        name: "Transportation",
-        description: "For DOT and transit authorities",
-        primaryColor: "#0b5583",
-        selectors: ["[data-theme='transportation']", ".nys-theme-transportation"],
-    },
+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",
 ];
-/**
- * Get recommended pairings and validation for a token in a specific context
- */
-function validateTokenInContext(token, context) {
-    const recommendations = [];
-    const alternatives = [];
-    const warnings = [];
-    let valid = true;
-    const varName = token.cssVariable;
-    // Context-specific validation rules
-    if (context === "text") {
-        if (varName.includes("-surface-")) {
-            valid = false;
-            warnings.push("Surface colors should not be used for text. Use --nys-color-text-* tokens.");
-            alternatives.push("--nys-color-text", "--nys-color-text-weak", "--nys-color-text-weaker");
-        }
-        else if (varName.includes("-text-")) {
-            recommendations.push("Pair with --nys-color-surface for optimal contrast on light backgrounds");
-            recommendations.push("Pair with --nys-color-surface-reverse for dark backgrounds");
-        }
-        else if (varName.includes("-link-")) {
-            recommendations.push("Ensure links are distinguishable from body text");
-            recommendations.push("Include visible focus and hover states");
-        }
-        else if (varName.includes("-danger-") || varName.includes("-warning-")) {
-            recommendations.push("Pair with corresponding icon for accessibility");
-        }
-    }
-    else if (context === "background") {
-        if (varName.includes("-text-")) {
-            valid = false;
-            warnings.push("Text colors should not be used for backgrounds. Use --nys-color-surface-* tokens.");
-            alternatives.push("--nys-color-surface", "--nys-color-surface-raised", "--nys-color-surface-reverse");
-        }
-        else if (varName.includes("-surface-")) {
-            if (varName.includes("-reverse")) {
-                recommendations.push("Use --nys-color-text-reverse for text on dark surfaces");
-            }
-            else {
-                recommendations.push("Use --nys-color-text for text on light surfaces");
-            }
-        }
-        else if (varName.includes("-weak") &&
-            (varName.includes("-success-") ||
-                varName.includes("-info-") ||
-                varName.includes("-warning-") ||
-                varName.includes("-danger-"))) {
-            recommendations.push("Use for alert/notification backgrounds");
-            recommendations.push("Pair with corresponding -strong variant for text color");
-        }
-    }
-    else if (context === "border") {
-        if (varName.includes("-base-")) {
-            recommendations.push("Good for borders and dividers");
-        }
-        else if (varName.includes("-focus")) {
-            recommendations.push("Reserved for focus ring outlines");
-            recommendations.push("Use 2px solid for visible focus indication");
-        }
-        else if (varName.includes("-theme-")) {
-            recommendations.push("Use for branded accent borders");
-        }
-    }
-    else if (context === "icon") {
-        if (varName.includes("-ink-")) {
-            recommendations.push("Primary choice for icons");
-            if (varName.includes("-reverse")) {
-                recommendations.push("Use on dark backgrounds");
-            }
-        }
-        else if (varName.includes("-text-")) {
-            recommendations.push("Icons can use text colors for consistency");
-        }
-        else if (varName.includes("-success-") ||
-            varName.includes("-danger-") ||
-            varName.includes("-warning-") ||
-            varName.includes("-info-")) {
-            recommendations.push("Use for status icons to reinforce meaning with color");
-        }
-    }
-    // Find similar tokens as alternatives
-    if (alternatives.length === 0) {
-        const tokens = getCSSTokens();
-        const category = token.category;
-        const similar = tokens
-            .filter((t) => t.category === category &&
-            t.cssVariable !== varName &&
-            ((context === "text" && t.cssVariable.includes("-text-")) ||
-                (context === "background" && t.cssVariable.includes("-surface-")) ||
-                (context === "border" && t.cssVariable.includes("-base-")) ||
-                (context === "icon" && t.cssVariable.includes("-ink-"))))
-            .slice(0, 3)
-            .map((t) => t.cssVariable);
-        alternatives.push(...similar);
-    }
-    return {
-        valid,
-        cssVariable: token.cssVariable,
-        context,
-        recommendations,
-        alternatives,
-        warnings: warnings.length > 0 ? warnings : undefined,
-    };
-}
+const TOKEN_TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 // ============================================================================
 // Tool Registration
 // ============================================================================
 export function registerTokenTools(server) {
     // -------------------------------------------------------------------------
-    // get_tokens - Consolidated token retrieval (tokens, categories, or themes)
+    // find_tokens - Search or browse tokens (discovery)
     // -------------------------------------------------------------------------
-    server.tool("get_tokens", "Get NYSDS design tokens, token categories, or agency themes", {
-        output: z
-            .enum(["tokens", "categories", "themes"])
-            .default("tokens")
-            .describe("What to return: 'tokens' for CSS variables, 'categories' for category list with counts, 'themes' for agency themes"),
-        category: z
-            .enum([
-            "color",
-            "font",
-            "space",
-            "size",
-            "radius",
-            "shadow",
-            "border",
-            "form",
-            "gutter",
-            "icon",
-        ])
-            .optional()
-            .describe("Filter tokens by category (only applies when output='tokens')"),
-        layer: z
-            .enum(["primitive", "applied", "theme", "appearance"])
+    server.tool("find_tokens", "Search or browse NYSDS design tokens. Omit query to list all. Returns CSS variable names for use with var().", {
+        query: z
+            .string()
             .optional()
-            .describe("Filter tokens by layer (only applies when output='tokens'). primitive = raw values, applied = semantic tokens, theme = agency theme tokens, appearance = light/dark mode"),
-        includeResolvedValues: z
-            .boolean()
-            .default(false)
-            .describe("Include resolved hex/rem values (only applies when output='tokens')"),
-        includeDescriptions: z
-            .boolean()
-            .default(true)
-            .describe("Include token descriptions (only applies when output='tokens')"),
-    }, async ({ output, category, layer, includeResolvedValues, includeDescriptions, }) => {
-        // Return categories
-        if (output === "categories") {
-            const categories = getCSSTokenCategories();
-            const total = categories.reduce((sum, c) => sum + c.count, 0);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: formatResponse({ categories, totalTokens: total }),
-                    },
-                ],
-            };
-        }
-        // Return themes
-        if (output === "themes") {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: formatResponse({
-                            themes: AGENCY_THEMES,
-                            usage: {
-                                htmlAttribute: '<html data-theme="admin">',
-                                cssClass: '<body class="nys-theme-admin">',
-                                cssCustomProperty: "Themes modify --nys-color-theme-* tokens",
-                            },
-                            totalThemes: AGENCY_THEMES.length,
-                        }),
-                    },
-                ],
-            };
-        }
-        // Return tokens (default)
+            .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 (category) {
-            tokens = getCSSTokensByCategory(category);
+        if (include === "primitive") {
+            tokens = getPrimitiveTokens();
         }
-        else if (layer) {
-            tokens = getCSSTokensByLayer(layer);
+        else if (include === "all") {
+            tokens = getCSSTokens();
         }
         else {
-            tokens = getCSSTokens();
+            tokens = getRecommendedTokens();
         }
-        // Format output based on options
-        const formatted = tokens.map((t) => {
-            const result = {
-                cssVariable: t.cssVariable,
-                cssValue: t.cssValue,
-            };
-            if (includeResolvedValues && t.resolvedValue) {
-                result.resolvedValue = t.resolvedValue;
-            }
-            if (includeDescriptions && t.description) {
-                result.description = t.description;
-            }
-            return result;
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: formatResponse({ count: tokens.length, tokens: formatted }),
-                },
-            ],
-        };
-    });
-    // -------------------------------------------------------------------------
-    // find_tokens - Search tokens
-    // -------------------------------------------------------------------------
-    server.tool("find_tokens", "Search for design tokens by CSS variable name, value, or description", {
-        query: z
-            .string()
-            .describe("Search query to match against CSS variable names, values, and descriptions"),
-        category: z
-            .enum([
-            "color",
-            "font",
-            "space",
-            "size",
-            "radius",
-            "shadow",
-            "border",
-            "form",
-            "gutter",
-            "icon",
-        ])
-            .optional()
-            .describe("Optionally filter results to a specific category"),
-    }, async ({ query, category }) => {
-        let results = searchCSSTokens(query);
+        // Apply category filter
         if (category) {
-            results = results.filter((t) => t.category.toLowerCase() === category.toLowerCase());
+            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 formatted = results.map((t) => ({
+        const results = tokens.map((t) => ({
             cssVariable: t.cssVariable,
-            cssValue: t.cssValue,
             description: t.description,
             category: t.category,
         }));
@@ -317,46 +79,35 @@ export function registerTokenTools(server) {
             content: [
                 {
                     type: "text",
-                    text: formatResponse({
-                        query,
-                        count: results.length,
-                        results: formatted,
-                    }),
+                    text: JSON.stringify({ count: results.length, results }, null, 2),
                 },
             ],
         };
     });
     // -------------------------------------------------------------------------
-    // get_token_info - Get detailed token info with optional context validation
+    // get_token - Get full details for a specific token (deep dive)
     // -------------------------------------------------------------------------
-    server.tool("get_token_info", "Get detailed information about a specific design token. Optionally validate usage in a specific context (text, background, border, icon).", {
+    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., "--nys-color-text" or "color-text")'),
-        context: z
-            .enum(["text", "background", "border", "icon"])
-            .optional()
-            .describe("Optional: validate token usage for a specific context. When provided, includes recommendations and warnings."),
-    }, async ({ token, context }) => {
+    }, TOKEN_TOOL_ANNOTATIONS, async ({ token }) => {
         const tokenInfo = getCSSTokenByVariable(token);
         if (!tokenInfo) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: formatResponse({
+                        text: JSON.stringify({
                             error: `Token not found: ${token}`,
-                            suggestion: "Try searching with find_tokens to discover available tokens",
-                        }),
+                            suggestion: "Use find_tokens to search for available tokens",
+                        }, null, 2),
                     },
                 ],
+                isError: true,
             };
         }
-        // Get dependents (tokens that use this one)
-        const graph = buildTokenGraph();
-        const node = graph.get(tokenInfo.cssVariable);
-        const usedBy = node?.usedBy || [];
-        // Base token info
+        const alternatives = getAlternativeTokens(tokenInfo);
         const result = {
             cssVariable: tokenInfo.cssVariable,
             cssValue: tokenInfo.cssValue,
@@ -364,30 +115,14 @@ export function registerTokenTools(server) {
             description: tokenInfo.description,
             category: tokenInfo.category,
             layer: tokenInfo.layer,
-            usedBy: usedBy.length > 0 ? usedBy : undefined,
-            usage: `var(${tokenInfo.cssVariable})`,
+            alternatives,
             resourceUri: "nysds://tokens",
         };
-        // If context provided, add validation info
-        if (context) {
-            const validation = validateTokenInContext(tokenInfo, context);
-            result.validation = {
-                context,
-                valid: validation.valid,
-                recommendations: validation.recommendations.length > 0
-                    ? validation.recommendations
-                    : undefined,
-                warnings: validation.warnings,
-                alternatives: validation.alternatives.length > 0
-                    ? validation.alternatives
-                    : undefined,
-            };
-        }
         return {
             content: [
                 {
                     type: "text",
-                    text: formatResponse(result),
+                    text: JSON.stringify(result, null, 2),
                 },
             ],
         };
@@ -401,18 +136,7 @@ export function registerTokenTools(server) {
             .default("all")
             .describe("Filter the graph to specific token types"),
         category: z
-            .enum([
-            "color",
-            "font",
-            "space",
-            "size",
-            "radius",
-            "shadow",
-            "border",
-            "form",
-            "gutter",
-            "icon",
-        ])
+            .enum(CATEGORY_ENUM)
             .optional()
             .describe("Filter to a specific category"),
         limit: z
@@ -422,7 +146,7 @@ export function registerTokenTools(server) {
             .max(100)
             .default(20)
             .describe("Maximum number of tokens to return (default: 20)"),
-    }, async ({ filter, category, limit }) => {
+    }, TOKEN_TOOL_ANNOTATIONS, async ({ filter, category, limit }) => {
         const graph = buildTokenGraph();
         const tokens = getCSSTokens();
         // Build lookup for categories
@@ -430,7 +154,8 @@ export function registerTokenTools(server) {
         for (const t of tokens) {
             tokenCategories.set(t.cssVariable, t.category);
         }
-        let nodes = Array.from(graph.values());
+        const allNodes = Array.from(graph.values());
+        let nodes = allNodes;
         // Apply category filter
         if (category) {
             nodes = nodes.filter((n) => tokenCategories.get(n.cssVariable) === category);
@@ -448,8 +173,6 @@ export function registerTokenTools(server) {
         }
         // Apply limit
         nodes = nodes.slice(0, limit);
-        // Calculate stats
-        const allNodes = Array.from(graph.values());
         const stats = {
             totalTokens: allNodes.length,
             aliasTokens: allNodes.filter((n) => n.referencesVariable).length,
@@ -467,7 +190,7 @@ export function registerTokenTools(server) {
             content: [
                 {
                     type: "text",
-                    text: formatResponse({
+                    text: JSON.stringify({
                         filter,
                         category: category || "all",
                         nodes: nodes.map((n) => ({
@@ -476,7 +199,7 @@ export function registerTokenTools(server) {
                             usedBy: n.usedBy.length > 0 ? n.usedBy : undefined,
                         })),
                         stats,
-                    }),
+                    }, null, 2),
                 },
             ],
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/mcp-server",
-  "version": "1.18.1",
+  "version": "1.18.3",
   "description": "MCP server for the New York State Design System. Exposes components, tokens, and documentation to AI assistants.",
   "type": "module",
   "bin": {
@@ -30,8 +30,8 @@
     "zod": "^3.25"
   },
   "devDependencies": {
-    "@nysds/styles": "^1.18.1",
-    "@nysds/tokens": "^1.18.1",
+    "@nysds/styles": "^1.18.3",
+    "@nysds/tokens": "^1.18.3",
     "@types/node": "^22.0.0",
     "typescript": "^5.9.3"
   },