@nysds/mcp-server 1.0.0 → 1.14.0

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * NYSDS MCP Server Entry Point
+ *
+ * Starts the MCP server with stdio transport for local execution.
+ * Run via: npx @nysds/mcp-server
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * NYSDS MCP Server Entry Point
+ *
+ * Starts the MCP server with stdio transport for local execution.
+ * Run via: npx @nysds/mcp-server
+ */
+import { createServer } from "./server.js";
+async function main() {
+    const server = await createServer();
+    await server.start();
+}
+main().catch((error) => {
+    console.error("Failed to start NYSDS MCP server:", error);
+    process.exit(1);
+});

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

@@ -0,0 +1,96 @@
+/**
+ * Custom Elements Manifest Parser
+ *
+ * Reads and parses the custom-elements.json manifest from @nysds/components.
+ */
+export interface CEMAttribute {
+    name: string;
+    type?: {
+        text: string;
+    };
+    default?: string;
+    description?: string;
+    fieldName?: string;
+}
+export interface CEMMember {
+    kind: "field" | "method";
+    name: string;
+    type?: {
+        text: string;
+    };
+    default?: string;
+    description?: string;
+    privacy?: "public" | "private" | "protected";
+    attribute?: string;
+}
+export interface CEMEvent {
+    name: string;
+    type?: {
+        text: string;
+    };
+    description?: string;
+}
+export interface CEMSlot {
+    name: string;
+    description?: string;
+}
+export interface CEMCssProperty {
+    name: string;
+    default?: string;
+    description?: string;
+}
+export interface CEMCssPart {
+    name: string;
+    description?: string;
+}
+export interface CEMDeclaration {
+    kind: "class";
+    name: string;
+    tagName?: string;
+    summary?: string;
+    description?: string;
+    attributes?: CEMAttribute[];
+    members?: CEMMember[];
+    events?: CEMEvent[];
+    slots?: CEMSlot[];
+    cssProperties?: CEMCssProperty[];
+    cssParts?: CEMCssPart[];
+    superclass?: {
+        name: string;
+        package?: string;
+    };
+}
+export interface CEMModule {
+    kind: "javascript-module";
+    path: string;
+    declarations?: CEMDeclaration[];
+    exports?: Array<{
+        kind: string;
+        name: string;
+        declaration: {
+            name: string;
+        };
+    }>;
+}
+export interface CustomElementsManifest {
+    schemaVersion: string;
+    readme?: string;
+    modules: CEMModule[];
+}
+/**
+ * Load and parse the Custom Elements Manifest
+ */
+export declare function getCEM(): CustomElementsManifest;
+/**
+ * Get all component declarations from the manifest
+ */
+export declare function getAllComponents(): CEMDeclaration[];
+/**
+ * Get a specific component by tag name
+ */
+export declare function getComponent(tagName: string): CEMDeclaration | undefined;
+/**
+ * Clear the cached CEM (useful for testing)
+ */
+export declare function clearCache(): void;
+//# sourceMappingURL=cem-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cem-parser.d.ts","sourceRoot":"","sources":["../../src/lib/cem-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAgCD;;GAEG;AACH,wBAAgB,MAAM,IAAI,sBAAsB,CAkB/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,EAAE,CAiBnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAKxE;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/lib/cem-parser.js

@@ -0,0 +1,82 @@
+/**
+ * Custom Elements Manifest Parser
+ *
+ * Reads and parses the custom-elements.json manifest from @nysds/components.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let cachedCEM = null;
+/**
+ * Get the path to the custom-elements.json file
+ */
+function getCEMPath() {
+    // Try multiple locations
+    const possiblePaths = [
+        // Relative to the package (when installed as dependency)
+        resolve(__dirname, "../../../node_modules/@nysds/components/dist/custom-elements.json"),
+        // Relative to monorepo root (during development)
+        resolve(__dirname, "../../../../dist/custom-elements.json"),
+        // Direct path for testing
+        resolve(process.cwd(), "dist/custom-elements.json"),
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    throw new Error(`custom-elements.json not found. Searched paths:\n${possiblePaths.join("\n")}`);
+}
+/**
+ * Load and parse the Custom Elements Manifest
+ */
+export function getCEM() {
+    if (cachedCEM) {
+        return cachedCEM;
+    }
+    try {
+        const cemPath = getCEMPath();
+        const content = readFileSync(cemPath, "utf-8");
+        cachedCEM = JSON.parse(content);
+        return cachedCEM;
+    }
+    catch (error) {
+        // Return empty manifest if file not found (for development/testing)
+        console.error("Warning: Could not load custom-elements.json:", error);
+        return {
+            schemaVersion: "1.0.0",
+            modules: [],
+        };
+    }
+}
+/**
+ * Get all component declarations from the manifest
+ */
+export function getAllComponents() {
+    const cem = getCEM();
+    const components = [];
+    for (const module of cem.modules) {
+        if (module.declarations) {
+            for (const declaration of module.declarations) {
+                if (declaration.kind === "class" && declaration.tagName) {
+                    components.push(declaration);
+                }
+            }
+        }
+    }
+    return components.sort((a, b) => (a.tagName || "").localeCompare(b.tagName || ""));
+}
+/**
+ * Get a specific component by tag name
+ */
+export function getComponent(tagName) {
+    const components = getAllComponents();
+    return components.find((c) => c.tagName?.toLowerCase() === tagName.toLowerCase());
+}
+/**
+ * Clear the cached CEM (useful for testing)
+ */
+export function clearCache() {
+    cachedCEM = null;
+}

package/dist/lib/search.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Search Utilities
+ *
+ * Fuzzy search functionality for components and tokens.
+ */
+export interface SearchResult {
+    tagName: string;
+    name: string;
+    summary: string;
+    score: number;
+}
+/**
+ * Search components by name or description
+ */
+export declare function searchComponents(query: string): SearchResult[];
+/**
+ * Check if a string matches a search query
+ */
+export declare function matchesQuery(text: string, query: string): boolean;
+//# sourceMappingURL=search.d.ts.map

package/dist/lib/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAsDD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CA8B9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/lib/search.js

@@ -0,0 +1,87 @@
+/**
+ * Search Utilities
+ *
+ * Fuzzy search functionality for components and tokens.
+ */
+import { getAllComponents } from "./cem-parser.js";
+/**
+ * Simple fuzzy matching score
+ * Returns a score between 0 and 1, where 1 is an exact match
+ */
+function fuzzyScore(query, text) {
+    const lowerQuery = query.toLowerCase();
+    const lowerText = text.toLowerCase();
+    // Exact match
+    if (lowerText === lowerQuery)
+        return 1;
+    // Contains exact query
+    if (lowerText.includes(lowerQuery)) {
+        // Bonus for matching at word boundaries
+        const wordBoundary = new RegExp(`\\b${escapeRegex(lowerQuery)}`, "i");
+        if (wordBoundary.test(lowerText)) {
+            return 0.9;
+        }
+        return 0.7;
+    }
+    // Character-by-character fuzzy match
+    let queryIndex = 0;
+    let score = 0;
+    let consecutiveBonus = 0;
+    for (let i = 0; i < lowerText.length && queryIndex < lowerQuery.length; i++) {
+        if (lowerText[i] === lowerQuery[queryIndex]) {
+            score += 1 + consecutiveBonus * 0.5;
+            consecutiveBonus++;
+            queryIndex++;
+        }
+        else {
+            consecutiveBonus = 0;
+        }
+    }
+    // Did we match all query characters?
+    if (queryIndex < lowerQuery.length) {
+        return 0;
+    }
+    // Normalize score
+    return Math.min(score / (lowerQuery.length * 2), 0.6);
+}
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Search components by name or description
+ */
+export function searchComponents(query) {
+    const components = getAllComponents();
+    const results = [];
+    for (const component of components) {
+        const tagName = component.tagName || "";
+        const name = component.name || "";
+        const description = component.description || "";
+        const summary = component.summary || description.split("\n")[0] || "";
+        // Calculate scores for different fields
+        const tagScore = fuzzyScore(query, tagName) * 1.2; // Boost tag matches
+        const nameScore = fuzzyScore(query, name) * 1.1;
+        const summaryScore = fuzzyScore(query, summary);
+        const descScore = fuzzyScore(query, description) * 0.8;
+        const maxScore = Math.max(tagScore, nameScore, summaryScore, descScore);
+        if (maxScore > 0) {
+            results.push({
+                tagName,
+                name,
+                summary,
+                score: maxScore,
+            });
+        }
+    }
+    // Sort by score descending
+    return results.sort((a, b) => b.score - a.score);
+}
+/**
+ * Check if a string matches a search query
+ */
+export function matchesQuery(text, query) {
+    return fuzzyScore(query, text) > 0;
+}

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

@@ -0,0 +1,140 @@
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+export interface CSSTokenInfo {
+    /** CSS variable name, e.g., "--nys-color-text" */
+    cssVariable: string;
+    /** CSS value as it appears in tokens.css, e.g., "var(--nys-color-neutral-900)" or "#1b1b1b" */
+    cssValue: string;
+    /** If this is an alias, the variable it references, e.g., "--nys-color-neutral-900" */
+    referencesVariable?: string;
+    /** Fully resolved value for previews, e.g., "#1b1b1b" */
+    resolvedValue?: string;
+    /** Token description from $description field */
+    description?: string;
+    /** Token category (color, font, space, etc.) */
+    category: string;
+    /** Token layer (primitive, applied, color, etc.) */
+    layer: string;
+    /** Original JSON path for debugging */
+    jsonPath: string;
+}
+/**
+ * Token dependency graph node
+ */
+export interface TokenGraphNode {
+    cssVariable: string;
+    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
+ */
+export declare function getTokensPath(): string | null;
+/**
+ * Get the path to tokens.css file
+ */
+export declare function getTokensCSSPath(): string | null;
+/**
+ * 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 declare function toCSSVariable(jsonPath: string): string;
+/**
+ * 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 declare function aliasToVarRef(aliasValue: string): {
+    cssValue: string;
+    referencesVariable: string;
+};
+/**
+ * Build a dependency graph of tokens
+ * Shows which tokens reference which, and which tokens are used by which
+ */
+export declare function buildTokenGraph(): Map<string, TokenGraphNode>;
+/**
+ * Get all tokens in CSS-centric format
+ */
+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
+ */
+export declare function getCSSTokenByVariable(variableName: string): CSSTokenInfo | undefined;
+/**
+ * Get all unique categories
+ */
+export declare function getCSSTokenCategories(): {
+    category: string;
+    count: number;
+}[];
+/**
+ * Get raw tokens.css content
+ */
+export declare function getTokensCSS(): string | null;
+/**
+ * Load all design tokens (legacy format)
+ */
+export declare function getAllTokens(): DesignToken[];
+/**
+ * Get tokens filtered by category (legacy format)
+ */
+export declare function getTokensByCategory(category: string): DesignToken[];
+/**
+ * Search tokens by name or value (legacy format)
+ */
+export declare function searchTokens(query: string): DesignToken[];
+/**
+ * Get available token categories (legacy format)
+ */
+export declare function getTokenCategories(): string[];
+/**
+ * Clear all cached tokens (useful for testing)
+ */
+export declare function clearTokenCache(): void;
+//# sourceMappingURL=token-parser.d.ts.map

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

@@ -0,0 +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,CAsB7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAgBhD;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"}