optics-mcp

Name: optics-mcp
Author: RoleModel

本地服务

github.com/RoleModel开发工具137 周前更新

代码仓库

关于 optics-mcp

optics-mcp 是一个 MCP 服务，为 AI 客户端提供 Optics Design System 的设计令牌、组件和文档。它还提供主题生成、令牌校验、无障碍检查、代码脚手架和样式指南生成功能。

主要功能

01查询设计令牌和组件
02搜索 Optics 文档
03生成主题和样式指南
04校验令牌使用并替换硬编码值
05检查颜色对比度并建议迁移
06为多种框架生成组件脚手架

适用场景

01实现界面时查询设计令牌
02检查代码中的硬编码样式
03评估设计令牌之间的对比度
04生成带主题的组件脚手架

MCP 相关

该服务向 MCP 客户端提供 Optics 工具、文档、令牌、组件和提示词。工具涵盖设计系统查询、生成、校验及无障碍检查。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y optics-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmoptics-mcp0.2.6stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
tokenName	string	是	设计令牌的名称（例如，"color-primary"、"spacing-md"）

详细介绍

Optics MCP 服务

一个用于 Optics Design System 的 Model Context Protocol（MCP）服务，使大模型能够理解和使用 https://docs.optics.rolemodel.design 中的设计令牌、组件和文档。

⚠️ 重要：了解 Optics

如果你是 AI Agent，请先阅读 SYSTEM_OVERVIEW.md！

Optics 使用一种复杂的、基于 HSL 的颜色系统，与典型的设计系统不同。系统概览会说明：

为什么没有 --color-primary 令牌（请改用 --op-color-primary-base）
三层令牌架构（HSL 基础值 → Scale → On 令牌）
如何查找和使用正确的令牌
常见错误及其避免方法

关键要点： Optics 有 500 多个颜色令牌，它们按可预测的比例系统组织，而非简单的名称—值对。

概述

此 MCP 服务提供 14 个工具和资源，用于使用 Optics 设计系统：

83 个设计令牌：基于真实 HSL 的颜色、基于 calc 的间距、排版、边框和阴影
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 🎨

快速设置：

命令面板 → MCP: Open User Configuration
添加以下配置：

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

在 Agent Mode 中打开 GitHub Copilot
点击工具图标，查看可用的 Optics 工具

或者，在工作区中创建 .vscode/mcp.json，并填入相同配置。

官方 MCP Registry：已在 registry.modelcontextprotocol.io 收录 ✅

Cursor 🎯

一键安装（点击以打开 Cursor）：

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

或者手动设置：

打开 Cursor 设置 → MCP
添加以下配置：

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

与 Cursor AI 聊天以使用 Optics 工具

快速开始（零安装）⚡

使用 Optics MCP 最简单的方法——无需安装！

Claude Desktop

添加到 MCP 配置中：

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

Claude Code CLI

使用一条命令添加：

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 Variables JSON 的自定义品牌主题。

输出基于 HSL 的主题覆盖值
生成 Figma Variables 格式
创建主题预览

`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 - 所有组件

设计系统概览

设计令牌类别

颜色（25 个令牌）：基于 HSL 的颜色系统，包含主色、中性色和警示色
间距（11 个令牌）：基于 calc 的 rem 单位，采用基数为 10 的比例（2px 至 80px）
字体排版（32 个令牌）：Noto Sans/Serif 字体，包含字号、字重和行高
边框（10 个令牌）：圆角（从小到药丸形）和宽度
阴影（5 个令牌）：层级系统（从极小到极大）

组件（共 24 个）

所有组件均提取自实际的 Optics SCSS，并准确标注了令牌依赖关系：

Accordion：可折叠内容面板
Alert：通知消息（警告、危险、信息、提示）
Avatar：用户头像
Badge：状态指示器和标签
Breadcrumbs：导航层级
Button：带不同变体的交互按钮
ButtonGroup：分组按钮容器
Card：带层级效果的内容容器
ConfirmDialog：操作确认模态框
Divider：内容分隔线
Form：输入框、文本区域和选择框
Icon：Material Symbols 图标
Modal：覆盖层对话框
Navbar：顶部导航
Pagination：页面导航
SidePanel：滑出式侧边面板
Sidebar：侧边导航
Spinner：加载指示器
Switch：切换开关
Tab：选项卡界面
Table：数据表格
Tag：分类标签
TextPair：标签-值对
Tooltip：上下文信息

每个组件都会标明其使用的 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

令牌使用情况跟踪

服务会跟踪每个组件使用的设计令牌，从而支持：

依赖分析：了解组件依赖哪些令牌
影响分析：查看令牌变更会影响哪些组件
使用统计：了解令牌的使用模式

贡献

如需添加新的设计令牌或组件：

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

许可证

MIT

链接

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

optics-mcp

关于 optics-mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Optics MCP 服务

⚠️ 重要：了解 Optics

概述

架构

安装

VS Code 🎨

Cursor 🎯

快速开始（零安装）⚡

Claude Desktop

Claude Code CLI

本地安装（用于开发）

用法

直接运行

可用工具（共 14 个）

核心工具

get_token

search_tokens

get_token_usage_stats

get_component_info

list_components

get_component_tokens

search_documentation

高级工具

generate_theme

validate_token_usage

replace_hard_coded_values

check_contrast

suggest_token_migration

generate_component_scaffold

generate_sticker_sheet