@nysds/mcp-server 1.18.1 → 1.19.0

package/dist/lib/token-parser.d.ts

@@ -9,15 +9,6 @@
  * - Alias references become var() expressions
  * - Layer prefixes (primitive, applied) are stripped
  */
-/**
- * Legacy interface for backward compatibility
- */
-export interface DesignToken {
-    name: string;
-    value: string;
-    category: string;
-    description?: string;
-}
 /**
  * CSS-centric token info aligned with tokens.css output
  */
@@ -47,10 +38,6 @@ export interface TokenGraphNode {
     referencesVariable?: string;
     usedBy: string[];
 }
-export interface TokenGroup {
-    category: string;
-    tokens: DesignToken[];
-}
 /**
  * Get the path to tokens.json file
  * Uses ESM-compatible path resolution with fallbacks for different contexts
@@ -94,14 +81,6 @@ export declare function getCSSTokens(): CSSTokenInfo[];
  * Get CSS tokens filtered by category
  */
 export declare function getCSSTokensByCategory(category: string): CSSTokenInfo[];
-/**
- * Get CSS tokens filtered by layer
- */
-export declare function getCSSTokensByLayer(layer: string): CSSTokenInfo[];
-/**
- * Search CSS tokens by variable name, value, or description
- */
-export declare function searchCSSTokens(query: string): CSSTokenInfo[];
 /**
  * Get a single token by CSS variable name
  */
@@ -118,21 +97,30 @@ export declare function getCSSTokenCategories(): {
  */
 export declare function getTokensCSS(): string | null;
 /**
- * Load all design tokens (legacy format)
- */
-export declare function getAllTokens(): DesignToken[];
-/**
- * Get tokens filtered by category (legacy format)
+ * 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 declare function getTokensByCategory(category: string): DesignToken[];
+export declare function getRecommendedTokens(): CSSTokenInfo[];
 /**
- * Search tokens by name or value (legacy format)
+ * Get only primitive (raw value) tokens across all categories.
  */
-export declare function searchTokens(query: string): DesignToken[];
+export declare function getPrimitiveTokens(): CSSTokenInfo[];
 /**
- * Get available token categories (legacy format)
+ * 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 + "-"):
+ *   --nys-color-text  →  finds --nys-color-text-weak, --nys-color-text-reverse, etc.
+ *
+ * If no children exist, looks for siblings (tokens sharing the same parent prefix):
+ *   --nys-color-text-weak  →  parent: --nys-color-text  →  finds text, text-weaker, etc.
+ *
+ * Returns an array of cssVariable strings (empty if none found).
  */
-export declare function getTokenCategories(): string[];
+export declare function getAlternativeTokens(token: CSSTokenInfo): string[];
 /**
  * Clear all cached tokens (useful for testing)
  */

package/dist/lib/token-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-parser.d.ts","sourceRoot":"","sources":["../../src/lib/token-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAeD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAuB7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAkBhD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAUA;AA6LD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CA6B7D;AAMD;;GAEG;AACH,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAc7C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAKvE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAGjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAW7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,YAAY,GAAG,SAAS,CAO1B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAW7E;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAW5C;AAkDD;;GAEG;AACH,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAa5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAKnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAUzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAI7C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}
+{"version":3,"file":"token-parser.d.ts","sourceRoot":"","sources":["../../src/lib/token-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAcD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAuB7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAkBhD;AAYD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAUA;AAyLD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CA6B7D;AAMD;;GAEG;AACH,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAc7C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAKvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,YAAY,GAAG,SAAS,CAO1B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAW7E;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAW5C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,EAAE,CAiBrD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAGnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CA2BlE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC"}

package/dist/lib/token-parser.js

@@ -18,7 +18,6 @@ const __dirname = dirname(__filename);
 // ============================================================================
 // Token Data Cache
 // ============================================================================
-let cachedLegacyTokens = null;
 let cachedCSSTokens = null;
 let cachedTokenGraph = null;
 let cachedRawTokens = null;
@@ -72,6 +71,10 @@ export function getTokensCSSPath() {
     return null;
 }
 // ============================================================================
+// Constants
+// ============================================================================
+const LAYER_PREFIXES = ["primitive", "applied", "appearance", "theme"];
+// ============================================================================
 // CSS Variable Transformation
 // ============================================================================
 /**
@@ -87,7 +90,7 @@ export function toCSSVariable(jsonPath) {
     let name = "--nys-" +
         jsonPath
             // Strip layer prefixes
-            .replace(/^(primitive|applied|appearance|theme)\./, "")
+            .replace(new RegExp(`^(${LAYER_PREFIXES.join("|")})\\.`), "")
             // Dots to hyphens
             .replace(/\./g, "-");
     // Strip trailing -default suffix
@@ -117,9 +120,7 @@ export function aliasToVarRef(aliasValue) {
 function getCategoryFromPath(jsonPath) {
     const parts = jsonPath.split(".");
     // Skip layer prefix if present
-    const startIndex = ["primitive", "applied", "appearance", "theme"].includes(parts[0])
-        ? 1
-        : 0;
+    const startIndex = LAYER_PREFIXES.includes(parts[0]) ? 1 : 0;
     return parts[startIndex] || "unknown";
 }
 /**
@@ -134,7 +135,7 @@ function getCategoryFromPath(jsonPath) {
 function getLayerFromPath(jsonPath) {
     const parts = jsonPath.split(".");
     // Check for explicit layer prefixes
-    if (["primitive", "applied", "appearance", "theme"].includes(parts[0])) {
+    if (LAYER_PREFIXES.includes(parts[0])) {
         return parts[0];
     }
     // color.theme.* tokens are applied semantic tokens (agency themes override these)
@@ -321,24 +322,6 @@ 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
  */
@@ -378,83 +361,70 @@ export function getTokensCSS() {
         return null;
     }
 }
-// ============================================================================
-// Public API - Legacy (Backward Compatible)
-// ============================================================================
 /**
- * Parse DTCG format tokens recursively (legacy format)
+ * 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.
  */
-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));
+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 tokens;
+        return 0;
+    });
+    return filtered;
 }
 /**
- * Load all design tokens (legacy format)
+ * Get only primitive (raw value) tokens across all categories.
  */
-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));
+export function getPrimitiveTokens() {
+    const tokens = getCSSTokens();
+    return tokens.filter((t) => t.layer === "primitive");
 }
 /**
- * Get available token categories (legacy format)
+ * 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 + "-"):
+ *   --nys-color-text  →  finds --nys-color-text-weak, --nys-color-text-reverse, etc.
+ *
+ * If no children exist, looks for siblings (tokens sharing the same parent prefix):
+ *   --nys-color-text-weak  →  parent: --nys-color-text  →  finds text, text-weaker, etc.
+ *
+ * Returns an array of cssVariable strings (empty if none found).
  */
-export function getTokenCategories() {
-    const tokens = getAllTokens();
-    const categories = new Set(tokens.map((t) => t.category));
-    return Array.from(categories).sort();
+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 []; // "--nys-" 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() {
-    cachedLegacyTokens = null;
     cachedCSSTokens = null;
     cachedTokenGraph = null;
     cachedRawTokens = null;

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

@@ -1 +1 @@
-{"version":3,"file":"guide-tools.d.ts","sourceRoot":"","sources":["../../src/tools/guide-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6CzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAyC1D"}
+{"version":3,"file":"guide-tools.d.ts","sourceRoot":"","sources":["../../src/tools/guide-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8CzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0C1D"}

package/dist/tools/guide-tools.js

@@ -41,9 +41,10 @@ const TOPIC_TO_FILE = {
     styles: "styles.md",
     fonts: "fonts.md",
     "page-structure": "page-structure.md",
+    themes: "themes.md",
 };
 export function registerGuideTools(server) {
-    server.tool("get_guide", "Get NYSDS guides for installation, forms, styles, fonts, page structure, or framework setup", {
+    server.tool("get_guide", "Get NYSDS guides for installation, forms, styles, fonts, page structure, themes, or framework setup", {
         topic: z
             .enum([
             "installation",
@@ -51,6 +52,7 @@ export function registerGuideTools(server) {
             "styles",
             "fonts",
             "page-structure",
+            "themes",
         ])
             .describe("The guide topic to retrieve"),
         framework: z

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

@@ -4,9 +4,8 @@
  * 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 type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

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

@@ -1 +1 @@
-{"version":3,"file":"token-tools.d.ts","sourceRoot":"","sources":["../../src/tools/token-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqOzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwX1D"}
+{"version":3,"file":"token-tools.d.ts","sourceRoot":"","sources":["../../src/tools/token-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuCzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6N1D"}