dss/tools/dss_mcp/MCP_PHASE_2_3_IMPLEMENTATION_PLAN.md

MCP Phase 2/3 Implementation Plan: Translation Dictionary & Theme Configuration Tools

Version: 2.0.0 Date: December 9, 2024 Status: READY FOR IMPLEMENTATION Author: Gemini 3 Pro Simulation (Architecture Planning)

---

Executive Summary

This document provides a comprehensive implementation plan for MCP Phase 2/3 tools that expose the newly implemented Translation Dictionary System. The plan reflects the actual codebase architecture and renames the outdated "Skin Management" terminology to "Project Theme Configuration" to accurately reflect the DSS approach.

Key Accomplishments

Component	Status	Location
Translation Dictionary Python Core	COMPLETE	dss-mvp1/dss/translations/ (8 modules)
Storybook MCP Integration	COMPLETE	tools/dss_mcp/integrations/storybook.py
MCP Handler Pattern	COMPLETE	tools/dss_mcp/handler.py
Phase 2/3 MCP Tools	THIS PLAN	tools/dss_mcp/integrations/translations.py

What This Plan Delivers

1. 12 New MCP Tools organized into 3 categories
2. Complete Workflow Support for Workflows 2 & 3
3. Integration Architecture following existing patterns
4. Clear Implementation Phases with dependencies

---

1. Architecture Overview

1.1 System Integration Diagram

+====================================================================================+
|                           DSS MCP PLUGIN ARCHITECTURE                               |
+====================================================================================+
|                                                                                     |
|  MCP LAYER (tools/dss_mcp/)                                                        |
|  +---------------------------------------------------------------------------+     |
|  |  server.py                                                                 |     |
|  |    |                                                                       |     |
|  |    v                                                                       |     |
|  |  handler.py                                                                |     |
|  |    |                                                                       |     |
|  |    +-----> integrations/figma.py          (5 tools - COMPLETE)            |     |
|  |    +-----> integrations/storybook.py      (5 tools - COMPLETE)            |     |
|  |    +-----> integrations/translations.py   (12 tools - THIS PLAN)  [NEW]   |     |
|  |    +-----> tools/project_tools.py         (7 tools - COMPLETE)            |     |
|  +---------------------------------------------------------------------------+     |
|                                   |                                                 |
|                                   v                                                 |
|  PYTHON CORE (dss-mvp1/dss/)                                                       |
|  +---------------------------------------------------------------------------+     |
|  |  translations/                                                             |     |
|  |    +-- __init__.py          # Module exports                              |     |
|  |    +-- models.py            # TranslationDictionary, ResolvedTheme, etc.  |     |
|  |    +-- loader.py            # TranslationDictionaryLoader                 |     |
|  |    +-- resolver.py          # TokenResolver                               |     |
|  |    +-- merger.py            # ThemeMerger                                 |     |
|  |    +-- validator.py         # TranslationValidator                        |     |
|  |    +-- writer.py            # TranslationDictionaryWriter                 |     |
|  |    +-- canonical.py         # DSS_CANONICAL_TOKENS, DSS_CANONICAL_COMPONENTS |  |
|  +---------------------------------------------------------------------------+     |
|                                                                                     |
+====================================================================================+

1.2 Data Flow for Theme Resolution

+--------------------------------------------------------------------------------+
|                    THEME RESOLUTION DATA FLOW                                   |
+--------------------------------------------------------------------------------+
|                                                                                 |
|  1. LOAD DICTIONARIES                                                          |
|     +-------------------+                                                       |
|     | .dss/translations |                                                       |
|     |   figma.json      |---+                                                   |
|     |   legacy-css.json |---+---> TranslationDictionaryLoader                   |
|     |   custom.json     |---+            |                                      |
|     +-------------------+                v                                      |
|                              +-------------------+                              |
|                              | TranslationRegistry                              |
|                              | - combined_token_map                             |
|                              | - all_custom_props                               |
|                              | - conflicts                                      |
|                              +-------------------+                              |
|                                        |                                        |
|  2. RESOLVE TOKENS                     v                                        |
|     +-------------------+     +-------------------+                             |
|     | Base Theme        |---->| TokenResolver     |                             |
|     | (light/dark)      |     | - resolve_to_dss()                              |
|     +-------------------+     | - resolve_all_mappings()                        |
|                               +-------------------+                             |
|                                        |                                        |
|  3. MERGE THEME                        v                                        |
|                               +-------------------+                             |
|                               | ThemeMerger       |                             |
|                               | - merge()                                       |
|                               +-------------------+                             |
|                                        |                                        |
|  4. OUTPUT                             v                                        |
|                               +-------------------+                             |
|                               | ResolvedTheme     |-----> CSS Variables         |
|                               | - tokens          |-----> SCSS Variables        |
|                               | - custom_props    |-----> JSON Export           |
|                               | - provenance      |-----> Storybook Theme       |
|                               +-------------------+                             |
|                                                                                 |
+--------------------------------------------------------------------------------+

---

2. Tool Categories & Definitions

2.1 Category Overview

Category	Tools	Purpose
Category 1: Translation Dictionary CRUD	5 tools	Create, read, update, delete translation dictionaries
Category 2: Theme Configuration & Merging	4 tools	Configure project theme, merge base + translations + custom
Category 3: Token Resolution & Code Generation	3 tools	Resolve tokens, generate CSS/SCSS output

2.2 Complete Tool List

Translation Dictionary Tools (12 total):

Category 1: Dictionary Management
  1. translation_list_dictionaries     - List available translation dictionaries
  2. translation_get_dictionary        - Get dictionary details and mappings
  3. translation_create_dictionary     - Create new translation dictionary
  4. translation_update_dictionary     - Update existing dictionary mappings
  5. translation_validate_dictionary   - Validate dictionary schema and mappings

Category 2: Theme Configuration
  6. theme_get_config                  - Get project theme configuration
  7. theme_resolve                     - Resolve complete project theme
  8. theme_add_custom_prop             - Add custom property to project
  9. theme_get_canonical_tokens        - Get DSS canonical token structure

Category 3: Code Generation
  10. codegen_export_css               - Generate CSS variables from resolved theme
  11. codegen_export_scss              - Generate SCSS variables from resolved theme
  12. codegen_export_json              - Export resolved theme as JSON

---

3. Detailed Tool Specifications

3.1 Category 1: Translation Dictionary Management

Tool 1: translation_list_dictionaries

types.Tool(
    name="translation_list_dictionaries",
    description="List all available translation dictionaries for a project. Returns dictionary types (figma, css, heroui, custom, etc.), mapping counts, and validation status.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "include_stats": {
                "type": "boolean",
                "description": "Include mapping statistics (default: true)",
                "default": True
            }
        },
        "required": ["project_id"]
    }
)

Implementation:

async def list_dictionaries(
    self,
    project_id: str,
    include_stats: bool = True
) -> Dict[str, Any]:
    """List all translation dictionaries for project."""
    project_path = await self._get_project_path(project_id)
    loader = TranslationDictionaryLoader(project_path)

    available = loader.list_available_dictionaries()

    result = {
        "project_id": project_id,
        "dictionaries": [],
        "has_translations": loader.has_translations(),
        "translations_dir": str(loader.get_translations_dir())
    }

    if include_stats:
        registry = await loader.load_all()
        for source in available:
            dict_info = {
                "source": source,
                "file": f"{source}.json"
            }
            if source in registry.dictionaries:
                d = registry.dictionaries[source]
                dict_info["token_count"] = len(d.mappings.tokens)
                dict_info["component_count"] = len(d.mappings.components)
                dict_info["custom_prop_count"] = len(d.custom_props)
                dict_info["unmapped_count"] = len(d.unmapped)
            result["dictionaries"].append(dict_info)

        result["conflicts"] = registry.conflicts
    else:
        result["dictionaries"] = [{"source": s} for s in available]

    return result

Output Example:

{
  "project_id": "proj-123",
  "dictionaries": [
    {
      "source": "figma",
      "file": "figma.json",
      "token_count": 45,
      "component_count": 12,
      "custom_prop_count": 3,
      "unmapped_count": 2
    },
    {
      "source": "css",
      "file": "css.json",
      "token_count": 23,
      "component_count": 0,
      "custom_prop_count": 5,
      "unmapped_count": 8
    }
  ],
  "has_translations": true,
  "translations_dir": "/project/.dss/translations",
  "conflicts": []
}

---

Tool 2: translation_get_dictionary

types.Tool(
    name="translation_get_dictionary",
    description="Get detailed information about a specific translation dictionary including all token mappings, component mappings, and custom props.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "source": {
                "type": "string",
                "description": "Dictionary source type",
                "enum": ["figma", "css", "scss", "heroui", "shadcn", "tailwind", "json", "custom"]
            },
            "include_unmapped": {
                "type": "boolean",
                "description": "Include list of unmapped source tokens (default: true)",
                "default": True
            }
        },
        "required": ["project_id", "source"]
    }
)

Implementation:

async def get_dictionary(
    self,
    project_id: str,
    source: str,
    include_unmapped: bool = True
) -> Dict[str, Any]:
    """Get translation dictionary details."""
    project_path = await self._get_project_path(project_id)
    loader = TranslationDictionaryLoader(project_path)

    dictionary = await loader.load_dictionary(source)
    if not dictionary:
        return {
            "error": f"Dictionary not found: {source}",
            "project_id": project_id,
            "available": loader.list_available_dictionaries()
        }

    result = {
        "project_id": project_id,
        "source": source,
        "uuid": dictionary.uuid,
        "version": dictionary.version,
        "created_at": dictionary.created_at.isoformat(),
        "updated_at": dictionary.updated_at.isoformat(),
        "mappings": {
            "tokens": dictionary.mappings.tokens,
            "components": dictionary.mappings.components,
            "patterns": dictionary.mappings.patterns
        },
        "custom_props": dictionary.custom_props,
        "notes": dictionary.notes
    }

    if include_unmapped:
        result["unmapped"] = dictionary.unmapped

    return result

---

Tool 3: translation_create_dictionary

types.Tool(
    name="translation_create_dictionary",
    description="Create a new translation dictionary for a project. Maps external tokens (Figma, CSS, etc.) to DSS canonical tokens.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "source": {
                "type": "string",
                "description": "Source type for the dictionary",
                "enum": ["figma", "css", "scss", "heroui", "shadcn", "tailwind", "json", "custom"]
            },
            "token_mappings": {
                "type": "object",
                "description": "Token mappings: source_token -> DSS canonical path",
                "additionalProperties": {
                    "type": "string"
                }
            },
            "component_mappings": {
                "type": "object",
                "description": "Component mappings: source_component -> DSS component",
                "additionalProperties": {
                    "type": "string"
                }
            },
            "custom_props": {
                "type": "object",
                "description": "Custom properties (must use DSS namespace like 'color.brand.myproject.primary')",
                "additionalProperties": {}
            },
            "notes": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Human-readable notes"
            }
        },
        "required": ["project_id", "source"]
    }
)

Implementation:

async def create_dictionary(
    self,
    project_id: str,
    source: str,
    token_mappings: Optional[Dict[str, str]] = None,
    component_mappings: Optional[Dict[str, str]] = None,
    custom_props: Optional[Dict[str, Any]] = None,
    notes: Optional[List[str]] = None
) -> Dict[str, Any]:
    """Create new translation dictionary."""
    project_path = await self._get_project_path(project_id)
    writer = TranslationDictionaryWriter(project_path)

    # Validate before creating
    validator = TranslationValidator()
    test_data = {
        "$schema": "dss-translation-v1",
        "project": project_id,
        "source": source,
        "mappings": {
            "tokens": token_mappings or {},
            "components": component_mappings or {}
        },
        "custom_props": custom_props or {}
    }

    validation_result = validator.validate_dictionary(test_data)
    if not validation_result.is_valid:
        return {
            "error": "Validation failed",
            "errors": [str(e) for e in validation_result.errors],
            "warnings": [str(w) for w in validation_result.warnings]
        }

    dictionary = await writer.create(
        source=source,
        project=project_id,
        token_mappings=token_mappings,
        component_mappings=component_mappings,
        custom_props=custom_props,
        notes=notes
    )

    return {
        "project_id": project_id,
        "source": source,
        "uuid": dictionary.uuid,
        "created": True,
        "file_path": str(writer.translations_dir / f"{source}.json"),
        "token_count": len(dictionary.mappings.tokens),
        "component_count": len(dictionary.mappings.components),
        "custom_prop_count": len(dictionary.custom_props),
        "warnings": [str(w) for w in validation_result.warnings]
    }

---

Tool 4: translation_update_dictionary

types.Tool(
    name="translation_update_dictionary",
    description="Update an existing translation dictionary. Add or modify token mappings, component mappings, or custom props.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "source": {
                "type": "string",
                "description": "Dictionary source type to update",
                "enum": ["figma", "css", "scss", "heroui", "shadcn", "tailwind", "json", "custom"]
            },
            "token_mappings": {
                "type": "object",
                "description": "Token mappings to add/update",
                "additionalProperties": {"type": "string"}
            },
            "component_mappings": {
                "type": "object",
                "description": "Component mappings to add/update",
                "additionalProperties": {"type": "string"}
            },
            "custom_props": {
                "type": "object",
                "description": "Custom props to add/update",
                "additionalProperties": {}
            },
            "remove_tokens": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Source tokens to remove from mappings"
            },
            "notes": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Notes to append"
            }
        },
        "required": ["project_id", "source"]
    }
)

---

Tool 5: translation_validate_dictionary

types.Tool(
    name="translation_validate_dictionary",
    description="Validate a translation dictionary. Checks schema compliance, DSS token path validity, and detects conflicts.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "source": {
                "type": "string",
                "description": "Dictionary source type to validate",
                "enum": ["figma", "css", "scss", "heroui", "shadcn", "tailwind", "json", "custom"]
            },
            "strict": {
                "type": "boolean",
                "description": "Strict mode - unknown tokens are errors (default: false)",
                "default": False
            }
        },
        "required": ["project_id", "source"]
    }
)

---

3.2 Category 2: Theme Configuration & Merging

Tool 6: theme_get_config

types.Tool(
    name="theme_get_config",
    description="Get project theme configuration including base theme, loaded dictionaries, and custom props summary.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            }
        },
        "required": ["project_id"]
    }
)

Implementation:

async def get_config(self, project_id: str) -> Dict[str, Any]:
    """Get project theme configuration."""
    project_path = await self._get_project_path(project_id)
    loader = TranslationDictionaryLoader(project_path)

    # Load registry to get full picture
    registry = await loader.load_all()

    return {
        "project_id": project_id,
        "base_themes_available": ["light", "dark"],
        "translation_dictionaries": list(registry.dictionaries.keys()),
        "total_token_mappings": len(registry.combined_token_map),
        "total_component_mappings": len(registry.combined_component_map),
        "total_custom_props": len(registry.all_custom_props),
        "conflicts": registry.conflicts,
        "has_config": loader.has_translations()
    }

---

Tool 7: theme_resolve

types.Tool(
    name="theme_resolve",
    description="Resolve complete project theme by merging base theme with translation dictionaries and custom props. Returns fully resolved tokens with provenance.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "base_theme": {
                "type": "string",
                "description": "Base theme to use",
                "enum": ["light", "dark"],
                "default": "light"
            },
            "include_provenance": {
                "type": "boolean",
                "description": "Include token resolution provenance chain (default: false)",
                "default": False
            }
        },
        "required": ["project_id"]
    }
)

Implementation:

async def resolve_theme(
    self,
    project_id: str,
    base_theme: str = "light",
    include_provenance: bool = False
) -> Dict[str, Any]:
    """Resolve complete project theme."""
    project_path = await self._get_project_path(project_id)

    # Load translation registry
    loader = TranslationDictionaryLoader(project_path)
    registry = await loader.load_all()

    # Create merger and resolve
    merger = ThemeMerger(registry)
    resolved = await merger.merge(
        base_theme=base_theme,
        project_name=project_id
    )

    # Format tokens for output
    tokens = {}
    for dss_path, resolved_token in resolved.tokens.items():
        token_data = {
            "value": resolved_token.value,
            "source_token": resolved_token.source_token,
            "is_custom": resolved_token.is_custom
        }
        if include_provenance:
            token_data["provenance"] = resolved_token.provenance
        tokens[dss_path] = token_data

    custom_props = {}
    for dss_path, resolved_token in resolved.custom_props.items():
        prop_data = {
            "value": resolved_token.value
        }
        if include_provenance:
            prop_data["provenance"] = resolved_token.provenance
        custom_props[dss_path] = prop_data

    return {
        "project_id": project_id,
        "name": resolved.name,
        "base_theme": resolved.base_theme,
        "version": resolved.version,
        "resolved_at": resolved.resolved_at.isoformat(),
        "translations_applied": resolved.translations_applied,
        "token_count": len(tokens),
        "custom_prop_count": len(custom_props),
        "tokens": tokens,
        "custom_props": custom_props
    }

---

Tool 8: theme_add_custom_prop

types.Tool(
    name="theme_add_custom_prop",
    description="Add a custom property to the project's custom.json translation dictionary. Custom props extend DSS with project-specific tokens.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "prop_name": {
                "type": "string",
                "description": "Property name using DSS namespace (e.g., 'color.brand.acme.primary')"
            },
            "prop_value": {
                "description": "Property value (string, number, or object)"
            },
            "description": {
                "type": "string",
                "description": "Optional description of the custom prop"
            }
        },
        "required": ["project_id", "prop_name", "prop_value"]
    }
)

---

Tool 9: theme_get_canonical_tokens

types.Tool(
    name="theme_get_canonical_tokens",
    description="Get the DSS canonical token structure. Useful for understanding available tokens and valid mapping targets.",
    inputSchema={
        "type": "object",
        "properties": {
            "category": {
                "type": "string",
                "description": "Filter by category (optional)",
                "enum": ["color", "spacing", "typography", "border", "shadow", "motion", "zIndex", "opacity", "breakpoint"]
            },
            "include_aliases": {
                "type": "boolean",
                "description": "Include token aliases (default: true)",
                "default": True
            },
            "include_components": {
                "type": "boolean",
                "description": "Include canonical components (default: false)",
                "default": False
            }
        },
        "required": []
    }
)

Implementation:

async def get_canonical_tokens(
    self,
    category: Optional[str] = None,
    include_aliases: bool = True,
    include_components: bool = False
) -> Dict[str, Any]:
    """Get DSS canonical token structure."""
    from dss.translations.canonical import (
        DSS_CANONICAL_TOKENS,
        DSS_TOKEN_ALIASES,
        DSS_CANONICAL_COMPONENTS,
        get_canonical_token_categories
    )

    result = {
        "total_tokens": len(DSS_CANONICAL_TOKENS)
    }

    if category:
        # Filter by category
        categories = get_canonical_token_categories()
        result["category"] = category
        result["tokens"] = categories.get(category, [])
    else:
        # Return all organized by category
        result["tokens_by_category"] = get_canonical_token_categories()

    if include_aliases:
        result["aliases"] = DSS_TOKEN_ALIASES

    if include_components:
        result["components"] = list(DSS_CANONICAL_COMPONENTS)

    return result

---

3.3 Category 3: Code Generation

Tool 10: codegen_export_css

types.Tool(
    name="codegen_export_css",
    description="Generate CSS custom properties from resolved project theme. Outputs :root variables and optional utility classes.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "base_theme": {
                "type": "string",
                "description": "Base theme to use",
                "enum": ["light", "dark"],
                "default": "light"
            },
            "selector": {
                "type": "string",
                "description": "CSS selector for variables (default: ':root')",
                "default": ":root"
            },
            "prefix": {
                "type": "string",
                "description": "CSS variable prefix (default: 'dss')",
                "default": "dss"
            },
            "include_comments": {
                "type": "boolean",
                "description": "Include provenance comments (default: true)",
                "default": True
            },
            "output_path": {
                "type": "string",
                "description": "Optional: Write to file instead of returning content"
            }
        },
        "required": ["project_id"]
    }
)

Implementation:

async def export_css(
    self,
    project_id: str,
    base_theme: str = "light",
    selector: str = ":root",
    prefix: str = "dss",
    include_comments: bool = True,
    output_path: Optional[str] = None
) -> Dict[str, Any]:
    """Generate CSS variables from resolved theme."""
    # Resolve theme first
    resolved_result = await self.resolve_theme(
        project_id,
        base_theme,
        include_provenance=include_comments
    )

    if "error" in resolved_result:
        return resolved_result

    # Generate CSS
    css_lines = []
    if include_comments:
        css_lines.append(f"/* DSS Theme: {resolved_result['name']} */")
        css_lines.append(f"/* Base: {base_theme} | Generated: {resolved_result['resolved_at']} */")
        css_lines.append(f"/* Translations: {', '.join(resolved_result['translations_applied'])} */")
        css_lines.append("")

    css_lines.append(f"{selector} {{")

    # Core tokens
    for dss_path, token_data in resolved_result["tokens"].items():
        var_name = f"--{prefix}-{dss_path.replace('.', '-')}"
        value = token_data["value"]

        if include_comments and token_data.get("source_token"):
            css_lines.append(f"  /* Source: {token_data['source_token']} */")

        css_lines.append(f"  {var_name}: {value};")

    # Custom props
    if resolved_result["custom_props"]:
        css_lines.append("")
        css_lines.append("  /* Custom Properties */")
        for dss_path, prop_data in resolved_result["custom_props"].items():
            var_name = f"--{prefix}-{dss_path.replace('.', '-')}"
            css_lines.append(f"  {var_name}: {prop_data['value']};")

    css_lines.append("}")

    css_content = "\n".join(css_lines)

    if output_path:
        project_path = await self._get_project_path(project_id)
        full_path = project_path / output_path
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(css_content)

        return {
            "project_id": project_id,
            "output_path": str(full_path),
            "written": True,
            "token_count": resolved_result["token_count"],
            "custom_prop_count": resolved_result["custom_prop_count"]
        }

    return {
        "project_id": project_id,
        "content": css_content,
        "token_count": resolved_result["token_count"],
        "custom_prop_count": resolved_result["custom_prop_count"]
    }

---

Tool 11: codegen_export_scss

types.Tool(
    name="codegen_export_scss",
    description="Generate SCSS variables from resolved project theme. Outputs $variables and optional mixins.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "base_theme": {
                "type": "string",
                "description": "Base theme to use",
                "enum": ["light", "dark"],
                "default": "light"
            },
            "prefix": {
                "type": "string",
                "description": "SCSS variable prefix (default: 'dss')",
                "default": "dss"
            },
            "generate_map": {
                "type": "boolean",
                "description": "Generate SCSS map in addition to variables (default: true)",
                "default": True
            },
            "output_path": {
                "type": "string",
                "description": "Optional: Write to file instead of returning content"
            }
        },
        "required": ["project_id"]
    }
)

---

Tool 12: codegen_export_json

types.Tool(
    name="codegen_export_json",
    description="Export resolved theme as JSON. Useful for design tool integrations and token documentation.",
    inputSchema={
        "type": "object",
        "properties": {
            "project_id": {
                "type": "string",
                "description": "Project ID"
            },
            "base_theme": {
                "type": "string",
                "description": "Base theme to use",
                "enum": ["light", "dark"],
                "default": "light"
            },
            "format": {
                "type": "string",
                "description": "JSON structure format",
                "enum": ["flat", "nested", "style-dictionary"],
                "default": "flat"
            },
            "include_metadata": {
                "type": "boolean",
                "description": "Include resolution metadata (default: true)",
                "default": True
            },
            "output_path": {
                "type": "string",
                "description": "Optional: Write to file instead of returning content"
            }
        },
        "required": ["project_id"]
    }
)

---

4. File Structure & Implementation

4.1 New Files to Create

tools/dss_mcp/
+-- integrations/
|   +-- translations.py      # NEW - Translation dictionary MCP tools
|
+-- handler.py               # MODIFY - Register new tools
+-- server.py                # MODIFY - Import new tool lists

4.2 integrations/translations.py - Complete Structure

"""
Translation Dictionary Integration for MCP

Provides tools for managing translation dictionaries, theme configuration,
and code generation for design system tokens.
"""

from typing import Dict, Any, Optional, List
from pathlib import Path
from mcp import types

from .base import BaseIntegration
from ..context.project_context import get_context_manager


# =============================================================================
# MCP Tool Definitions
# =============================================================================

TRANSLATION_TOOLS = [
    # Category 1: Dictionary Management
    types.Tool(name="translation_list_dictionaries", ...),
    types.Tool(name="translation_get_dictionary", ...),
    types.Tool(name="translation_create_dictionary", ...),
    types.Tool(name="translation_update_dictionary", ...),
    types.Tool(name="translation_validate_dictionary", ...),

    # Category 2: Theme Configuration
    types.Tool(name="theme_get_config", ...),
    types.Tool(name="theme_resolve", ...),
    types.Tool(name="theme_add_custom_prop", ...),
    types.Tool(name="theme_get_canonical_tokens", ...),

    # Category 3: Code Generation
    types.Tool(name="codegen_export_css", ...),
    types.Tool(name="codegen_export_scss", ...),
    types.Tool(name="codegen_export_json", ...),
]


# =============================================================================
# Integration Class
# =============================================================================

class TranslationIntegration(BaseIntegration):
    """Translation dictionary integration wrapper for DSS tools"""

    def __init__(self, config: Optional[Dict[str, Any]] = None):
        super().__init__("translations", config or {})
        self.context_manager = get_context_manager()

    async def _get_project_path(self, project_id: str) -> Path:
        """Get project path from context manager."""
        context = await self.context_manager.get_context(project_id)
        if not context or not context.path:
            raise ValueError(f"Project not found: {project_id}")
        return Path(context.path)

    # Category 1: Dictionary Management
    async def list_dictionaries(self, ...) -> Dict[str, Any]: ...
    async def get_dictionary(self, ...) -> Dict[str, Any]: ...
    async def create_dictionary(self, ...) -> Dict[str, Any]: ...
    async def update_dictionary(self, ...) -> Dict[str, Any]: ...
    async def validate_dictionary(self, ...) -> Dict[str, Any]: ...

    # Category 2: Theme Configuration
    async def get_config(self, ...) -> Dict[str, Any]: ...
    async def resolve_theme(self, ...) -> Dict[str, Any]: ...
    async def add_custom_prop(self, ...) -> Dict[str, Any]: ...
    async def get_canonical_tokens(self, ...) -> Dict[str, Any]: ...

    # Category 3: Code Generation
    async def export_css(self, ...) -> Dict[str, Any]: ...
    async def export_scss(self, ...) -> Dict[str, Any]: ...
    async def export_json(self, ...) -> Dict[str, Any]: ...


# =============================================================================
# MCP Tool Executor
# =============================================================================

class TranslationTools:
    """MCP tool executor for translation integration"""

    def __init__(self, config: Optional[Dict[str, Any]] = None):
        self.translations = TranslationIntegration(config)

    async def execute_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
        """Execute translation tool."""
        handlers = {
            # Category 1
            "translation_list_dictionaries": self.translations.list_dictionaries,
            "translation_get_dictionary": self.translations.get_dictionary,
            "translation_create_dictionary": self.translations.create_dictionary,
            "translation_update_dictionary": self.translations.update_dictionary,
            "translation_validate_dictionary": self.translations.validate_dictionary,
            # Category 2
            "theme_get_config": self.translations.get_config,
            "theme_resolve": self.translations.resolve_theme,
            "theme_add_custom_prop": self.translations.add_custom_prop,
            "theme_get_canonical_tokens": self.translations.get_canonical_tokens,
            # Category 3
            "codegen_export_css": self.translations.export_css,
            "codegen_export_scss": self.translations.export_scss,
            "codegen_export_json": self.translations.export_json,
        }

        handler = handlers.get(tool_name)
        if not handler:
            return {"error": f"Unknown translation tool: {tool_name}"}

        try:
            clean_args = {k: v for k, v in arguments.items() if not k.startswith("_")}
            return await handler(**clean_args)
        except Exception as e:
            return {"error": f"Tool execution failed: {str(e)}", "tool": tool_name}

4.3 Handler Registration Update

# In handler.py - add to _initialize_tools()

from .integrations.translations import TRANSLATION_TOOLS, TranslationTools

# Register Translation tools
for tool in TRANSLATION_TOOLS:
    self._tool_registry[tool.name] = {
        "tool": tool,
        "category": "translations",
        "requires_integration": False
    }

# Add to execute_tool() method
if category == "translations":
    tools = TranslationTools()
    result = await tools.execute_tool(tool_name, arguments)

---

5. Workflow Integration

5.1 Workflow 2: Load Project Theme into Storybook

+--------------------------------------------------------------------------------+
|                    WORKFLOW 2: Load Project Theme into Storybook               |
+--------------------------------------------------------------------------------+
|                                                                                 |
|  Step 1: Check translations                                                    |
|  +-----------------------+                                                      |
|  | translation_list_     |                                                      |
|  | dictionaries          |---> List available dictionaries                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 2: Resolve theme                                                         |
|  +-----------------------+                                                      |
|  | theme_resolve         |---> Merge base + translations + custom props        |
|  | (base_theme="light")  |                                                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 3: Generate Storybook theme                                              |
|  +-----------------------+                                                      |
|  | storybook_generate_   |---> Generate theme files with resolved tokens       |
|  | theme                 |                                                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 4: Configure Storybook                                                   |
|  +-----------------------+                                                      |
|  | storybook_configure   |---> Update Storybook config to use theme            |
|  | (action="add_theme")  |                                                      |
|  +-----------------------+                                                      |
|                                                                                 |
+--------------------------------------------------------------------------------+

Example Tool Sequence:
1. translation_list_dictionaries(project_id="proj-123")
   -> Returns: ["figma", "css", "custom"]

2. theme_resolve(project_id="proj-123", base_theme="light", include_provenance=true)
   -> Returns: Complete resolved theme with 150 tokens

3. storybook_generate_theme(project_id="proj-123", base_theme="light", write_files=true)
   -> Writes: .storybook/dss-theme.ts, manager.ts, preview.ts

4. storybook_configure(project_id="proj-123", action="add_theme")
   -> Updates Storybook configuration

5.2 Workflow 3: Apply Design to Project

+--------------------------------------------------------------------------------+
|                    WORKFLOW 3: Apply Design to Project                         |
+--------------------------------------------------------------------------------+
|                                                                                 |
|  Step 1: View canonical structure                                              |
|  +-----------------------+                                                      |
|  | theme_get_canonical_  |---> Understand available DSS tokens                 |
|  | tokens                |                                                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 2: Create/update translations                                            |
|  +-----------------------+                                                      |
|  | translation_create_   |---> Map legacy tokens to DSS                        |
|  | dictionary            |                                                      |
|  | (source="css")        |                                                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 3: Add custom props                                                      |
|  +-----------------------+                                                      |
|  | theme_add_custom_prop |---> Add project-specific tokens                     |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 4: Validate                                                              |
|  +-----------------------+                                                      |
|  | translation_validate_ |---> Ensure all mappings are valid                   |
|  | dictionary            |                                                      |
|  +-----------------------+                                                      |
|            |                                                                    |
|            v                                                                    |
|  Step 5: Resolve and export                                                    |
|  +-----------------------+                                                      |
|  | theme_resolve         |---> Generate complete theme                         |
|  |         +             |                                                      |
|  | codegen_export_css    |---> Generate CSS variables file                     |
|  +-----------------------+                                                      |
|                                                                                 |
+--------------------------------------------------------------------------------+

Example Tool Sequence:
1. theme_get_canonical_tokens(category="color", include_aliases=true)
   -> Returns: All color tokens and aliases

2. translation_create_dictionary(
     project_id="proj-123",
     source="css",
     token_mappings={
       "--brand-primary": "color.primary.500",
       "--brand-secondary": "color.secondary.500"
     }
   )
   -> Creates: .dss/translations/css.json

3. theme_add_custom_prop(
     project_id="proj-123",
     prop_name="color.brand.acme.highlight",
     prop_value="#ff6b00"
   )
   -> Updates: .dss/translations/custom.json

4. translation_validate_dictionary(project_id="proj-123", source="css")
   -> Returns: Validation result with warnings

5. codegen_export_css(
     project_id="proj-123",
     base_theme="light",
     output_path="src/styles/tokens.css"
   )
   -> Writes: src/styles/tokens.css

---

6. Implementation Phases

Phase 1: Core Infrastructure (Day 1)

Priority: Critical

1. Create integrations/translations.py with basic structure
2. Implement Category 1 tools (Dictionary CRUD):
   • translation_list_dictionaries
   • translation_get_dictionary
   • translation_create_dictionary
3. Register in handler.py
4. Basic unit tests

Deliverables:

• New translations.py file
• 3 working MCP tools
• Handler registration
• Test fixtures

Phase 2: Theme Resolution (Day 2)

Priority: High

1. Implement remaining Category 1 tools:
   • translation_update_dictionary
   • translation_validate_dictionary
2. Implement Category 2 tools:
   • theme_get_config
   • theme_resolve
   • theme_add_custom_prop
   • theme_get_canonical_tokens
3. Integration tests for Workflow 2

Deliverables:

• 6 additional MCP tools
• Workflow 2 tested end-to-end
• Integration with storybook tools verified

Phase 3: Code Generation (Day 3)

Priority: High

1. Implement Category 3 tools:
   • codegen_export_css
   • codegen_export_scss
   • codegen_export_json
2. Integration tests for Workflow 3
3. End-to-end testing

Deliverables:

• 3 code generation tools
• Workflow 3 tested end-to-end
• All 12 tools complete

Phase 4: Polish & Documentation (Day 4)

Priority: Medium

1. Error handling improvements
2. Edge case testing
3. Performance optimization
4. Update API documentation
5. Example workflows

Deliverables:

• Comprehensive error messages
• Test coverage > 80%
• Documentation updated

---

7. Testing Strategy

7.1 Unit Tests

# tests/test_translation_tools.py

class TestTranslationDictionaryTools:
    """Test Category 1: Dictionary Management"""

    async def test_list_dictionaries_empty_project(self):
        """Test listing on project with no translations."""
        pass

    async def test_list_dictionaries_with_stats(self):
        """Test listing with statistics."""
        pass

    async def test_create_dictionary_valid(self):
        """Test creating valid dictionary."""
        pass

    async def test_create_dictionary_invalid_tokens(self):
        """Test creating dictionary with invalid DSS tokens."""
        pass

    async def test_validate_dictionary_warnings(self):
        """Test validation with warnings."""
        pass


class TestThemeConfigurationTools:
    """Test Category 2: Theme Configuration"""

    async def test_resolve_theme_light(self):
        """Test resolving light theme."""
        pass

    async def test_resolve_theme_with_custom_props(self):
        """Test resolution with custom props."""
        pass

    async def test_get_canonical_tokens_by_category(self):
        """Test getting tokens by category."""
        pass


class TestCodeGenerationTools:
    """Test Category 3: Code Generation"""

    async def test_export_css_basic(self):
        """Test basic CSS export."""
        pass

    async def test_export_css_to_file(self):
        """Test CSS export to file."""
        pass

    async def test_export_scss_with_map(self):
        """Test SCSS export with map."""
        pass

    async def test_export_json_nested(self):
        """Test nested JSON export."""
        pass

7.2 Integration Tests

# tests/integration/test_translation_workflows.py

class TestWorkflow2:
    """Test: Load Project Theme into Storybook"""

    async def test_complete_workflow(self):
        """Test full workflow from translations to Storybook."""
        # 1. Create translation dictionary
        # 2. Resolve theme
        # 3. Generate Storybook theme
        # 4. Verify output files
        pass


class TestWorkflow3:
    """Test: Apply Design to Project"""

    async def test_complete_workflow(self):
        """Test full workflow from analysis to CSS generation."""
        # 1. Get canonical structure
        # 2. Create translations
        # 3. Add custom props
        # 4. Export CSS
        pass

7.3 Test Fixtures

tests/fixtures/
+-- translation_dictionaries/
|   +-- figma.json           # Sample Figma translation
|   +-- css.json             # Sample CSS translation
|   +-- custom.json          # Sample custom props
|
+-- projects/
|   +-- empty_project/       # Project with no .dss
|   +-- configured_project/  # Project with full .dss setup

---

8. Complete Tool Registry

After implementation, the MCP handler will register these tools:

Project Tools (7):
- dss_get_project_summary
- dss_list_components
- dss_get_component
- dss_get_design_tokens
- dss_get_project_health
- dss_list_styles
- dss_get_discovery_data

Figma Tools (5):
- figma_get_file
- figma_get_styles
- figma_get_components
- figma_extract_tokens
- figma_get_node

Storybook Tools (5):
- storybook_scan
- storybook_generate_stories
- storybook_generate_theme
- storybook_get_status
- storybook_configure

Translation Tools (12): [NEW - THIS PLAN]
- translation_list_dictionaries
- translation_get_dictionary
- translation_create_dictionary
- translation_update_dictionary
- translation_validate_dictionary
- theme_get_config
- theme_resolve
- theme_add_custom_prop
- theme_get_canonical_tokens
- codegen_export_css
- codegen_export_scss
- codegen_export_json

Jira Tools (5):
- jira_list_projects
- jira_get_issue
- jira_search_issues
- jira_create_issue
- jira_update_issue

Confluence Tools (5):
- confluence_list_spaces
- confluence_get_page
- confluence_search_content
- confluence_create_page
- confluence_update_page

Total: 39 tools

---

9. Risk Assessment & Mitigation

Risk	Probability	Impact	Mitigation
Translation system async issues	Low	Medium	All Python core functions support async, use run_in_executor if needed
Path traversal vulnerabilities	Low	High	All path operations validated against project root (already implemented)
Large dictionary files	Medium	Low	Lazy loading, pagination for list operations
Conflicting translations	Medium	Medium	Conflict detection and reporting in registry
Invalid DSS paths	Medium	Low	Strict validation with helpful error messages

---

10. Success Criteria

Minimum Viable Delivery

• All 12 MCP tools implemented and registered
• Workflow 2 (Load into Storybook) works end-to-end
• Workflow 3 (Apply Design) works end-to-end
• Unit test coverage > 70%
• Documentation complete

Full Delivery

• Integration tests for all workflows
• Error handling with actionable messages
• Performance optimized (< 1s for typical operations)
• Example workflows documented
• Test coverage > 80%

---

Appendix A: JSON Examples

A.1 Translation Dictionary Example

{
  "$schema": "dss-translation-v1",
  "uuid": "dict-001",
  "project": "acme-web",
  "source": "css",
  "version": "1.0.0",
  "created_at": "2024-12-09T10:00:00Z",
  "updated_at": "2024-12-09T10:00:00Z",
  "mappings": {
    "tokens": {
      "--brand-primary": "color.primary.500",
      "--brand-secondary": "color.secondary.500",
      "--text-base": "typography.size.base",
      "--spacing-sm": "spacing.sm"
    },
    "components": {
      ".btn-primary": "Button[variant=primary]",
      ".btn-outline": "Button[variant=outline]"
    },
    "patterns": {}
  },
  "custom_props": {
    "color.brand.acme.highlight": "#ff6b00",
    "color.brand.acme.accent": "#00b4d8"
  },
  "unmapped": [
    "--legacy-gradient-1",
    "--deprecated-shadow"
  ],
  "notes": [
    "Mapped from legacy CSS variables",
    "Some gradient variables need manual review"
  ]
}

A.2 Resolved Theme Example

{
  "project_id": "acme-web",
  "name": "resolved-light",
  "base_theme": "light",
  "version": "1.0.0",
  "resolved_at": "2024-12-09T12:00:00Z",
  "translations_applied": ["css", "custom"],
  "token_count": 89,
  "custom_prop_count": 2,
  "tokens": {
    "color.primary.500": {
      "value": "#3b82f6",
      "source_token": "--brand-primary",
      "is_custom": false
    },
    "color.secondary.500": {
      "value": "#8b5cf6",
      "source_token": "--brand-secondary",
      "is_custom": false
    }
  },
  "custom_props": {
    "color.brand.acme.highlight": {
      "value": "#ff6b00"
    }
  }
}

A.3 Generated CSS Example

/* DSS Theme: resolved-light */
/* Base: light | Generated: 2024-12-09T12:00:00Z */
/* Translations: css, custom */

:root {
  /* Source: --brand-primary */
  --dss-color-primary-500: #3b82f6;
  /* Source: --brand-secondary */
  --dss-color-secondary-500: #8b5cf6;
  --dss-typography-size-base: 1rem;
  --dss-spacing-sm: 0.5rem;

  /* Custom Properties */
  --dss-color-brand-acme-highlight: #ff6b00;
  --dss-color-brand-acme-accent: #00b4d8;
}

---

Document Version: 2.0.0 Last Updated: December 9, 2024 Author: Gemini 3 Pro Simulation (Architecture Planning)