# DSS - Design System Server

## FIRST: Enable DSS MCP Tools

**Before starting work, check if DSS tools are available.** If you don't see `dss_*` tools in your available MCP tools, run:

```bash
./scripts/setup-mcp.sh
```

Then tell the user: "I've configured the DSS MCP server. Please restart Claude Code to load the DSS tools, then continue this conversation."

The DSS MCP server provides 40+ design system tools for Figma sync, token management, component generation, and project analysis.

### Manual verification

Check if `.claude/mcp.json` exists and has valid paths:
- `command` should point to `.venv/bin/python3` (must exist)
- `args` should point to `dss-claude-plugin/servers/dss-mcp-server.py` (must exist)

## Project Structure

```
dss/
├── dss/                    # Core Python library
│   ├── mcp_server/         # MCP server implementation
│   ├── analyze/            # Code analysis tools
│   ├── ingest/             # Token ingestion
│   ├── figma/              # Figma integration
│   ├── storybook/          # Storybook generation
│   └── storage/            # JSON-based storage
├── apps/
│   ├── api/                # FastAPI server (port 6220)
│   └── cli/                # TypeScript CLI
├── admin-ui/               # Admin dashboard (port 6221)
├── dss-claude-plugin/      # Claude Code MCP plugin
│   └── servers/            # MCP server scripts
└── scripts/                # Setup & utility scripts
```

## Standard Ports

| Service    | Port |
|------------|------|
| API Server | 6220 |
| Admin UI   | 6221 |
| MCP Server | 6222 |
| Storybook  | 6226 |

## Development Setup

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

# Admin UI
cd admin-ui && npm install

# Generate MCP config
./scripts/setup-mcp.sh
```

## Starting Services

```bash
# API Server
source .venv/bin/activate
PYTHONPATH="/path/to/dss:/path/to/dss/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220

# Admin UI
cd admin-ui && npm run dev
```

## Key Files

- `dss/mcp_server/handler.py` - MCP tool execution handler
- `dss/storage/json_store.py` - JSON-based data storage
- `apps/api/server.py` - FastAPI server
- `.claude/mcp.json` - Local MCP configuration (generated)

## Troubleshooting MCP Connection Issues

### DSS MCP server fails to connect

If `/mcp` shows "Failed to reconnect to dss", check:

1. **Virtual environment exists**: The `.venv` directory must exist with Python installed
   ```bash
   # If missing, create it:
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   ```

2. **MCP config paths are valid**: Check `.claude/mcp.json` points to existing files:
   - `.venv/bin/python3` must exist
   - `dss-claude-plugin/servers/dss-mcp-server.py` must exist

3. **Restart Claude Code** after fixing any configuration issues

### Disabling unwanted MCP servers

MCP servers can be configured in multiple locations. Check all of these:

| Location | Used By |
|----------|---------|
| `~/.claude/mcp.json` | Claude Code (global) |
| `~/.config/claude/claude_desktop_config.json` | Claude Desktop app |
| `.claude/mcp.json` (project) | Claude Code (project-specific) |
| `../.mcp.json` | Parent directory inheritance |

To disable a server, remove its entry from the relevant config file and restart Claude Code.

### Common issue: Figma MCP errors

If you see repeated `MCP server "figma": No token data found` errors, the figma server is likely configured in `~/.config/claude/claude_desktop_config.json`. Remove the `"figma"` entry from that file.

## Notes

- DSS uses JSON-based storage, not SQL database
- The `dss/mcp_server/` directory was renamed from `dss/mcp/` to avoid shadowing the pip `mcp` package
- Integration configs (Figma, Jira, etc.) are stored encrypted when database is configured