Optics MCP

🚀 Optics MCP 服務器

Optics MCP 服務器是專為 Optics 設計系統打造的模型上下文協議（MCP）服務器，它能讓大語言模型（LLMs）理解並運用來自 Optics 設計系統文檔 的設計令牌、組件和文檔。

🚀 快速開始

瞭解 Optics ⚠️

如果你是 AI 代理，請先閱讀 SYSTEM_OVERVIEW.md！

Optics 採用了一套基於 HSL 的複雜色彩系統，這與典型的設計系統有所不同。系統概述文檔解釋了以下內容：

• 為何沒有 --color-primary 令牌（請使用 --op-color-primary-base 替代）
• 三層令牌架構（HSL 基礎 → 比例 → 上層令牌）
• 如何查找和使用正確的令牌
• 常見錯誤及避免方法

關鍵要點：Optics 擁有 500 多個色彩令牌，它們按照可預測的比例系統進行組織，而非簡單的名稱 - 值對。

服務器概述

此 MCP 服務器為 Optics 設計系統提供了 14 種工具 和資源：

• 83 個設計令牌：基於真實 HSL 的色彩、基於計算的間距、排版、邊框和陰影
• 24 個組件：所有 Optics 組件，其準確的令牌依賴關係從 SCSS 中提取
• 7 個核心工具：查詢令牌、組件和文檔
• 7 個高級工具：主題生成、驗證、可訪問性檢查、代碼腳手架生成和樣式指南生成
• 5 個 MCP 提示：針對常見設計系統任務的預配置工作流程
• 文檔：設計系統指南和最佳實踐

架構

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

安裝

VS Code 🎨

快速設置：

1. 打開命令面板 → MCP: Open User Configuration
2. 添加以下配置：

   {
     "servers": {
       "optics": {
         "command": "npx",
         "args": ["-y", "optics-mcp"]
       }
     }
   }
   

3. 以 代理模式 打開 GitHub Copilot
4. 點擊工具圖標查看可用的 Optics 工具

或者 在工作區創建 .vscode/mcp.json 文件，並添加相同的配置。

官方 MCP 註冊表：可在 registry.modelcontextprotocol.io 查看 ✅

Cursor 🎯

一鍵安裝（點擊打開 Cursor）：

cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==

或者手動設置：

1. 打開 Cursor 設置 → MCP
2. 添加以下配置：

   {
     "servers": {
       "optics": {
         "command": "npx",
         "args": ["-y", "optics-mcp"]
       }
     }
   }
   

3. 與 Cursor AI 聊天以訪問 Optics 工具

快速開始（免安裝） ⚡

這是使用 Optics MCP 最簡單的方法，無需安裝！

Claude Desktop

在 MCP 配置中添加以下內容：

{
  "mcpServers": {
    "optics": {
      "command": "npx",
      "args": ["-y", "optics-mcp"]
    }
  }
}

Claude Code CLI

使用以下命令添加：

claude mcp add optics -- npx -y optics-mcp

其他有用命令：

# 列出所有 MCP 服務器
claude mcp list

# 移除 Optics 服務器
claude mcp remove optics

# 查看服務器詳細信息
claude mcp get optics

# 測試連接
claude mcp test optics

就這麼簡單！ 每當 MCP 客戶端需要時，服務器將自動運行。

本地安裝（用於開發）

如果你想修改服務器或做出貢獻，請執行以下操作：

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

然後使用本地路徑進行配置：

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

使用方法

直接運行

npm start

可用工具（共 14 種）

如需所有工具的詳細文檔，請參閱 TOOLS.md。

核心工具

• get_token：獲取特定設計令牌的詳細信息。
• search_tokens：按類別或名稱模式搜索設計令牌。
• get_token_usage_stats：獲取系統中設計令牌使用情況的統計信息。
• get_component_info：獲取組件的詳細信息，包括其設計令牌依賴關係。
• list_components：列出設計系統中所有可用的組件。
• get_component_tokens：獲取特定組件使用的所有設計令牌。
• search_documentation：搜索 Optics 文檔。

高級工具

• generate_theme：使用 CSS 變量和 Figma 變量 JSON 創建自定義品牌主題。
  • 輸出基於 HSL 的主題覆蓋
  • 生成 Figma 變量格式
  • 創建主題預覽
• validate_token_usage：查找代碼中應使用設計令牌的硬編碼值。
  • 檢測顏色、間距、字體、邊框、陰影
  • 建議令牌替換
  • 驗證令牌使用情況
• replace_hard_coded_values：自動將硬編碼值替換為設計令牌。
  • 手動模式：僅提供建議
  • 自動修復模式：應用替換
  • 保留代碼結構
• check_contrast：檢查令牌之間的 WCAG 顏色對比度。
  • 支持 AA 和 AAA 級別
  • 支持令牌名稱或十六進制顏色
  • 提供可訪問性建議
• suggest_token_migration：為舊代碼遷移建議令牌。
  • 將舊值映射到新令牌
  • 優先考慮語義令牌
  • 提供理由
• generate_component_scaffold：使用 Optics 令牌生成組件代碼。
  • 支持 React、Vue、Svelte、HTML
  • 預配置設計令牌
  • 包含 TypeScript 類型
• generate_sticker_sheet：生成視覺樣式指南，展示所有設計令牌和組件。
  • 完整的調色板和樣本
  • 排版比例示例
  • 間距可視化
  • 組件示例
  • 多框架支持（React、Vue、Svelte、HTML）
  • 輸出可用於生產的代碼

可用資源

服務器通過 optics:// URI 方案公開以下資源：

文檔

• optics://documentation/introduction - Optics 概述
• optics://documentation/getting-started - 入門指南
• optics://documentation/design-tokens - 設計令牌文檔
• optics://documentation/color-system - 色彩系統指南
• optics://documentation/spacing - 間距系統指南
• optics://documentation/typography - 排版指南
• optics://documentation/components - 組件庫概述
• optics://documentation/accessibility - 可訪問性指南

令牌

• optics://tokens/all - 所有設計令牌
• optics://tokens/color - 僅色彩令牌
• optics://tokens/spacing - 僅間距令牌
• optics://tokens/typography - 僅排版令牌

組件

• optics://components/all - 所有組件

設計系統概述

設計令牌類別

1. 顏色（25 個令牌）：基於 HSL 的色彩系統，包括主色、中性色和警示色
2. 間距（11 個令牌）：基於計算的 rem 單位，採用 10 進制比例（2px 到 80px）
3. 排版（32 個令牌）：Noto Sans/Serif 字體，包括字號、字重和行高
4. 邊框（10 個令牌）：邊框半徑（小到藥丸形）和寬度
5. 陰影（5 個令牌）：高程系統（極小到極大）

組件（共 24 個）

所有組件均從真實的 Optics SCSS 中提取，具有準確的令牌依賴關係：

• 手風琴：可摺疊內容面板
• 警報：通知消息（警告、危險、信息、通知）
• 頭像：用戶頭像
• 徽章：狀態指示器和標籤
• 麵包屑：導航層次結構
• 按鈕：具有不同變體的交互式按鈕
• 按鈕組：分組按鈕容器
• 卡片：具有高程效果的內容容器
• 確認對話框：操作確認模態框
• 分隔線：內容分隔符
• 表單：輸入字段、文本區域、選擇框
• 圖標：Material Symbols 圖標
• 模態框：覆蓋式對話框
• 導航欄：頂部導航
• 分頁：頁面導航
• 側邊面板：滑動側邊面板
• 側邊欄：側邊導航
• 加載指示器：加載狀態指示器
• 開關：切換開關
• 標籤頁：標籤式界面
• 表格：數據表
• 標籤：分類標籤
• 文本對：標籤 - 值對
• 工具提示：上下文信息

每個組件都指定了其所使用的 Optics 設計令牌，便於理解依賴關係並保持一致性。

開發

構建

npm run build

監聽模式

npm run watch

項目結構

optics-mcp/
├── src/
│   ├── index.ts          # MCP 服務器實現
│   └── optics-data.ts    # 設計令牌和組件數據
├── dist/                 # 編譯後的 JavaScript
├── package.json
├── tsconfig.json
└── README.md

令牌使用跟蹤

服務器跟蹤每個組件使用的設計令牌，實現以下功能：

• 依賴分析：瞭解組件依賴哪些令牌
• 影響分析：查看哪些組件會受到令牌更改的影響
• 使用統計：深入瞭解令牌使用模式

貢獻

若要添加新的設計令牌或組件，請按以下步驟操作：

1. 編輯 src/optics-data.ts 文件。
2. 將令牌添加到 designTokens 數組中。
3. 將組件添加到 components 數組中，並指定其令牌依賴關係。
4. 重新構建項目：npm run build

許可證

本項目採用 MIT 許可證。

鏈接

• Optics 設計系統文檔
• 模型上下文協議
• MCP TypeScript SDK