@triptease/design-system-mcp 1.0.0 → 1.0.2

package/src/index.ts

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import packageJson from '@/../package.json' with { type: 'json' };
 
-import getComponentDocsTool from '@/tools/getComponentDocs/index.js';
-import listComponentsTool from '@/tools/listComponents/index.js';
-import getDesignTokensTool from '@/tools/getCSSTokens/index.js';
-import searchComponentsTool from '@/tools/searchComponents/index.js';
-import getSetupGuideTool from '@/tools/getSetupGuide/index.js';
-import listCSSTokens from '@/tools/listCSSTokens/index.js';
+import {
+  listComponents,
+  getComponentDocs,
+  listCSSTokens,
+  getCSSTokens,
+  getSetupGuide,
+  getPrinciplesGuide,
+} from '@/resources/index.js';
 
 // Initialize MCP server
 const server = new McpServer(
@@ -19,18 +21,96 @@ const server = new McpServer(
   },
   {
     capabilities: {
+      resources: {},
       tools: {},
     },
   }
 );
 
-// Register getComponentDocsTool definitions
-server.registerTool(getComponentDocsTool.name, getComponentDocsTool.config, getComponentDocsTool.handler);
-server.registerTool(listComponentsTool.name, listComponentsTool.config, listComponentsTool.handler);
-server.registerTool(getDesignTokensTool.name, getDesignTokensTool.config, getDesignTokensTool.handler);
-server.registerTool(searchComponentsTool.name, searchComponentsTool.config, searchComponentsTool.handler);
-server.registerTool(getSetupGuideTool.name, getSetupGuideTool.config, getSetupGuideTool.handler);
-server.registerTool(listCSSTokens.name, listCSSTokens.config, listCSSTokens.handler);
+// Register resources
+server.registerResource(
+  'list_components',
+  'designsystem://components',
+  {
+    description: 'List all available design system components',
+    mimeType: 'application/json',
+  },
+  listComponents
+);
+
+server.registerResource(
+  'get_component_docs',
+  new ResourceTemplate('designsystem://components/{name}', { list: undefined }),
+  {
+    description: 'Get documentation for a specific component',
+    mimeType: 'application/json',
+  },
+  async (_uri, { name }) => {
+    return getComponentDocs(name as string);
+  }
+);
+
+server.registerResource(
+  'list_css_tokens',
+  'designsystem://tokens',
+  {
+    description: 'List all CSS token categories with counts',
+    mimeType: 'application/json',
+  },
+  listCSSTokens
+);
+
+server.registerResource(
+  'get_css_tokens',
+  new ResourceTemplate('designsystem://tokens/{category}', { list: undefined }),
+  {
+    description: 'Get CSS tokens for a specific category',
+    mimeType: 'application/json',
+  },
+  async (_uri, { category }) => {
+    return getCSSTokens(category as string);
+  }
+);
+
+server.registerResource(
+  'setup_guide_all',
+  'designsystem://guides/setup',
+  {
+    description: 'Get all setup and installation instructions',
+    mimeType: 'application/json',
+  },
+  async () => getSetupGuide()
+);
+
+server.registerResource(
+  'setup_guide_npm',
+  'designsystem://guides/setup/npm',
+  {
+    description: 'Get NPM setup and installation instructions',
+    mimeType: 'application/json',
+  },
+  async () => getSetupGuide('npm')
+);
+
+server.registerResource(
+  'setup_guide_cdn',
+  'designsystem://guides/setup/cdn',
+  {
+    description: 'Get CDN setup and installation instructions',
+    mimeType: 'application/json',
+  },
+  async () => getSetupGuide('cdn')
+);
+
+server.registerResource(
+  'principles_guide',
+  'designsystem://guides/principles',
+  {
+    description: 'Get design system usage principles and best practices',
+    mimeType: 'application/json',
+  },
+  getPrinciplesGuide
+);
 
 // Start the server
 async function main() {

package/src/manifests/components/entries/barChart.ts

@@ -37,7 +37,7 @@ export default {
           name: 'tt-bar-chart',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           pinnedVersionUrl: buildCDNUrl('tt-bar-chart', latestBarChartVersion),
           pinnedMajorVersionUrl: buildCDNUrl('tt-bar-chart', buildMajorVersion(latestBarChartVersion)),
           latestVersionUrl: buildCDNUrl('tt-bar-chart', 'latest'),
@@ -48,7 +48,7 @@ export default {
           name: 'tt-dataset',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           pinnedVersionUrl: buildCDNUrl('tt-dataset', latestDatasetVersion),
           pinnedMajorVersionUrl: buildCDNUrl('tt-dataset', buildMajorVersion(latestDatasetVersion)),
           latestVersionUrl: buildCDNUrl('tt-dataset', 'latest'),
@@ -59,7 +59,7 @@ export default {
           name: 'tt-data-point',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           pinnedVersionUrl: buildCDNUrl('tt-data-point', latestDataPointVersion),
           pinnedMajorVersionUrl: buildCDNUrl('tt-data-point', buildMajorVersion(latestDataPointVersion)),
           latestVersionUrl: buildCDNUrl('tt-data-point', 'latest'),

package/src/manifests/components/entries/card.ts

@@ -19,8 +19,8 @@ export default {
       ],
     },
     classes: {
-      card: 'Standard card with padding',
-      'card-dataview': 'Card optimized for displaying metrics/data',
+      card: 'Pre-styled container with flex layout, spacing, borders, and elevation',
+      'card-dataview': 'Card variant with grid layout optimized for displaying metrics/data',
     },
     examples: [
       {
@@ -28,6 +28,14 @@ export default {
         code: `<div class="card">
   <h3>Card Title</h3>
   <p>Card content goes here...</p>
+</div>`,
+      },
+      {
+        title: 'Card with custom padding',
+        description: 'Customize using --card-padding or --card-vertical-spacing CSS variables',
+        code: `<div class="card" style="--card-padding: var(--space-scale-4)">
+  <h3>Card with more padding</h3>
+  <p>Customized via CSS variable instead of writing custom CSS</p>
 </div>`,
       },
     ],

package/src/manifests/components/entries/combobox.ts

@@ -30,7 +30,7 @@ export default {
           name: '@triptease/tt-combobox',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           latestVersionUrl: buildCDNUrl('tt-combobox', 'latest'),
           pinnedMajorVersionUrl: buildCDNUrl('tt-combobox', buildMajorVersion(version)),
           pinnedVersionUrl: buildCDNUrl('tt-combobox', version),

package/src/manifests/components/entries/datePicker.ts

@@ -26,7 +26,7 @@ export default {
           name: '@triptease/tt-date-picker',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           latestVersionUrl: buildCDNUrl('tt-date-picker', 'latest'),
           pinnedMajorVersionUrl: buildCDNUrl('tt-date-picker', buildMajorVersion(version)),
           pinnedVersionUrl: buildCDNUrl('tt-date-picker', version),

package/src/manifests/components/entries/dateRangePicker.ts

@@ -30,7 +30,7 @@ export default {
           name: '@triptease/tt-date-range-picker',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           latestVersionUrl: buildCDNUrl('tt-date-range-picker', 'latest'),
           pinnedMajorVersionUrl: buildCDNUrl('tt-date-range-picker', buildMajorVersion(version)),
           pinnedVersionUrl: buildCDNUrl('tt-date-range-picker', version),

package/src/manifests/components/entries/dialog.ts

@@ -31,7 +31,7 @@ export default {
           name: 'tt-dialog',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           pinnedVersionUrl: buildCDNUrl('tt-dialog', version),
           pinnedMajorVersionUrl: buildCDNUrl('tt-dialog', buildMajorVersion(version)),
           latestVersionUrl: buildCDNUrl('tt-dialog', 'latest'),

package/src/manifests/components/entries/lineChart.ts

@@ -46,7 +46,7 @@ export default {
           name: 'tt-dataset',
           includesTypes: false,
           optional: false,
-          moduleFormat: "esm",
+          moduleFormat: 'esm',
           pinnedVersionUrl: buildCDNUrl('tt-dataset', latestDatasetVersion),
           pinnedMajorVersionUrl: buildCDNUrl('tt-dataset', buildMajorVersion(latestDatasetVersion)),
           latestVersionUrl: buildCDNUrl('tt-dataset', 'latest'),

package/src/resources/components/get.test.ts

@@ -0,0 +1,39 @@
+import { getComponentDocs } from './get.js';
+import { describe, expect, it } from 'vitest';
+
+describe('getComponentDocs resource', () => {
+  it('should return error for non-existent component', async () => {
+    const result = await getComponentDocs('foo');
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.error).toBe("Component 'foo' not found");
+    expect(data.available).toBeDefined();
+    expect(Array.isArray(data.available)).toBe(true);
+  });
+
+  it('should return component manifest for valid component', async () => {
+    const result = await getComponentDocs('button');
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.name).toBe('Button');
+    expect(data.element).toBe('button');
+    expect(data.description).toBeDefined();
+    expect(data.dataAttributes).toBeDefined();
+  });
+
+  it('should return contents with correct URI and mimeType', async () => {
+    const result = await getComponentDocs('button');
+
+    expect(result.contents).toBeDefined();
+    expect(result.contents).toHaveLength(1);
+    expect(result.contents[0].uri).toBe('designsystem://components/button');
+    expect(result.contents[0].mimeType).toBe('application/json');
+  });
+
+  it('should handle case-insensitive component names', async () => {
+    const lowerResult = await getComponentDocs('button');
+    const upperResult = await getComponentDocs('BUTTON');
+
+    expect(JSON.parse(lowerResult.contents[0].text)).toEqual(JSON.parse(upperResult.contents[0].text));
+  });
+});

package/src/resources/components/get.ts

@@ -0,0 +1,35 @@
+import { componentManifest } from '@/manifests/components/index.js';
+
+export const getComponentDocs = async (name: string) => {
+  const componentName = name.toLowerCase();
+  const component = componentManifest[componentName];
+
+  if (!component) {
+    return {
+      contents: [
+        {
+          uri: `designsystem://components/${name}`,
+          mimeType: 'application/json',
+          text: JSON.stringify(
+            {
+              error: `Component '${componentName}' not found`,
+              available: Object.keys(componentManifest),
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  return {
+    contents: [
+      {
+        uri: `designsystem://components/${name}`,
+        mimeType: 'application/json',
+        text: JSON.stringify(component, null, 2),
+      },
+    ],
+  };
+};

package/src/resources/components/index.ts

@@ -0,0 +1,2 @@
+export { listComponents } from './list.js';
+export { getComponentDocs } from './get.js';

package/src/resources/components/list.test.ts

@@ -0,0 +1,40 @@
+import { listComponents } from './list.js';
+import { describe, expect, it } from 'vitest';
+
+describe('listComponents resource', () => {
+  it('should return contents with correct URI and mimeType', async () => {
+    const result = await listComponents();
+
+    expect(result.contents).toBeDefined();
+    expect(result.contents).toHaveLength(1);
+    expect(result.contents[0].uri).toBe('designsystem://components');
+    expect(result.contents[0].mimeType).toBe('application/json');
+  });
+
+  it('should return all 18 components', async () => {
+    const result = await listComponents();
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.components).toHaveLength(18);
+  });
+
+  it('should include component key, name, description, and element', async () => {
+    const result = await listComponents();
+    const data = JSON.parse(result.contents[0].text);
+    const firstComponent = data.components[0];
+
+    expect(firstComponent).toHaveProperty('key');
+    expect(firstComponent).toHaveProperty('name');
+    expect(firstComponent).toHaveProperty('description');
+    expect(firstComponent).toHaveProperty('element');
+  });
+
+  it('should include button component', async () => {
+    const result = await listComponents();
+    const data = JSON.parse(result.contents[0].text);
+    const buttonComponent = data.components.find((c: any) => c.key === 'button');
+
+    expect(buttonComponent).toBeDefined();
+    expect(buttonComponent.name).toBe('Button');
+  });
+});

package/src/resources/components/list.ts

@@ -0,0 +1,20 @@
+import { componentManifest } from '@/manifests/components/index.js';
+
+export const listComponents = async () => {
+  const components = Object.entries(componentManifest).map(([key, comp]) => ({
+    key,
+    name: comp.name,
+    description: comp.description,
+    element: comp.element,
+  }));
+
+  return {
+    contents: [
+      {
+        uri: 'designsystem://components',
+        mimeType: 'application/json',
+        text: JSON.stringify({ components }, null, 2),
+      },
+    ],
+  };
+};

package/src/resources/guides/index.ts

@@ -0,0 +1,2 @@
+export { getSetupGuide } from './setup.js';
+export { getPrinciplesGuide } from './principles.js';

package/src/resources/guides/principles.ts

@@ -0,0 +1,160 @@
+export const designSystemPrinciples = {
+  overview: {
+    corePrinciple:
+      'Trust the design system. Components and classes are fully styled and production-ready. Use them as-is.',
+    philosophy:
+      'The design system handles styling, spacing, colors, and layouts. Your role is to compose components, not recreate their styling.',
+  },
+  cssClassUsage: {
+    defaultApproach: 'Use existing classes without writing additional CSS',
+    do: [
+      'Use classes as-is without extra styling (e.g., <div class="card">)',
+      'Check component documentation BEFORE writing any custom CSS',
+      'Compose with multiple classes when needed (e.g., class="card stat-card")',
+      'Override using CSS variables when provided (e.g., style="--card-padding: var(--space-scale-4)")',
+      'Trust that design system classes include ALL necessary styling (layout, spacing, colors, shadows)',
+    ],
+    dont: [
+      "Don't duplicate CSS that classes already provide (border, background, padding, etc.)",
+      "Don't create new classes without checking if design system has it",
+      "Don't assume classes need additional styling - verify in docs first",
+      "Don't override design tokens with hardcoded values (use CSS variables instead)",
+      "Don't add wrapper divs just to style - compose classes directly",
+    ],
+  },
+  verificationWorkflow: {
+    description: 'Follow this workflow BEFORE writing any custom CSS',
+    steps: [
+      '1. Check: Does the design system have this component? (Query designsystem://components)',
+      '2. Read: What does the component provide? (Check component docs)',
+      '3. Use: Apply the class without custom CSS first',
+      '4. Test: Does it work as-is? (Usually yes!)',
+      '5. Customize: Only if truly needed, use CSS variables or add modifier classes',
+    ],
+  },
+  whenToWriteCustomCSS: {
+    description: 'Write custom CSS only in these scenarios',
+    scenarios: [
+      'User explicitly requests custom/unique styling',
+      'Design system genuinely lacks the needed component',
+      'Truly unique layout requirements that cannot be solved with existing classes or composition',
+      'Dashboard-specific or app-specific layout patterns (grids, specialized containers)',
+    ],
+    notValidReasons: [
+      'Not valid: "I need a card with padding" - .card already has padding',
+      'Not valid: "I need a button with a border" - button already has borders',
+      'Not valid: "I need spacing between elements" - use design system spacing tokens',
+    ],
+  },
+  compositionPatterns: {
+    description: 'How to combine design system classes effectively',
+    patterns: [
+      {
+        pattern: 'Base + Modifier',
+        example: '<div class="card stat-card">',
+        explanation: 'Use base design system class (card) + your modifier class (stat-card) for extensions',
+      },
+      {
+        pattern: 'CSS Variable Override',
+        example: '<div class="card" style="--card-padding: var(--space-scale-5)">',
+        explanation: 'Override CSS variables for customization without duplicating styles',
+      },
+      {
+        pattern: 'Multiple Design System Classes',
+        example: '<button class="primary large">',
+        explanation: 'Compose multiple utility/variant classes from design system',
+      },
+    ],
+  },
+  designTokens: {
+    description: 'Use design tokens instead of hardcoded values',
+    principle: 'All spacing, colors, typography should use CSS custom properties (--*)',
+    examples: [
+      {
+        wrong: 'padding: 24px',
+        right: 'padding: var(--space-scale-3)',
+        why: 'Tokens ensure consistency and enable theming',
+      },
+      {
+        wrong: 'color: #DA0707',
+        right: 'color: var(--color-alert-400)',
+        why: 'Semantic tokens communicate intent and adapt to themes',
+      },
+      {
+        wrong: 'font-size: 16px',
+        right: 'font-size: var(--font-size-300)',
+        why: 'Typography scale ensures visual hierarchy',
+      },
+    ],
+  },
+  commonMistakes: {
+    description: 'Common mistakes developers make (and how to avoid them)',
+    mistakes: [
+      {
+        mistake: 'Recreating .card styling',
+        problem: 'Duplicating background, border, padding, shadows that .card already provides',
+        solution: 'Use <div class="card"> directly. It includes everything.',
+        prevention: 'Read component docs BEFORE writing CSS',
+      },
+      {
+        mistake: 'Adding wrapper divs for styling',
+        problem: '<div class="my-wrapper"><div class="card">...</div></div>',
+        solution: 'Style the card directly: <div class="card my-modifier">',
+        prevention: 'Compose classes instead of wrapping',
+      },
+      {
+        mistake: 'Hardcoding spacing values',
+        problem: 'margin: 16px; gap: 12px;',
+        solution: 'margin: var(--space-scale-2); gap: var(--space-scale-1-5);',
+        prevention: 'Query designsystem://tokens/space for available values',
+      },
+      {
+        mistake: 'Assuming classes are incomplete',
+        problem: 'Adding display: flex, border: 1px solid, etc. to classes that already have these',
+        solution: "Trust the design system. Check docs to see what's included.",
+        prevention: 'Default assumption: classes are complete, not partial',
+      },
+    ],
+  },
+  resources: {
+    description: 'MCP resources for discovering design system capabilities',
+    available: [
+      {
+        resource: 'designsystem://components',
+        purpose: 'List all available components',
+      },
+      {
+        resource: 'designsystem://components/{name}',
+        purpose: 'Get detailed component documentation',
+      },
+      {
+        resource: 'designsystem://tokens',
+        purpose: 'List all token categories',
+      },
+      {
+        resource: 'designsystem://tokens/{category}',
+        purpose: 'Get tokens for specific category (color, space, font, etc.)',
+      },
+      {
+        resource: 'designsystem://guides/setup',
+        purpose: 'Installation instructions',
+      },
+      {
+        resource: 'designsystem://guides/principles',
+        purpose: 'This guide - design system usage principles',
+      },
+    ],
+  },
+};
+
+export const getPrinciplesGuide = async () => {
+  return {
+    contents: [
+      {
+        uri: 'designsystem://guides/principles',
+        mimeType: 'application/json',
+        text: JSON.stringify(designSystemPrinciples, null, 2),
+      },
+    ],
+  };
+};

package/src/resources/guides/setup.test.ts

@@ -0,0 +1,72 @@
+import { getSetupGuide } from './setup.js';
+import { describe, expect, it } from 'vitest';
+
+describe('getSetupGuide resource', () => {
+  it('should return all guides when no type is specified', async () => {
+    const result = await getSetupGuide();
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.message).toBeDefined();
+    expect(data.options).toBeDefined();
+    expect(Array.isArray(data.options)).toBe(true);
+    expect(data.options).toHaveLength(2);
+    expect(data.options.some((opt: any) => opt.type === 'npm')).toBe(true);
+    expect(data.options.some((opt: any) => opt.type === 'cdn')).toBe(true);
+  });
+
+  it('should return npm guide with correct structure', async () => {
+    const result = await getSetupGuide('npm');
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.name).toBe('NPM Stylesheet Setup');
+    expect(data.description).toBeDefined();
+    expect(Array.isArray(data.steps)).toBe(true);
+    expect(data.steps.length).toBeGreaterThan(0);
+    expect(data.notes).toBeDefined();
+  });
+
+  it('should return cdn guide with correct structure', async () => {
+    const result = await getSetupGuide('cdn');
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.name).toBe('CDN Stylesheet Setup');
+    expect(data.description).toBeDefined();
+    expect(Array.isArray(data.steps)).toBe(true);
+    expect(data.steps.length).toBeGreaterThan(0);
+  });
+
+  it('should return error for invalid guide type', async () => {
+    const result = await getSetupGuide('invalid');
+    const data = JSON.parse(result.contents[0].text);
+
+    expect(data.error).toBe("Setup guide 'invalid' not found");
+    expect(data.available).toBeDefined();
+    expect(Array.isArray(data.available)).toBe(true);
+  });
+
+  it('should include code snippets in steps', async () => {
+    const result = await getSetupGuide('npm');
+    const data = JSON.parse(result.contents[0].text);
+    const firstStep = data.steps[0];
+
+    expect(firstStep).toHaveProperty('title');
+    expect(firstStep).toHaveProperty('code');
+    expect(firstStep).toHaveProperty('language');
+  });
+
+  it('should return contents with correct URI and mimeType for npm', async () => {
+    const result = await getSetupGuide('npm');
+
+    expect(result.contents).toBeDefined();
+    expect(result.contents).toHaveLength(1);
+    expect(result.contents[0].uri).toBe('designsystem://guides/setup/npm');
+    expect(result.contents[0].mimeType).toBe('application/json');
+  });
+
+  it('should handle case-insensitive guide type', async () => {
+    const lowerResult = await getSetupGuide('npm');
+    const upperResult = await getSetupGuide('NPM');
+
+    expect(JSON.parse(lowerResult.contents[0].text)).toEqual(JSON.parse(upperResult.contents[0].text));
+  });
+});