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