Unify MCP across clients; remove legacy plugin server
Some checks failed
DSS Project Analysis / dss-context-update (push) Has been cancelled
Some checks failed
DSS Project Analysis / dss-context-update (push) Has been cancelled
This commit is contained in:
DSS
187
README.md
187
README.md
@@ -1,158 +1,95 @@
|
||||
# DSS - Design System Server
|
||||
# DSS (Design System Server)
|
||||
|
||||
Monolithic design system platform. Ingest tokens from Figma/CSS/SCSS/Tailwind, normalize to canonical format, generate outputs.
|
||||
DSS is a design-system toolkit that works both as:
|
||||
|
||||
## Quick Start
|
||||
- a **local developer tool** (run analysis and generation across many repos), and
|
||||
- a **headless server** (so UX/QA/Admin teams can use the web Admin UI and AI-assisted workflows without a local dev environment).
|
||||
|
||||
## What DSS does
|
||||
|
||||
- Ingest tokens from **Figma / CSS / SCSS / Tailwind**, normalize them, and generate outputs
|
||||
- Analyze codebases (components, styles, dependency graph, quick wins)
|
||||
- Automate Storybook setup (scan/generate/configure)
|
||||
- Expose a consistent set of `dss_*` tools via:
|
||||
- local MCP (Claude Code)
|
||||
- headless server MCP endpoints (`/api/mcp/*`)
|
||||
- Claude chat/tool-calling (`/api/claude/chat`)
|
||||
|
||||
## Docs
|
||||
|
||||
Human docs live in `docs/README.md`.
|
||||
|
||||
AI/agent-oriented docs live in `docs/ai.md` (entry points include `CLAUDE.md` and `admin-ui/AI-REFERENCE.md`).
|
||||
|
||||
## Quickstart (local + server)
|
||||
|
||||
### 1) Python setup
|
||||
|
||||
```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
|
||||
### 2) Run the headless API
|
||||
|
||||
# 3. Start services
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
PYTHONPATH="$PWD:$PWD/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220
|
||||
```
|
||||
|
||||
## Claude Code Plugin Integration
|
||||
If you want a single-port server that serves the built Admin UI too, see `docs/quickstart.md` (Option B) or run `./scripts/dss start` after building `admin-ui`.
|
||||
|
||||
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**
|
||||
### 3) Run the Admin UI (dev mode)
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cd admin-ui
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Step 2: Run the setup script**
|
||||
Admin UI: `http://localhost:6221`
|
||||
API: `http://localhost:6220`
|
||||
|
||||
### 4) Run analysis on any project
|
||||
|
||||
```bash
|
||||
./dss-cli.py analyze --project-path /absolute/path/to/your-project
|
||||
```
|
||||
|
||||
This writes `<project>/.dss/analysis_graph.json` (portable JSON output).
|
||||
|
||||
### 5) Claude Code MCP setup
|
||||
|
||||
```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:
|
||||
Enable MCP for Claude + Codex + Gemini (when installed):
|
||||
|
||||
```bash
|
||||
# Verify paths exist
|
||||
ls -la .venv/bin/python3
|
||||
ls -la dss-claude-plugin/servers/dss-mcp-server.py
|
||||
./scripts/enable-mcp-clients.sh
|
||||
```
|
||||
|
||||
**DSS server not connecting?**
|
||||
See `docs/configuration.md` for proxy mode (`--api-url`) and environment variables.
|
||||
|
||||
Add DSS to your global MCP config (`~/.claude/mcp.json`):
|
||||
## Storage (JSON-only)
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
By default DSS stores data under:
|
||||
- `DSS_HOME` (if set), else
|
||||
- `./.dss` (if present), else
|
||||
- `~/.dss`
|
||||
|
||||
**Test the MCP server manually:**
|
||||
See `docs/storage.md` for layout and guidance on what to commit.
|
||||
|
||||
```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
|
||||
## Repo layout
|
||||
|
||||
```
|
||||
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
|
||||
dss/ # Core Python library (analysis/ingest/storage/mcp)
|
||||
apps/api/ # FastAPI headless server
|
||||
admin-ui/ # Preact Admin UI (Vite dev server + build output)
|
||||
dss-claude-plugin/ # Claude Code plugin assets (commands/skills)
|
||||
scripts/ # Setup and operational scripts
|
||||
docs/ # Human documentation
|
||||
.knowledge/ # Internal knowledge base (AI-oriented)
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user