{
  "$schema": "dss-knowledge-v1",
  "type": "mcp_tools",
  "version": "1.0.0",
  "last_updated": "2025-12-07",
  "architecture": "MCP-first - All work via MCP tools, no REST endpoints",
  "tools": [
    {
      "name": "dss_create_project",
      "purpose": "Create a new DSS project with empty Figma manifest",
      "inputs": {
        "name": "string (required) - Project name",
        "root_path": "string (required) - Project root path",
        "description": "string (optional) - Project description"
      },
      "outputs": {
        "project_id": "string",
        "name": "string",
        "root_path": "string",
        "manifest_path": "string",
        "status": "string"
      },
      "operations": [
        "Insert into projects table",
        "Create figma.json manifest in project folder",
        "Return project metadata",
        "Emit project-created event"
      ]
    },
    {
      "name": "dss_setup_figma_credentials",
      "purpose": "Store Figma API token at user level (encrypted)",
      "inputs": {
        "api_token": "string (required) - Figma Personal Access Token"
      },
      "outputs": {
        "status": "string",
        "figma_user": "string",
        "workspace": "string",
        "message": "string"
      },
      "operations": [
        "Validate token by testing Figma API",
        "Encrypt and store in project_integrations table",
        "Update integration_health table"
      ]
    },
    {
      "name": "dss_get_project_manifest",
      "purpose": "Read project's figma.json manifest",
      "inputs": {
        "project_id": "string (required) - Project ID"
      },
      "outputs": {
        "version": "string",
        "files": "array",
        "lastUpdated": "string"
      }
    },
    {
      "name": "dss_add_figma_file",
      "purpose": "Add Figma file reference to project manifest",
      "inputs": {
        "project_id": "string (required) - Project ID",
        "file_key": "string (required) - Figma file key or URL",
        "file_name": "string (optional) - Display name for the file"
      },
      "outputs": {
        "project_id": "string",
        "file_key": "string",
        "file_name": "string",
        "status": "string",
        "files_count": "number"
      },
      "operations": [
        "Extract file key from URL if needed",
        "Check if file already linked",
        "Add file to manifest",
        "Write manifest back to filesystem"
      ]
    },
    {
      "name": "dss_discover_figma_files",
      "purpose": "Discover available Figma files and suggest linking",
      "inputs": {
        "project_id": "string (required) - Project ID"
      },
      "outputs": {
        "project_id": "string",
        "linked_files": "array",
        "available_files": "array",
        "total_available": "number",
        "message": "string"
      },
      "operations": [
        "Get user's Figma credentials from database",
        "Fetch user's teams from Figma API",
        "Get projects and files in each team",
        "Return available files excluding already linked"
      ]
    },
    {
      "name": "dss_list_project_figma_files",
      "purpose": "List all Figma files currently linked to project",
      "inputs": {
        "project_id": "string (required) - Project ID"
      },
      "outputs": {
        "project_id": "string",
        "files": "array",
        "count": "number"
      }
    }
  ],
  "architecture_benefits": [
    "No REST endpoints - All work via MCP tools",
    "User-level credentials - Figma tokens stored per-user in database",
    "Manifest-driven - figma.json declares project dependencies",
    "Versionable - Manifests can be checked into git",
    "Discoverable - Claude can list available Figma files",
    "Audit trail - All operations logged in mcp_tool_usage",
    "Circuit breaker - Protected against cascading API failures",
    "Encrypted storage - Credentials encrypted with Fernet"
  ],
  "context_compiler_tools": [
    {
      "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)",
      "parameters": ["manifest_path", "debug", "force_refresh"]
    },
    {
      "name": "dss_resolve_token",
      "description": "Resolve a specific design token through the cascade. Use dot-notation (e.g. 'colors.primary')",
      "parameters": ["manifest_path", "token_path", "force_refresh"]
    },
    {
      "name": "dss_validate_manifest",
      "description": "Validate project manifest (ds.config.json) against schema",
      "parameters": ["manifest_path"]
    },
    {
      "name": "dss_list_skins",
      "description": "List all available design system skins in the registry",
      "parameters": []
    },
    {
      "name": "dss_get_compiler_status",
      "description": "Get Context Compiler health and configuration status",
      "parameters": []
    }
  ]
}