Major cleanup: Remove redundant code, consolidate knowledge base
- Delete redundant directories: demo/, server/, orchestrator/, team-portal/, servers/ - Remove all human-readable documentation (docs/, .dss/*.md, admin-ui/*.md) - Consolidate 4 knowledge JSON files into single DSS_CORE.json - Clear browser logs (7.5MB), backups, temp files - Remove obsolete configs (.cursorrules, .dss-boundaries.yaml, .ds-swarm/) - Reduce project from 20MB to ~8MB Kept: tools/, admin-ui/, cli/, dss-claude-plugin/, .dss/schema/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,224 +0,0 @@
|
||||
# Context Compiler - Production Deployment
|
||||
|
||||
**Date**: 2025-12-07
|
||||
**Status**: ✅ DEPLOYED TO PRODUCTION
|
||||
**Version**: 1.0.0
|
||||
|
||||
## Deployment Summary
|
||||
|
||||
The Context Compiler has been successfully integrated into the DSS MCP Server and is ready for production use.
|
||||
|
||||
### What Was Deployed
|
||||
|
||||
**5 New MCP Tools** added to dss-mcp-server.py:
|
||||
|
||||
1. **dss_get_resolved_context** - Get fully resolved design system context (3-layer cascade)
|
||||
2. **dss_resolve_token** - Resolve specific token through cascade (dot-notation)
|
||||
3. **dss_validate_manifest** - Validate ds.config.json against schema
|
||||
4. **dss_list_skins** - List all available skins in registry
|
||||
5. **dss_get_compiler_status** - Get compiler health and configuration
|
||||
|
||||
### Integration Points
|
||||
|
||||
#### 1. Imports (lines 69-81)
|
||||
```python
|
||||
# Context Compiler imports
|
||||
try:
|
||||
from core import (
|
||||
get_active_context,
|
||||
resolve_token,
|
||||
validate_manifest,
|
||||
list_skins,
|
||||
get_compiler_status
|
||||
)
|
||||
CONTEXT_COMPILER_AVAILABLE = True
|
||||
except ImportError as e:
|
||||
CONTEXT_COMPILER_AVAILABLE = False
|
||||
CONTEXT_COMPILER_IMPORT_ERROR = str(e)
|
||||
```
|
||||
|
||||
#### 2. Tool Definitions (lines 600-681)
|
||||
- Added 5 tool definitions with full input schemas
|
||||
- Tools support debug mode, force_refresh, and provenance tracking
|
||||
- Integrated into tool list: `dss_tools + devtools_tools + browser_tools + context_compiler_tools`
|
||||
|
||||
#### 3. Tool Handlers (lines 823-894)
|
||||
- Added 5 tool handlers in call_tool() function
|
||||
- Error handling for unavailable Context Compiler
|
||||
- JSON parsing and result wrapping
|
||||
|
||||
### Test Results
|
||||
|
||||
✅ **All Tests Passing**
|
||||
```
|
||||
Context Compiler: 27/27 tests passed
|
||||
- Basic compilation (3-layer cascade)
|
||||
- Debug provenance tracking
|
||||
- Token resolution
|
||||
- Skin listing
|
||||
- Safe Boot Protocol
|
||||
- Path traversal prevention (security)
|
||||
- Compiler status
|
||||
```
|
||||
|
||||
✅ **Integration Tests**
|
||||
```
|
||||
✓ Syntax check passed (Python compilation)
|
||||
✓ Context Compiler imports successful
|
||||
✓ list_skins() returned 3 skins: ['base', 'workbench', 'classic']
|
||||
✓ get_compiler_status() returned status: active
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
**3-Layer Cascade**:
|
||||
```
|
||||
Base Skin → Extended Skin → Project Overrides = Final Context
|
||||
```
|
||||
|
||||
**Key Features**:
|
||||
- ✅ Cache invalidation (mtime-based)
|
||||
- ✅ Force refresh parameter
|
||||
- ✅ Debug mode with provenance tracking
|
||||
- ✅ Safe Boot Protocol (emergency fallback)
|
||||
- ✅ Path traversal security
|
||||
- ✅ Thread-safe implementation
|
||||
|
||||
### Files Modified
|
||||
|
||||
1. **servers/dss-mcp-server.py**
|
||||
- Added imports (lines 69-81)
|
||||
- Added 5 tool definitions (lines 600-681)
|
||||
- Added 5 tool handlers (lines 823-894)
|
||||
- Total: +151 lines
|
||||
|
||||
### Total Tool Count
|
||||
|
||||
**MCP Server now provides 36 tools**:
|
||||
- 31 existing DSS tools
|
||||
- 5 new Context Compiler tools
|
||||
|
||||
### Cache Behavior
|
||||
|
||||
- **Non-debug mode**: Results cached with mtime validation
|
||||
- **Debug mode**: Cache bypassed (provenance must be fresh)
|
||||
- **Force refresh**: Manual cache bypass available
|
||||
- **Cache keys**: `{manifest_path}:debug={debug}` (prevents collision)
|
||||
|
||||
### Error Handling
|
||||
|
||||
All tools include:
|
||||
- ✅ Availability check (CONTEXT_COMPILER_AVAILABLE)
|
||||
- ✅ Try-catch error handling
|
||||
- ✅ Structured error responses
|
||||
- ✅ Safe Boot Protocol fallback
|
||||
|
||||
### Security
|
||||
|
||||
- ✅ Path traversal prevention in _load_skin()
|
||||
- ✅ Input validation for manifest paths
|
||||
- ✅ No server-side path allowlist (delegated to MCP client)
|
||||
- ✅ Emergency fallback on catastrophic failure
|
||||
|
||||
### Documentation
|
||||
|
||||
Created comprehensive documentation:
|
||||
- **DEPLOYMENT_INTEGRATION.md** - Step-by-step integration guide
|
||||
- **This file** - Production deployment summary
|
||||
- **Test suite** - test_context_compiler.py (27 tests)
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### Get Resolved Context
|
||||
```python
|
||||
dss_get_resolved_context(
|
||||
manifest_path="/path/to/ds.config.json",
|
||||
debug=False,
|
||||
force_refresh=False
|
||||
)
|
||||
```
|
||||
|
||||
#### Resolve Specific Token
|
||||
```python
|
||||
dss_resolve_token(
|
||||
manifest_path="/path/to/ds.config.json",
|
||||
token_path="colors.primary",
|
||||
force_refresh=False
|
||||
)
|
||||
```
|
||||
|
||||
#### List Available Skins
|
||||
```python
|
||||
dss_list_skins()
|
||||
# Returns: ["base", "workbench", "classic"]
|
||||
```
|
||||
|
||||
#### Get Compiler Status
|
||||
```python
|
||||
dss_get_compiler_status()
|
||||
# Returns: {"status": "active", "skins_directory": "...", ...}
|
||||
```
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. ✅ Integration complete
|
||||
2. ✅ Tests passing
|
||||
3. ✅ Documentation written
|
||||
4. 🔄 **MCP Server restart required** - Claude Code will pick up new tools on next connection
|
||||
|
||||
### How to Use
|
||||
|
||||
After MCP server restarts, the 5 new tools will be available to Claude Code:
|
||||
|
||||
```bash
|
||||
# Claude Code will automatically discover these tools:
|
||||
- mcp__plugin_dss-claude-plugin_dss__dss_get_resolved_context
|
||||
- mcp__plugin_dss-claude-plugin_dss__dss_resolve_token
|
||||
- mcp__plugin_dss-claude-plugin_dss__dss_validate_manifest
|
||||
- mcp__plugin_dss-claude-plugin_dss__dss_list_skins
|
||||
- mcp__plugin_dss-claude-plugin_dss__dss_get_compiler_status
|
||||
```
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
If issues arise, revert changes in dss-mcp-server.py:
|
||||
1. Remove imports (lines 69-81)
|
||||
2. Remove tool definitions (lines 600-681)
|
||||
3. Remove tool handlers (lines 823-894)
|
||||
4. Restart MCP server
|
||||
|
||||
### Performance Impact
|
||||
|
||||
- **Bundle size**: +3KB (mcp_extensions.py)
|
||||
- **Initialization**: +10ms (import time)
|
||||
- **Memory**: +~500KB (compiler instance + cache)
|
||||
- **First compilation**: ~50-100ms
|
||||
- **Cached compilation**: ~1-5ms
|
||||
|
||||
### Monitoring
|
||||
|
||||
Monitor these metrics:
|
||||
- Tool invocation count (via MCP logging)
|
||||
- Cache hit rate (check logger.debug messages)
|
||||
- Error rate (CONTEXT_COMPILER_IMPORT_ERROR)
|
||||
- Compilation time (especially for large manifests)
|
||||
|
||||
---
|
||||
|
||||
## Deployment Checklist
|
||||
|
||||
- [x] Context Compiler implementation complete
|
||||
- [x] 27/27 tests passing
|
||||
- [x] Cache invalidation implemented
|
||||
- [x] Force refresh parameter added
|
||||
- [x] Debug mode cache collision fixed
|
||||
- [x] Imports added to dss-mcp-server.py
|
||||
- [x] 5 tool definitions added
|
||||
- [x] 5 tool handlers added
|
||||
- [x] Integration tests passed
|
||||
- [x] Documentation complete
|
||||
- [ ] MCP server restarted (requires user action)
|
||||
- [ ] Tools verified in Claude Code (after restart)
|
||||
|
||||
**Status**: ✅ Ready for production use
|
||||
**Action Required**: Restart MCP server to activate new tools
|
||||
@@ -1,565 +0,0 @@
|
||||
# DSS Claude Plugin
|
||||
|
||||
Design System Server (DSS) integration for Claude Code - A comprehensive plugin for analyzing, extracting, and generating design system tokens and components.
|
||||
|
||||
## Overview
|
||||
|
||||
The DSS Claude Plugin brings the power of DSS directly into Claude Code, enabling:
|
||||
|
||||
- **Project Analysis**: Scan codebases for design patterns and tokenization opportunities
|
||||
- **Token Extraction**: Extract design tokens from CSS, SCSS, Tailwind, and JSON
|
||||
- **Theme Generation**: Generate theme files using style-dictionary
|
||||
- **Component Auditing**: Audit components for design system adoption
|
||||
- **Storybook Integration**: Set up and configure Storybook
|
||||
- **Figma Sync**: Import tokens directly from Figma files
|
||||
- **Quick Wins**: Find low-effort, high-impact improvements
|
||||
|
||||
## Installation
|
||||
|
||||
### Local Development Setup
|
||||
|
||||
For local machines with GUI (desktop/laptop):
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/overbits/dss.git
|
||||
cd dss
|
||||
|
||||
# 2. Run the setup script
|
||||
./setup.sh
|
||||
|
||||
# 3. Install the plugin in Claude Code
|
||||
claude /plugin install ./dss-claude-plugin
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
# 1. Create and activate virtual environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 2. Install dependencies
|
||||
pip install -r requirements.txt
|
||||
playwright install chromium
|
||||
|
||||
# 3. Install the plugin
|
||||
claude /plugin install ./dss-claude-plugin
|
||||
```
|
||||
|
||||
### Remote/Headless Server Setup
|
||||
|
||||
For remote servers, VPS, Docker, or CI/CD environments:
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/overbits/dss.git
|
||||
cd dss
|
||||
|
||||
# 2. Install dependencies (headless mode)
|
||||
pip install -r requirements.txt
|
||||
playwright install chromium --with-deps # Installs system dependencies
|
||||
|
||||
# 3. Install the plugin in Claude Code
|
||||
claude /plugin install ./dss-claude-plugin
|
||||
```
|
||||
|
||||
**Docker Setup:**
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.10-slim
|
||||
|
||||
# Install system dependencies for Playwright
|
||||
RUN apt-get update && apt-get install -y \
|
||||
libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
|
||||
libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
|
||||
libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2
|
||||
|
||||
WORKDIR /app
|
||||
COPY . .
|
||||
|
||||
RUN pip install -r requirements.txt
|
||||
RUN playwright install chromium
|
||||
|
||||
# DSS MCP server runs on stdio
|
||||
CMD ["python3", "dss-claude-plugin/servers/dss-mcp-server.py"]
|
||||
```
|
||||
|
||||
### Claude Code Configuration
|
||||
|
||||
After installing the plugin, Claude Code automatically configures the MCP server. The configuration is stored in `.mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"dss": {
|
||||
"command": "python3",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/dss-mcp-server.py"],
|
||||
"env": {
|
||||
"PYTHONPATH": "/path/to/dss/dss-mvp1",
|
||||
"DSS_HOME": "~/.dss"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Connecting Local Claude Code to Remote Server
|
||||
|
||||
You can run Claude Code locally while connecting to a DSS MCP server running on a remote machine.
|
||||
|
||||
#### Option 1: SSH Tunnel (Recommended)
|
||||
|
||||
Create an SSH tunnel to forward the remote MCP server:
|
||||
|
||||
```bash
|
||||
# On local machine - tunnel remote MCP server
|
||||
ssh -L 9222:localhost:9222 -L 3456:localhost:3456 user@remote-server
|
||||
```
|
||||
|
||||
This forwards:
|
||||
- Port 9222: Chrome DevTools Protocol
|
||||
- Port 3456: Your web application
|
||||
|
||||
Then use `devtools_connect(port=9222)` as if it were local.
|
||||
|
||||
#### Option 2: Remote MCP via SSH
|
||||
|
||||
Configure Claude Code to run the MCP server over SSH. Add to your local `~/.claude/settings.json` or project `.mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"dss-remote": {
|
||||
"command": "ssh",
|
||||
"args": [
|
||||
"user@remote-server",
|
||||
"python3",
|
||||
"/home/user/dss/dss-claude-plugin/servers/dss-mcp-server.py"
|
||||
],
|
||||
"env": {
|
||||
"PYTHONPATH": "/home/user/dss/dss-mvp1"
|
||||
},
|
||||
"description": "Remote DSS MCP server via SSH"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 3: HTTP Proxy (Advanced)
|
||||
|
||||
For shared team access, run the MCP server behind an HTTP proxy:
|
||||
|
||||
```bash
|
||||
# On remote server - start MCP with HTTP transport
|
||||
# (Requires mcp-proxy or similar)
|
||||
python3 -m mcp.server.http --port 8080 dss-claude-plugin/servers/dss-mcp-server.py
|
||||
```
|
||||
|
||||
Then configure Claude Code to connect via HTTP:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"dss-remote": {
|
||||
"url": "http://remote-server:8080",
|
||||
"transport": "http"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 4: VS Code Remote / SSH Workspace
|
||||
|
||||
If using Claude Code in VS Code with Remote SSH extension:
|
||||
|
||||
1. Connect VS Code to remote server via Remote SSH
|
||||
2. Install Claude Code extension in remote context
|
||||
3. DSS plugin runs natively on remote - no tunneling needed
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
# Check DSS tools are available
|
||||
claude --list-tools | grep dss
|
||||
|
||||
# Check DevTools are available (requires Playwright)
|
||||
claude --list-tools | grep devtools
|
||||
|
||||
# Test the MCP server directly
|
||||
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 dss-claude-plugin/servers/dss-mcp-server.py
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code >= 1.0.0
|
||||
- Python 3.10+
|
||||
- Node.js 18+ (for style-dictionary)
|
||||
- DSS MVP1 installed at `/path/to/dss/dss-mvp1`
|
||||
|
||||
### Python Dependencies
|
||||
|
||||
```bash
|
||||
pip install mcp pydantic pydantic-settings playwright aiohttp
|
||||
playwright install chromium
|
||||
```
|
||||
|
||||
Or run the full setup:
|
||||
```bash
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
### Optional: Figma Integration
|
||||
|
||||
Set your Figma personal access token:
|
||||
```bash
|
||||
export FIGMA_TOKEN=your-figma-token
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/dss-analyze [path]` | Analyze project for design system patterns |
|
||||
| `/dss-extract [path] [sources]` | Extract design tokens |
|
||||
| `/dss-generate <format> [name]` | Generate theme files |
|
||||
| `/dss-audit [path]` | Audit components for DS adoption |
|
||||
| `/dss-storybook <action> [path]` | Storybook setup and configuration |
|
||||
| `/dss-figma <file_key>` | Sync tokens from Figma |
|
||||
| `/dss-quick-wins [path]` | Find quick win opportunities |
|
||||
|
||||
## Skills
|
||||
|
||||
The plugin includes 7 procedural skills:
|
||||
|
||||
1. **design-system-analysis** - Comprehensive codebase analysis
|
||||
2. **token-extraction** - Multi-source token extraction
|
||||
3. **theme-generation** - Style-dictionary theme generation
|
||||
4. **component-audit** - React component auditing
|
||||
5. **storybook-integration** - Storybook setup and stories
|
||||
6. **figma-sync** - Figma API integration
|
||||
7. **quick-wins** - Quick win identification
|
||||
|
||||
## Agents
|
||||
|
||||
Two specialized agents for complex tasks:
|
||||
|
||||
### DSS Architect
|
||||
Planning and designing design system implementations.
|
||||
```
|
||||
"Help me plan a design system for our React application"
|
||||
```
|
||||
|
||||
### DSS Migrator
|
||||
Migrating existing codebases to design systems.
|
||||
```
|
||||
"Help me migrate our button components to use design tokens"
|
||||
```
|
||||
|
||||
## MCP Tools
|
||||
|
||||
The plugin exposes DSS tools and Chrome DevTools tools:
|
||||
|
||||
### DSS Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `dss_analyze_project` | Full project analysis |
|
||||
| `dss_extract_tokens` | Extract tokens from sources |
|
||||
| `dss_generate_theme` | Generate theme files |
|
||||
| `dss_list_themes` | List available themes |
|
||||
| `dss_get_status` | Get DSS system status |
|
||||
| `dss_audit_components` | Component audit |
|
||||
| `dss_setup_storybook` | Storybook configuration |
|
||||
| `dss_sync_figma` | Figma token sync |
|
||||
| `dss_find_quick_wins` | Quick win analysis |
|
||||
| `dss_transform_tokens` | Token format transformation |
|
||||
|
||||
### Chrome DevTools Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `devtools_launch` | Launch headless Chromium (for remote/headless servers) |
|
||||
| `devtools_connect` | Connect to running Chrome with CDP (port 9222) |
|
||||
| `devtools_disconnect` | Disconnect and clean up resources |
|
||||
| `devtools_list_pages` | List all browser tabs/pages |
|
||||
| `devtools_select_page` | Select active page for operations |
|
||||
| `devtools_goto` | Navigate to a URL |
|
||||
| `devtools_console_logs` | Get captured console messages |
|
||||
| `devtools_network_requests` | Get captured network activity |
|
||||
| `devtools_evaluate` | Execute JavaScript in page context |
|
||||
| `devtools_query_dom` | Query DOM elements with CSS selector |
|
||||
| `devtools_screenshot` | Capture page/element screenshots (base64 PNG) |
|
||||
| `devtools_performance` | Get Core Web Vitals and performance metrics |
|
||||
|
||||
## Hooks
|
||||
|
||||
The plugin includes hooks for automation:
|
||||
|
||||
- **PreToolUse**: Validates Figma token before sync
|
||||
- **PostToolUse**: Logs completion of major operations
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Analyze a Project
|
||||
|
||||
```
|
||||
/dss-analyze /path/to/project
|
||||
```
|
||||
|
||||
Returns comprehensive analysis including:
|
||||
- File counts and types
|
||||
- Style patterns discovered
|
||||
- Component analysis
|
||||
- Recommendations
|
||||
|
||||
### Extract and Generate Tokens
|
||||
|
||||
```
|
||||
/dss-extract /path/to/styles css,scss
|
||||
/dss-generate css my-theme
|
||||
```
|
||||
|
||||
### Audit Components
|
||||
|
||||
```
|
||||
/dss-audit /path/to/components
|
||||
```
|
||||
|
||||
Identifies:
|
||||
- Hardcoded values
|
||||
- Consolidation opportunities
|
||||
- Refactoring suggestions
|
||||
|
||||
### Sync from Figma
|
||||
|
||||
```
|
||||
/dss-figma abc123xyz456
|
||||
```
|
||||
|
||||
Extracts:
|
||||
- Colors from fill styles
|
||||
- Typography from text styles
|
||||
- Spacing from auto-layout
|
||||
- Effects and shadows
|
||||
|
||||
## Chrome DevTools Integration
|
||||
|
||||
The plugin includes Chrome DevTools Protocol (CDP) integration for browser debugging, console capture, network monitoring, and performance analysis.
|
||||
|
||||
### Remote/Headless Server Setup
|
||||
|
||||
For remote or headless servers (no GUI), use the `devtools_launch` tool to spawn a headless Chromium instance:
|
||||
|
||||
```python
|
||||
# 1. Launch headless browser and navigate to your app
|
||||
devtools_launch(url="http://localhost:3456")
|
||||
|
||||
# 2. Get console logs
|
||||
devtools_console_logs()
|
||||
|
||||
# 3. Navigate to another page
|
||||
devtools_goto(url="http://localhost:3456/dashboard")
|
||||
|
||||
# 4. Capture screenshot
|
||||
devtools_screenshot(full_page=True)
|
||||
|
||||
# 5. Get performance metrics
|
||||
devtools_performance()
|
||||
|
||||
# 6. Execute JavaScript
|
||||
devtools_evaluate(expression="document.title")
|
||||
|
||||
# 7. Query DOM
|
||||
devtools_query_dom(selector=".error-message")
|
||||
|
||||
# 8. Clean up
|
||||
devtools_disconnect()
|
||||
```
|
||||
|
||||
### Local Desktop Setup
|
||||
|
||||
For local development with Chrome GUI, launch Chrome with remote debugging enabled:
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
google-chrome --remote-debugging-port=9222
|
||||
|
||||
# macOS
|
||||
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
|
||||
|
||||
# Windows
|
||||
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
|
||||
```
|
||||
|
||||
Then connect using the `devtools_connect` tool:
|
||||
|
||||
```python
|
||||
# 1. Connect to running Chrome
|
||||
devtools_connect(port=9222)
|
||||
|
||||
# 2. List available tabs
|
||||
devtools_list_pages()
|
||||
|
||||
# 3. Select a tab
|
||||
devtools_select_page(page_id="...")
|
||||
|
||||
# 4. Capture console logs, network, etc.
|
||||
devtools_console_logs()
|
||||
devtools_network_requests()
|
||||
|
||||
# 5. Disconnect when done
|
||||
devtools_disconnect()
|
||||
```
|
||||
|
||||
### DevTools Configuration
|
||||
|
||||
The MCP server includes configurable limits:
|
||||
|
||||
```python
|
||||
DEVTOOLS_CONSOLE_MAX_ENTRIES = 1000 # Max console messages stored
|
||||
DEVTOOLS_NETWORK_MAX_ENTRIES = 500 # Max network requests stored
|
||||
DEVTOOLS_CONNECTION_TIMEOUT_MS = 30000 # Connection timeout (30s)
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
|
||||
**Debug Console Errors:**
|
||||
```python
|
||||
devtools_launch(url="http://localhost:3000")
|
||||
devtools_console_logs(level="error")
|
||||
```
|
||||
|
||||
**Monitor Network Requests:**
|
||||
```python
|
||||
devtools_launch(url="http://localhost:3000")
|
||||
devtools_network_requests(filter_url="api/")
|
||||
```
|
||||
|
||||
**Performance Analysis:**
|
||||
```python
|
||||
devtools_launch(url="http://localhost:3000")
|
||||
devtools_performance()
|
||||
# Returns: FCP, LCP, TTFB, DOM metrics
|
||||
```
|
||||
|
||||
**Visual Regression Testing:**
|
||||
```python
|
||||
devtools_launch(url="http://localhost:3000")
|
||||
devtools_screenshot(full_page=True)
|
||||
# Returns: base64 PNG image
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
dss-claude-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Plugin metadata
|
||||
├── commands/ # 7 slash commands
|
||||
├── skills/ # 7 procedural skills
|
||||
├── agents/ # 2 specialized agents
|
||||
├── hooks/
|
||||
│ └── hooks.json # Event hooks
|
||||
├── servers/
|
||||
│ └── dss-mcp-server.py # Python MCP server
|
||||
├── .mcp.json # MCP configuration
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `FIGMA_TOKEN` | Figma personal access token |
|
||||
| `DSS_HOME` | DSS home directory (default: ~/.dss) |
|
||||
| `PYTHONPATH` | Path to DSS MVP1 modules |
|
||||
|
||||
### Timeouts
|
||||
|
||||
The MCP server includes configurable timeouts:
|
||||
|
||||
```python
|
||||
TIMEOUT_CONFIG = {
|
||||
"analyze": 60, # Large project scanning
|
||||
"extract": 30, # Token extraction
|
||||
"generate": 30, # Theme generation
|
||||
"figma_api": 15, # Figma API calls
|
||||
"storybook": 60, # Storybook operations
|
||||
"devtools_connect": 20, # DevTools CDP connection
|
||||
"devtools_default": 10, # DevTools operations
|
||||
}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Running the MCP Server Directly
|
||||
|
||||
```bash
|
||||
cd /home/overbits/dss/dss-claude-plugin
|
||||
python3 servers/dss-mcp-server.py
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Test MCP server
|
||||
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 servers/dss-mcp-server.py
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### DSS Modules Not Found
|
||||
|
||||
Ensure PYTHONPATH is set correctly:
|
||||
```bash
|
||||
export PYTHONPATH=/home/overbits/dss/dss-mvp1
|
||||
```
|
||||
|
||||
### Figma Sync Fails
|
||||
|
||||
1. Check FIGMA_TOKEN is set
|
||||
2. Verify file key is correct
|
||||
3. Check API rate limits
|
||||
|
||||
### Slow Analysis
|
||||
|
||||
For large projects, analysis may take longer. The timeout is set to 60 seconds by default.
|
||||
|
||||
### DevTools Launch Fails
|
||||
|
||||
1. Ensure Playwright is installed: `pip install playwright`
|
||||
2. Install Chromium browser: `playwright install chromium`
|
||||
3. On Docker/remote: ensure `--no-sandbox` flag is used (handled automatically)
|
||||
|
||||
### DevTools Connect Fails
|
||||
|
||||
1. Ensure Chrome is running with: `--remote-debugging-port=9222`
|
||||
2. Check the port is not blocked by firewall
|
||||
3. Verify connection: `curl http://localhost:9222/json`
|
||||
|
||||
### DevTools Playwright Not Available
|
||||
|
||||
The server gracefully degrades if Playwright isn't installed. DevTools tools will not appear in the tool list. Install with:
|
||||
|
||||
```bash
|
||||
pip install playwright aiohttp
|
||||
playwright install chromium
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See LICENSE file for details.
|
||||
|
||||
## Author
|
||||
|
||||
overbits - https://overbits.luz.uy
|
||||
|
||||
## Links
|
||||
|
||||
- [DSS Homepage](https://dss.overbits.luz.uy)
|
||||
- [Model Context Protocol](https://modelcontextprotocol.io)
|
||||
- [Claude Code](https://claude.ai/code)
|
||||
- [Style Dictionary](https://amzn.github.io/style-dictionary)
|
||||
@@ -1,220 +0,0 @@
|
||||
# Context Compiler - MCP Server Integration Guide
|
||||
|
||||
## Overview
|
||||
This guide shows how to integrate the 5 new Context Compiler tools into `dss-mcp-server.py`.
|
||||
|
||||
## Step 1: Add Import Statement
|
||||
|
||||
Add this import after line 67 (after the DSS imports):
|
||||
|
||||
```python
|
||||
# Context Compiler imports
|
||||
try:
|
||||
from core import (
|
||||
get_active_context,
|
||||
resolve_token,
|
||||
validate_manifest,
|
||||
list_skins,
|
||||
get_compiler_status
|
||||
)
|
||||
CONTEXT_COMPILER_AVAILABLE = True
|
||||
except ImportError as e:
|
||||
CONTEXT_COMPILER_AVAILABLE = False
|
||||
CONTEXT_COMPILER_IMPORT_ERROR = str(e)
|
||||
```
|
||||
|
||||
## Step 2: Add Tool Definitions
|
||||
|
||||
Add these 5 tools to the `list_tools()` function (around line 400, after the existing DSS tools):
|
||||
|
||||
```python
|
||||
# Context Compiler Tools
|
||||
Tool(
|
||||
name="dss_get_resolved_context",
|
||||
description="Get fully resolved design system context for a project. Returns compiled tokens from 3-layer cascade (base → skin → project).",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"manifest_path": {
|
||||
"type": "string",
|
||||
"description": "Absolute path to ds.config.json"
|
||||
},
|
||||
"debug": {
|
||||
"type": "boolean",
|
||||
"description": "Enable debug provenance tracking",
|
||||
"default": False
|
||||
},
|
||||
"force_refresh": {
|
||||
"type": "boolean",
|
||||
"description": "Bypass cache and recompile",
|
||||
"default": False
|
||||
}
|
||||
},
|
||||
"required": ["manifest_path"]
|
||||
}
|
||||
),
|
||||
Tool(
|
||||
name="dss_resolve_token",
|
||||
description="Resolve a specific design token through the cascade. Use dot-notation (e.g. 'colors.primary').",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"manifest_path": {
|
||||
"type": "string",
|
||||
"description": "Absolute path to ds.config.json"
|
||||
},
|
||||
"token_path": {
|
||||
"type": "string",
|
||||
"description": "Dot-notation path to token (e.g. 'colors.primary')"
|
||||
},
|
||||
"force_refresh": {
|
||||
"type": "boolean",
|
||||
"description": "Bypass cache and recompile",
|
||||
"default": False
|
||||
}
|
||||
},
|
||||
"required": ["manifest_path", "token_path"]
|
||||
}
|
||||
),
|
||||
Tool(
|
||||
name="dss_validate_manifest",
|
||||
description="Validate project manifest (ds.config.json) against schema.",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"manifest_path": {
|
||||
"type": "string",
|
||||
"description": "Absolute path to ds.config.json"
|
||||
}
|
||||
},
|
||||
"required": ["manifest_path"]
|
||||
}
|
||||
),
|
||||
Tool(
|
||||
name="dss_list_skins",
|
||||
description="List all available design system skins in the registry.",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {}
|
||||
}
|
||||
),
|
||||
Tool(
|
||||
name="dss_get_compiler_status",
|
||||
description="Get Context Compiler health and configuration status.",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {}
|
||||
}
|
||||
),
|
||||
```
|
||||
|
||||
## Step 3: Add Tool Handlers
|
||||
|
||||
Add these handlers in the `call_tool()` function (around line 640, after the existing DSS tool handlers):
|
||||
|
||||
```python
|
||||
# Context Compiler tools
|
||||
elif name == "dss_get_resolved_context":
|
||||
if not CONTEXT_COMPILER_AVAILABLE:
|
||||
result = {
|
||||
"success": False,
|
||||
"error": f"Context Compiler not available: {CONTEXT_COMPILER_IMPORT_ERROR}"
|
||||
}
|
||||
else:
|
||||
try:
|
||||
context_json = get_active_context(
|
||||
arguments.get("manifest_path"),
|
||||
arguments.get("debug", False),
|
||||
arguments.get("force_refresh", False)
|
||||
)
|
||||
result = {"success": True, "context": json.loads(context_json)}
|
||||
except Exception as e:
|
||||
result = {"success": False, "error": str(e)}
|
||||
|
||||
elif name == "dss_resolve_token":
|
||||
if not CONTEXT_COMPILER_AVAILABLE:
|
||||
result = {
|
||||
"success": False,
|
||||
"error": f"Context Compiler not available: {CONTEXT_COMPILER_IMPORT_ERROR}"
|
||||
}
|
||||
else:
|
||||
try:
|
||||
token_value = resolve_token(
|
||||
arguments.get("manifest_path"),
|
||||
arguments.get("token_path"),
|
||||
arguments.get("force_refresh", False)
|
||||
)
|
||||
result = {"success": True, "token_path": arguments.get("token_path"), "value": token_value}
|
||||
except Exception as e:
|
||||
result = {"success": False, "error": str(e)}
|
||||
|
||||
elif name == "dss_validate_manifest":
|
||||
if not CONTEXT_COMPILER_AVAILABLE:
|
||||
result = {
|
||||
"success": False,
|
||||
"error": f"Context Compiler not available: {CONTEXT_COMPILER_IMPORT_ERROR}"
|
||||
}
|
||||
else:
|
||||
try:
|
||||
validation_result = validate_manifest(arguments.get("manifest_path"))
|
||||
result = {"success": True, "validation": validation_result}
|
||||
except Exception as e:
|
||||
result = {"success": False, "error": str(e)}
|
||||
|
||||
elif name == "dss_list_skins":
|
||||
if not CONTEXT_COMPILER_AVAILABLE:
|
||||
result = {
|
||||
"success": False,
|
||||
"error": f"Context Compiler not available: {CONTEXT_COMPILER_IMPORT_ERROR}"
|
||||
}
|
||||
else:
|
||||
try:
|
||||
skins_json = list_skins()
|
||||
result = {"success": True, "skins": json.loads(skins_json)}
|
||||
except Exception as e:
|
||||
result = {"success": False, "error": str(e)}
|
||||
|
||||
elif name == "dss_get_compiler_status":
|
||||
if not CONTEXT_COMPILER_AVAILABLE:
|
||||
result = {
|
||||
"success": False,
|
||||
"error": f"Context Compiler not available: {CONTEXT_COMPILER_IMPORT_ERROR}"
|
||||
}
|
||||
else:
|
||||
try:
|
||||
status_json = get_compiler_status()
|
||||
result = {"success": True, "status": json.loads(status_json)}
|
||||
except Exception as e:
|
||||
result = {"success": False, "error": str(e)}
|
||||
```
|
||||
|
||||
## Step 4: Restart MCP Server
|
||||
|
||||
After making these changes, restart the MCP server for Claude Code to recognize the new tools.
|
||||
|
||||
## Testing
|
||||
|
||||
Test the integration with:
|
||||
|
||||
```python
|
||||
# Test 1: Get resolved context
|
||||
dss_get_resolved_context(manifest_path="/path/to/ds.config.json")
|
||||
|
||||
# Test 2: Resolve specific token
|
||||
dss_resolve_token(manifest_path="/path/to/ds.config.json", token_path="colors.primary")
|
||||
|
||||
# Test 3: List available skins
|
||||
dss_list_skins()
|
||||
|
||||
# Test 4: Check compiler status
|
||||
dss_get_compiler_status()
|
||||
```
|
||||
|
||||
## Security Note
|
||||
|
||||
The Context Compiler follows the same security model as the existing 31 DSS tools:
|
||||
- File access is restricted by the MCP client (Claude Code)
|
||||
- Server runs with user permissions
|
||||
- No additional server-side path validation required
|
||||
|
||||
For enhanced security across all 36 tools, consider implementing server-wide path validation against an allowlist.
|
||||
@@ -1,20 +0,0 @@
|
||||
# Context Compiler Architecture (Phase 1)
|
||||
|
||||
## Overview
|
||||
The DSS Context Compiler transforms the application from a simple token extractor into a context-aware system. It uses a 3-layer cascade to resolve the final design system context.
|
||||
|
||||
## Layer Cascade
|
||||
1. **Base Layer** (`skins/base.json`): Universal tokens (white, black, system stacks).
|
||||
2. **Skin Layer** (`skins/[name].json`): Thematic definitions (Workbench, Classic).
|
||||
3. **Project Layer** (`ds.config.json`): Project-specific overrides.
|
||||
|
||||
## Safe Boot Protocol
|
||||
If the JSON parser fails or files are missing, the compiler falls back to an in-memory `EMERGENCY_SKIN` to prevent crash loops.
|
||||
|
||||
## Integration
|
||||
MCP Tools should now use the `with_context` wrapper or interact via the 5 new context tools:
|
||||
1. `get_active_context`
|
||||
2. `resolve_token`
|
||||
3. `validate_manifest`
|
||||
4. `list_skins`
|
||||
5. `get_compiler_status`
|
||||
Reference in New Issue
Block a user