Triptease Design System MCP Server

Model Context Protocol (MCP) server that provides programmatic access to Triptease design system documentation, componentManifest, and tokens.

What is this?

This MCP server enables Claude Code and other MCP-compatible tools to query design system information directly. Instead of manually looking up component documentation or design tokens, you can ask Claude to retrieve this information for you.

Installation

Prerequisites

• Node.js 18+
• Yarn

Building

From this directory:

yarn install
yarn build

This will compile the TypeScript source to JavaScript in the dist/ directory.

Configuration

Claude Code CLI (Recommended)

Use the Claude Code CLI to install the MCP server globally for all your projects:

claude mcp add --scope user --transport stdio triptease-design-system -- npx -y @triptease/design-system-mcp

Verify installation:

# List all MCP servers
claude mcp list

# Should show: triptease-design-system: ... - ✓ Connected

Restart Claude Code after installation. The design system tools will now be available in all your sessions.

Management commands:

# Remove the server
claude mcp remove triptease-design-system

# Get server details
claude mcp get triptease-design-system

# Check status within Claude Code
/mcp

Claude Desktop (GUI Application)

For the Claude Desktop application, manually edit the configuration file:

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add to the configuration file:

{
  "mcpServers": {
    "triptease-design-system": {
      "command": "node",
      "args": ["/absolute/path/to/component-library/design-system-mcp/dist/index.js"]
    }
  }
}

macOS example:

{
  "mcpServers": {
    "triptease-design-system": {
      "command": "node",
      "args": ["/Users/yourname/repos/component-library/design-system-mcp/dist/index.js"]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "triptease-design-system": {
      "command": "node",
      "args": ["C:\\Users\\yourname\\repos\\component-library\\design-system-mcp\\dist\\index.js"]
    }
  }
}

[!IMPORTANT] Use absolute paths, not relative paths. After saving the configuration, restart Claude Desktop completely.

Usage with NVM

If Claude Desktop has issues starting the MCP servers due to resolving the wrong nvm-managed node version, replace the command with the absolute path to the nvm-managed node version, e.g. in MacOS:

{
  "mcpServers": {
    "triptease-design-system": {
      "command": "/Users/yourname/.nvm/versions/node/v24.11.1/bin/node",
      "args": ["/Users/yourname/repos/component-library/design-system-mcp/dist/index.js"]
    }
  }
}

Per-Project Installation

To enable the server for a specific project only (works with both Claude Code and Claude Desktop):

Claude Code CLI:

# Install for current project only (default scope)
claude mcp add --transport stdio triptease-design-system -- \
  node /absolute/path/to/component-library/design-system-mcp/dist/index.js

# Or install for team sharing (committed to version control)
claude mcp add --scope project --transport stdio triptease-design-system -- \
  node /absolute/path/to/component-library/design-system-mcp/dist/index.js

Manual configuration:

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "triptease-design-system": {
      "command": "node",
      "args": ["<path-to-component-library>/design-system-mcp/dist/index.js"]
    }
  }
}

Replace <path-to-component-library> with the relative or absolute path to the component-library repository.

Available Resources

The MCP server provides access to design system documentation through resources:

1. Components

List all components: designsystem://components

Returns a list of all available design system components with name, description, and element type.

Get component details: designsystem://components/{name}

Returns complete documentation for a specific component including usage guidance, attributes (with variant selection guidance!), states, examples, and design tokens.

Example usage with Claude:

"Show me all available components" "Get me the documentation for the button component"

2. Design Tokens

List token categories: designsystem://tokens

Returns available token categories with counts.

Get tokens by category: designsystem://tokens/{category}

Returns design tokens for a specific category (colors, spacing, typography, shadows, etc.).

Example usage with Claude:

"Show me all the color tokens in the design system" "What spacing tokens are available?"

3. Setup Guides

All guides: designsystem://guides/setup

NPM installation: designsystem://guides/setup/npm

CDN installation: designsystem://guides/setup/cdn

Returns installation instructions with current recommended versions.

Usage Examples

Once configured, you can interact with the MCP server naturally through Claude Code:

Getting component documentation:

You: "How do I create a destructive button?"
Claude: [Reads designsystem://components/button]
       "Here's how to create a destructive button:
       <button data-theme="destructive-primary">Delete</button>

       Use destructive-primary for irreversible actions like deletions."

Exploring design tokens:

You: "What color should I use for error states?"
Claude: [Reads designsystem://tokens/colors]
       "For error states, use the alert color tokens:
       - --color-alert-400 for primary error color
       - --color-alert-100 for error backgrounds"

Finding components:

You: "What components are available for forms?"
Claude: [Reads designsystem://components, filters results]
       "Here are the form-related components:
       - Text Input (input)
       - Number Input (input[type='number'])
       - Textarea (textarea)
       - Select (select)
       - Checkbox (input[type='checkbox'])
       - Radio (input[type='radio'])

       Would you like details on any of these?"

Architecture

• Transport: StdioServerTransport (local, on-demand)
• Token Source: ../../packages/stylesheet/dist/web/tokens.json (relative to compiled dist directory)
• Components: Individual manifest entries in src/manifests/components/entries/, aggregated by src/manifests/components/index.ts
• Response Format: JSON for all tool responses

Maintenance

Adding New Components

Each component has its own manifest entry file. Follow these steps:

1. Create an entry file at src/manifests/components/entries/<componentName>.ts:

import { ComponentManifest } from '@/manifests/components/types.js';

export default {
  componentName: {
    name: 'Component Name',
    description: 'Brief description',
    element: 'html-element',
    usageGuidance: {
      whenToUse: ['...'],
      bestPractices: ['...'],
      accessibility: ['...'],
      avoid: ['...'],
    },
    attributes: {
      /* optional */
    },
    dataAttributes: {
      /* optional */
    },
    classes: {
      /* optional */
    },
    events: {
      /* optional */
    },
    states: [
      /* optional */
    ],
    examples: [
      {
        title: 'Example name',
        code: `<html example code>`,
      },
    ],
  },
} satisfies ComponentManifest;

For web components distributed via CDN, also add installation options with versioned URLs:

import packageJson from '@/../package.json' with { type: 'json' };
import { buildCDNUrl, buildMajorVersion } from '@/utils/buildCDNUrls.js';

const version = packageJson.componentVersions['@triptease/tt-my-component'];

// Then in the manifest entry:
installationOptions: {
  npm: [{ name: '@triptease/tt-my-component', includesTypes: true, optional: false }],
  cdn: [{
    name: 'tt-my-component',
    includesTypes: false,
    optional: false,
    moduleFormat: 'esm',
    pinnedVersionUrl: buildCDNUrl('tt-my-component', version),
    pinnedMajorVersionUrl: buildCDNUrl('tt-my-component', buildMajorVersion(version)),
    latestVersionUrl: buildCDNUrl('tt-my-component', 'latest'),
    guidance: 'Prefer pinned major version URL to avoid unexpected breaking changes.',
  }],
},

2. Register the entry in src/manifests/components/index.ts:

import myComponent from '@/manifests/components/entries/myComponent.js';

export const componentManifest: ComponentManifest = {
  // ...existing entries
  ...myComponent,
};

3. Add the version (web components only) to componentVersions in package.json:

"componentVersions": {
  "@triptease/tt-my-component": "1.0.0"
}

4. Build and verify:

yarn build

Troubleshooting

"Failed to load tokens.json" error:

• Ensure tokens.json exists at packages/stylesheet/dist/web/tokens.json
• Try rebuilding the stylesheet package: cd packages/stylesheet && yarn build

Server not appearing in Claude Code:

For Claude Code CLI:

• Run claude mcp list to verify the server is installed
• Check that the server shows ✓ Connected status
• If not installed, run the installation command again
• Restart Claude Code after installation
• Check logs: ~/.claude/debug/*.txt for error messages

For Claude Desktop:

• Verify the configuration file exists at the correct location
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Check that the path to dist/index.js is correct and absolute
• Verify JSON syntax is valid (no trailing commas, proper quotes)
• Restart Claude Desktop completely (not just reload)
• Check logs: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows)

For project-level installation:

• Verify .mcp.json exists in your project root
• Check that the path to dist/index.js is correct
• Restart after configuration changes

Tool calls failing:

• Ensure the build completed successfully (yarn build)
• Check Node.js version is 18+
• Verify no TypeScript compilation errors

Distribution

This MCP server is distributed through two channels:

1. npm (@triptease/design-system-mcp): Published via Changesets on release. Users with npx -y get the latest version automatically on each Claude session.
2. Claude Code plugin (triptease-design-system in the triptease-plugins marketplace): The plugin bundles an .mcp.json that points to this npm package. The plugin provides design guidance (SKILL.md) while this server provides structured component data.

Changes to component manifests, tokens, or setup guides in this repo propagate to users automatically after an npm release — no plugin update is needed. The plugin only needs updating when its own files change (SKILL.md, .mcp.json).

Related

• Design System Plugin: triptease/claude-plugins — triptease-design-system marketplace plugin
• Design System Documentation: For design system patterns and usage, see the main component library README
• MCP Protocol: https://modelcontextprotocol.io/