125 lines
3.8 KiB
Markdown
125 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|