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

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

subgraph "Optics MCP Server"
SERVER[MCP Server
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
HSL colors, spacing,
typography, borders, shadows]
COMPONENTS[24 Components
with token dependencies]
DOCS[Documentation
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 --> T6
SERVER --> T7
SERVER --> T8
SERVER --> T9
SERVER --> T10
SERVER --> T11
SERVER --> T12
SERVER --> T13
SERVER --> T14
SERVER --> P1
SERVER --> P2
SERVER --> P3
SERVER --> P4
SERVER --> P5
T1 --> TOKENS
T2 --> TOKENS
T3 --> TOKENS
T4 --> COMPONENTS
T5 --> COMPONENTS
T6 --> COMPONENTS
T7 --> DOCS
T8 --> TOKENS
T9 --> TOKENS
T10 --> TOKENS
T11 --> TOKENS
T12 --> TOKENS
T13 --> COMPONENTS
T14 --> TOKENS
T14 --> COMPONENTS
P1 --> SYSTEM
P2 --> TOKENS
P3 --> COMPONENTS
P4 --> T8
P5 --> T12
`

Installation

$3

Quick Setup:

1. Command Palette → MCP: Open User Configuration
2. Add this configuration:

`json
{
"servers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
`

3. Open GitHub Copilot in Agent Mode
4. Click the tools icon to see Optics tools available

Or create .vscode/mcp.json in your workspace with the same config.

Official MCP Registry: Listed at registry.modelcontextprotocol.io ✅

$3

One-Click Install (click to open Cursor):
`
cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==
`

Or Manual Setup:

1. Open Cursor Settings → MCP
2. Add this configuration:

`json
{
"servers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
`

3. Chat with Cursor AI to access Optics tools

$3

The easiest way to use Optics MCP - no installation required!

#### Claude Desktop

Add to your MCP configuration:

`json
{
"mcpServers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
`

#### Claude Code CLI

Add with a single command:

`bash
claude mcp add optics -- npx -y optics-mcp
`

Other useful commands:

`bash


List all MCP servers

claude mcp list

Remove the Optics server

claude mcp remove optics

View server details

claude mcp get optics

Test the connection

claude mcp test optics
`

That's it! The server runs automatically whenever your MCP client needs it.

$3

If you want to modify the server or contribute:

`bash
git clone https://github.com/RoleModel/optics-mcp.git
cd optics-mcp
npm install
npm run build
`

Then configure with the local path:

`json
{
"mcpServers": {
"optics": {
"command": "node",
"args": ["/absolute/path/to/optics-mcp/dist/index.js"]
}
}
}
`

Usage

$3

`bash
npm start
`

Available Tools (14 Total)

For detailed documentation of all tools, see TOOLS.md.

$3

#### get_token
Get detailed information about a specific design token.

#### search_tokens
Search for design tokens by category or name pattern.

#### get_token_usage_stats
Get statistics about design token usage across the system.

#### get_component_info
Get detailed information about a component including its design token dependencies.

#### list_components
List all available components in the design system.

#### get_component_tokens
Get all design tokens used by a specific component.

#### search_documentation
Search through Optics documentation.

$3

#### generate_theme
Create a custom branded theme with CSS variables and Figma Variables JSON.
- Outputs HSL-based theme overrides
- Generates Figma Variables format
- Creates theme preview

#### validate_token_usage
Find hard-coded values in code that should use design tokens.
- Detects colors, spacing, fonts, borders, shadows
- Suggests token replacements
- Validates token usage

#### replace_hard_coded_values
Automatically replace hard-coded values with design tokens.
- Manual mode: suggestions only
- Autofix mode: applies replacements
- Preserves code structure

#### check_contrast
Check WCAG color contrast ratios between tokens.
- Supports AA and AAA levels
- Works with token names or hex colors
- Provides accessibility recommendations

#### suggest_token_migration
Suggest tokens for legacy code migration.
- Maps old values to new tokens
- Prioritizes semantic tokens
- Provides rationale

#### generate_component_scaffold
Generate component code with Optics tokens.
- React, Vue, Svelte, HTML support
- Pre-configured with design tokens
- TypeScript types included

#### generate_sticker_sheet
Generate a visual style guide showing all design tokens and components.
- Complete color palettes with swatches
- Typography scale examples
- Spacing visualizations
- Component examples
- Multi-framework support (React, Vue, Svelte, HTML)
- Production-ready code output

Available Resources

The server exposes the following resources via the optics:// URI scheme:

$3


- optics://documentation/introduction - Overview of Optics
- optics://documentation/getting-started - Getting started guide
- optics://documentation/design-tokens - Design token documentation
- optics://documentation/color-system - Color system guide
- optics://documentation/spacing - Spacing system guide
- optics://documentation/typography - Typography guide
- optics://documentation/components - Component library overview
- optics://documentation/accessibility - Accessibility guidelines

$3

- optics://tokens/all - All design tokens
- optics://tokens/color - Color tokens only
- optics://tokens/spacing - Spacing tokens only
- optics://tokens/typography - Typography tokens only

$3

- optics://components/all - All components

Design System Overview

$3

1. Colors (25 tokens): HSL-based color system with primary, neutral, and alert colors
2. Spacing (11 tokens): calc-based rem units with base-10 scale (2px to 80px)
3. Typography (32 tokens): Noto Sans/Serif fonts with sizes, weights, and line heights
4. Borders (10 tokens): Border radius (small to pill) and widths
5. Shadows (5 tokens): Elevation system (x-small to x-large)

$3

All components extracted from real Optics SCSS with accurate token dependencies:

- Accordion: Collapsible content panel
- Alert: Notification messages (warning, danger, info, notice)
- Avatar: User profile pictures
- Badge: Status indicators and labels
- Breadcrumbs: Navigation hierarchy
- Button: Interactive buttons with variants
- ButtonGroup: Grouped button container
- Card: Content containers with elevation
- ConfirmDialog: Action confirmation modals
- Divider: Content separators
- Form: Input fields, textareas, selects
- Icon: Material Symbols icons
- Modal: Overlay dialogs
- Navbar: Top navigation
- Pagination: Page navigation
- SidePanel: Sliding side panels
- Sidebar: Side navigation
- Spinner: Loading indicators
- Switch: Toggle switches
- Tab: Tabbed interfaces
- Table: Data tables
- Tag: Categorization labels
- TextPair: Label-value pairs
- Tooltip: Contextual information

Each component specifies which Optics design tokens it uses, making it easy to understand dependencies and maintain consistency.

Development

$3

`bash
npm run build
`

$3

`bash
npm run watch
`

$3

`
optics-mcp/
├── src/
│ ├── index.ts # MCP server implementation
│ └── optics-data.ts # Design tokens and component data
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
`

Token Usage Tracking

The server tracks which design tokens are used by each component, enabling:
- Dependency Analysis: Understand which tokens a component relies on
- Impact Analysis: See which components are affected by token changes
- Usage Statistics: Get insights into token usage patterns

Contributing

To add new design tokens or components:

1. Edit src/optics-data.ts
2. Add tokens to the designTokens array
3. Add components to the components array, specifying their token dependencies
4. Rebuild the project: npm run build`

License

MIT

Links

- Optics Design System Documentation
- Model Context Protocol
- MCP TypeScript SDK