Optics MCP Server

A Model Context Protocol (MCP) server for the Optics Design System, enabling LLMs to understand and work with design tokens, components, and documentation from https://docs.optics.rolemodel.design.

⚠️ IMPORTANT: Understanding Optics

If you're an AI agent, read SYSTEM_OVERVIEW.md FIRST!

Optics uses a sophisticated HSL-based color system that's different from typical design systems. The system overview explains:

• Why there's no --color-primary token (use --op-color-primary-base instead)
• The three-layer token architecture (HSL base → Scale → On tokens)
• How to find and use the correct tokens
• Common mistakes and how to avoid them

Key insight: Optics has 500+ color tokens organized as a predictable scale system, not simple name-value pairs.

Overview

This MCP server provides 14 tools and resources for working with the Optics design system:

• 83 Design Tokens: Real HSL-based colors, calc-based spacing, typography, borders, and shadows
• 24 Components: All Optics components with accurate token dependencies extracted from SCSS
• 7 Core Tools: Query tokens, components, and documentation
• 7 Advanced Tools: Theme generation, validation, accessibility checking, code scaffolding, and style guide generation
• 5 MCP Prompts: Pre-configured workflows for common design system tasks
• Documentation: Design system guidelines and best practices

Architecture

graph TB
    subgraph "MCP Client (AI/LLM)"
        CLIENT[AI Agent/LLM]
    end

    subgraph "Optics MCP Server"
        SERVER[MCP Server<br/>stdio transport]

        subgraph "Resources (13)"
            SYSTEM[optics://system-overview]
            DOC_INTRO[optics://documentation/introduction]
            DOC_START[optics://documentation/getting-started]
            DOC_TOKENS[optics://documentation/design-tokens]
            DOC_COLOR[optics://documentation/color-system]
            DOC_SPACING[optics://documentation/spacing]
            DOC_TYPO[optics://documentation/typography]
            DOC_COMP[optics://documentation/components]
            DOC_A11Y[optics://documentation/accessibility]
            TOK_ALL[optics://tokens/all]
            TOK_COLOR[optics://tokens/color]
            TOK_SPACING[optics://tokens/spacing]
            TOK_TYPO[optics://tokens/typography]
            COMP_ALL[optics://components/all]
        end

        subgraph "Core Tools (7)"
            T1[get_token]
            T2[search_tokens]
            T3[get_token_usage_stats]
            T4[get_component_info]
            T5[list_components]
            T6[get_component_tokens]
            T7[search_documentation]
        end

        subgraph "Advanced Tools (7)"
            T8[generate_theme]
            T9[validate_token_usage]
            T10[replace_hard_coded_values]
            T11[check_contrast]
            T12[suggest_token_migration]
            T13[generate_component_scaffold]
            T14[generate_sticker_sheet]
        end

        subgraph "Prompts (5)"
            P1[start-here]
            P2[get-token-reference]
            P3[component-guide]
            P4[theme-customization]
            P5[migration-guide]
        end

        subgraph "Data Layer"
            TOKENS[83 Design Tokens<br/>HSL colors, spacing,<br/>typography, borders, shadows]
            COMPONENTS[24 Components<br/>with token dependencies]
            DOCS[Documentation<br/>Guidelines & best practices]
        end
    end

    CLIENT -->|JSON-RPC| SERVER
    SERVER --> SYSTEM
    SERVER --> DOC_INTRO
    SERVER --> DOC_START
    SERVER --> DOC_TOKENS
    SERVER --> DOC_COLOR
    SERVER --> DOC_SPACING
    SERVER --> DOC_TYPO
    SERVER --> DOC_COMP
    SERVER --> DOC_A11Y
    SERVER --> TOK_ALL
    SERVER --> TOK_COLOR
    SERVER --> TOK_SPACING
    SERVER --> TOK_TYPO
    SERVER --> COMP_ALL
    SERVER --> T1
    SERVER --> T2
    SERVER --> T3
    SERVER --> T4
    SERVER --> T5
    SERVER --> 

... [View full README on GitHub](https://github.com/RoleModel/optics-mcp#readme)