auto-backup: 2025-12-11 20:35:05 (68 files: +19 ~23 -25)

Generated by DSS Git Backup Hook
2025-12-11 17:35:05 -03:00
parent 09b234a07f
commit 1ff198c177
68 changed files with 3229 additions and 7102 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,124 @@
+# 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