# 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

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build
```

## Configuration

Create a `.env` file from the example:

```bash
cp .env.example .env
```

Configure your repository settings:

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

## Usage

### Running the Server

```bash
node dist/index.js
```

### Configuring with Claude Desktop

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

```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

```bash
# Watch mode for development
pnpm watch

# Build
pnpm build
```

## License

ISC