276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
7.8 KiB
7.8 KiB
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):
# 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):
# 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):
# 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:
# 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.