Coolors MCP

Coolors MCP

支持 Material Design 3、CSS 主题匹配、图像颜色提取和无障碍合规的高级颜色操作 MCP 服务。

功能

• 🎨 颜色空间转换 - RGB、HSL、HSV、LAB、XYZ 和 Google 的 HCT
• 📏 感知颜色指标 - Delta E（76/94/2000）和基于 HCT 的距离
• 🎭 Material Design 3 - 生成包含色调调色板的完整主题
• 🔍 智能主题匹配 - 为任意颜色查找最接近的 CSS 变量
• 🖼️ 图像颜色提取 - 使用 Celebi 量化提取主色
• ♿ WCAG 合规 - 自动检查对比度
• 🔄 CSS 重构 - 自动使用主题变量替换旧版颜色
• 🎯 上下文感知 - 针对文本、背景和边框采用不同的匹配策略
• 🌈 高级调色板生成 - 创建包含锁定颜色的调色板
• 🎨 渐变生成 - 使用多种插值方法创建平滑渐变
• 🚫 厌恶度分析 - 检测并修复普遍不受欢迎的颜色
• 👁️ 色盲模拟 - 使用 Brettel/Machado 矩阵模拟红色盲、绿色盲和蓝黄色盲，并进行无障碍审查
• 🆎 APCA 对比度 - 除经典 WCAG 2.x 比率外，还提供 WCAG 3 草案中的对比度（Lc）
• 🎚️ 色调比例与状态颜色 - Tailwind 风格的 50–950 比例，以及 HCT 中的悬停/激活/焦点/禁用变体
• 🧬 调色板协调度评分 - 量化视觉统一性（色调／彩度／色相协调度），并提供针对性的修复建议
• 🪪 语义调色板 - 从一种品牌色生成统一色系中的主色/次色/第三色，以及成功/警告/错误/信息颜色
• 📦 调色板导出 - CSS 自定义属性、SCSS、Tailwind 配置、W3C 设计令牌、JSON

安装

方法 1：NPX（推荐）

无需安装 - 直接运行：

Claude Desktop 配置

{
  "mcpServers": {
    "coolors": {
      "command": "npx",
      "args": ["-y", "@trishchuk/coolors-mcp"]
    }
  }
}

Claude Code 配置

claude mcp add coolors --npm-package @trishchuk/coolors-mcp

方法 2：NPM 安装

npm install @trishchuk/coolors-mcp

方法 3：从源代码安装

git clone https://github.com/x51xxx/coolors-mcp
cd coolors-mcp
pnpm install
pnpm run build

快速开始

作为 MCP 服务运行

# Run the built server
node dist/bin/server.js

# Or use with MCP Inspector for testing
npx fastmcp inspect src/bin/server.ts

使用 Claude Desktop 配置

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "coolors": {
      "command": "node",
      "args": ["/path/to/coolors-mcp/dist/bin/server.js"]
    }
  }
}

可用工具

核心颜色操作

convert_color

在不同格式（hex、rgb、hsl、lab、hct）之间转换颜色。

{
  "color": "#6750a4",
  "to": "hct"
}
// Output: "hct(258.1, 47.3, 41.2)"

color_distance

计算颜色之间的感知距离。

{
  "color1": "#6750a4",
  "color2": "#7f67be",
  "metric": "deltaE2000"
}
// Output: "Distance: 8.45"

check_contrast

检查两种颜色之间的对比度。支持 WCAG 2.x 亮度比率（默认）、APCA Lc（WCAG 3 草案），或并排显示两者。

{
  "foreground": "#000000",
  "background": "#ffffff",
  "algorithm": "both"  // "wcag" (default) | "apca" | "both"
}
// Output: WCAG 21.00:1 + APCA Lc 106.0

adjust_color

对颜色进行变亮／变暗／提高饱和度／降低饱和度／灰度化／反转／混合处理。

{
  "color": "#6750a4",
  "operation": "mix",
  "with": "#ff6b6b",
  "amount": 0.5  // weight (0-1) for mix, percent (0-100) for the others
}

调色板生成

generate_palette

生成调色板（单色、类似色、互补色、三角色、四角色）。

{
  "baseColor": "#6750a4",
  "type": "analogous",
  "count": 5
}

generate_palette_with_locks

生成调色板，同时保留指定颜色。

{
  "lockedColors": ["#6750a4", "#ff6b6b"],
  "totalColors": 7,
  "mode": "harmony",  // or "contrast", "gradient"
  "colorSpace": "lab"  // or "hsl"
}

generate_gradient

使用高级插值创建平滑渐变。

{
  "colors": ["#6750a4", "#ff6b6b"],
  "steps": 10,
  "interpolation": "lab",  // or "hsl", "rgb", "lch", "hct"
  "easing": "ease-in-out",  // or "linear", "ease-in", "ease-out"
  "format": "css-linear"  // or "array", "hex", "css-radial"
}

Material Design 3

generate_material_theme

生成完整的 Material Design 3 颜色主题。

{
  "sourceColor": "#6750a4",
  "includeCustomColors": true
}

generate_tonal_palette

创建 Material Design 色调调色板。

{
  "color": "#6750a4",
  "tones": [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
}

harmonize_colors

协调多种颜色，使它们相互搭配。

{
  "colors": ["#6750a4", "#ff6b6b", "#4ecdc4"],
  "method": "harmonize",  // or "blend", "temperature"
  "factor": 0.5
}

CSS 主题匹配

match_theme_color

为任意颜色查找最接近的主题变量。

{
  "color": "#6850a0",
  "themeCSS": ":root { --color-primary-40: #6750a4; }",
  "context": "background",
  "minConfidence": 70
}

refactor_css_with_theme

自动重构 CSS，使其使用主题变量。

{
  "css": ".button { background: #6750a4; }",
  "themeCSS": ":root { --color-primary-40: #6750a4; }",
  "preserveOriginal": true,
  "generateReport": true
}

generate_theme_css

为完整主题生成 CSS 自定义属性。

{
  "sourceColor": "#6750a4",
  "prefix": "color",
  "includeTones": [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100]
}

图像颜色提取

extract_image_colors

使用 Celebi 量化从图像中提取主色。

{
  "imageData": {
    "data": [/* RGBA array */],
    "width": 1920,
    "height": 1080
  },
  "maxColors": 5,
  "quality": "high",
  "format": "json"
}

generate_theme_from_image

根据图像颜色生成 Material Design 主题。

{
  "imageData": {/* image data */},
  "isDark": false,
  "includeCustomColors": true
}

视觉协调度

generate_tonal_scale

根据一种种子颜色构建 Tailwind 风格的 50/100/.../900/950 比例。使用 HCT，确保无论色相如何，各级之间的感知差异都均匀。

{
  "seed": "#6750a4",
  "name": "brand",        // CSS variable base name
  "chromaBoost": 1,       // multiplier on seed chroma
  "stops": [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
}

generate_state_colors

根据基础颜色推导交互状态（悬停／激活／按下／聚焦／禁用／选中），并保持色调变化一致。

{
  "base": "#6750a4",
  "isDark": false   // true to lighten on hover instead of darkening
}

analyze_palette_consistency

评估调色板的视觉协调性：色调阶梯均匀度、彩度分布、色相协调性，并给出单一的 0–100 分数和有针对性的建议。

{
  "colors": ["#6750a4", "#7f67be", "#a48dc8", "#ff0000"]
}
// Output: cohesion 77/100 + outlier #ff0000 (chroma 105 vs avg 60)

generate_semantic_palette

根据一种品牌色生成主色／次色／第三色，以及成功／警告／错误／信息色，并对彩度和色调进行归一化，让所有颜色看起来属于同一色系。

{
  "brand": "#6750a4",
  "isDark": false
}

无障碍与色盲

simulate_color_blindness

模拟红色盲／绿色盲／蓝黄色盲（及较轻的异常类型，以及全色盲）用户所看到的颜色。使用 Machado 风格的线性 sRGB 混淆线矩阵。

{
  "colors": ["#e63946", "#2a9d8f"],
  "types": ["protanopia", "deuteranopia"]  // optional, defaults to all 7
}

check_palette_accessibility

审查调色板是否对色盲用户友好——标记在每种 CVD 类型下会变得难以区分的颜色对。

{
  "colors": ["#e63946", "#2a9d8f", "#264653", "#f4a261"],
  "indistinguishableThreshold": 10  // ΔE2000 below which colors collide
}

调色板导出

export_palette

将调色板导出为 CSS 自定义属性、SCSS 变量、Tailwind 配置片段、W3C 设计令牌或 JSON。

{
  "colors": ["#fef3c7", "#fde68a", "#fcd34d"],
  "format": "tailwind",   // "css" | "scss" | "tailwind" | "tokens" | "json"
  "prefix": "amber",
  "names": ["50", "100", "200"]   // optional, default uses 50/100…900 scale
}

色彩心理学

analyze_color_likability

检查颜色是否落入普遍不受欢迎的范围。

{
  "color": "#6b6b00"  // Dark yellow-green
}
// Output: Analysis with fix suggestions

fix_disliked_colors_batch

自动修正多个不受欢迎的颜色。

{
  "colors": ["#6b6b00", "#7a7a10", "#808020"],
  "strategy": "hue_shift"  // or "desaturate", "brighten"
}

色彩科学

HCT 色彩空间

Google 的 HCT（色相、彩度、色调）色彩空间提供：

• 色相（0-360°）：色轮上的位置
• 彩度（0-150）：颜色强度
• 色调（0-100）：具有 WCAG 对比度保证的明度

主要优势：

• 色调差值为 40 = 3:1 对比度
• 色调差值为 50 = 4.5:1 对比度
• 感知均匀，适用于 UI 设计

插值方法

用于生成渐变的不同色彩空间：

• RGB：简单，但可能产生浑浊的颜色
• HSL：适用于基于色相的过渡
• LAB：感知均匀的亮度
• LCH：圆柱形 LAB，可实现平滑的色相过渡
• HCT：针对 Material Design 优化

主题匹配算法

多因素评分系统：

1. 感知距离（60%） - 基于 HCT 的相似度
2. 语义上下文（20%） - 角色适用性
3. 无障碍性（20%） - 对比度合规性

开发

本项目使用 pnpm。使用 npm i -g pnpm 或 corepack enable 安装一次即可。

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

# Format code
pnpm run format

# Lint
pnpm run lint

架构

src/
├── bin/
│   └── server.ts               # MCP server entry
├── tools/                      # Tool implementations
│   ├── color-conversion.tool.ts
│   ├── color-distance.tool.ts
│   ├── contrast-checker.tool.ts
│   ├── palette-generator.tool.ts
│   ├── palette-with-locks.tool.ts
│   ├── gradient-generator.tool.ts
│   ├── material-theme.tools.ts
│   ├── theme-matching.tools.ts
│   ├── image-extraction.tools.ts
│   └── dislike-analyzer.tool.ts
├── color/                      # Core color utilities
│   ├── conversions.ts          # Color space conversions
│   ├── metrics.ts              # Distance calculations
│   ├── utils.ts                # Color utilities
│   ├── hct/                   # HCT color space
│   ├── quantize/               # Celebi quantization
│   ├── score/                  # Color scoring
│   └── dislike/                # Dislike analysis
└── theme/                      # Theme system
    ├── parser.ts               # CSS parsing
    ├── matcher.ts              # Variable matching
    └── refactor.ts             # CSS refactoring

使用场景

设计系统迁移

将硬编码颜色转换为 CSS 变量，并提供置信度分数。

无障碍合规

确保所有颜色组合都符合 WCAG AA/AAA 标准。

采用 Material Design

生成包含色调调色板的完整 Material Design 3 主题。

品牌色协调

创建彼此协调的调色板。

基于图像的主题设计

从徽标或照片中提取颜色，生成匹配的主题。

渐变设计

为现代 UI 创建平滑且感知均匀的渐变。

贡献

欢迎贡献！请确保：

• 测试通过（pnpm test）
• 代码已格式化（pnpm run format）
• 类型检查通过（pnpm run lint）

许可证

MIT © Taras Trishchuk

致谢

• 使用 Anthropic 的 MCP SDK 构建
• 集成了 Google 的 Material Color Utilities 算法
• HCT 色彩空间为 Material Design 3 开发
• 使用 Celebi 量化算法实现最佳颜色提取