# DS MCP Sync Server

An MCP (Model Context Protocol) server that enables seamless synchronization between your Figma design system and your Design System codebase.

## Features

- **🎨 Design Token Sync** - Extract colors, typography, spacing, and shadows from Figma styles
- **🧩 Component Generation** - Automatically generate React components from Figma components
- **📚 Storybook Integration** - Auto-generate Storybook stories with all component variants
- **⚛️ Atomic Design** - Maps Figma components to atoms, molecules, and organisms
- **🔄 Incremental Updates** - Only sync what has changed
- **🔍 Smart Analysis** - Learns from existing component patterns

## Installation

1. **Clone and install dependencies:**

```bash
git clone <repository-url>
cd ds-mcp-sync
npm install
npm run build
```

2. **Configure your credentials:**

Create a `config/mcp-config.json` file or set environment variables:

```json
{
  "figma": {
    "fileId": "your-figma-file-id",
    "accessToken": "your-figma-personal-access-token",
    "componentPrefix": "DS"
  },
  "mds": {
    "rootPath": "../design-system",
    "componentPath": "component-lib/components",
    "tokenPath": "component-lib/tokens",
    "storybookPath": "component-lib/.storybook"
  }
}
```

**Environment Variables (alternative):**
```bash
export FIGMA_ACCESS_TOKEN="your-token-here"
export FIGMA_FILE_ID="your-file-id"
export DS_ROOT_PATH="../design-system"
```

## Getting Figma Credentials

### 1. Get Figma Personal Access Token

1. Go to [Figma Account Settings](https://www.figma.com/settings)
2. Scroll to "Personal Access Tokens"
3. Click "Create a new personal access token"
4. Give it a name (e.g., "DS Sync") and create
5. Copy the token and add it to your config

### 2. Get Figma File ID

From your Figma design system URL:
```
https://www.figma.com/file/ABC123DEF456/Design-System
                        ^^^^^^^^^^^^
                        This is your file ID
```

## MCP Integration with Claude Code

Add this server to your Claude Code MCP configuration:

**macOS/Linux:** `~/.claude_mcp.json`
**Windows:** `%APPDATA%\Claude\claude_mcp.json`

```json
{
  "mcpServers": {
    "ds-mcp-sync": {
      "command": "node",
      "args": ["/path/to/ds-mcp-sync/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token",
        "FIGMA_FILE_ID": "your-file-id"
      }
    }
  }
}
```

## Usage with Claude Code

Once configured, you can use these commands in Claude Code:

### Check for Updates
```bash
claude "Check if there are any new components in Figma"
```

### Sync Design Tokens
```bash
claude "Sync design tokens from Figma to DS"
```

### Generate Specific Component
```bash
claude "Generate the Button component from Figma"
```

### Full Synchronization
```bash
claude "Sync all new components from Figma to DS"
```

### Validate Setup
```bash
claude "Validate the MCP server setup"
```

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `check_figma_updates` | Compare Figma with current DS and report differences |
| `sync_tokens` | Extract and update design tokens from Figma styles |
| `generate_component` | Create a specific component with TypeScript and stories |
| `sync_all` | Perform complete synchronization (with optional dry-run) |
| `validate_setup` | Test Figma connection and validate configuration |

## How It Works

### 1. Design Token Extraction
- Fetches color, typography, and effect styles from Figma
- Converts to DS token format (`colors.primary.500`)
- Updates `component-lib/tokens/tokens.ts`

### 2. Component Analysis
- Scans Figma components and their variants
- Determines atomic level (atoms/molecules/organisms) based on name and structure
- Extracts component properties and maps to TypeScript props

### 3. Code Generation
- Generates React components following DS patterns
- Creates TypeScript interfaces with proper typing
- Adds theme provider integration
- Generates comprehensive Storybook stories

### 4. File Organization
```
component-lib/
├── components/
│   ├── atoms/
│   │   └── Button/
│   │       ├── Button.tsx
│   │       ├── Button.stories.tsx
│   │       └── index.ts
│   ├── molecules/
│   └── organisms/
└── tokens/
    └── tokens.ts
```

## Component Mapping Rules

| Figma Component | Atomic Level | Reason |
|----------------|--------------|--------|
| Button, Input, Icon | Atoms | Basic UI elements |
| Card, Modal, Dropdown | Molecules | Groups of atoms |
| Header, Table, Navigation | Organisms | Complex layouts |

## Configuration Options

```json
{
  "figma": {
    "fileId": "string",           // Required: Figma file ID
    "accessToken": "string",      // Required: Personal access token
    "componentPrefix": "string"   // Optional: Filter components by prefix
  },
  "mds": {
    "rootPath": "string",         // Path to MDS root directory
    "componentPath": "string",    // Relative path to components
    "tokenPath": "string",        // Relative path to tokens
    "storybookPath": "string"     // Relative path to Storybook config
  },
  "dryRun": false,               // Run without making file changes
  "verbose": true                // Enable detailed logging
}
```

## Troubleshooting

### Common Issues

**"Figma API connection failed"**
- Verify your personal access token
- Check that the token has access to the file
- Ensure the file ID is correct

**"DS paths not accessible"**
- Verify the `rootPath` points to your DS directory
- Check that component directories exist
- Ensure write permissions

**"Component generation failed"**
- Check that the Figma component has proper naming
- Verify component properties are set up correctly
- Look for TypeScript compilation errors

### Debug Mode

Set `verbose: true` in config or `VERBOSE=true` environment variable for detailed logging.

## Development

```bash
# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Run linting
npm run lint

# Type checking
npm run typecheck
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

---

**Need help?** Check the troubleshooting section or create an issue on GitHub.# ds-mcp-sync