159 lines
3.4 KiB
Markdown
159 lines
3.4 KiB
Markdown
# DSS - Design System Server
|
|
|
|
Monolithic design system platform. Ingest tokens from Figma/CSS/SCSS/Tailwind, normalize to canonical format, generate outputs.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Create Python virtual environment
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# 2. Generate MCP config for Claude Code
|
|
./scripts/setup-mcp.sh
|
|
|
|
# 3. Start services
|
|
PYTHONPATH="$PWD:$PWD/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220
|
|
```
|
|
|
|
## Claude Code Plugin Integration
|
|
|
|
DSS integrates with Claude Code as a **plugin** that provides MCP tools, slash commands, skills, and agents.
|
|
|
|
### Installation
|
|
|
|
**Step 1: Set up the Python environment**
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
**Step 2: Run the setup script**
|
|
|
|
```bash
|
|
./scripts/setup-mcp.sh
|
|
```
|
|
|
|
**Step 3: Add the DSS marketplace and install the plugin**
|
|
|
|
In Claude Code, run:
|
|
|
|
```
|
|
/plugin marketplace add /path/to/dss/dss-claude-plugin
|
|
```
|
|
|
|
Replace `/path/to/dss` with your actual DSS installation path.
|
|
|
|
Then install the plugin:
|
|
|
|
```
|
|
/plugin install dss-claude-plugin@dss
|
|
```
|
|
|
|
**Alternative: Manual configuration**
|
|
|
|
Add to your `~/.claude/settings.json`:
|
|
|
|
```json
|
|
{
|
|
"extraKnownMarketplaces": {
|
|
"dss": {
|
|
"source": {
|
|
"source": "directory",
|
|
"path": "/path/to/dss/dss-claude-plugin"
|
|
}
|
|
}
|
|
},
|
|
"enabledPlugins": {
|
|
"dss-claude-plugin@dss": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 4: Restart Claude Code** completely (quit and reopen)
|
|
|
|
### Verification
|
|
|
|
After restart, verify the plugin is loaded:
|
|
|
|
1. Run `/mcp` - DSS server should appear in the list
|
|
2. If DSS shows as disconnected, select it to enable
|
|
3. DSS tools will be available as `dss_*` functions
|
|
|
|
### Troubleshooting
|
|
|
|
**Plugin not found error in debug logs?**
|
|
|
|
The plugin must be discoverable. Ensure the path in `.claude/mcp.json` points to valid files:
|
|
|
|
```bash
|
|
# Verify paths exist
|
|
ls -la .venv/bin/python3
|
|
ls -la dss-claude-plugin/servers/dss-mcp-server.py
|
|
```
|
|
|
|
**DSS server not connecting?**
|
|
|
|
Add DSS to your global MCP config (`~/.claude/mcp.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"dss": {
|
|
"command": "/path/to/dss/.venv/bin/python3",
|
|
"args": ["/path/to/dss/dss-claude-plugin/servers/dss-mcp-server.py"],
|
|
"env": {
|
|
"PYTHONPATH": "/path/to/dss:/path/to/dss/dss-claude-plugin",
|
|
"DSS_HOME": "/path/to/dss/.dss",
|
|
"DSS_BASE_PATH": "/path/to/dss"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Test the MCP server manually:**
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
PYTHONPATH="$PWD:$PWD/dss-claude-plugin" \
|
|
python3 dss-claude-plugin/servers/dss-mcp-server.py
|
|
```
|
|
|
|
**Check debug logs:**
|
|
|
|
```bash
|
|
cat ~/.claude/debug/latest | grep -i "dss\|plugin"
|
|
```
|
|
|
|
### Available Tools
|
|
|
|
Once connected, DSS provides tools prefixed with `dss_`:
|
|
- `dss_figma_*` - Figma integration and token extraction
|
|
- `dss_token_*` - Design token management
|
|
- `dss_component_*` - Component generation
|
|
- `dss_project_*` - Project analysis
|
|
|
|
## Structure
|
|
|
|
```
|
|
tools/ # Python backend (API, ingestion, analysis)
|
|
admin-ui/ # Web dashboard
|
|
cli/ # TypeScript CLI
|
|
dss-claude-plugin/ # Claude Code integration (skills, commands, agents)
|
|
.knowledge/ # AI knowledge base (DSS_CORE.json)
|
|
.dss/ # Runtime data, schemas, database
|
|
```
|
|
|
|
## Core Concept
|
|
|
|
DSS structure is immutable. External systems adapt TO DSS via translation dictionaries.
|
|
|
|
See `.knowledge/DSS_CORE.json` for complete specification.
|
|
|
|
# Test Commit to Verify Hooks
|
|
\n- CI/CD Verification Run
|