dss/CLAUDE.md

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:

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

# 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

# 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

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

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