@nysds/mcp-server 1.0.0 → 1.14.0

package/dist/resources/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Resources Registration
+ *
+ * Registers all NYSDS 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"}

package/dist/resources/index.js

@@ -0,0 +1,13 @@
+/**
+ * MCP Resources Registration
+ *
+ * Registers all NYSDS resources with the MCP server.
+ */
+import { registerComponentResources } from "./components.js";
+import { registerTokenResources } from "./tokens.js";
+import { registerGuideResources } from "./guides.js";
+export function registerResources(server) {
+    registerComponentResources(server);
+    registerTokenResources(server);
+    registerGuideResources(server);
+}

package/dist/resources/tokens.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Token Resources
+ *
+ * MCP resources for NYSDS design tokens.
+ *
+ * Resources:
+ * - nysds://tokens - All tokens in CSS-centric format
+ * - nysds://tokens/css - Raw tokens.css file content
+ * - nysds://tokens/graph - Token dependency graph with stats
+ * - nysds://tokens/color - Color tokens only
+ * - nysds://tokens/font - Typography tokens
+ * - nysds://tokens/space - Spacing tokens
+ * - nysds://tokens/size - Size tokens
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTokenResources(server: McpServer): void;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/resources/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiZ9D"}

package/dist/resources/tokens.js

@@ -0,0 +1,312 @@
+/**
+ * Token Resources
+ *
+ * MCP resources for NYSDS design tokens.
+ *
+ * Resources:
+ * - nysds://tokens - All tokens in CSS-centric format
+ * - nysds://tokens/css - Raw tokens.css file content
+ * - nysds://tokens/graph - Token dependency graph with stats
+ * - nysds://tokens/color - Color tokens only
+ * - nysds://tokens/font - Typography tokens
+ * - nysds://tokens/space - Spacing tokens
+ * - nysds://tokens/size - Size tokens
+ */
+import { getCSSTokens, getCSSTokensByCategory, getCSSTokenCategories, buildTokenGraph, getTokensCSS, } from "../lib/token-parser.js";
+export function registerTokenResources(server) {
+    // ---------------------------------------------------------------------------
+    // nysds://tokens - All design tokens in CSS-centric format
+    // ---------------------------------------------------------------------------
+    server.resource("tokens", "nysds://tokens", {
+        description: "All NYSDS design tokens with CSS variable names, values, and descriptions",
+        mimeType: "application/json",
+    }, async () => {
+        const tokens = getCSSTokens();
+        const categories = getCSSTokenCategories();
+        const formatted = tokens.map((t) => ({
+            cssVariable: t.cssVariable,
+            cssValue: t.cssValue,
+            referencesVariable: t.referencesVariable,
+            resolvedValue: t.resolvedValue,
+            description: t.description,
+            category: t.category,
+            layer: t.layer,
+        }));
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalTokens: tokens.length,
+                        categories: categories.map((c) => c.category),
+                        tokens: formatted,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/css - Raw tokens.css file content
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-css", "nysds://tokens/css", {
+        description: "Raw tokens.css file content for direct CSS usage",
+        mimeType: "text/css",
+    }, async () => {
+        const css = getTokensCSS();
+        if (!css) {
+            return {
+                contents: [
+                    {
+                        uri: "nysds://tokens/css",
+                        mimeType: "text/plain",
+                        text: "/* tokens.css not found. Run 'npm run build -w packages/tokens' to generate. */",
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/css",
+                    mimeType: "text/css",
+                    text: css,
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/graph - Token dependency graph with stats
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-graph", "nysds://tokens/graph", {
+        description: "Token dependency graph showing which tokens reference which and usage statistics",
+        mimeType: "application/json",
+    }, async () => {
+        const graph = buildTokenGraph();
+        const nodes = Array.from(graph.values());
+        // Calculate statistics
+        const aliasTokens = nodes.filter((n) => n.referencesVariable);
+        const primitiveTokens = nodes.filter((n) => !n.referencesVariable);
+        const usedTokens = nodes.filter((n) => n.usedBy.length > 0);
+        // Find most referenced tokens
+        const mostReferenced = [...usedTokens]
+            .sort((a, b) => b.usedBy.length - a.usedBy.length)
+            .slice(0, 10)
+            .map((n) => ({
+            cssVariable: n.cssVariable,
+            usedByCount: n.usedBy.length,
+            usedBy: n.usedBy.slice(0, 5),
+        }));
+        // Build a simplified graph representation
+        const graphData = nodes
+            .filter((n) => n.referencesVariable || n.usedBy.length > 0)
+            .map((n) => ({
+            cssVariable: n.cssVariable,
+            referencesVariable: n.referencesVariable,
+            usedBy: n.usedBy.length > 0 ? n.usedBy : undefined,
+        }));
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/graph",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        stats: {
+                            totalTokens: nodes.length,
+                            aliasTokens: aliasTokens.length,
+                            primitiveTokens: primitiveTokens.length,
+                            tokensWithDependents: usedTokens.length,
+                        },
+                        mostReferenced,
+                        graph: graphData,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/color - Color tokens only
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-color", "nysds://tokens/color", {
+        description: "All NYSDS color tokens including primitives, semantic colors, and theme colors",
+        mimeType: "application/json",
+    }, async () => {
+        const tokens = getCSSTokensByCategory("color");
+        // Group by layer for better organization
+        const primitive = tokens.filter((t) => t.layer === "primitive");
+        const applied = tokens.filter((t) => t.layer === "applied");
+        const base = tokens.filter((t) => t.layer === "base" || t.layer === "color");
+        const formatToken = (t) => ({
+            cssVariable: t.cssVariable,
+            cssValue: t.cssValue,
+            referencesVariable: t.referencesVariable,
+            resolvedValue: t.resolvedValue,
+            description: t.description,
+        });
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/color",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalColors: tokens.length,
+                        layers: {
+                            primitive: {
+                                count: primitive.length,
+                                description: "Raw color values - reference these via applied tokens",
+                                tokens: primitive.map(formatToken),
+                            },
+                            applied: {
+                                count: applied.length,
+                                description: "Semantic color tokens - use these in code",
+                                tokens: applied.map(formatToken),
+                            },
+                            theme: {
+                                count: base.length,
+                                description: "Theme-aware colors that change per agency",
+                                tokens: base.map(formatToken),
+                            },
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/font - Typography tokens
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-font", "nysds://tokens/font", {
+        description: "All NYSDS typography tokens including font families, sizes, weights, and line heights",
+        mimeType: "application/json",
+    }, async () => {
+        const tokens = getCSSTokensByCategory("font");
+        // Group by subcategory based on CSS variable name
+        const families = tokens.filter((t) => t.cssVariable.includes("-font-family-"));
+        const sizes = tokens.filter((t) => t.cssVariable.includes("-font-size-"));
+        const weights = tokens.filter((t) => t.cssVariable.includes("-font-weight-"));
+        const lineHeights = tokens.filter((t) => t.cssVariable.includes("-font-lineheight-"));
+        const letterSpacing = tokens.filter((t) => t.cssVariable.includes("-font-letterspacing-"));
+        const formatToken = (t) => ({
+            cssVariable: t.cssVariable,
+            cssValue: t.cssValue,
+            resolvedValue: t.resolvedValue,
+            description: t.description,
+        });
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/font",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalTypography: tokens.length,
+                        groups: {
+                            families: {
+                                count: families.length,
+                                description: "Font family stacks",
+                                tokens: families.map(formatToken),
+                            },
+                            sizes: {
+                                count: sizes.length,
+                                description: "Font sizes for different contexts",
+                                tokens: sizes.map(formatToken),
+                            },
+                            weights: {
+                                count: weights.length,
+                                description: "Font weight values",
+                                tokens: weights.map(formatToken),
+                            },
+                            lineHeights: {
+                                count: lineHeights.length,
+                                description: "Line height values",
+                                tokens: lineHeights.map(formatToken),
+                            },
+                            letterSpacing: {
+                                count: letterSpacing.length,
+                                description: "Letter spacing adjustments",
+                                tokens: letterSpacing.map(formatToken),
+                            },
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/space - Spacing tokens
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-space", "nysds://tokens/space", {
+        description: "All NYSDS spacing tokens for margins, padding, and gaps. Based on an 8px grid.",
+        mimeType: "application/json",
+    }, async () => {
+        const tokens = getCSSTokensByCategory("space");
+        const formatToken = (t) => ({
+            cssVariable: t.cssVariable,
+            cssValue: t.cssValue,
+            resolvedValue: t.resolvedValue,
+            description: t.description,
+        });
+        // Sort by numeric value if possible
+        const sorted = [...tokens].sort((a, b) => {
+            const aNum = parseFloat(a.resolvedValue || "0");
+            const bNum = parseFloat(b.resolvedValue || "0");
+            return aNum - bNum;
+        });
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/space",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalSpacing: tokens.length,
+                        description: "Spacing scale based on 8px base unit. Use for margins, padding, and gaps.",
+                        tokens: sorted.map(formatToken),
+                        usage: {
+                            padding: "padding: var(--nys-space-200);",
+                            margin: "margin-block: var(--nys-space-400);",
+                            gap: "gap: var(--nys-space-100);",
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // nysds://tokens/size - Size tokens
+    // ---------------------------------------------------------------------------
+    server.resource("tokens-size", "nysds://tokens/size", {
+        description: "All NYSDS size tokens for widths, heights, and component dimensions",
+        mimeType: "application/json",
+    }, async () => {
+        const tokens = getCSSTokensByCategory("size");
+        const formatToken = (t) => ({
+            cssVariable: t.cssVariable,
+            cssValue: t.cssValue,
+            resolvedValue: t.resolvedValue,
+            description: t.description,
+        });
+        // Sort by numeric value if possible
+        const sorted = [...tokens].sort((a, b) => {
+            const aNum = parseFloat(a.resolvedValue || "0");
+            const bNum = parseFloat(b.resolvedValue || "0");
+            return aNum - bNum;
+        });
+        return {
+            contents: [
+                {
+                    uri: "nysds://tokens/size",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        totalSizes: tokens.length,
+                        description: "Size tokens for component dimensions, icon sizes, and fixed widths/heights.",
+                        tokens: sorted.map(formatToken),
+                        usage: {
+                            iconSize: "width: var(--nys-size-200); height: var(--nys-size-200);",
+                            minHeight: "min-height: var(--nys-size-400);",
+                            componentSize: "inline-size: var(--nys-size-600);",
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * NYSDS MCP Server Setup
+ *
+ * Configures the MCP server with tools, resources, and prompts
+ * for the New York State Design System.
+ */
+export interface NysdsMcpServer {
+    start(): Promise<void>;
+}
+export declare function createServer(): Promise<NysdsMcpServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,cAAc,CAAC,CAkB5D"}

package/dist/server.js

@@ -0,0 +1,30 @@
+/**
+ * NYSDS MCP Server Setup
+ *
+ * Configures the MCP server with tools, resources, and prompts
+ * for the New York State Design System.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools/index.js";
+import { registerResources } from "./resources/index.js";
+import { registerPrompts } from "./prompts/nysds-mode.js";
+const SERVER_NAME = "nysds-mcp";
+const SERVER_VERSION = "1.0.0";
+export async function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    // Register all capabilities
+    registerTools(server);
+    registerResources(server);
+    registerPrompts(server);
+    return {
+        async start() {
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+            console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+        },
+    };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Component Tools
+ *
+ * MCP tools for working with NYSDS components.
+ *
+ * P0 Tools:
+ * - list_components: List all NYSDS components with summaries
+ * - get_component_docs: Full documentation for a specific component
+ * - find_components: Search by name/description (fuzzy)
+ * - get_usage_guide: Installation and usage patterns
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerComponentTools(server: McpServer): void;
+//# sourceMappingURL=component-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"component-tools.d.ts","sourceRoot":"","sources":["../../src/tools/component-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8I9D"}

package/dist/tools/component-tools.js

@@ -0,0 +1,127 @@
+/**
+ * Component Tools
+ *
+ * MCP tools for working with NYSDS components.
+ *
+ * P0 Tools:
+ * - list_components: List all NYSDS components with summaries
+ * - get_component_docs: Full documentation for a specific component
+ * - find_components: Search by name/description (fuzzy)
+ * - get_usage_guide: Installation and usage patterns
+ */
+import { z } from "zod";
+import { getComponent, getAllComponents } from "../lib/cem-parser.js";
+import { searchComponents } from "../lib/search.js";
+export function registerComponentTools(server) {
+    // list_components - List all NYSDS components with summaries
+    server.tool("list_components", "List all NYSDS web components with their tag names and brief descriptions", {}, 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 {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(list, null, 2),
+                },
+            ],
+        };
+    });
+    // get_component_docs - Full documentation for a specific component
+    server.tool("get_component_docs", "Get full documentation for a specific NYSDS component including properties, events, slots, and CSS custom properties", {
+        tagName: z
+            .string()
+            .describe("The tag name of the component (e.g., 'nys-button')"),
+    }, async ({ tagName }) => {
+        const component = getComponent(tagName);
+        if (!component) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component "${tagName}" not found. Use list_components to see available components.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(component, null, 2),
+                },
+            ],
+        };
+    });
+    // find_components - Search by name/description
+    server.tool("find_components", "Search for NYSDS components by name or description", {
+        query: z
+            .string()
+            .describe("Search query to match against component names and descriptions"),
+    }, async ({ query }) => {
+        const results = searchComponents(query);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(results, null, 2),
+                },
+            ],
+        };
+    });
+    // get_usage_guide - Installation and usage patterns
+    server.tool("get_usage_guide", "Get installation and usage guide for NYSDS components", {}, async () => {
+        const guide = `# NYSDS Component Usage Guide
+
+## Installation
+
+\`\`\`bash
+npm install @nysds/components
+\`\`\`
+
+## Basic Usage
+
+Import components individually:
+
+\`\`\`javascript
+import '@nysds/components/nys-button';
+import '@nysds/components/nys-alert';
+\`\`\`
+
+Or import all components:
+
+\`\`\`javascript
+import '@nysds/components';
+\`\`\`
+
+## Using Components in HTML
+
+\`\`\`html
+<nys-button label="Click me" variant="primary"></nys-button>
+<nys-alert type="info">This is an informational message.</nys-alert>
+\`\`\`
+
+## CSS Custom Properties
+
+NYSDS components use CSS custom properties for theming. Import the base styles:
+
+\`\`\`css
+@import '@nysds/components/dist/styles.css';
+\`\`\`
+
+Use the get_design_tokens tool to explore available tokens.
+`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: guide,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/index.d.ts

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

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

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

package/dist/tools/index.js

@@ -0,0 +1,13 @@
+/**
+ * MCP Tools Registration
+ *
+ * Registers all NYSDS tools with the MCP server.
+ */
+import { registerComponentTools } from "./component-tools.js";
+import { registerTokenTools } from "./token-tools.js";
+import { registerValidationTools } from "./validation-tools.js";
+export function registerTools(server) {
+    registerComponentTools(server);
+    registerTokenTools(server);
+    registerValidationTools(server);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Token Tools
+ *
+ * MCP tools for working with NYSDS design tokens.
+ *
+ * Tools:
+ * - get_design_tokens: Get tokens with filtering and options
+ * - find_tokens: Search tokens by CSS variable, value, or description
+ * - list_themes: List all 8 agency themes
+ * - get_token_value: Get detailed info for a specific token
+ * - validate_token_usage: Validate token usage in context
+ * - list_token_categories: List categories with token counts
+ * - get_token_graph: Get token dependency graph
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTokenTools(server: McpServer): void;
+//# sourceMappingURL=token-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"token-tools.d.ts","sourceRoot":"","sources":["../../src/tools/token-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoOzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4a1D"}