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