dss/CLAUDE.md

DSS - Design System Server

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 40+ design system tools for Figma sync, token management, component generation, and project analysis.

Manual verification

Check if .claude/mcp.json exists and has valid paths:

• command should point to .venv/bin/python3 (must exist)
• args should point to dss-claude-plugin/servers/dss-mcp-server.py (must exist)

Project Structure

dss/
├── dss/                    # Core Python library
│   ├── mcp_server/         # MCP server implementation
│   ├── 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 MCP plugin
│   └── servers/            # MCP server scripts
└── 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_server/handler.py - MCP tool execution handler
• 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
   • dss-claude-plugin/servers/dss-mcp-server.py must exist

3. Restart Claude Code after fixing any configuration issues

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)
../.mcp.json	Parent directory inheritance

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
• The dss/mcp_server/ directory was renamed from dss/mcp/ to avoid shadowing the pip mcp package
• Integration configs (Figma, Jira, etc.) are stored encrypted when database is configured