内容
# 色彩调色板提取器MCP
[](https://github.com/aka-kika/color-palette-extractor-mcp/actions/workflows/build.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
MCP 服务器，可将图像转换为可访问的、导出的颜色调色板。完全本地化 — 没有图像离开本地。包括窗口检测，以便截图获取应用程序 + 壁纸调色板 **分离**，以及一键式交付生成器，构建一个完整的每个图像文件夹，包含预览、导出、README 和 HTML 设计系统指南。
**9 种工具** · 窗口感知提取 · 端到端交付生成器 · 完全本地化处理。
## 工具
### `build_palette_folder` — 主要工具
端到端流程：检测应用程序窗口 → 提取应用程序 + 壁纸调色板分别 → 检测源模式（暗/亮）并派生逆模式 → 渲染预览 → 以 5 种格式写入导出 → 写入 README.md → 生成 HTML 设计系统指南，带有暗/亮切换和主题页面边框 → 使用无头 Chrome 截图指南。一次调用，一个文件夹，25 个文件。
参数：
- `target_mode`（`"auto"` / `"dark"` / `"light"`）— 控制交付成果中哪个主题被标记为主要。两个主题始终都会生成；自动检测选择主要主题以匹配源亮度。
- `brand_mode`（`"auto"` / `"brand"` / `"ui"`）— 控制源是被视为品牌调色板还是 UI 截图。在 **brand** 模式下，导出为 `brand.{...}` （要发送的令牌）加上 `demo-inverse.{...}` （品牌逆调的预览 — 清晰标记，*不是*推荐的 UI 主题）。HTML 指南使用“品牌调色板”标题和一个横幅，解释逆调仅供参考。**自动**模式下，如果窗口填充图像且没有壁纸（例如设计系统表、模拟器上的中性背景），则选择品牌模式；否则选择 UI 模式（当前行为，`app-{light,dark}.{...}`导出）。
你会得到：
- HTML 指南的边框（页面背景、面板、标题、页脚、表格、切换按钮）根据调色板进行主题化 — 浅色主题在浅色页面上渲染，深色主题在深海军蓝页面上渲染，两者都带有品牌的提取强调色作为切换高亮。两个状态之间有 250ms 的渐变。
- 边框从品牌强调色中着色（不是硬编码的蓝色）— 暗模式标签药丸、切换按钮高亮和部分标签都使用品牌的强调色的色调。在温暖的灰色调色板上，页面呈现温暖的灰色；在板岩调色板上，页面呈现板岩色；在粉色调色板上，页面呈现粉色。
### 其他八种工具
- `extract_palette` — 从图像 URL 或路径中进行 k-means / median-cut 提取。可选的 `min_population_ratio` （默认 `0.001`）保留小强调色。
- `extract_app_palette` — 自动检测截图中的应用程序窗口，并返回 **单独**的前景（应用程序）和背景（壁纸）调色板。
- `score_accessibility` — 调色板对之间的 WCAG AA/AAA 对比度。
- `suggest_role` — 为选择的用途分配 `background` / `text` / `accent` / `surface` / `muted`。
- `export_palette` — 输出 `css_vars` / `scss` / `tailwind` / `figma_tokens` / `json` / `ase`。
- `harmonize` — 从种子中生成类似色 / 三色 / 互补色 / 分割 / 四色 / 单色。
- `match_vibe` — 为情绪描述（“森林黄昏”，“东京霓虹”…）精选调色板。
- `compare_palettes` — 两个调色板之间的 ΔE2000 感知差异。
## 资源
- `palette://recent` — 此会话中的最后 20 个提取的调色板。
## 提示
- `design_system_audit` — 审核调色板的 a11y + 结构质量。
- `a11y_fixer` — 提出一个重新调整的调色板，通过 WCAG AA。
## 代理技能
一个可立即使用的 `color-palette-mcp` 技能与存储库一起打包在 `.skills/color-palette-mcp/` 中。它包括：
- `SKILL.md` — 入口点：何时使用工具，实际需要的工具（`build_palette_folder`），`brand_mode` 的决策树（自动/品牌/UI），参数速查表，自动检测规则，JSON 响应形状，以及代理应注意的故障模式
- `references/full-tool-reference.md` — 每个工具的每个参数，详尽
- `references/brand-vs-ui-examples.md` — 真实图像上的示例，何时使用每种模式
- `references/output-folder-shape.md` — 每个模式下生成的确切文件
其他代理（goose、Claude、Codex 等）可以 `load_skill color-palette-mcp` 立即了解如何使用此 MCP 而无需阅读完整的 README。技能不包含在 npm tarball 中 — 它捆绑在 GitHub 源代码中以供直接克隆。
## 安装
```bash
cd color-palette-mcp
npm ci # 可复制安装（匹配 CI）
npm test # 18 个单元测试（颜色数学 + SSRF 防护）
npm run build
```
**要求：** Node ≥ 18。CI 在 `ubuntu-latest` 上运行，跨 Node 18 和 22（放弃 Node 20，因为 GitHub 在运行器上弃用了它），并在类型检查、测试套件和运行时依赖项 `npm audit` 上设置门槛。
### 作为已发布的包安装（发布到 npm 后）
```bash
npm install -g color-palette-extractor-mcp # 然后在任何 MCP 客户端中使用二进制名称
# 或
npx color-palette-extractor-mcp # 一次调用
```
**自行发布：** 存储库的源代码以 `color-palette-extractor-mcp` 的名称发布（原始 `color-palette-mcp` 被 npm 上的另一个作者占用）。要发布新版本：
```bash
npm login # 一次性
npm version patch # 或 minor / major
npm publish # 运行 `prepublishOnly` → `npm run build`
```
## 在本地运行
```bash
npm run dev
```
## 连接到 MCP 客户端
添加到您的 MCP 配置（例如 Claude Desktop）：
**本地安装（当前设置）：**
```json
{
"mcpServers": {
"color-palette": {
"command": "node",
"args": ["/absolute/path/to/color-palette-extractor-mcp/dist/server.js"]
}
}
}
```
**在 `npm install -g color-palette-extractor-mcp` 之后：**
```json
{
"mcpServers": {
"color-palette": {
"command": "color-palette-extractor-mcp"
}
}
}
```
## 配置
两者都是可选的环境变量：
- `PALETTE_OUTPUT_DIR` — `build_palette_folder` 将其交付文件夹写入此处。默认为 `<cwd>/output`。当连接到始终在线的 MCP 客户端时，将其设置为固定、可写入的路径，以便输出不会落在客户端启动的任意目录中。
- `CHROME_PATH` — 设计指南截图的 Chrome/Chromium 二进制文件的路径。默认为 macOS 上的系统 Google Chrome 安装；如果未设置且未找到 Chrome，则仍会写入 HTML 指南，但不包含 `index.png`。
## 安全
完全本地化 — 没有图像数据离开机器。服务器针对工具参数来自不受信任的源（例如，注入内容的代理）的情况下进行了加强：
- **无 Shell** — 无头 Chrome 截图使用参数数组生成，因此 `output_dir` 不能变成 Shell 命令。
- **转义 HTML** — 渲染到设计系统指南中的每个动态值在无头 Chrome 渲染之前都会进行 HTML 转义。
- **SSRF 防护 Fetch** — `image_url` 下载拒绝私有/环路/本地主机和非 http(s) 方案，重新验证每个重定向，在 10 秒后超时，最大大小为 25 MB。
`image_path` 读取和 `PALETTE_OUTPUT_DIR` 写入不受设计限制 — 以您给予任何本地文件工具的权限运行服务器。
## 示例对话
> *"从 `/Users/me/Screenshots/inbox.png` 为我创建一个调色板文件夹。"*
模型调用 `build_palette_folder` 一次，你会得到一个类似 `inbox_2026-06-29_13-10-00_a1b2c3d4/` 的文件夹，包含：
```
README.md ← 调色板、角色、人口、a11y、比较
index.html ← 交互式设计系统指南
index.png ← 指南截图
source.png ← 原始图像
app-window-cropped.png ← 检测到的应用程序区域
preview-app-dark.png ← 视觉色块
preview-app-light.png
preview-wallpaper.png
preview-app-pair.png ← 暗 vs 亮
preview-all.png
exports/
app-dark.{css_vars,scss,tailwind,json,figma}
app-light.{css_vars,scss,tailwind,json,figma}
wallpaper.{css_vars,scss,tailwind,json,figma}
```
文件夹名称为 `{stem}_{ISO timestamp}_{8-char sha256 of file contents}`，因此在同一图像上重新运行，时间不同，仍会创建新文件夹。
## 示例输出
一个真实的交付成果被检入 [`examples/akakika-com/`](examples/akakika-com/) — 通过运行 `build_palette_folder` 在 [akakika.com](https://akakika.com) 的截图上生成。打开 [`examples/akakika-com/index.html`](examples/akakika-com/index.html) 获取交互式指南，或 `index.png` 获取静态预览。
## 另见
- **`GUIDE.md`** — 完整的操作手册：何时使用每个工具、常见工作流程、故障排除、限制。
