@czi-sds/mcp 0.2.1 → 0.3.0

package/dist/stdio.js

@@ -3,9 +3,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import fs from 'fs';
-import path, { join } from 'path';
+import path from 'path';
 import { fileURLToPath } from 'url';
-import { readFile } from 'fs/promises';
 
 var server = new McpServer({
   name: "sds-mcp",
@@ -124,6 +123,37 @@ async function fetchComponentPropsStorybook(component) {
     );
   }
 }
+async function fetchTailwindTokens() {
+  try {
+    const possiblePaths = [
+      path.join(dirname, "../../data/tailwind.json"),
+      // From src/lib in dev
+      path.join(dirname, "../data/tailwind.json"),
+      // From dist in prod
+      path.join(process.cwd(), "data/tailwind.json")
+      // From current working directory
+    ];
+    let dataPath = "";
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        dataPath = p;
+        break;
+      }
+    }
+    if (!dataPath) {
+      throw new Error(
+        "Component list not found in any expected location. Please run 'yarn generate:tailwind-tokens' first."
+      );
+    }
+    const fileContent = fs.readFileSync(dataPath, "utf-8");
+    const tailwindTokens = JSON.parse(fileContent);
+    return tailwindTokens;
+  } catch (error) {
+    throw new Error(
+      `Failed to load tailwind tokens: ${error instanceof Error ? error.message : `Unknown error ${error}`}`
+    );
+  }
+}
 
 // src/tools/get-component-props.ts
 var getComponentPropsTool = {
@@ -254,13 +284,293 @@ var getComponentPropsStorybookTool = {
     );
   }
 };
+
+// src/lib/tailwind-guidance.ts
+var TAILWIND_TOKEN_GUIDANCE = {
+  colors: {
+    category: "Colors",
+    description: "Theme-aware color tokens with light/dark mode support. Both light and dark mode colors are using the same token name. Use the dark:color-token-name to use the dark mode color.",
+    prefixes: [
+      "bg-",
+      "border-",
+      "divide-",
+      "outline-",
+      "ring-",
+      "ring-offset-",
+      "text-",
+      "placeholder-",
+      "caret-",
+      "decoration-",
+      "accent-",
+      "shadow-",
+      "fill-",
+      "stroke-",
+      "from-",
+      "via-",
+      "to-"
+    ],
+    examples: [
+      {
+        description: "Basic text and background colors",
+        code: `<div className="bg-sds-color-semantic-base-background-primary dark:bg-sds-color-semantic-base-background-primary text-sds-color-semantic-base-text-primary dark:text-sds-color-semantic-base-text-primary">
+  Content with semantic colors
+</div>`
+      },
+      {
+        description: "Dark mode with hover states",
+        code: `<button className="bg-sds-color-semantic-accent-fill-primary dark:bg-sds-color-semantic-accent-fill-primary
+        hover:bg-sds-color-semantic-accent-fill-hover dark:hover:bg-sds-color-semantic-accent-fill-hover">
+  Click me
+</button>`
+      },
+      {
+        description: "Border and focus states",
+        code: `<input className="
+  border-sds-color-semantic-base-border-primary
+  hover:border-sds-color-semantic-base-border-primary-hover
+  focus:border-sds-color-semantic-base-border-primary-pressed
+"/>`
+      }
+    ],
+    tips: [
+      "Always use semantic colors (e.g., 'sds-color-semantic-base-background-primary') over primitive colors when possible",
+      "Include both light and dark variants for proper theme support"
+    ]
+  },
+  typography: {
+    category: "Typography",
+    description: "Complete text styling presets including font, size, weight, and spacing",
+    prefixes: ["font-", "text-", "leading-", "tracking-"],
+    examples: [
+      {
+        description: "Typography presets (recommended). SDS typography tokens come in narrow and wide variants: use token-narrow on screens smaller than md, and token-wide on md and up.",
+        code: `<!-- Use typography tokens for complete text styling -->
+<h1 className="prose-sds-title-l-700-wide">Title</h1>     
+<h1 className="prose-sds-header-xl-600-wide">Heading</h1>
+<p className="prose-sds-body-m-500-wide">Body text</p>
+<span className="prose-sds-caps-xxs-600-wide">SMALL CAPS TEXT</span>
+<span className="prose-sds-tabular-xxs-600-wide">Tabular Numbers</span>
+<span className="prose-sds-code-s-500-wide">Code</span>
+<span className="prose-sds-link-l-500-wide">Link style</span>`
+      },
+      {
+        description: "Individual typography properties",
+        code: `<!-- Or use individual properties when needed -->
+<p className="
+  font-sds-body
+  text-sds-body-m-400-wide
+  leading-sds-body-m-400-wide
+  tracking-sds-body-m-400-wide
+">
+  Custom styled text
+</p>`
+      }
+    ],
+    tips: [
+      "Use 'narrow' variants for mobile/compact layouts",
+      "Use 'wide' variants for desktop/spacious layouts",
+      "Font weights: 400 (regular), 500 (medium), 600 (semibold), 700 (bold)"
+    ]
+  },
+  spacing: {
+    category: "Spacing",
+    description: "Consistent spacing scale for padding, margin, and gaps",
+    prefixes: [
+      "p-",
+      "px-",
+      "py-",
+      "pt-",
+      "pr-",
+      "pb-",
+      "pl-",
+      "m-",
+      "mx-",
+      "my-",
+      "mt-",
+      "mr-",
+      "mb-",
+      "ml-",
+      "gap-",
+      "gap-x-",
+      "gap-y-",
+      "space-x-",
+      "space-y-"
+    ],
+    examples: [
+      {
+        description: "Padding and margin",
+        code: `<div className="p-sds-m mx-sds-l my-sds-s">
+  Content with medium padding and different margins
+</div>`
+      },
+      {
+        description: "Flexbox and grid gaps",
+        code: `<div className="flex gap-sds-m">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+
+<div className="grid grid-cols-3 gap-sds-l">
+  <div>Grid item</div>
+</div>`
+      },
+      {
+        description: "Negative margins for overlapping",
+        code: `<div className="-mt-sds-s">
+  Overlapping element
+</div>`
+      }
+    ],
+    tips: [
+      "Scale: sds-s (small), sds-default (default), sds-m (medium), sds-l (large), sds-xl (extra large)",
+      "Use consistent spacing throughout your component",
+      "Combine with responsive prefixes: sm:p-sds-m lg:p-sds-l"
+    ]
+  },
+  borderRadius: {
+    category: "Border Radius",
+    description: "Corner radius values for rounded elements",
+    prefixes: [
+      "rounded-",
+      "rounded-t-",
+      "rounded-r-",
+      "rounded-b-",
+      "rounded-l-"
+    ],
+    examples: [
+      {
+        description: "Basic rounded corners",
+        code: `<div className="rounded-sds-default">
+  Standard rounded corners
+</div>
+
+<button className="rounded-sds-m">
+  More rounded button
+</button>`
+      },
+      {
+        description: "Directional radius",
+        code: `<div className="rounded-t-sds-l rounded-b-none">
+  Only top corners rounded
+</div>`
+      }
+    ],
+    tips: [
+      "Use sds-default for most UI elements",
+      "Larger values (sds-l, sds-xl) for prominent elements",
+      "Combine with borders: border rounded-sds-m"
+    ]
+  },
+  boxShadow: {
+    category: "Box Shadow",
+    description: "Elevation shadows for depth and hierarchy",
+    prefixes: ["shadow-", "hover:shadow-", "focus:shadow-"],
+    examples: [
+      {
+        description: "Basic shadows",
+        code: `<div className="shadow-sds-s">
+  Subtle shadow
+</div>
+
+<div className="shadow-sds-m">
+  Medium elevation
+</div>`
+      },
+      {
+        description: "Interactive shadows",
+        code: `<button className="
+  shadow-sds-s
+  hover:shadow-sds-m
+  active:shadow-sds-xs
+  transition-shadow
+">
+  Interactive element
+</button>`
+      }
+    ],
+    tips: [
+      "Use smaller shadows (sds-xs, sds-s) for subtle depth",
+      "Use larger shadows (sds-l, sds-xl) for modals and popovers",
+      "Combine with hover states for interactive feedback"
+    ]
+  }
+};
+function getTokenGuidance(category) {
+  if (!category || category === "all") {
+    return `SDS Design System Tokens for Tailwind CSS
+
+The Science Design System provides a comprehensive set of design tokens that map directly to Tailwind utilities.
+
+QUICK START:
+1. Request specific categories for detailed guidance: fontFamily, fontSize, fontVariantNumeric, letterSpacing, lineHeight, textDecoration, textTransform, typography, height, width, borderRadius, boxShadow, breakpoints, colors, spacing
+2. Use semantic tokens over primitive ones when available
+3. Include responsive and theme variants for robust implementations
+4. Use the @czi-sds/components/dist/tailwind.json file to get the exact token name and value
+5. To use the typography tokens, you need to add the @tailwindcss/typography plugin to your tailwind.config.js file and then use the typography tokens in your tailwind classes like prose-[typography-token-name] for example prose-sds-body-m-400-wide.
+6. Colors have been defined in light and dark mode with the same name. Use the dark:color-token-name to use the dark mode color.
+7. Use spacing tokens like sds-m for paddings, margins, etc. for example p-sds-m for padding-medium.
+8. Use borderRadius tokens like sds-default for rounded corners for example rounded-sds-default.
+9. Use boxShadow tokens like sds-s for subtle shadows for example shadow-sds-s.
+10. Use breakpoints tokens like sds-m for medium breakpoints for example md:sds-m.
+11. Use fontFamily tokens like sds-body for body font for example font-sds-body.
+12. Use fontSize tokens like sds-body-m-400-wide for body font size for example text-sds-body-m-400-wide.
+13. Use fontVariantNumeric tokens like sds-body-m-400-wide for body font variant numeric for example font-variant-numeric-sds-body-m-400-wide.
+14. Use letterSpacing tokens like sds-body-m-400-wide for body letter spacing for example tracking-sds-body-m-400-wide.
+
+For detailed examples, request a specific category.`;
+  }
+  const guidance = TAILWIND_TOKEN_GUIDANCE[category];
+  if (!guidance) {
+    return `Category "${category}" not found. Available categories: ${Object.keys(
+      TAILWIND_TOKEN_GUIDANCE
+    ).join(", ")}`;
+  }
+  let output = `## ${guidance.category} Tokens
+
+`;
+  output += `${guidance.description}
+
+`;
+  output += `**Tailwind Prefixes:** ${guidance.prefixes.join(", ")}
+
+`;
+  output += `### Examples:
+
+`;
+  guidance.examples.forEach((example, index) => {
+    output += `${index + 1}. **${example.description}**
+\`\`\`jsx
+${example.code}
+\`\`\`
+
+`;
+  });
+  if (guidance.tips && guidance.tips.length > 0) {
+    output += `### Tips:
+`;
+    guidance.tips.forEach((tip) => {
+      output += `- ${tip}
+`;
+    });
+  }
+  return output;
+}
+
+// src/tools/get-tailwind-tokens.ts
 var getTailwindTokensTool = {
   name: "get_tailwind_tokens",
-  description: "Get all available Tailwind tokens from the SDS design system. Returns design tokens including colors, typography, spacing, borders, shadows, and other design system values formatted for Tailwind CSS.",
+  description: "Get all available Tailwind tokens from the SDS design system. Available design tokens include fontFamily, fontSize, fontVariantNumeric, letterSpacing, lineHeight, textDecoration, textTransform, typography, height, width, borderRadius, boxShadow, breakpoints, colors, spacing, and more.",
   async ctx() {
-    return {};
+    try {
+      const tailwindTokens = await fetchTailwindTokens();
+      return { tailwindTokens };
+    } catch (error) {
+      throw new Error(
+        `Failed to initialize tailwind tokens tool: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
   },
-  exec(server2, { name, description }) {
+  exec(server2, { ctx, name, description }) {
     server2.tool(
       name,
       description,
@@ -288,18 +598,210 @@ var getTailwindTokensTool = {
       },
       async ({ category }) => {
         try {
-          const dataPath = join(process.cwd(), "data", "tailwind.json");
-          const fileContent = await readFile(dataPath, "utf-8");
-          const tokens = JSON.parse(fileContent);
-          let result = tokens;
-          if (category && category !== "all") {
+          const tokens = ctx.tailwindTokens;
+          let result;
+          if (!category || category === "all") {
+            result = tokens;
+          } else {
             result = tokens[category] || {};
           }
+          const responseContent = [];
+          const guidance = getTokenGuidance(category);
+          responseContent.push({
+            type: "text",
+            text: guidance
+          });
+          responseContent.push({
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          });
+          return {
+            content: responseContent
+          };
+        } catch (error) {
           return {
             content: [
               {
                 type: "text",
-                text: JSON.stringify(result, null, 2)
+                text: `Failed to get Tailwind tokens: ${error instanceof Error ? error.message : "Unknown error"}`
+              }
+            ]
+          };
+        }
+      }
+    );
+  }
+};
+var filename2 = fileURLToPath(import.meta.url);
+var dirname2 = path.dirname(filename2);
+function mapComponentToFile(componentName, exportedFiles) {
+  const componentToFileMap = {
+    // Button components
+    "Button": "Buttons",
+    "ButtonDropdown": "Buttons",
+    "ButtonIcon": "Buttons",
+    "ButtonToggle": "Buttons",
+    // Table components
+    "TableHeader": "Table",
+    "TableRow": "Table",
+    // Input components
+    "InputCheckbox": "Control-Inputs",
+    "InputRadio": "Control-Inputs",
+    "InputToggle": "Control-Inputs",
+    "InputText": "Field-Inputs",
+    "InputDropdown": "Dropdown-Input",
+    "InputSearch": "Search-Input",
+    "InputSlider": "Control-Inputs",
+    // Dropdown components
+    "Dropdown": "Dropdown-Menu",
+    "DropdownMenu": "Dropdown-Menu",
+    // Content components
+    "ContentCard": "Content-Card",
+    "LoadingIndicator": "Loading-Indicator",
+    // Navigation components
+    "NavigationFooter": "Navigation",
+    "NavigationHeader": "Navigation",
+    "NavigationJumpTo": "Navigation",
+    // Control components
+    "SegmentedControl": "Segmented-Control",
+    // List and menu components
+    "List": "Lists",
+    "Menu": "Dropdown-Menu",
+    "MenuItem": "Dropdown-Menu",
+    "MenuSelect": "Dropdown-Menu",
+    // Tag components
+    "Tag": "Tags",
+    "TagFilter": "Tags",
+    // Tooltip components
+    "Tooltip": "Tooltips",
+    "TooltipCondensed": "Tooltips",
+    "TooltipTable": "Tooltips",
+    // Table Cell components
+    "CellBasic": "Table",
+    "CellComponent": "Table",
+    "CellHeader": "Table",
+    // Filter components
+    "ComplexFilter": "Filters",
+    // Other components
+    "Icon": "Icons",
+    "Chip": "Tags",
+    // Chips are often similar to tags
+    "Pagination": "Navigation"
+    // Pagination is often part of navigation
+  };
+  const mappedFile = componentToFileMap[componentName];
+  if (mappedFile && exportedFiles.includes(mappedFile)) {
+    return `${mappedFile}.md`;
+  }
+  if (exportedFiles.includes(componentName)) {
+    return `${componentName}.md`;
+  }
+  return null;
+}
+function getExportedFiles() {
+  try {
+    const possiblePaths = [
+      path.join(dirname2, "../../data/zeroheight-exports"),
+      // From src/lib in dev
+      path.join(dirname2, "../data/zeroheight-exports"),
+      // From dist in prod
+      path.join(process.cwd(), "data/zeroheight-exports")
+      // From current working directory
+    ];
+    let exportDir = "";
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        exportDir = p;
+        break;
+      }
+    }
+    if (!exportDir) {
+      console.warn("Export directory not found in any expected location. Please run Zeroheight export first.");
+      return [];
+    }
+    const files = fs.readdirSync(exportDir).filter((file) => file.endsWith(".md") && file !== "README.md").map((file) => file.replace(".md", ""));
+    return files;
+  } catch (error) {
+    console.warn("Could not read exported files:", error);
+    return [];
+  }
+}
+function getComponentsWithDocs(allComponents, exportedFiles) {
+  return allComponents.filter((component) => {
+    const mappedFile = mapComponentToFile(component, exportedFiles);
+    return mappedFile !== null;
+  });
+}
+var getComponentDocsTool = {
+  name: "get_component_docs",
+  description: "Get design system documentation for a specific component. Retrieves the corresponding Zeroheight documentation file for the given component name. Supports all SDS components and maps them to their appropriate documentation files.",
+  async ctx() {
+    try {
+      const componentList = await getAllComponentNames();
+      const allComponents = [
+        ...componentList.components,
+        ...componentList["data-viz"]
+      ];
+      const exportedFiles = getExportedFiles();
+      const componentsWithDocs = getComponentsWithDocs(allComponents, exportedFiles);
+      return {
+        componentsWithDocs,
+        exportedFiles
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to initialize get component docs tool: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  },
+  exec(server2, { ctx, name, description }) {
+    server2.tool(
+      name,
+      description,
+      {
+        component: z.enum(ctx.componentsWithDocs).describe("The name of the SDS component to get documentation for")
+      },
+      async ({ component }) => {
+        try {
+          const mappedFile = mapComponentToFile(component, ctx.exportedFiles);
+          if (!mappedFile) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `No documentation found for component '${component}'. This component may not have design system documentation available.`
+                }
+              ]
+            };
+          }
+          const possiblePaths = [
+            path.join(dirname2, "../../data/zeroheight-exports", mappedFile),
+            // From src/lib in dev
+            path.join(dirname2, "../data/zeroheight-exports", mappedFile),
+            // From dist in prod
+            path.join(process.cwd(), "data/zeroheight-exports", mappedFile)
+            // From current working directory
+          ];
+          let filePath = "";
+          for (const p of possiblePaths) {
+            if (fs.existsSync(p)) {
+              filePath = p;
+              break;
+            }
+          }
+          if (!filePath) {
+            throw new Error(`Documentation file ${mappedFile} not found`);
+          }
+          const documentation = fs.readFileSync(filePath, "utf8");
+          return {
+            content: [
+              {
+                type: "text",
+                text: `# Documentation for ${component}
+
+Source: ${mappedFile}
+
+${documentation}`
               }
             ]
           };
@@ -308,7 +810,7 @@ var getTailwindTokensTool = {
             content: [
               {
                 type: "text",
-                text: `Failed to get Tailwind tokens: ${error instanceof Error ? error.message : "Unknown error"}`
+                text: `Error reading documentation file for '${component}': ${error instanceof Error ? error.message : "Unknown error"}`
               }
             ]
           };
@@ -322,6 +824,7 @@ var getTailwindTokensTool = {
 var tools = [
   getComponentPropsTool,
   getComponentPropsStorybookTool,
+  getComponentDocsTool,
   listComponentsTool,
   getTailwindTokensTool
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@czi-sds/mcp",
   "description": "The official MCP server for SDS",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "main": "dist/stdio.js",
   "files": [
     "dist",
@@ -23,7 +23,8 @@
     "generate:components-list": "tsx scripts/generate-component-list.ts",
     "generate:component-props": "tsx scripts/generate-component-props.ts",
     "generate:component-props-storybook": "tsx scripts/generate-component-props-from-storybook.ts",
-    "generate:all": "yarn generate:tailwind-tokens && yarn generate:components-list && yarn generate:component-props && yarn generate:component-props-storybook",
+    "generate:zeroheight-export": "tsx scripts/export-zeroheight-pages.ts",
+    "generate:all": "yarn generate:tailwind-tokens && yarn generate:components-list && yarn generate:component-props && yarn generate:component-props-storybook && yarn generate:zeroheight-export",
     "prebuild": "yarn generate:all",
     "build": "yarn prebuild && tsup && chmod 755 dist/stdio.js",
     "dev": "tsup --watch",
@@ -62,5 +63,5 @@
     "tsx": "^4.20.3",
     "typescript": "^5.9.2"
   },
-  "gitHead": "fa7e676b7f69b6999cc8d6fe86c04b8069bfdb1e"
+  "gitHead": "c4bbb6751f8efd89ff5b6e560d8aea687cf8a84c"
 }