DSS - Design System Server

Monolithic design system platform. Ingest tokens from Figma/CSS/SCSS/Tailwind, normalize to canonical format, generate outputs.

Quick Start

# 1. Create Python virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Generate MCP config for Claude Code
./scripts/setup-mcp.sh

# 3. Start services
PYTHONPATH="$PWD:$PWD/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220

Claude Code Plugin Integration

DSS integrates with Claude Code as a plugin that provides MCP tools, slash commands, skills, and agents.

Installation

Step 1: Set up the Python environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 2: Run the setup script

./scripts/setup-mcp.sh

Step 3: Add the DSS marketplace and install the plugin

In Claude Code, run:

/plugin marketplace add /path/to/dss/dss-claude-plugin

Replace /path/to/dss with your actual DSS installation path.

Then install the plugin:

/plugin install dss-claude-plugin@dss

Alternative: Manual configuration

Add to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "dss": {
      "source": {
        "source": "directory",
        "path": "/path/to/dss/dss-claude-plugin"
      }
    }
  },
  "enabledPlugins": {
    "dss-claude-plugin@dss": true
  }
}

Step 4: Restart Claude Code completely (quit and reopen)

Verification

After restart, verify the plugin is loaded:

1. Run /mcp - DSS server should appear in the list
2. If DSS shows as disconnected, select it to enable
3. DSS tools will be available as dss_* functions

Troubleshooting

Plugin not found error in debug logs?

The plugin must be discoverable. Ensure the path in .claude/mcp.json points to valid files:

# Verify paths exist
ls -la .venv/bin/python3
ls -la dss-claude-plugin/servers/dss-mcp-server.py

DSS server not connecting?

Add DSS to your global MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "dss": {
      "command": "/path/to/dss/.venv/bin/python3",
      "args": ["/path/to/dss/dss-claude-plugin/servers/dss-mcp-server.py"],
      "env": {
        "PYTHONPATH": "/path/to/dss:/path/to/dss/dss-claude-plugin",
        "DSS_HOME": "/path/to/dss/.dss",
        "DSS_BASE_PATH": "/path/to/dss"
      }
    }
  }
}

Test the MCP server manually:

source .venv/bin/activate
PYTHONPATH="$PWD:$PWD/dss-claude-plugin" \
  python3 dss-claude-plugin/servers/dss-mcp-server.py

Check debug logs:

cat ~/.claude/debug/latest | grep -i "dss\|plugin"

Available Tools

Once connected, DSS provides tools prefixed with dss_:

• dss_figma_* - Figma integration and token extraction
• dss_token_* - Design token management
• dss_component_* - Component generation
• dss_project_* - Project analysis

Structure

tools/           # Python backend (API, ingestion, analysis)
admin-ui/        # Web dashboard
cli/             # TypeScript CLI
dss-claude-plugin/  # Claude Code integration (skills, commands, agents)
.knowledge/      # AI knowledge base (DSS_CORE.json)
.dss/            # Runtime data, schemas, database

Core Concept

DSS structure is immutable. External systems adapt TO DSS via translation dictionaries.

See .knowledge/DSS_CORE.json for complete specification.

Test Commit to Verify Hooks

\n- CI/CD Verification Run