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、版本和禁用写法。

本项目补齐这一层：

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 组件知识库：

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 和校准。

输出候选组件示例：

{
  "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 组件验证案例效果。

目录结构

.
├── 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>/ 目录遵循同一套结构：

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               # 案例样式

启动方式

安装依赖

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

启动预览

npm run preview

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

预览入口：

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

构建预览

npm run preview:build

运行案例检索

npm run case:test2
npm run case:test3
npm run case:test4

等价于手动运行：

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：

npm run build
node dist/mcp/server.js

开发期：

npm run dev:mcp

Qdrant 向量库

启动本地 Qdrant：

docker compose up qdrant

生成本地 embedding：

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

同步到 Qdrant：

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。

当前案例

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

输入：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

验证命令

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。