Enables AI agents to interact with the Optics Design System by querying design tokens, components, and documentation.
Also known as RoleModel/optics-mcp
- Stars
- 1
- Tools
- ā
- Downloads, 30 days
- ā
- Latest version
- 0.2.6
- Last commit
- Oct 22, 2026
- License
- MIT
What is Optics MCP?
Optics enables AI agents to interact with the Optics Design System by querying design tokens, components, and documentation.
Summary generated from the project's README
About Optics MCP server
The optics-mcp server allows AI agents to interact directly with the Optics Design System. It provides a bridge for large language models to query design tokens, components, and official documentation. This server is designed for developers using MCP clients like Claude Desktop, Cursor, or VS Code with GitHub Copilot. It operates via stdio transport and can be installed using npx.
Users can access 83 design tokens covering HSL-based colors, spacing, typography, borders, and shadows. The server includes 24 components with their specific token dependencies extracted from SCSS. Beyond simple queries, it offers advanced capabilities such as generating custom themes, checking WCAG color contrast ratios, and scaffolding component code for React, Vue, Svelte, or HTML. It also features tools to validate token usage and replace hard-coded values with correct design system tokens.
What you can do with it
- 1Audit color contrastAsk the AI to verify if specific design tokens meet accessibility standards.
- 2Generate branded themesRequest the creation of a custom theme including CSS variables and Figma JSON.
- 3Refactor hard-coded stylesHave the agent identify and replace manual CSS values with official design tokens.
- 4Create component codeUse the agent to build out new component structures using the design system.
Written from the project's README. Every use case is checked against a quote from it.
How to install Optics MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Optics MCP in Claude Code
$ claude mcp add optics-mcp -- npx -y optics-mcpInstall Optics MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"optics-mcp": {
"command": "npx",
"args": [
"-y",
"optics-mcp"
]
}
}
}Install Optics MCP in VS Code
.vscode/mcp.json
{
"servers": {
"optics-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"optics-mcp"
]
}
}
}Install Optics MCP in VS Code CLI
$ code --add-mcp '{"name":"optics-mcp","type":"stdio","command":"npx","args":["-y","optics-mcp"]}'Install Optics MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"optics-mcp": {
"command": "npx",
"args": [
"-y",
"optics-mcp"
]
}
}
}Install Optics MCP in Codex
$ codex mcp add optics-mcp -- npx -y optics-mcpInstall Optics MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.optics-mcp] command = "npx" args = ["-y", "optics-mcp"]
Install Optics MCP in Gemini CLI
$ gemini mcp add -s user optics-mcp npx -- -y optics-mcpInstall Optics MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"optics-mcp": {
"command": "npx",
"args": [
"-y",
"optics-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report āPassed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablerolemodel/optics-mcp is public and reachablegithub.com/rolemodel/optics-mcp āPass
- Package names this repository as its sourceoptics-mcp names rolemodel/optics-mcp as sourcenpmjs.com/package/optics-mcp āPass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html āPass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/rolemodel/optics-mcp āPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from optics-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev āPass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOptics 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-primarytoken (use--op-color-primary-baseinstead) - 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 --> 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
VS Code šØ
Quick Setup:
- Command Palette ā MCP: Open User Configuration
- Add this configuration:
{
"servers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
- Open GitHub Copilot in Agent Mode
- 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 ā
Cursor šÆ
One-Click Install (click to open Cursor):
cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==
Or Manual Setup:
- Open Cursor Settings ā MCP
- Add this configuration:
{
"servers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
- Chat with Cursor AI to access Optics tools
Quick Start (Zero-Install) ā”
The easiest way to use Optics MCP - no installation required!
Claude Desktop
Add to your MCP configuration:
{
"mcpServers": {
"optics": {
"command": "npx",
"args": [
"@rolemodel/optics-mcp@latest"
]
}
}
}
Claude Code CLI
Add with a single command:
claude mcp add optics -- npx -y optics-mcp
Other useful commands:
# 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.
Local Installation (For Development)
If you want to modify the server or contribute:
git clone https://github.com/RoleModel/optics-mcp.git
cd optics-mcp
npm install
npm run build
Then configure with the local path:
{
"mcpServers": {
"optics": {
"command": "node",
"args": ["/absolute/path/to/optics-mcp/dist/index.js"]
}
}
}
Usage
Running Directly
npm start
Available Tools (14 Total)
For detailed documentation of all tools, see TOOLS.md.
Core Tools
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.
Advanced Tools
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:
Documentation
optics://documentation/introduction- Overview of Opticsoptics://documentation/getting-started- Getting started guideoptics://documentation/design-tokens- Design token documentationoptics://documentation/color-system- Color system guideoptics://documentation/spacing- Spacing system guideoptics://documentation/typography- Typography guideoptics://documentation/components- Component library overviewoptics://documentation/accessibility- Accessibility guidelines
Tokens
optics://tokens/all- All design tokensoptics://tokens/color- Color tokens onlyoptics://tokens/spacing- Spacing tokens onlyoptics://tokens/typography- Typography tokens only
Components
optics://components/all- All components
Design System Overview
Design Token Categories
- Colors (25 tokens): HSL-based color system with primary, neutral, and alert colors
- Spacing (11 tokens): calc-based rem units with base-10 scale (2px to 80px)
- Typography (32 tokens): Noto Sans/Serif fonts with sizes, weights, and line heights
- Borders (10 tokens): Border radius (small to pill) and widths
- Shadows (5 tokens): Elevation system (x-small to x-large)
Components (24 Total)
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
Build
npm run build
Watch Mode
npm run watch
Project Structure
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:
- Edit
src/optics-data.ts - Add tokens to the
designTokensarray - Add components to the
componentsarray, specifying their token dependencies - Rebuild the project:
npm run build
License
MIT
Links
Optics MCP questions
How do I add Optics MCP to Claude Code?
Run claude mcp add optics-mcp -- npx -y optics-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Optics MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can I do with the Optics MCP server?
You can query design tokens, list components, search documentation, generate custom themes, validate token usage, and check color contrast for accessibility.