Skip to main content
Glama
Gu-Peach

F2C Component Retrieval MCP

by Gu-Peach
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: MCP Component Review

核心链路

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。

当前案例

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

验证命令

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。

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Gu-Peach/F2C-Component-Retrieval-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server