# sketch-to-html-mcp

一个基于 Model Context Protocol (MCP) 的 server，用于解析 `.sketch` 设计稿（从 js.design 导出）为 CSS-aligned 的、对 LLM 友好的 JSON，让 AI 编码 agent 能高保真地生成 HTML/Vue/React 等代码。

## 功能特性

- **基于命名约定的过滤**：通过 `#WEB#/#NATIVE#/#NOTE#` 前缀标记图层，原生界面自动跳过，注释与目标图层关联
- **CSS-aligned 输出**：Sketch 字段映射为 CSS 属性名（`backgroundColor`、`flexDirection`、`boxShadow` 等），贴合 LLM 训练数据
- **布局推断**：自动将自由布局转换为 flexbox，无法推断时回退为绝对定位
- **资源导出**：位图导出为 WebP/PNG（`@3x` 文件名规范），矢量图标导出为 SVG
- **设计 token 提取**：提取颜色和文字样式，给出 SCSS 变量建议

## 快速开始

```bash
npm install
npm run build
```

在 `opencode.json` 中注册：

```jsonc
{
  "mcp": {
    "sketch-to-html": {
      "type": "local",
      "command": ["node", "D:/fjc/code/work/AI/tools/mcp-servers/sketch-to-html/dist/index.cjs"],
      "env": {
        "DEFAULT_IMAGE_SCALE": "3",
        "DEFAULT_IMAGE_FORMAT": "webp"
      }
    }
  }
}
```

### 环境变量

| 变量 | 作用 | 默认值 |
| --- | --- | --- |
| `DEFAULT_IMAGE_SCALE` | 图片导出倍率 | `3` |
| `DEFAULT_IMAGE_FORMAT` | 图片导出格式（webp/png） | `webp` |

## 提供的工具

| 工具 | 作用 |
| --- | --- |
| `list_artboards` | 列出画板，报告包含 `#WEB#` 标记图层的画板及顶层 WEB 入口 |
| `get_layer_tree` | **核心工具**：返回 CSS-aligned 图层树 JSON + `#NOTE#` 注释 + symbols 字典 |
| `export_image` | 导出位图图层为 webp/png 到指定目录（默认 3 倍图） |
| `export_svg` | 导出矢量图层为 SVG |
| `get_design_tokens` | 提取颜色/字体 design tokens，生成 SCSS 变量建议 |

## 使用流程

```
1. list_artboards → 发现 #WEB# 入口
2. get_design_tokens → 得到颜色/字体变量
3. get_layer_tree → 得到 CSS-aligned 图层树 + 注释
4. 对 image 图层调 export_image → 图片导出到 public/images/
5. AI 综合数据 + 项目规范 → 生成代码
```

## 使用注意

- `export_image` / `export_svg` 的 `outputDir`：先询问用户目标目录；用户未回答时默认 `public/images/`
- `fileName`：由 AI 自行生成有意义的名称（避免与现有文件重名），不确定时询问用户。默认从图层名生成的文件名会剥掉非 ASCII 字符，中文图层名会退化成无意义的名字

## 图层命名规范

完整规范见 [`docs/naming-convention.md`](docs/naming-convention.md)。快速一览：

| 前缀 | 含义 |
| --- | --- |
| `#WEB#pageId-path` | UI 内容 — 转换为代码 |
| `#NATIVE#xxx` | 原生界面 — 跳过 |
| `#NOTE#pageId-path` | 注释文本 — 关联到 `#WEB#` 目标图层 |

嵌套图层：子图层标记优先级高于祖先图层。

## 项目记忆

实现细节、设计决策、开发进度见 [`PROJECT_MEMORY.md`](PROJECT_MEMORY.md)。

## 状态

核心功能已实现并通过测试（125 个测试全部通过），当前处于 AI 实际生成代码的集成验证阶段。