dss/dss-claude-plugin/README.md

DSS Claude Plugin

Design System Server (DSS) integration for Claude Code - A comprehensive plugin for analyzing, extracting, and generating design system tokens and components.

Overview

The DSS Claude Plugin brings the power of DSS directly into Claude Code, enabling:

• Project Analysis: Scan codebases for design patterns and tokenization opportunities
• Token Extraction: Extract design tokens from CSS, SCSS, Tailwind, and JSON
• Theme Generation: Generate theme files using style-dictionary
• Component Auditing: Audit components for design system adoption
• Storybook Integration: Set up and configure Storybook
• Figma Sync: Import tokens directly from Figma files
• Quick Wins: Find low-effort, high-impact improvements

Installation

Local Development Setup

For local machines with GUI (desktop/laptop):

# 1. Clone the repository
git clone https://github.com/overbits/dss.git
cd dss

# 2. Run the setup script
./setup.sh

# 3. Install the plugin in Claude Code
claude /plugin install ./dss-claude-plugin

Or manually:

# 1. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt
playwright install chromium

# 3. Install the plugin
claude /plugin install ./dss-claude-plugin

Remote/Headless Server Setup

For remote servers, VPS, Docker, or CI/CD environments:

# 1. Clone the repository
git clone https://github.com/overbits/dss.git
cd dss

# 2. Install dependencies (headless mode)
pip install -r requirements.txt
playwright install chromium --with-deps  # Installs system dependencies

# 3. Install the plugin in Claude Code
claude /plugin install ./dss-claude-plugin

Docker Setup:

FROM python:3.10-slim

# Install system dependencies for Playwright
RUN apt-get update && apt-get install -y \
    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
    libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

WORKDIR /app
COPY . .

RUN pip install -r requirements.txt
RUN playwright install chromium

# DSS MCP server runs on stdio
CMD ["python3", "dss-claude-plugin/servers/dss-mcp-server.py"]

Claude Code Configuration

After installing the plugin, Claude Code automatically configures the MCP server. The configuration is stored in .mcp.json:

{
  "mcpServers": {
    "dss": {
      "command": "python3",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/dss-mcp-server.py"],
      "env": {
        "PYTHONPATH": "/path/to/dss/dss-mvp1",
        "DSS_HOME": "~/.dss"
      }
    }
  }
}

Connecting Local Claude Code to Remote Server

You can run Claude Code locally while connecting to a DSS MCP server running on a remote machine.

Option 1: SSH Tunnel (Recommended)

Create an SSH tunnel to forward the remote MCP server:

# On local machine - tunnel remote MCP server
ssh -L 9222:localhost:9222 -L 3456:localhost:3456 user@remote-server

This forwards:

• Port 9222: Chrome DevTools Protocol
• Port 3456: Your web application

Then use devtools_connect(port=9222) as if it were local.

Option 2: Remote MCP via SSH

Configure Claude Code to run the MCP server over SSH. Add to your local ~/.claude/settings.json or project .mcp.json:

{
  "mcpServers": {
    "dss-remote": {
      "command": "ssh",
      "args": [
        "user@remote-server",
        "python3",
        "/home/user/dss/dss-claude-plugin/servers/dss-mcp-server.py"
      ],
      "env": {
        "PYTHONPATH": "/home/user/dss/dss-mvp1"
      },
      "description": "Remote DSS MCP server via SSH"
    }
  }
}

Option 3: HTTP Proxy (Advanced)

For shared team access, run the MCP server behind an HTTP proxy:

# On remote server - start MCP with HTTP transport
# (Requires mcp-proxy or similar)
python3 -m mcp.server.http --port 8080 dss-claude-plugin/servers/dss-mcp-server.py

Then configure Claude Code to connect via HTTP:

{
  "mcpServers": {
    "dss-remote": {
      "url": "http://remote-server:8080",
      "transport": "http"
    }
  }
}

Option 4: VS Code Remote / SSH Workspace

If using Claude Code in VS Code with Remote SSH extension:

1. Connect VS Code to remote server via Remote SSH
2. Install Claude Code extension in remote context
3. DSS plugin runs natively on remote - no tunneling needed

Verify Installation

# Check DSS tools are available
claude --list-tools | grep dss

# Check DevTools are available (requires Playwright)
claude --list-tools | grep devtools

# Test the MCP server directly
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 dss-claude-plugin/servers/dss-mcp-server.py

Requirements

• Claude Code >= 1.0.0
• Python 3.10+
• Node.js 18+ (for style-dictionary)
• DSS MVP1 installed at /path/to/dss/dss-mvp1

Python Dependencies

pip install mcp pydantic pydantic-settings playwright aiohttp
playwright install chromium

Or run the full setup:

./setup.sh

Optional: Figma Integration

Set your Figma personal access token:

export FIGMA_TOKEN=your-figma-token

Commands

Command	Description
/dss-analyze [path]	Analyze project for design system patterns
/dss-extract [path] [sources]	Extract design tokens
/dss-generate <format> [name]	Generate theme files
/dss-audit [path]	Audit components for DS adoption
/dss-storybook <action> [path]	Storybook setup and configuration
/dss-figma <file_key>	Sync tokens from Figma
/dss-quick-wins [path]	Find quick win opportunities

Skills

The plugin includes 7 procedural skills:

1. design-system-analysis - Comprehensive codebase analysis
2. token-extraction - Multi-source token extraction
3. theme-generation - Style-dictionary theme generation
4. component-audit - React component auditing
5. storybook-integration - Storybook setup and stories
6. figma-sync - Figma API integration
7. quick-wins - Quick win identification

Agents

Two specialized agents for complex tasks:

DSS Architect

Planning and designing design system implementations.

"Help me plan a design system for our React application"

DSS Migrator

Migrating existing codebases to design systems.

"Help me migrate our button components to use design tokens"

MCP Tools

The plugin exposes DSS tools and Chrome DevTools tools:

DSS Tools

Tool	Description
dss_analyze_project	Full project analysis
dss_extract_tokens	Extract tokens from sources
dss_generate_theme	Generate theme files
dss_list_themes	List available themes
dss_get_status	Get DSS system status
dss_audit_components	Component audit
dss_setup_storybook	Storybook configuration
dss_sync_figma	Figma token sync
dss_find_quick_wins	Quick win analysis
dss_transform_tokens	Token format transformation

Chrome DevTools Tools

Tool	Description
devtools_launch	Launch headless Chromium (for remote/headless servers)
devtools_connect	Connect to running Chrome with CDP (port 9222)
devtools_disconnect	Disconnect and clean up resources
devtools_list_pages	List all browser tabs/pages
devtools_select_page	Select active page for operations
devtools_goto	Navigate to a URL
devtools_console_logs	Get captured console messages
devtools_network_requests	Get captured network activity
devtools_evaluate	Execute JavaScript in page context
devtools_query_dom	Query DOM elements with CSS selector
devtools_screenshot	Capture page/element screenshots (base64 PNG)
devtools_performance	Get Core Web Vitals and performance metrics

Hooks

The plugin includes hooks for automation:

• PreToolUse: Validates Figma token before sync
• PostToolUse: Logs completion of major operations

Usage Examples

Analyze a Project

/dss-analyze /path/to/project

Returns comprehensive analysis including:

• File counts and types
• Style patterns discovered
• Component analysis
• Recommendations

Extract and Generate Tokens

/dss-extract /path/to/styles css,scss
/dss-generate css my-theme

Audit Components

/dss-audit /path/to/components

Identifies:

• Hardcoded values
• Consolidation opportunities
• Refactoring suggestions

Sync from Figma

/dss-figma abc123xyz456

Extracts:

• Colors from fill styles
• Typography from text styles
• Spacing from auto-layout
• Effects and shadows

Chrome DevTools Integration

The plugin includes Chrome DevTools Protocol (CDP) integration for browser debugging, console capture, network monitoring, and performance analysis.

Remote/Headless Server Setup

For remote or headless servers (no GUI), use the devtools_launch tool to spawn a headless Chromium instance:

# 1. Launch headless browser and navigate to your app
devtools_launch(url="http://localhost:3456")

# 2. Get console logs
devtools_console_logs()

# 3. Navigate to another page
devtools_goto(url="http://localhost:3456/dashboard")

# 4. Capture screenshot
devtools_screenshot(full_page=True)

# 5. Get performance metrics
devtools_performance()

# 6. Execute JavaScript
devtools_evaluate(expression="document.title")

# 7. Query DOM
devtools_query_dom(selector=".error-message")

# 8. Clean up
devtools_disconnect()

Local Desktop Setup

For local development with Chrome GUI, launch Chrome with remote debugging enabled:

# Linux
google-chrome --remote-debugging-port=9222

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Then connect using the devtools_connect tool:

# 1. Connect to running Chrome
devtools_connect(port=9222)

# 2. List available tabs
devtools_list_pages()

# 3. Select a tab
devtools_select_page(page_id="...")

# 4. Capture console logs, network, etc.
devtools_console_logs()
devtools_network_requests()

# 5. Disconnect when done
devtools_disconnect()

DevTools Configuration

The MCP server includes configurable limits:

DEVTOOLS_CONSOLE_MAX_ENTRIES = 1000    # Max console messages stored
DEVTOOLS_NETWORK_MAX_ENTRIES = 500     # Max network requests stored
DEVTOOLS_CONNECTION_TIMEOUT_MS = 30000 # Connection timeout (30s)

Common Use Cases

Debug Console Errors:

devtools_launch(url="http://localhost:3000")
devtools_console_logs(level="error")

Monitor Network Requests:

devtools_launch(url="http://localhost:3000")
devtools_network_requests(filter_url="api/")

Performance Analysis:

devtools_launch(url="http://localhost:3000")
devtools_performance()
# Returns: FCP, LCP, TTFB, DOM metrics

Visual Regression Testing:

devtools_launch(url="http://localhost:3000")
devtools_screenshot(full_page=True)
# Returns: base64 PNG image

Architecture

dss-claude-plugin/
├── .claude-plugin/
│   └── plugin.json           # Plugin metadata
├── commands/                  # 7 slash commands
├── skills/                    # 7 procedural skills
├── agents/                    # 2 specialized agents
├── hooks/
│   └── hooks.json            # Event hooks
├── servers/
│   └── dss-mcp-server.py     # Python MCP server
├── .mcp.json                 # MCP configuration
└── README.md

Configuration

Environment Variables

Variable	Description
FIGMA_TOKEN	Figma personal access token
DSS_HOME	DSS home directory (default: ~/.dss)
PYTHONPATH	Path to DSS MVP1 modules

Timeouts

The MCP server includes configurable timeouts:

TIMEOUT_CONFIG = {
    "analyze": 60,           # Large project scanning
    "extract": 30,           # Token extraction
    "generate": 30,          # Theme generation
    "figma_api": 15,         # Figma API calls
    "storybook": 60,         # Storybook operations
    "devtools_connect": 20,  # DevTools CDP connection
    "devtools_default": 10,  # DevTools operations
}

Development

Running the MCP Server Directly

cd /home/overbits/dss/dss-claude-plugin
python3 servers/dss-mcp-server.py

Testing

# Test MCP server
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 servers/dss-mcp-server.py

Troubleshooting

DSS Modules Not Found

Ensure PYTHONPATH is set correctly:

export PYTHONPATH=/home/overbits/dss/dss-mvp1

Figma Sync Fails

1. Check FIGMA_TOKEN is set
2. Verify file key is correct
3. Check API rate limits

Slow Analysis

For large projects, analysis may take longer. The timeout is set to 60 seconds by default.

DevTools Launch Fails

1. Ensure Playwright is installed: pip install playwright
2. Install Chromium browser: playwright install chromium
3. On Docker/remote: ensure --no-sandbox flag is used (handled automatically)

DevTools Connect Fails

1. Ensure Chrome is running with: --remote-debugging-port=9222
2. Check the port is not blocked by firewall
3. Verify connection: curl http://localhost:9222/json

DevTools Playwright Not Available

The server gracefully degrades if Playwright isn't installed. DevTools tools will not appear in the tool list. Install with:

pip install playwright aiohttp
playwright install chromium

License

MIT License - See LICENSE file for details.

Author

overbits - https://overbits.luz.uy

Links

• DSS Homepage
• Model Context Protocol
• Claude Code
• Style Dictionary