Frontend Design Loop MCP

io.github.alexalexalex222Published by GitHub account alexalexalex222v1.0.0Updated Oct 25, 2026

Design-first MCP for coding agents that improves websites with screenshot-grounded iteration.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper ToolsMedia & Design

Overview

AI-generated overview

A local MCP server that lets a coding agent improve an existing frontend by iterating on rendered screenshots and returning a winning patch with proof artifacts

What you can do
Run the main design loop on a repo and goal: boot a local preview, capture screenshots, iterate against the rendered page, and return the winning patch plus screenshots and run artifacts. Evaluate an existing patch in an isolated worktree with deterministic checks, screenshots and proof fields. Use a narrower toolkit variant to fetch a playbook, build context, run gates, start and stop a preview, and capture screenshots while the host agent does the judging. Run an advanced unattended solve workflow.
When to use it
Use it when a page already works but looks generic, flat or under-designed, and you want the agent to improve the design rather than only critique it. Also useful when you have a patch and want deterministic checks and screenshot proof before accepting it.
Requirements
Local Python install from PyPI (pipx), with a setup helper that registers detected clients. Playwright Chromium is installed by the local setup path. A local preview command and URL are supplied per call, and a provider and model lane (for example a Gemini CLI lane) are chosen for generation and vision.
Before you install
The design workflow edits a real repository and creates worktrees, so review returned patches before merging. Custom preview commands run as shell-free argv by default; shell syntax and inline interpreter execution require unsafe_shell_commands=true, and external preview fetches require unsafe_external_preview=true. Auto-context skips common secret paths, but check what is sent to the chosen provider. Provider credentials may be needed for non-client-side vision.

Installation

In SourceWeft

  1. Open Frontend Design Loop MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Frontend Design Loop MCP

Coding agents can get a page functional. Frontend Design Loop makes it materially better with screenshot-grounded iteration and proof artifacts.

Use it when the base model got the page working but the result is still generic, flat, rough, or visibly under-designed. The main design workflow stays on one main provider and model lane by default, so multi-model routing is opt-in instead of the default story.

Quick Start

Install the current public build from PyPI:

bash
pipx install frontend-design-loop-mcp

Set up every detected supported client:

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

Real MCP call example:

text
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-Owned Toolkit Variant

This repo now also ships an additive MCP entrypoint for agent-owned frontend loops:

  • console script: frontend-design-toolkit-mcp
  • module fallback: PYTHONPATH=src .venv/bin/python -m design_toolkit.server

That variant is intentionally narrow:

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

It does not hide vision scoring, creativity judging, or patch generation behind MCP. The host agent owns planning, edits, screenshot review, scoring, iteration, and winner selection directly.

See test-prompt-codex.md for the end-to-end Codex exercise prompt.

What The MCP Does

frontend_design_loop_design is the main workflow:

  • the host agent points the MCP at a real repo plus a concrete design goal
  • the MCP boots a local preview, captures screenshots, and iterates against the rendered result
  • the same main provider and model lane is used by default across planning, generation, and vision unless you explicitly override it
  • the MCP returns the winning patch plus screenshots and run artifacts

frontend_design_loop_eval is the proof workflow:

  • use it when the host agent already has the patch
  • the MCP applies the patch in an isolated worktree, runs deterministic checks, captures screenshots, and returns proof artifacts

This is the wedge:

  • coding agents can already get pages working
  • this MCP helps them make pages materially better
  • screenshot-grounded iteration plus proof artifacts is the differentiator

Official MCP Registry metadata is tracked in server.json.

Proof Gallery

The public proof set uses owned/generated GA SMB previews plus the ACA full-page before/after.

Selected Hero / Top Crops

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

ACA Full-Page Before / After

Before: early ACA full homepage.

[ACA full-page before]

After: rebuilt ACA homepage with a stronger hero, cleaner sequencing, and a materially better full-page result.

[ACA full-page after]

See the proof notes in the case studies index.

How It Works In Practice

  1. Point the MCP at a real repo and give it a concrete design goal.
  2. It creates an isolated worktree, boots a preview, and captures rendered screenshots.
  3. It iterates against the actual rendered page instead of only raw code.
  4. It returns the winning patch, screenshot proof, and run artifacts so the host agent can judge the result.

Workflow Summary

frontend_design_loop_design

Use it when:

  • the page is functional but weak
  • the section structure is there but the design is not
  • you want the MCP to improve the page instead of only judging it

Key defaults:

  • one main provider + model lane by default
  • planning_mode="single"
  • vision_mode="on"
  • section_creativity_mode="on"
  • split planner or vision lanes only happen when explicitly requested

frontend_design_loop_eval

Use it when:

  • the host agent already has the patch
  • you want deterministic checks, screenshots, and artifact capture
  • you want the host agent to judge the result from returned screenshots

Returned proof fields include:

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

frontend_design_loop_solve

frontend_design_loop_solve still exists for advanced unattended workflows, but it is not the main public story.

Install And Setup

Public install now

bash
pipx install frontend-design-loop-mcpfrontend-design-loop-setup --install-all-detected-clients

GitHub install remains the fallback:

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

Local clone path

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

The local setup path:

  • creates .venv
  • installs the package
  • installs Playwright Chromium
  • installs detected client entries when supported clients are present
  • runs the built-in doctor
  • runs the stdio smoke test

If you want the repo-local environment without auto-installing client entries:

bash
FDL_SKIP_CLIENT_INSTALL=1 ./scripts/setup.sh

Setup helpers

Bulk installer:

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

Targeted installers:

bash
frontend-design-loop-setup --install-claude --scope userfrontend-design-loop-setup --install-codexfrontend-design-loop-setup --install-geminifrontend-design-loop-setup --install-droidfrontend-design-loop-setup --install-opencode

Config printers:

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

Safety Defaults

  • custom commands are parsed as shell-free argv by default
  • shell syntax, substitutions, and inline interpreter execution like bash -c, python -c, and node -e require unsafe_shell_commands=true
  • preview_url must match the launched local preview origin and port by default
  • external preview fetches require unsafe_external_preview=true
  • preview readiness checks reject cross-origin redirects, and browser screenshots block cross-origin subresources by default
  • auto-context skips common secret-bearing paths such as .env*, .git/, .aws/, .ssh/, .config/gcloud/, .docker/, .kube/, token-named files, and service-account-style JSON
  • native CLI providers inherit a minimal allowlisted environment instead of the full host shell environment
  • shared worktree reuse directories are off by default

Client-side vision is the default proof path for frontend_design_loop_eval, so the host agent can judge the screenshots without provider credentials.

Proxy-only MiniMax vision lanes are explicitly treated as structural-only review:

  • vision_review_mode="proxy_structural"
  • they do not count as full automated visual scoring

Verification

Offline preflight:

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

stdio smoke:

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

Built-in doctor:

bash
frontend-design-loop-setup --doctorfrontend-design-loop-setup --doctor --smoke

Docs

Distribution State

Current public install path:

bash
pipx install frontend-design-loop-mcp

Source: README.md at commit c65f7ca

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts