@nysds/mcp-server 1.16.0-alpha4 → 1.16.0-alpha5

package/dist/tools/component-tools.js

@@ -3,123 +3,89 @@
  *
  * 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
+ * Tools:
+ * - find_components: Search or list all components
+ * - get_component: Full documentation for a specific component
  */
 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",
+    // find_components - Search or list all components
+    server.tool("find_components", "Search for NYSDS components by name or description. Omit query to list all components.", {
+        query: z
+            .string()
+            .optional()
+            .describe("Search query to match against component names and descriptions. Omit to list all components."),
+    }, async ({ query }) => {
+        // If no query, return all components
+        if (!query || query.trim() === "") {
+            const components = getAllComponents();
+            const list = components.map((c) => ({
+                tagName: c.tagName,
+                name: c.name,
+                summary: c.summary || c.description?.split("\n")[0] || "No description",
+                resourceUri: `nysds://component/${c.tagName}`,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(list, null, 2),
+                    },
+                ],
+            };
+        }
+        // Otherwise search
+        const results = searchComponents(query).map((r) => ({
+            ...r,
+            resourceUri: `nysds://component/${r.tagName}`,
         }));
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(list, null, 2),
+                    text: JSON.stringify(results, 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", {
+    // get_component - Full documentation for a specific component
+    server.tool("get_component", "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 }) => {
+        includeExamples: z
+            .boolean()
+            .default(false)
+            .describe("Include HTML code examples from component JSDoc. Set to true when you need usage patterns."),
+    }, async ({ tagName, includeExamples }) => {
         const component = getComponent(tagName);
         if (!component) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Component "${tagName}" not found. Use list_components to see available components.`,
+                        text: `Component "${tagName}" not found. Use find_components to see available components.`,
                     },
                 ],
                 isError: true,
             };
         }
+        // Remove members array to avoid duplication with attributes
+        // Attributes contains the HTML API, members duplicates this plus private methods
+        const { members: _members, examples, ...componentWithoutMembers } = component;
         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,
+                    text: JSON.stringify({
+                        ...componentWithoutMembers,
+                        examples: includeExamples && examples && examples.length > 0
+                            ? examples
+                            : undefined,
+                        resourceUri: `nysds://component/${tagName}`,
+                    }, null, 2),
                 },
             ],
         };

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

@@ -0,0 +1,9 @@
+/**
+ * Guide Tools
+ *
+ * Consolidated MCP tool for NYSDS guides and documentation.
+ * Loads guide content from data/guides/ markdown files.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGuideTools(server: McpServer): void;
+//# sourceMappingURL=guide-tools.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/guide-tools.js

@@ -0,0 +1,78 @@
+/**
+ * Guide Tools
+ *
+ * Consolidated MCP tool for NYSDS guides and documentation.
+ * Loads guide content from data/guides/ markdown files.
+ */
+import { z } from "zod";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+// ESM-compatible __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Path to guides directory (relative to dist/tools/)
+const GUIDES_DIR = join(__dirname, "../../data/guides");
+/**
+ * Load a guide markdown file
+ */
+function loadGuide(filename) {
+    try {
+        return readFileSync(join(GUIDES_DIR, filename), "utf-8");
+    }
+    catch {
+        return `Guide not found: ${filename}`;
+    }
+}
+/**
+ * Load a framework-specific guide
+ */
+function loadFrameworkGuide(framework) {
+    try {
+        return readFileSync(join(GUIDES_DIR, "frameworks", `${framework}.md`), "utf-8");
+    }
+    catch {
+        return `Framework guide not found: ${framework}`;
+    }
+}
+const TOPIC_TO_FILE = {
+    installation: "installation.md",
+    "form-validation": "form-validation.md",
+    styles: "styles.md",
+    fonts: "fonts.md",
+    "page-structure": "page-structure.md",
+};
+export function registerGuideTools(server) {
+    server.tool("get_guide", "Get NYSDS guides for installation, forms, styles, fonts, page structure, or framework setup", {
+        topic: z
+            .enum([
+            "installation",
+            "form-validation",
+            "styles",
+            "fonts",
+            "page-structure",
+        ])
+            .describe("The guide topic to retrieve"),
+        framework: z
+            .enum(["angular", "react", "dotnet", "drupal", "vanilla"])
+            .optional()
+            .describe("When provided, returns framework-specific setup guide instead of the topic guide. Use with topic 'installation' to get framework install instructions."),
+    }, async ({ topic, framework }) => {
+        let content;
+        if (framework) {
+            content = loadFrameworkGuide(framework);
+        }
+        else {
+            const filename = TOPIC_TO_FILE[topic];
+            content = filename ? loadGuide(filename) : `Unknown topic: ${topic}`;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: content,
+                },
+            ],
+        };
+    });
+}

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

@@ -1 +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"}
+{"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;AAOzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAMrD"}

package/dist/tools/index.js

@@ -6,8 +6,12 @@
 import { registerComponentTools } from "./component-tools.js";
 import { registerTokenTools } from "./token-tools.js";
 import { registerValidationTools } from "./validation-tools.js";
+import { registerUtilityTools } from "./utility-tools.js";
+import { registerGuideTools } from "./guide-tools.js";
 export function registerTools(server) {
     registerComponentTools(server);
     registerTokenTools(server);
     registerValidationTools(server);
+    registerUtilityTools(server);
+    registerGuideTools(server);
 }

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

@@ -4,12 +4,9 @@
  * MCP tools for working with NYSDS design tokens.
  *
  * Tools:
- * - get_design_tokens: Get tokens with filtering and options
+ * - get_tokens: Get tokens, categories, or themes
  * - 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_info: Get detailed token info with optional context validation
  * - 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;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoOzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4a1D"}
+{"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"}

package/dist/tools/token-tools.js

@@ -4,16 +4,14 @@
  * MCP tools for working with NYSDS design tokens.
  *
  * Tools:
- * - get_design_tokens: Get tokens with filtering and options
+ * - get_tokens: Get tokens, categories, or themes
  * - 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_info: Get detailed token info with optional context validation
  * - 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",
@@ -181,9 +179,13 @@ function validateTokenInContext(token, context) {
 // ============================================================================
 export function registerTokenTools(server) {
     // -------------------------------------------------------------------------
-    // get_design_tokens - Enhanced token retrieval
+    // get_tokens - Consolidated token retrieval (tokens, categories, or themes)
     // -------------------------------------------------------------------------
-    server.tool("get_design_tokens", "Get NYSDS design tokens with optional filtering by category or layer. Returns CSS variable names and values.", {
+    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",
@@ -198,20 +200,53 @@ export function registerTokenTools(server) {
             "icon",
         ])
             .optional()
-            .describe("Filter by token category"),
+            .describe("Filter tokens by category (only applies when output='tokens')"),
         layer: z
             .enum(["primitive", "applied", "theme", "appearance"])
             .optional()
-            .describe("Filter by token layer (primitive = raw values, applied = semantic tokens, theme = agency theme tokens, appearance = light/dark mode)"),
+            .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 for previews"),
+            .describe("Include resolved hex/rem values (only applies when output='tokens')"),
         includeDescriptions: z
             .boolean()
             .default(true)
-            .describe("Include token descriptions"),
-    }, async ({ category, layer, includeResolvedValues, includeDescriptions }) => {
+            .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)
         let tokens;
         if (category) {
             tokens = getCSSTokensByCategory(category);
@@ -240,10 +275,7 @@ export function registerTokenTools(server) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        count: tokens.length,
-                        tokens: formatted,
-                    }, null, 2),
+                    text: formatResponse({ count: tokens.length, tokens: formatted }),
                 },
             ],
         };
@@ -285,54 +317,37 @@ export function registerTokenTools(server) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: formatResponse({
                         query,
                         count: results.length,
                         results: formatted,
-                    }, null, 2),
+                    }),
                 },
             ],
         };
     });
     // -------------------------------------------------------------------------
-    // list_themes - List agency themes
+    // get_token_info - Get detailed token info with optional context validation
     // -------------------------------------------------------------------------
-    server.tool("list_themes", "List all NYSDS agency themes with their selectors and primary colors", {}, async () => {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        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,
-                    }, null, 2),
-                },
-            ],
-        };
-    });
-    // -------------------------------------------------------------------------
-    // get_token_value - Get detailed token info
-    // -------------------------------------------------------------------------
-    server.tool("get_token_value", "Get detailed information about a specific design token including its value, description, and which tokens use it", {
+    server.tool("get_token_info", "Get detailed information about a specific design token. Optionally validate usage in a specific context (text, background, border, icon).", {
         token: z
             .string()
             .describe('CSS variable name (e.g., "--nys-color-text" or "color-text")'),
-    }, async ({ token }) => {
+        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 }) => {
         const tokenInfo = getCSSTokenByVariable(token);
         if (!tokenInfo) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({
+                        text: formatResponse({
                             error: `Token not found: ${token}`,
                             suggestion: "Try searching with find_tokens to discover available tokens",
-                        }, null, 2),
+                        }),
                     },
                 ],
             };
@@ -341,73 +356,38 @@ export function registerTokenTools(server) {
         const graph = buildTokenGraph();
         const node = graph.get(tokenInfo.cssVariable);
         const usedBy = node?.usedBy || [];
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        cssVariable: tokenInfo.cssVariable,
-                        cssValue: tokenInfo.cssValue,
-                        resolvedValue: tokenInfo.resolvedValue,
-                        description: tokenInfo.description,
-                        category: tokenInfo.category,
-                        layer: tokenInfo.layer,
-                        usedBy: usedBy.length > 0 ? usedBy : undefined,
-                        usage: `var(${tokenInfo.cssVariable})`,
-                    }, null, 2),
-                },
-            ],
+        // Base token info
+        const result = {
+            cssVariable: tokenInfo.cssVariable,
+            cssValue: tokenInfo.cssValue,
+            resolvedValue: tokenInfo.resolvedValue,
+            description: tokenInfo.description,
+            category: tokenInfo.category,
+            layer: tokenInfo.layer,
+            usedBy: usedBy.length > 0 ? usedBy : undefined,
+            usage: `var(${tokenInfo.cssVariable})`,
+            resourceUri: "nysds://tokens",
         };
-    });
-    // -------------------------------------------------------------------------
-    // validate_token_usage - Validate token in context
-    // -------------------------------------------------------------------------
-    server.tool("validate_token_usage", "Validate whether a token is appropriate for a specific usage context (text, background, border, icon)", {
-        token: z
-            .string()
-            .describe('CSS variable name (e.g., "--nys-color-text" or "color-text")'),
-        context: z
-            .enum(["text", "background", "border", "icon"])
-            .describe("How the token will be used"),
-    }, async ({ token, context }) => {
-        const tokenInfo = getCSSTokenByVariable(token);
-        if (!tokenInfo) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: `Token not found: ${token}`,
-                            suggestion: "Try searching with find_tokens to discover available tokens",
-                        }, null, 2),
-                    },
-                ],
+        // 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,
             };
         }
-        const validation = validateTokenInContext(tokenInfo, context);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(validation, null, 2),
-                },
-            ],
-        };
-    });
-    // -------------------------------------------------------------------------
-    // list_token_categories - List categories with counts
-    // -------------------------------------------------------------------------
-    server.tool("list_token_categories", "List all token categories with the number of tokens in each", {}, async () => {
-        const categories = getCSSTokenCategories();
-        const total = categories.reduce((sum, c) => sum + c.count, 0);
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        categories,
-                        totalTokens: total,
-                    }, null, 2),
+                    text: formatResponse(result),
                 },
             ],
         };
@@ -440,8 +420,8 @@ export function registerTokenTools(server) {
             .int()
             .min(1)
             .max(100)
-            .default(50)
-            .describe("Maximum number of tokens to return"),
+            .default(20)
+            .describe("Maximum number of tokens to return (default: 20)"),
     }, async ({ filter, category, limit }) => {
         const graph = buildTokenGraph();
         const tokens = getCSSTokens();
@@ -487,7 +467,7 @@ export function registerTokenTools(server) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: formatResponse({
                         filter,
                         category: category || "all",
                         nodes: nodes.map((n) => ({
@@ -496,7 +476,7 @@ export function registerTokenTools(server) {
                             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 NYSDS 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;AAwOzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8D5D"}