Optics MCP Server

光学MCP服务器

光学设计系统的模型上下文协议（MCP）服务器，使LLM能够理解和使用来自https://docs.optics.rolemodel.design.

⚠️ 重要提示：了解光学

如果你是一名AI代理，请阅读 SYSTEM_OVERVIEW.md 第一！

Optics使用了一种复杂的基于HSL的颜色系统，与典型的设计系统不同。系统概述解释了：

• 为什么没有 --color-primary 令牌（使用 --op-color-primary-base 相反）
• 三层令牌架构（HSL基础→ 规模→ 关于代币）
• 如何找到和使用正确的令牌
• 常见错误以及如何避免

关键见解： Optics有500多种颜色标记，它们被组织成一个可预测的比例系统，而不是简单的名称-值对。

概述

此MCP服务器提供 14工具 以及使用光学设计系统的资源：

• 83个设计代币：真正的基于HSL的颜色、基于计算的间距、排版、边框和阴影
• 24个组件：从SCSS中提取具有精确令牌依赖关系的所有光学组件
• 7核心工具：查询标记、组件和文档
• 7高级工具：主题生成、验证、可访问性检查、代码脚手架和样式指南生成
• 5 MCP提示：用于常见设计系统任务的预配置工作流
• 文档：设计系统准则和最佳做法

建筑

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

安装

VS Code🎨

快速设置:

1. 命令面板→ MCP：打开用户配置
2. 添加此配置：

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

1. 打开GitHub Copilot 代理模式
2. 单击工具图标查看可用的光学工具

或 创建 .vscode/mcp.json 在您的工作区中使用相同的配置。

MCP官方登记处：列在 register.modelcontextprotocol.io ✅

光标🎯

一键安装 （单击打开光标）：

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

或手动设置:

1. 打开光标设置→ 主控程序
2. 添加此配置：

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

1. 与Cursor AI聊天以访问光学工具

快速启动（零安装）⚡

使用光学MCP的最简单方法-无需安装！

克劳德桌面版

添加到MCP配置中：

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

Claude 代码命令行界面

使用单个命令添加：

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

其他有用的命令：

# 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

就是这样！ 只要您的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://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个代币）：以10为底的基于计算的rem单位（2px至80px）
3. 排版 （32个标记）：Noto Sans/Serif字体，具有大小、粗细和线条高度
4. 边界 （10个标记）：边界半径（小到药丸）和宽度
5. 阴影 （5个标记）：仰角系统（从x小到x大）

组件（共24个）

从具有精确令牌依赖关系的真实Optics SCSS中提取的所有组件：

• 手风琴：可折叠内容面板
• 警报：通知消息（警告、危险、信息、通知）
• 阿凡达：用户资料图片
• 徽章：状态指示器和标签
• 面包屑：导航层次结构
• 按钮：带有变体的交互式按钮
• 按钮组：分组按钮容器
• 卡：带标高的内容物容器
• 确认对话框：动作确认模式
• 分隔线：内容分隔符
• 表格：输入字段、文本区域、选择
• 图标：材质符号图标
• 模态：叠加对话框
• 导航栏：顶部导航
• 分页：页面导航
• 侧面板：滑动侧板
• 侧边栏：侧向导航
• 旋转器：加载指示器
• 开关：切换开关
• 选项卡：标签界面
• 表格：数据表
• 标签：分类标签
• 文本对：标签值对
• 工具提示：背景信息

每个组件都指定了它使用的Optics设计令牌，从而易于理解依赖关系并保持一致性。

发展

构建

npm run build

观看模式

npm run watch

项目结构

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

令牌使用跟踪

服务器跟踪每个组件使用的设计令牌，从而实现：

• 相关性分析：了解组件所依赖的令牌
• 影响分析：查看哪些组件受到令牌更改的影响
• 使用统计：深入了解代币使用模式

贡献

要添加新的设计标记或组件，请执行以下操作：

1. 编辑 src/optics-data.ts
2. 将令牌添加到 designTokens 数组
3. 将组件添加到 components 数组，指定其令牌依赖关系
4. 重建项目： npm run build

许可证

麻省理工学院

链接

• 光学设计系统文档
• 模型上下文协议
• MCP TypeScript SDK