# F2C Component Retrieval MCP

F2C Component Retrieval MCP 是一个面向 Figma-to-Code 的组件检索 MVP。它的核心目标不是只根据“候选组件列表”生成页面，而是综合 **Figma Context MCP 返回的 YAML、原始截图、M4B/Pulse 组件知识库**，检索并校准真实可用组件，最后输出组件契约、搭建计划和可预览的 React + M4B 实现。

## 项目解决什么问题

传统 Figma MCP 通常能读取设计稿结构、样式、文本和 Figma instance，但它不知道项目中应该使用哪个真实代码组件，也不知道组件的 import、props、版本和禁用写法。

本项目补齐这一层：

```text
Figma URL / Screenshot
  ↓
Figma Context MCP YAML
  ↓
Figma YAML Preprocessor
  ↓
Component Retrieval / Rerank / Calibration
  ↓
Component Usage Contract
  ↓
F2C Assembly Plan
  ↓
React + M4B Preview Implementation
```

## 核心链路

### 1. Figma MCP 输入

输入来自现有 Figma Context MCP，例如：

- `figma-mcp.yaml`：Figma MCP 返回的 YAML，包含节点树、文本、布局、组件 instance、component set 等信息。
- `source.png`：原始截图，用于对齐视觉比例、间距、层级和内容区域。

### 2. Figma 预处理

代码位置：`src/figma/`

- `parse-yaml.ts`：解析 Framelink/Figma Context MCP YAML。
- `semantic-summary.ts`：把 YAML 压缩成 `FigmaSemanticSummary`。

预处理输出：

- `layoutHints`：整体角色、布局方向、文本摘要。
- `componentHints`：Figma instance/component set 到候选代码组件的线索。
- `retrievalQueries`：用于检索组件文档 chunk 的 query。
- `structuredFilters`：preferred components、scenario tags、required props。

### 3. 组件库知识库

代码位置：`src/component-docs/`

本地已放入处理好的 M4B/Pulse 组件知识库：

```text
artifacts/component-metadata/
├── components/             # 每个 M4B 组件的结构化 JSON
└── indexes/
    ├── components.json     # 67 个组件摘要
    ├── chunks.jsonl        # 2637 个语义检索 chunk
    ├── props.jsonl         # 2024 条 props/type 校准数据
    └── packages.json       # package/import/installed/version 信息
```

检索策略：

- `chunks.jsonl`：负责语义召回。
- `props.jsonl`：负责 props/type 校准，防止生成不存在的 props。
- `packages.json`：负责 package 是否安装、import 是否可用、版本信息。

### 4. 检索与校准

代码位置：`src/retrieval/`

- `retrieve.ts`：根据 `retrievalQueries` 检索候选组件 chunk。
- `calibrate.ts`：结合 metadata、props、package 信息进行 rerank 和校准。

输出候选组件示例：

```json
{
  "componentName": "Button",
  "packageName": "@m4b-design/button",
  "installed": true,
  "score": 1.14,
  "warnings": []
}
```

### 5. 契约与搭建计划

代码位置：`src/contracts/`

- `ComponentUsageContract`：组件名、包名、import、可用 props、示例、置信度、warning。
- `F2CAssemblyPlan`：给前端 Agent 使用的结构搭建建议。

### 6. 预览实现

代码位置：`preview/app/`

预览不是 MCP 核心逻辑，而是用真实 React + M4B 组件验证案例效果。

## 目录结构

```text
.
├── src/
│   ├── cli/                 # CLI: mvp / embed / sync-qdrant
│   ├── component-docs/      # 组件库 metadata 加载
│   ├── contracts/           # 组件契约和搭建计划
│   ├── embedding/           # embedding provider 与本地 fallback
│   ├── figma/               # Figma YAML 解析和语义预处理
│   ├── mcp/                 # MCP stdio server
│   ├── retrieval/           # 召回、rerank、校准
│   ├── utils/               # JSONL 工具
│   └── vector-store/        # Memory / local JSON / Qdrant 适配
├── artifacts/
│   ├── cases/               # 案例输入、过程产物、结果和生成代码
│   │   ├── test2/           # Smart Trending: On Trend Tag 面板
│   │   ├── test3/           # Smart Trending: Women 面板
│   │   └── test4/           # Snow Dashboard UI Kit: Dashboard cover
│   ├── component-metadata/  # 已处理好的 M4B 组件文档与索引
│   └── raw-figma/           # Figma MCP 抓取和探索过程文件
├── preview/
│   ├── app/                 # React + M4B 真实预览应用
│   ├── static/              # 早期静态预览快照
│   └── dist/                # Vite build 输出
├── data/
│   ├── m4b/                 # embedding JSONL 输出
│   └── vector-store/        # local JSON vector-store snapshot
├── tests/fixtures/          # 兼容测试用 fixture
└── docker-compose.yml       # 本地 Qdrant
```

## artifacts 说明

每个 `artifacts/cases/<caseId>/` 目录遵循同一套结构：

```text
figma-mcp.yaml              # Figma MCP 返回或标准化后的 YAML
source.png                  # 原始截图
parsed-summary.json         # 预处理后的 FigmaSemanticSummary
retrieval-result.json       # 检索 + 校准完整结果
component-contracts.json    # 组件契约
assembly-plan.json          # 搭建计划
component-usage-summary.md  # 候选组件 vs 实际使用组件说明
component-usage-summary.json# 机器可读版本
Test*Card.tsx               # 案例预览实现
Test*Card.css               # 案例样式
```

## 启动方式

### 安装依赖

```bash
cd /Users/bytedance/learning/f2c-component-retrieval-mcp
npm install
```

### 启动预览

```bash
npm run preview
```

默认端口是 `5175`。如果端口被占用，Vite 会自动切换到后续端口。

预览入口：

- `/#test2`：Smart Trending / On Trend Tag 面板
- `/#test3`：Smart Trending / Women 面板
- `/#test4`：Snow Dashboard UI Kit / Dashboard cover

### 构建预览

```bash
npm run preview:build
```

## 运行案例检索

```bash
npm run case:test2
npm run case:test3
npm run case:test4
```

等价于手动运行：

```bash
npm run mvp -- \
  --yaml ./artifacts/cases/test2/figma-mcp.yaml \
  --image ./artifacts/cases/test2/source.png \
  --metadata ./artifacts/component-metadata \
  --out ./artifacts/cases/test2/retrieval-result.json
```

## 启动 MCP Server

构建并启动 stdio MCP server：

```bash
npm run build
node dist/mcp/server.js
```

开发期：

```bash
npm run dev:mcp
```

## Qdrant 向量库

启动本地 Qdrant：

```bash
docker compose up qdrant
```

生成本地 embedding：

```bash
npm run build
node dist/cli/embed.js \
  --chunks ./artifacts/component-metadata/indexes/chunks.jsonl \
  --out ./data/m4b/embeddings.jsonl \
  --provider local
```

同步到 Qdrant：

```bash
node dist/cli/sync-qdrant.js \
  --vectors ./data/m4b/embeddings.jsonl \
  --collection m4b_components \
  --url http://127.0.0.1:6333 \
  --recreate
```

说明：`--provider local` 是 MVP 的确定性本地 embedding fallback，用于离线跑通链路；后续可切换到真实开源 embedding provider。

## 当前案例

### test2: Smart Trending / On Trend Tag

- 输入：`artifacts/cases/test2/figma-mcp.yaml` + `source.png`
- 实际使用组件：`Image`、`Popover`、`Tag`
- 候选组件说明：`artifacts/cases/test2/component-usage-summary.md`
- 预览实现：`artifacts/cases/test2/Test2Card.tsx`

### test3: Smart Trending / Women Panel

- 输入：`artifacts/cases/test3/figma-mcp.yaml` + `source.png`
- 实际使用组件：`Button`、`Image`、`Tag`
- 候选组件说明：`artifacts/cases/test3/component-usage-summary.md`
- 预览实现：`artifacts/cases/test3/Test3Card.tsx`

### test4: Snow Dashboard UI Kit / Dashboard Cover

- 输入：`artifacts/cases/test4/figma-mcp.yaml` + `source.png`
- 实际使用组件：`Avatar`、`Button`、`Image`、`Space`、`Tag`
- 候选组件说明：`artifacts/cases/test4/component-usage-summary.md`
- 预览实现：`artifacts/cases/test4/Test4Card.tsx`

## 验证命令

```bash
npm run type-check
npm test
npm run build
npm run preview:build
```

当前验证内容：

- 组件 metadata 可加载。
- Figma YAML 可预处理为 retrieval queries 和 component intents。
- 案例可召回并校准候选组件。
- 预览应用可通过 Vite 构建。

## 关键原则

- 候选组件不能单独决定最终代码；最终实现必须同时参考原始图片、Figma YAML 和组件契约。
- 向量/语义检索只负责“找相关组件”，props/type/package 校准负责“判断能不能真实使用”。
- 未安装或 props 不确定的组件不能直接进入最终实现，需要 fallback 或 warning。