# DSS - Design System Server

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

## Quick Start

```bash
# 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**

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

**Step 2: Run the setup script**

```bash
./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`:

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

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

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

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

**Check debug logs:**

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