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:

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:

{
  "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):

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

{
  "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

claude "Check if there are any new components in Figma"

Sync Design Tokens

claude "Sync design tokens from Figma to DS"

Generate Specific Component

claude "Generate the Button component from Figma"

Full Synchronization

claude "Sync all new components from Figma to DS"

Validate Setup

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

{
  "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

# 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