CDS Components MCP Server

An MCP (Model Context Protocol) server for your component library and design system, enabling AI assistants to search, understand, and generate code using your components.

Features

• Component Search: Search by name, props, or functionality
• Component Details: Retrieve full documentation including props, examples, and dependencies
• Similar Components: Find alternatives based on requirements
• Prop Validation: Check if props match library conventions
• Code Generation: Generate boilerplate code with correct imports and props

Architecture

src/
├── types.ts              # TypeScript interfaces
├── config.ts             # Configuration management
├── repo-sync.ts          # Git repository synchronization
├── parsers/
│   ├── component.ts      # Parse React/TypeScript components
│   ├── story.ts          # Parse Storybook stories
│   ├── tokens.ts         # Parse design tokens
│   └── mdx.ts           # Parse MDX documentation
├── indexer.ts           # Orchestrates all parsers
├── search.ts            # Search and similarity algorithms
└── index.ts             # MCP server entry point

Installation

# Install dependencies
pnpm install

# Build the project
pnpm build

Configuration

Create a .env file from the example:

cp .env.example .env

Configure your repository settings:

REPO_OWNER=your-org
REPO_NAME=your-design-system-repo
REPO_BRANCH=main
PACKAGES_PATH=packages/components,packages/tokens

Usage

Running the Server

node dist/index.js

Configuring with Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cds-components": {
      "command": "node",
      "args": ["/path/to/cds-components-mcp/dist/index.js"],
      "env": {
        "REPO_OWNER": "your-org",
        "REPO_NAME": "your-design-system",
        "REPO_BRANCH": "main",
        "PACKAGES_PATH": "packages/components,packages/tokens"
      }
    }
  }
}

Available Tools

1. search_components

Search for components by name, props, or functionality.

Arguments:

• query (string, required): Search query
• filterBy (string, optional): Filter by "name", "props", "functionality", or "all"

Example:

Find all button components

2. get_component_details

Retrieve full documentation for a specific component.

Arguments:

• componentName (string, required): Name of the component

Example:

Get details for Button component

3. find_similar_components

Suggest alternative components based on requirements.

Arguments:

• requirements (string, required): Description of component requirements
• componentType (string, optional): Type or category filter

Example:

Find components for displaying user profiles

4. validate_component_usage

Check if props and patterns match library conventions.

Arguments:

• componentName (string, required): Component to validate
• props (object, required): Props object to validate

Example:

Validate Button usage with props {variant: "primary", size: "large"}

5. generate_component_code

Generate boilerplate code with correct imports and props.

Arguments:

• componentName (string, required): Component name
• props (array, optional): List of prop names
• includeStyles (boolean, optional): Include style templates

Example:

Generate code for Button component

How It Works

1. Repository Sync: Clones or pulls your design system repository
2. Indexing: Parses all components, stories, tokens, and docs using TypeScript AST
3. Search: Uses relevance scoring to find matching components
4. Tool Execution: Returns formatted documentation and code snippets

Supported File Types

• Components: .tsx, .jsx
• Stories: .stories.tsx, .stories.ts
• Tokens: .json, .ts, .js, .css, .scss
• Documentation: .mdx, .md

Development

# Watch mode for development
pnpm watch

# Build
pnpm build

License

ISC