# Configuration

## Ports (defaults)

| Service | Default |
| --- | --- |
| API server | `6220` |
| Admin UI (Vite dev) | `6221` |
| MCP server (stdio process) | `6222` |
| Storybook (DSS repo) | `6226` |

Notes:
- `./scripts/dss` runs a single-port server (UI + API) on `DSS_PORT` (defaults to `6220`).
- Many target projects run their own Storybook on `6006`/`6007`; DSS service discovery checks those ports.

## Storage

- `DSS_HOME`
  - **Server mode**: set this explicitly (e.g. `/var/lib/dss` or a project volume).
  - **Local mode**: if a project has `./.dss/`, DSS will use it automatically; otherwise it falls back to `~/.dss`.

See `docs/storage.md` for the directory layout.

## AI / Integrations

- `FIGMA_TOKEN` — enables live Figma extraction/sync.
- `ANTHROPIC_API_KEY` — enables `/api/claude/chat` AI chat and tool calling.
- `DSS_MCP_ENCRYPTION_KEY` — optional Fernet key; encrypts integration configs at rest when set.

## Dev workflow (optional)

- `DSS_ENABLE_DEV_COMMANDS`
  - When set to `1`, DSS exposes dev-only MCP workflow tools that wrap local scripts (`dss_init`, `dss_reset`, `dss_services`).
  - `scripts/dss-mcp` and `./scripts/setup-mcp.sh` set this automatically for local development.

## Single-port launcher

- `DSS_PORT` — port for `./scripts/dss` (single-port server wrapper).

## MCP / Proxy mode

- `DSS_API_URL` (or `DSS_SERVER_URL`) — if set, `dss.mcp.server` forwards tool calls to a headless DSS server.
- `DSS_PROJECT_ID` — default project context for MCP calls (when proxying or when tools omit `path`).
- `DSS_USER_ID` — optional user context for integrations.

## MCP client setup (Claude, Codex, Gemini)

All three clients can run the same DSS MCP stdio server.

Quick option (configures Claude + Codex + Gemini when installed):

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

### Claude Code

- Generate Claude Code MCP config: `./scripts/setup-mcp.sh`
- Restart Claude Code, then run `/mcp` to verify `dss` is connected.

### Codex CLI

Add DSS as a global MCP server:

```bash
codex mcp add dss -- /absolute/path/to/dss/scripts/dss-mcp
```

Remove it:

```bash
codex mcp remove dss
```

### Gemini CLI

Add DSS as an MCP server:

```bash
gemini mcp add dss /absolute/path/to/dss/scripts/dss-mcp
```

Remove it:

```bash
gemini mcp remove dss
```

### Notes

- The Claude Code *plugin* (commands/skills under `dss-claude-plugin/`) is Claude-specific; Codex/Gemini won’t “load” it as a plugin, but they can still use the same MCP tools.
- `scripts/dss-mcp` sets required env vars (`PYTHONPATH`, `DSS_HOME`, etc.) and runs `python -m dss.mcp.server`.
- DSS also exposes the plugin guides/hooks to all MCP clients via:
  - `dss_list_guides` (use `include_meta=true` to see `globs` / `alwaysApply` / `arguments`)
  - `dss_get_guide`
  - `dss_match_skills`

## Scripts

- `./scripts/setup-mcp.sh`:
  - generates `.claude/mcp.json` to run the local MCP stdio server (`python -m dss.mcp.server`)
  - `--api-url <url>` — enable proxy mode for the local MCP server