# Quickstart

## Prerequisites

- Python 3.10+
- Node.js 18+ (for `admin-ui` and Storybook tooling)

## 1) Install Python deps

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

## 2) Local developer workflow (CLI only)

Run analysis for any project on disk:

```bash
./dss-cli.py analyze --project-path /absolute/path/to/your-project
```

This writes a portable JSON artifact:
- `<project>/.dss/analysis_graph.json`

Generate Storybook stories for a project:

```bash
./dss-cli.py setup-storybook --action generate --project-path /absolute/path/to/your-project
```

## 3) Local developer workflow (Claude Code via MCP)

Generate Claude Code MCP config:

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

Then restart Claude Code and run `/mcp` to confirm the `dss` server is connected.

### Enable MCP for all supported clients (recommended)

```bash
./scripts/enable-mcp-clients.sh
```

### Proxy mode (MCP process local, tools executed on a server)

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

Set `DSS_PROJECT_ID` in the MCP server environment when you want tools to default to a specific registered project.

## 4) Headless server (API for Admin UI + teams)

Choose one of the following:

### Option A: Dev mode (Vite Admin UI + API)

Start the API server:

```bash
source .venv/bin/activate
PYTHONPATH="$PWD:$PWD/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220
```

Start the Admin UI (dev mode with `/api` proxy to `:6220`):

```bash
cd admin-ui
npm install
npm run dev
```

Admin UI: `http://localhost:6221`  
API: `http://localhost:6220`

### Option B: Single-port server (serves built Admin UI)

Build the Admin UI once:

```bash
cd admin-ui
npm install
npm run build
cd ..
```

Start DSS (serves UI + API from one process):

```bash
./scripts/dss start
```

Dashboard: `http://localhost:6220`  
API: `http://localhost:6220/api`

## 5) Common environment variables

- `DSS_HOME` — where DSS stores JSON data (defaults to `./.dss` when present, else `~/.dss`)
- `FIGMA_TOKEN` — enables live Figma tooling
- `ANTHROPIC_API_KEY` — enables AI chat/tool calling on the headless server
- `DSS_API_URL` — enables MCP proxy mode (local MCP → headless server)

See `docs/configuration.md` for the full list and details.