dss/docs/configuration.md

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

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

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

Remove it:

codex mcp remove dss

Gemini CLI

Add DSS as an MCP server:

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

Remove it:

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