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

Clone and install dependencies:

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

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

Go to Figma Account Settings
Scroll to "Personal Access Tokens"
Click "Create a new personal access token"
Give it a name (e.g., "DS Sync") and create
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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

ds-mcp-sync