# DSS - Design System Server

## Human Docs (start here)

- Overview + setup: `docs/README.md`
- Quickstart: `docs/quickstart.md`
- Architecture: `docs/architecture.md`

## 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 core `dss_*` tools for project analysis, token work, and Storybook automation.

### Manual verification

Check if `.claude/mcp.json` exists and has valid paths:
- `command` should point to `.venv/bin/python3` (must exist)
- `args` should be `["-m","dss.mcp.server"]`

## Project Structure

```
dss/
├── dss/                    # Core Python library
│   ├── mcp/                # Shared MCP tool layer + local MCP server
│   ├── 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 plugin assets (commands/skills)
└── 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/handler.py` - MCP tool registry + execution
- `dss/mcp/server.py` - Local MCP stdio server (`python -m dss.mcp.server`)
- `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
   - `args` should be `["-m","dss.mcp.server"]`

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

### Proxying tools to a headless DSS server

To run the MCP process locally but execute tools on a remote/headless server, set `DSS_API_URL` in the MCP env.

Example:
```bash
./scripts/setup-mcp.sh --api-url https://dss.example.com
```

### 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) |

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
- `dss.mcp` is an internal DSS module; it does not shadow the upstream `mcp` package
- Integration configs can be stored encrypted when `DSS_MCP_ENCRYPTION_KEY` is configured