Frontend Design Loop MCP

Frontend Design Loop MCP

编码 Agent 可以让页面实现功能。Frontend Design Loop 通过基于截图的迭代和证明材料，显著提升页面效果。

当基础模型已经让页面正常运行，但结果仍然显得普通、扁平、粗糙或明显缺乏设计时，就可以使用它。默认情况下，主要设计工作流始终使用同一个主服务提供商和模型通道，因此多模型路由是可选项，而非默认方案。

快速开始

从 PyPI 安装当前公开版本：

pipx install frontend-design-loop-mcp

为每个检测到的受支持客户端完成设置：

frontend-design-loop-setup --install-all-detected-clients

真实 MCP 调用示例：

frontend_design_loop_design(
  repo_path="/absolute/path/to/site",
  goal="make the homepage look materially more premium without changing the information architecture",
  provider="gemini_cli",
  model="gemini-3.1-pro-preview",
  preview_command="python3 -m http.server {port}",
  preview_url="http://127.0.0.1:{port}/index.html"
)

Agent 自主管理的工具包变体

此仓库现在还提供了一个附加的 MCP 入口点，用于由 Agent 自主管理的前端工作流：

• 控制台脚本：frontend-design-toolkit-mcp
• 模块回退方式：PYTHONPATH=src .venv/bin/python -m design_toolkit.server

此变体有意限定了范围：

• get_playbook
• build_context
• run_gates
• preview_start
• capture_screenshots
• preview_stop

它不会通过 MCP 隐藏视觉评分、创意评判或补丁生成。宿主 Agent 会直接负责规划、编辑、截图审查、评分、迭代和选出最佳结果。

端到端 Codex 练习提示词请参见 test-prompt-codex.md。

MCP 的功能

frontend_design_loop_design 是主要工作流：

• 宿主 Agent 将 MCP 指向真实仓库，并提供具体的设计目标
• MCP 启动本地预览、截取截图，并根据渲染结果进行迭代
• 除非你明确覆盖设置，否则规划、生成和视觉处理默认使用同一个主服务提供商和模型通道
• MCP 返回最终获胜补丁，以及截图和运行产物

frontend_design_loop_eval 是证明工作流：

• 宿主 Agent 已有补丁时使用
• MCP 在隔离的工作树中应用补丁、运行确定性检查、截取截图，并返回证明材料

这正是切入点：

• 编码 Agent 已经能够让页面正常运行
• 此 MCP 能帮助它们显著提升页面效果
• 基于截图的迭代加上证明材料，正是其差异化优势

官方 MCP Registry 元数据记录在 server.json 中。

证明图库

公开证明集使用自有或生成的 GA SMB 预览，以及 ACA 全页面前后对比。

精选主视觉 / 顶部裁剪图

11 Budget Movers Augusta	13 Peachtree Flooring Atlanta	19 TNT Cabinets Columbus
21 Henry Plumbing Savannah	22 Silverback Electric Savannah	25 Robins Body & Paint Warner Robins
34 Proof Roofing Services Gainesville	45 Metro Storage Columbus	47 Miller Light Construction Commerce

ACA 整页改造前 / 后

改造前：ACA 早期的完整首页。

改造后：重建后的 ACA 首页，主视觉更突出，内容编排更清晰，整页效果显著提升。

请参阅案例研究索引中的证明说明。

实际工作方式

1. 将 MCP 指向实际仓库，并为其指定明确的设计目标。
2. 它会创建隔离的工作树、启动预览，并截取渲染后的页面。
3. 它会针对实际渲染的页面迭代，而不只是处理原始代码。
4. 它会返回效果最佳的补丁、截图证明和运行产物，供宿主 Agent 评估结果。

工作流概述

frontend_design_loop_design

适用于以下情况：

• 页面可用，但效果较弱
• 页面已有分区结构，但设计尚不到位
• 希望 MCP 改进页面，而不只是进行评判

主要默认设置：

• 默认使用一条主 provider + model 通道
• planning_mode="single"
• vision_mode="on"
• section_creativity_mode="on"
• 仅在明确请求时才会拆分规划或视觉通道

frontend_design_loop_eval

适用于以下情况：

• 宿主 Agent 已有补丁
• 需要确定性检查、截图和产物采集
• 希望宿主 Agent 根据返回的截图评估结果

返回的证明字段包括：

• deterministic_passed
• vision_pending
• vision_scored
• final_pass
• run_dir
• candidate_dir
• screenshot_files
• patch

frontend_design_loop_solve

frontend_design_loop_solve 仍可用于高级的无人值守工作流，但它不是面向公众的主要介绍内容。

安装与设置

目前的公开安装方式

pipx install frontend-design-loop-mcp
frontend-design-loop-setup --install-all-detected-clients

GitHub 安装仍可作为备用方式：

pipx install git+https://github.com/alexalexalex222/frontend-design-loop-mcp.git
frontend-design-loop-setup --install-all-detected-clients

本地克隆路径

git clone https://github.com/alexalexalex222/frontend-design-loop-mcp.git
cd frontend-design-loop-mcp
./scripts/setup.sh

本地设置路径会：

• 创建 .venv
• 安装软件包
• 安装 Playwright Chromium
• 在检测到受支持的客户端时安装对应的客户端条目
• 运行内置诊断工具
• 运行 stdio 烟雾测试

如果你想使用仓库本地环境，但不自动安装客户端条目：

FDL_SKIP_CLIENT_INSTALL=1 ./scripts/setup.sh

设置辅助工具

批量安装程序：

frontend-design-loop-setup --install-all-detected-clients

指定目标的安装程序：

frontend-design-loop-setup --install-claude --scope user
frontend-design-loop-setup --install-codex
frontend-design-loop-setup --install-gemini
frontend-design-loop-setup --install-droid
frontend-design-loop-setup --install-opencode

配置打印工具：

frontend-design-loop-setup --print-claude-config
frontend-design-loop-setup --print-codex-config
frontend-design-loop-setup --print-gemini-config
frontend-design-loop-setup --print-droid-config
frontend-design-loop-setup --print-opencode-config

安全默认设置

• 默认情况下，自定义命令会解析为不使用 shell 的 argv
• shell 语法、替换操作以及 bash -c、python -c 和 node -e 之类的内联解释器执行，需要设置 unsafe_shell_commands=true
• 默认情况下，preview_url 必须与启动的本地预览的源和端口匹配
• 获取外部预览需要设置 unsafe_external_preview=true
• 预览就绪检查会拒绝跨源重定向，浏览器截图默认会阻止跨源子资源
• 自动上下文会跳过常见的敏感信息路径，例如 .env*、.git/、.aws/、.ssh/、.config/gcloud/、.docker/、.kube/、名称中含 token 的文件，以及类似服务账号的 JSON 文件
• 原生 CLI 提供程序会继承最小化的许可名单环境，而不是完整的主机 shell 环境
• 默认关闭共享工作树复用目录

对于 frontend_design_loop_eval，客户端视觉评审是默认的验证路径，因此主机 Agent 无需提供程序凭据即可评判截图。

仅代理的 MiniMax 视觉通道会明确按结构化评审处理：

• vision_review_mode="proxy_structural"
• 不计作完整的自动化视觉评分

验证

离线预检：

PYTHONPATH=src .venv/bin/python scripts/preflight_check.py

stdio 烟雾测试：

PYTHONPATH=src .venv/bin/python scripts/smoke_mcp_stdio.py

内置诊断工具：

frontend-design-loop-setup --doctor
frontend-design-loop-setup --doctor --smoke

文档

• 工作流参考
• 发布检查清单
• 目录提交文案
• 案例研究

分发状态

当前公开安装路径：

pipx install frontend-design-loop-mcp