dss/dss-claude-plugin/docs/DEPLOYMENT_INTEGRATION.md

# 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.