{
  "markdown": "# Optics MCP Server\n\nA 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.\n\n## ⚠️ IMPORTANT: Understanding Optics\n\n**If you're an AI agent, read [SYSTEM_OVERVIEW.md](./SYSTEM_OVERVIEW.md) FIRST!**\n\nOptics uses a sophisticated HSL-based color system that's different from typical design systems. The system overview explains:\n- Why there's no `--color-primary` token (use `--op-color-primary-base` instead)\n- The three-layer token architecture (HSL base → Scale → On tokens)\n- How to find and use the correct tokens\n- Common mistakes and how to avoid them\n\n**Key insight:** Optics has 500+ color tokens organized as a predictable scale system, not simple name-value pairs.\n\n## Overview\n\nThis MCP server provides **14 tools** and resources for working with the Optics design system:\n\n- **83 Design Tokens**: Real HSL-based colors, calc-based spacing, typography, borders, and shadows\n- **24 Components**: All Optics components with accurate token dependencies extracted from SCSS\n- **7 Core Tools**: Query tokens, components, and documentation\n- **7 Advanced Tools**: Theme generation, validation, accessibility checking, code scaffolding, and style guide generation\n- **5 MCP Prompts**: Pre-configured workflows for common design system tasks\n- **Documentation**: Design system guidelines and best practices\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"MCP Client (AI/LLM)\"\n        CLIENT[AI Agent/LLM]\n    end\n\n    subgraph \"Optics MCP Server\"\n        SERVER[MCP Server<br/>stdio transport]\n\n        subgraph \"Resources (13)\"\n            SYSTEM[optics://system-overview]\n            DOC_INTRO[optics://documentation/introduction]\n            DOC_START[optics://documentation/getting-started]\n            DOC_TOKENS[optics://documentation/design-tokens]\n            DOC_COLOR[optics://documentation/color-system]\n            DOC_SPACING[optics://documentation/spacing]\n            DOC_TYPO[optics://documentation/typography]\n            DOC_COMP[optics://documentation/components]\n            DOC_A11Y[optics://documentation/accessibility]\n            TOK_ALL[optics://tokens/all]\n            TOK_COLOR[optics://tokens/color]\n            TOK_SPACING[optics://tokens/spacing]\n            TOK_TYPO[optics://tokens/typography]\n            COMP_ALL[optics://components/all]\n        end\n\n        subgraph \"Core Tools (7)\"\n            T1[get_token]\n            T2[search_tokens]\n            T3[get_token_usage_stats]\n            T4[get_component_info]\n            T5[list_components]\n            T6[get_component_tokens]\n            T7[search_documentation]\n        end\n\n        subgraph \"Advanced Tools (7)\"\n            T8[generate_theme]\n            T9[validate_token_usage]\n            T10[replace_hard_coded_values]\n            T11[check_contrast]\n            T12[suggest_token_migration]\n            T13[generate_component_scaffold]\n            T14[generate_sticker_sheet]\n        end\n\n        subgraph \"Prompts (5)\"\n            P1[start-here]\n            P2[get-token-reference]\n            P3[component-guide]\n            P4[theme-customization]\n            P5[migration-guide]\n        end\n\n        subgraph \"Data Layer\"\n            TOKENS[83 Design Tokens<br/>HSL colors, spacing,<br/>typography, borders, shadows]\n            COMPONENTS[24 Components<br/>with token dependencies]\n            DOCS[Documentation<br/>Guidelines & best practices]\n        end\n    end\n\n    CLIENT -->|JSON-RPC| SERVER\n    SERVER --> SYSTEM\n    SERVER --> DOC_INTRO\n    SERVER --> DOC_START\n    SERVER --> DOC_TOKENS\n    SERVER --> DOC_COLOR\n    SERVER --> DOC_SPACING\n    SERVER --> DOC_TYPO\n    SERVER --> DOC_COMP\n    SERVER --> DOC_A11Y\n    SERVER --> TOK_ALL\n    SERVER --> TOK_COLOR\n    SERVER --> TOK_SPACING\n    SERVER --> TOK_TYPO\n    SERVER --> COMP_ALL\n    SERVER --> T1\n    SERVER --> T2\n    SERVER --> T3\n    SERVER --> T4\n    SERVER --> T5\n    SERVER --> T6\n    SERVER --> T7\n    SERVER --> T8\n    SERVER --> T9\n    SERVER --> T10\n    SERVER --> T11\n    SERVER --> T12\n    SERVER --> T13\n    SERVER --> T14\n    SERVER --> P1\n    SERVER --> P2\n    SERVER --> P3\n    SERVER --> P4\n    SERVER --> P5\n    T1 --> TOKENS\n    T2 --> TOKENS\n    T3 --> TOKENS\n    T4 --> COMPONENTS\n    T5 --> COMPONENTS\n    T6 --> COMPONENTS\n    T7 --> DOCS\n    T8 --> TOKENS\n    T9 --> TOKENS\n    T10 --> TOKENS\n    T11 --> TOKENS\n    T12 --> TOKENS\n    T13 --> COMPONENTS\n    T14 --> TOKENS\n    T14 --> COMPONENTS\n    P1 --> SYSTEM\n    P2 --> TOKENS\n    P3 --> COMPONENTS\n    P4 --> T8\n    P5 --> T12\n```\n\n## Installation\n\n### VS Code 🎨\n\n**Quick Setup**:\n\n1. Command Palette → **MCP: Open User Configuration**\n2. Add this configuration:\n\n```json\n{\n  \"servers\": {\n    \"optics\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@rolemodel/optics-mcp@latest\"\n      ]\n    }\n  }\n}\n```\n\n3. Open GitHub Copilot in **Agent Mode**\n4. Click the tools icon to see Optics tools available\n\n**Or** create `.vscode/mcp.json` in your workspace with the same config.\n\n**Official MCP Registry**: Listed at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/servers?search=optics) ✅\n\n### Cursor 🎯\n\n**One-Click Install** (click to open Cursor):\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==\n```\n\n**Or Manual Setup**:\n\n1. Open Cursor Settings → **MCP**\n2. Add this configuration:\n\n```json\n{\n  \"servers\": {\n    \"optics\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@rolemodel/optics-mcp@latest\"\n      ]\n    }\n  }\n}\n```\n\n3. Chat with Cursor AI to access Optics tools\n\n### Quick Start (Zero-Install) ⚡\n\nThe easiest way to use Optics MCP - no installation required!\n\n#### Claude Desktop\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"optics\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@rolemodel/optics-mcp@latest\"\n      ]\n    }\n  }\n}\n```\n\n#### Claude Code CLI\n\nAdd with a single command:\n\n```bash\nclaude mcp add optics -- npx -y optics-mcp\n```\n\n**Other useful commands:**\n\n```bash\n# List all MCP servers\nclaude mcp list\n\n# Remove the Optics server\nclaude mcp remove optics\n\n# View server details\nclaude mcp get optics\n\n# Test the connection\nclaude mcp test optics\n```\n\n**That's it!** The server runs automatically whenever your MCP client needs it.\n\n### Local Installation (For Development)\n\nIf you want to modify the server or contribute:\n\n```bash\ngit clone https://github.com/RoleModel/optics-mcp.git\ncd optics-mcp\nnpm install\nnpm run build\n```\n\nThen configure with the local path:\n\n```json\n{\n  \"mcpServers\": {\n    \"optics\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/optics-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Usage\n\n### Running Directly\n\n```bash\nnpm start\n```\n\n## Available Tools (14 Total)\n\nFor detailed documentation of all tools, see [TOOLS.md](./TOOLS.md).\n\n### Core Tools\n\n#### `get_token`\nGet detailed information about a specific design token.\n\n#### `search_tokens`\nSearch for design tokens by category or name pattern.\n\n#### `get_token_usage_stats`\nGet statistics about design token usage across the system.\n\n#### `get_component_info`\nGet detailed information about a component including its design token dependencies.\n\n#### `list_components`\nList all available components in the design system.\n\n#### `get_component_tokens`\nGet all design tokens used by a specific component.\n\n#### `search_documentation`\nSearch through Optics documentation.\n\n### Advanced Tools\n\n#### `generate_theme`\nCreate a custom branded theme with CSS variables and Figma Variables JSON.\n- Outputs HSL-based theme overrides\n- Generates Figma Variables format\n- Creates theme preview\n\n#### `validate_token_usage`\nFind hard-coded values in code that should use design tokens.\n- Detects colors, spacing, fonts, borders, shadows\n- Suggests token replacements\n- Validates token usage\n\n#### `replace_hard_coded_values`\nAutomatically replace hard-coded values with design tokens.\n- Manual mode: suggestions only\n- Autofix mode: applies replacements\n- Preserves code structure\n\n#### `check_contrast`\nCheck WCAG color contrast ratios between tokens.\n- Supports AA and AAA levels\n- Works with token names or hex colors\n- Provides accessibility recommendations\n\n#### `suggest_token_migration`\nSuggest tokens for legacy code migration.\n- Maps old values to new tokens\n- Prioritizes semantic tokens\n- Provides rationale\n\n#### `generate_component_scaffold`\nGenerate component code with Optics tokens.\n- React, Vue, Svelte, HTML support\n- Pre-configured with design tokens\n- TypeScript types included\n\n#### `generate_sticker_sheet`\n**Generate a visual style guide** showing all design tokens and components.\n- Complete color palettes with swatches\n- Typography scale examples\n- Spacing visualizations\n- Component examples\n- Multi-framework support (React, Vue, Svelte, HTML)\n- Production-ready code output\n\n## Available Resources\n\nThe server exposes the following resources via the `optics://` URI scheme:\n\n### Documentation\n- `optics://documentation/introduction` - Overview of Optics\n- `optics://documentation/getting-started` - Getting started guide\n- `optics://documentation/design-tokens` - Design token documentation\n- `optics://documentation/color-system` - Color system guide\n- `optics://documentation/spacing` - Spacing system guide\n- `optics://documentation/typography` - Typography guide\n- `optics://documentation/components` - Component library overview\n- `optics://documentation/accessibility` - Accessibility guidelines\n\n### Tokens\n- `optics://tokens/all` - All design tokens\n- `optics://tokens/color` - Color tokens only\n- `optics://tokens/spacing` - Spacing tokens only\n- `optics://tokens/typography` - Typography tokens only\n\n### Components\n- `optics://components/all` - All components\n\n## Design System Overview\n\n### Design Token Categories\n\n1. **Colors** (25 tokens): HSL-based color system with primary, neutral, and alert colors\n2. **Spacing** (11 tokens): calc-based rem units with base-10 scale (2px to 80px)\n3. **Typography** (32 tokens): Noto Sans/Serif fonts with sizes, weights, and line heights\n4. **Borders** (10 tokens): Border radius (small to pill) and widths\n5. **Shadows** (5 tokens): Elevation system (x-small to x-large)\n\n### Components (24 Total)\n\nAll components extracted from real Optics SCSS with accurate token dependencies:\n\n- **Accordion**: Collapsible content panel\n- **Alert**: Notification messages (warning, danger, info, notice)\n- **Avatar**: User profile pictures\n- **Badge**: Status indicators and labels\n- **Breadcrumbs**: Navigation hierarchy\n- **Button**: Interactive buttons with variants\n- **ButtonGroup**: Grouped button container\n- **Card**: Content containers with elevation\n- **ConfirmDialog**: Action confirmation modals\n- **Divider**: Content separators\n- **Form**: Input fields, textareas, selects\n- **Icon**: Material Symbols icons\n- **Modal**: Overlay dialogs\n- **Navbar**: Top navigation\n- **Pagination**: Page navigation\n- **SidePanel**: Sliding side panels\n- **Sidebar**: Side navigation\n- **Spinner**: Loading indicators\n- **Switch**: Toggle switches\n- **Tab**: Tabbed interfaces\n- **Table**: Data tables\n- **Tag**: Categorization labels\n- **TextPair**: Label-value pairs\n- **Tooltip**: Contextual information\n\nEach component specifies which Optics design tokens it uses, making it easy to understand dependencies and maintain consistency.\n\n## Development\n\n### Build\n```bash\nnpm run build\n```\n\n### Watch Mode\n```bash\nnpm run watch\n```\n\n### Project Structure\n```\noptics-mcp/\n├── src/\n│   ├── index.ts          # MCP server implementation\n│   └── optics-data.ts    # Design tokens and component data\n├── dist/                 # Compiled JavaScript\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Token Usage Tracking\n\nThe server tracks which design tokens are used by each component, enabling:\n- **Dependency Analysis**: Understand which tokens a component relies on\n- **Impact Analysis**: See which components are affected by token changes\n- **Usage Statistics**: Get insights into token usage patterns\n\n## Contributing\n\nTo add new design tokens or components:\n\n1. Edit `src/optics-data.ts`\n2. Add tokens to the `designTokens` array\n3. Add components to the `components` array, specifying their token dependencies\n4. Rebuild the project: `npm run build`\n\n## License\n\nMIT\n\n## Links\n\n- [Optics Design System Documentation](https://docs.optics.rolemodel.design)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n",
  "bytes": 12628,
  "sha": "0c3cfc9e9bb719ac0863c9ba273196c123e74cb139e8cd46fadecce0904a8444",
  "repo_slug": "rolemodel/optics-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rolemodel_optics_mcp_d6e177e3/readme"
}