PinoNoir/sds-components-mcp

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