# 🧩 componentize

> **截图 → 可复用的 Tailwind 组件。一行命令，任何 AI 都能用。**

```
npx @monlohua/componentize
```

[![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![Tailwind](https://img.shields.io/badge/Tailwind-CSS-06B6D4)](https://tailwindcss.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## ✨ 这是干什么的？

把任意设计截图扔进来 → componentize 自动识别每个 UI 组件，输出**独立的 Tailwind HTML 文件**。

不是生成一整页——是**拆组件**。像给建筑拍张照，拿回一箱砖。

```
                     componentize
  ┌──────────────┐       ▶       ┌─────────────────────┐
  │              │               │  navbar.html         │  ← 导航栏
  │  设计截图     │               │  hero-section.html   │  ← 主视觉
  │  (1440×900)  │               │  feature-card.html   │  ← 可复用
  │              │               │  pricing-table.html  │  ← 可复用
  │              │               │  testimonials.html   │  ← 可复用
  │              │               │  footer.html         │
  └──────────────┘               │  preview.html        │  ← 预览选组件
                                 └─────────────────────┘
```

---

## 🔥 为什么用这个？

| 功能 | componentize | 其他截图→代码工具 |
|------|-------------|----------------|
| 输出**独立组件**，不是一整页 | ✅ | ❌ 大多整页生成 |
| **任何 AI 都能用**（MCP 协议） | ✅ Claude / Cursor / Windsurf / Copilot | ❌ 锁定单一平台 |
| **零服务器**，本地运行 | ✅ | ❌ 很多要部署 |
| **可视化预览**，勾选再导出 | ✅ 浏览器预览 | ❌ 盲输出 |
| **全开源**，代码可审计 | ✅ MIT | ❌ |

---

## 🚀 快速开始（零配置）

### 你已经是 Claude Code 用户？

**不需要任何配置。** componentize 会自动读取你 Claude Code 已有的 API Key，直接使用。

在 Claude Code `~/.claude/settings.json` 中添加：

```json
{
  "mcpServers": {
    "componentize": {
      "command": "npx",
      "args": ["@monlohua/componentize"]
    }
  }
}
```

重启 Claude Code，直接开用。

### 用其他 AI 工具？

<details>
<summary><b>Cursor</b></summary>

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "componentize": {
      "command": "npx",
      "args": ["@monlohua/componentize"],
      "env": {
        "COMPONENTIZE_API_KEY": "你的 API Key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

```json
// .windsurfrules
MCP servers:
  componentize:
    command: npx
    args: ["@monlohua/componentize"]
    env:
      COMPONENTIZE_API_KEY: "你的 API Key"
```
</details>

### 自备 API Key

推荐提供商：

| 提供商 | 推荐模型 | 识图质量 | 国内直连 |
|--------|---------|---------|---------|
| [硅基流动](https://cloud.siliconflow.cn) | Qwen3-VL-32B | ⭐⭐⭐⭐⭐ | ✅ 是 |
| [阿里通义千问](https://dashscope.aliyun.com) | qwen-vl-max | ⭐⭐⭐⭐ | ✅ 是 |
| [OpenAI](https://platform.openai.com) | GPT-4o | ⭐⭐⭐⭐⭐ | ❌ 需代理 |

设置环境变量：

```bash
export COMPONENTIZE_API_KEY="sk-xxx"
export COMPONENTIZE_BASE_URL="https://api.siliconflow.cn/v1"
export COMPONENTIZE_MODEL="Qwen/Qwen3-VL-32B-Instruct"
```

---

## 📖 使用教程

### 场景：你看中了一个页面，想拿来用

**第 1 步：给 AI 截图**

直接跟你的 AI 说：

```
分析这个截图里的组件：D:\设计稿\首页.png
```
或者
```
截这个网站并分析组件：https://stripe.com
```

**第 2 步：AI 返回组件清单**

```
✅ 识别到 6 个组件 (5 个可复用)

1. 🔄 header-navigation — [导航] 顶部导航栏
2. 📄 hero-section — [主视觉] 大标题+行动按钮
3. 🔄 stats-display — [数据] 统计数字
4. 🔄 cta-buttons — [按钮] 行动号召
5. 🔄 logos-carousel — [客户] 品牌 Logo
6. 🔄 cookie-consent-banner — [弹窗] Cookie 提示

📁 预览: C:\Users\xxx\.componentize\preview.html
```

**第 3 步：打开预览看看**

浏览器打开 preview.html，你会看到：

```
┌─────────────────────────────────────────────┐
│  🧩 componentize                            │
│  [全选] [取消] [📥 导出选中]                   │
├─────────────────────────────────────────────┤
│  ☑ 导航栏       预览: [导航栏渲染效果]         │
│  ☑ 英雄区       预览: [英雄区渲染效果]         │
│  ☑ 功能卡片     预览: [三列卡片网格]           │
│  ☑ 定价方案     预览: [三个定价卡片]           │
│  ☑ 页脚         预览: [四列页脚链接]           │
│                                              │
│  选好了告诉 AI 你要保留哪些                    │
└─────────────────────────────────────────────┘
```

**第 4 步：告诉 AI 要保留的**

```
保留导航栏、英雄区、功能卡片、定价方案，导出到 ./my-components/
```

**第 5 步：拿到组件文件**

```
✅ 已导出 4 个组件
目录: D:\my-components\

  📄 header-navigation.html
  📄 hero-section.html
  📄 feature-card.html
  📄 pricing-table.html
```

每个文件用浏览器打开就是独立组件，把 `<div>...</div>` 复制到你项目里直接用。

---

## 🔒 安全说明

你的 API Key **只用于调用你配置的视觉识别 API**，绝对不发送到其他地方。

```
你的环境变量 → MCP Server（内存）→ Python 子进程（环境变量）→ 你配的 API 地址
                                                                ↓
                                                     硅基流动 / 阿里云 / OpenAI
```

**我们不做的事：**
- ❌ 绝不把 Key 写入日志或文件
- ❌ 绝不把 Key 发到任何未经你配置的服务器
- ❌ 绝不上传你的截图或组件
- ❌ 绝无任何埋点、统计、追踪

**你可以验证的：**
整个项目 300 多行 TypeScript + Python，全部开源，随便审计。

---

## ⚙️ 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `COMPONENTIZE_API_KEY` | — | API Key（不设则自动读 Claude Code 的 Key） |
| `COMPONENTIZE_BASE_URL` | `https://api.siliconflow.cn/v1` | API 地址 |
| `COMPONENTIZE_MODEL` | `Qwen/Qwen3-VL-32B-Instruct` | 视觉模型 |
| `COMPONENTIZE_PYTHON` | `python3` | Python 路径 |

---

## 🗺️ 路线图

- [x] 核心 MCP Server（分析 + 导出 + 截图）
- [x] 交互式预览面板（浏览器勾选）
- [x] 零配置自动检测 Claude Code Key
- [x] 支持多 AI 后端（硅基流动 / 阿里云 / OpenAI / DeepSeek）
- [ ] React / Vue 组件输出
- [ ] 批量分析（一次处理多张截图）
- [ ] Tailwind v4 支持
- [ ] Figma 设计 Token 提取

---

## 🧪 本地开发

```bash
git clone https://github.com/MonloHua/componentize
cd componentize
npm install
npm run build
```

### 项目结构

```
componentize/
├── src/
│   ├── index.ts        # MCP Server 入口
│   ├── analyzer.py     # 视觉分析 + 组件生成
│   └── capture.py      # URL 截图
├── dist/               # 编译后的 JS
└── package.json
```

---

## 📄 开源协议

MIT — 随意使用、修改、发布。

---

<p align="center">
  作者 <a href="https://github.com/MonloHua">Monlo Hua</a>
</p>