{ "markdown": "# Frontend Design Loop MCP\n\n\n\nCoding agents can get a page functional. Frontend Design Loop makes it materially better with screenshot-grounded iteration and proof artifacts.\n\nUse 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.\n\n## Quick Start\n\nInstall the current public build from PyPI:\n\n```bash\npipx install frontend-design-loop-mcp\n```\n\nSet up every detected supported client:\n\n```bash\nfrontend-design-loop-setup --install-all-detected-clients\n```\n\nReal MCP call example:\n\n```text\nfrontend_design_loop_design(\n repo_path=\"/absolute/path/to/site\",\n goal=\"make the homepage look materially more premium without changing the information architecture\",\n provider=\"gemini_cli\",\n model=\"gemini-3.1-pro-preview\",\n preview_command=\"python3 -m http.server {port}\",\n preview_url=\"http://127.0.0.1:{port}/index.html\"\n)\n```\n\n## Agent-Owned Toolkit Variant\n\nThis repo now also ships an additive MCP entrypoint for agent-owned frontend loops:\n\n- console script: `frontend-design-toolkit-mcp`\n- module fallback: `PYTHONPATH=src .venv/bin/python -m design_toolkit.server`\n\nThat variant is intentionally narrow:\n- `get_playbook`\n- `build_context`\n- `run_gates`\n- `preview_start`\n- `capture_screenshots`\n- `preview_stop`\n\nIt 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.\n\nSee [test-prompt-codex.md](test-prompt-codex.md) for the end-to-end Codex exercise prompt.\n\n## What The MCP Does\n\n`frontend_design_loop_design` is the main workflow:\n- the host agent points the MCP at a real repo plus a concrete design goal\n- the MCP boots a local preview, captures screenshots, and iterates against the rendered result\n- the same main provider and model lane is used by default across planning, generation, and vision unless you explicitly override it\n- the MCP returns the winning patch plus screenshots and run artifacts\n\n`frontend_design_loop_eval` is the proof workflow:\n- use it when the host agent already has the patch\n- the MCP applies the patch in an isolated worktree, runs deterministic checks, captures screenshots, and returns proof artifacts\n\nThis is the wedge:\n- coding agents can already get pages working\n- this MCP helps them make pages materially better\n- screenshot-grounded iteration plus proof artifacts is the differentiator\n\nOfficial MCP Registry metadata is tracked in [`server.json`](server.json).\n\n## Proof Gallery\n\nThe public proof set uses owned/generated GA SMB previews plus the ACA full-page before/after.\n\n### Selected Hero / Top Crops\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"11
11 Budget Movers Augusta		\"13
13 Peachtree Flooring Atlanta		\"19
19 TNT Cabinets Columbus
\"21
21 Henry Plumbing Savannah		\"22
22 Silverback Electric Savannah		\"25
25 Robins Body & Paint Warner Robins
\"34
34 Proof Roofing Services Gainesville		\"45
45 Metro Storage Columbus		\"47
47 Miller Light Construction Commerce
\n\n### ACA Full-Page Before / After\n\nBefore: early ACA full homepage.\n\n![ACA full-page before](docs/images/aca-site50-v9-fullpage-before.png)\n\nAfter: rebuilt ACA homepage with a stronger hero, cleaner sequencing, and a materially better full-page result.\n\n![ACA full-page after](docs/images/aca-site50-v22-fullpage-after.png)\n\nSee the proof notes in [the case studies index](docs/case-studies/index.md).\n\n## How It Works In Practice\n\n1. Point the MCP at a real repo and give it a concrete design goal.\n2. It creates an isolated worktree, boots a preview, and captures rendered screenshots.\n3. It iterates against the actual rendered page instead of only raw code.\n4. It returns the winning patch, screenshot proof, and run artifacts so the host agent can judge the result.\n\n## Workflow Summary\n\n### `frontend_design_loop_design`\n\nUse it when:\n- the page is functional but weak\n- the section structure is there but the design is not\n- you want the MCP to improve the page instead of only judging it\n\nKey defaults:\n- one main `provider` + `model` lane by default\n- `planning_mode=\"single\"`\n- `vision_mode=\"on\"`\n- `section_creativity_mode=\"on\"`\n- split planner or vision lanes only happen when explicitly requested\n\n### `frontend_design_loop_eval`\n\nUse it when:\n- the host agent already has the patch\n- you want deterministic checks, screenshots, and artifact capture\n- you want the host agent to judge the result from returned screenshots\n\nReturned proof fields include:\n- `deterministic_passed`\n- `vision_pending`\n- `vision_scored`\n- `final_pass`\n- `run_dir`\n- `candidate_dir`\n- `screenshot_files`\n- `patch`\n\n### `frontend_design_loop_solve`\n\n`frontend_design_loop_solve` still exists for advanced unattended workflows, but it is not the main public story.\n\n## Install And Setup\n\n### Public install now\n\n```bash\npipx install frontend-design-loop-mcp\nfrontend-design-loop-setup --install-all-detected-clients\n```\n\nGitHub install remains the fallback:\n\n```bash\npipx install git+https://github.com/alexalexalex222/frontend-design-loop-mcp.git\nfrontend-design-loop-setup --install-all-detected-clients\n```\n\n### Local clone path\n\n```bash\ngit clone https://github.com/alexalexalex222/frontend-design-loop-mcp.git\ncd frontend-design-loop-mcp\n./scripts/setup.sh\n```\n\nThe local setup path:\n- creates `.venv`\n- installs the package\n- installs Playwright Chromium\n- installs detected client entries when supported clients are present\n- runs the built-in doctor\n- runs the stdio smoke test\n\nIf you want the repo-local environment without auto-installing client entries:\n\n```bash\nFDL_SKIP_CLIENT_INSTALL=1 ./scripts/setup.sh\n```\n\n### Setup helpers\n\nBulk installer:\n\n```bash\nfrontend-design-loop-setup --install-all-detected-clients\n```\n\nTargeted installers:\n\n```bash\nfrontend-design-loop-setup --install-claude --scope user\nfrontend-design-loop-setup --install-codex\nfrontend-design-loop-setup --install-gemini\nfrontend-design-loop-setup --install-droid\nfrontend-design-loop-setup --install-opencode\n```\n\nConfig printers:\n\n```bash\nfrontend-design-loop-setup --print-claude-config\nfrontend-design-loop-setup --print-codex-config\nfrontend-design-loop-setup --print-gemini-config\nfrontend-design-loop-setup --print-droid-config\nfrontend-design-loop-setup --print-opencode-config\n```\n\n## Safety Defaults\n\n- custom commands are parsed as shell-free argv by default\n- shell syntax, substitutions, and inline interpreter execution like `bash -c`, `python -c`, and `node -e` require `unsafe_shell_commands=true`\n- `preview_url` must match the launched local preview origin and port by default\n- external preview fetches require `unsafe_external_preview=true`\n- preview readiness checks reject cross-origin redirects, and browser screenshots block cross-origin subresources by default\n- 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\n- native CLI providers inherit a minimal allowlisted environment instead of the full host shell environment\n- shared worktree reuse directories are off by default\n\nClient-side vision is the default proof path for `frontend_design_loop_eval`, so the host agent can judge the screenshots without provider credentials.\n\nProxy-only MiniMax vision lanes are explicitly treated as structural-only review:\n- `vision_review_mode=\"proxy_structural\"`\n- they do not count as full automated visual scoring\n\n## Verification\n\nOffline preflight:\n\n```bash\nPYTHONPATH=src .venv/bin/python scripts/preflight_check.py\n```\n\nstdio smoke:\n\n```bash\nPYTHONPATH=src .venv/bin/python scripts/smoke_mcp_stdio.py\n```\n\nBuilt-in doctor:\n\n```bash\nfrontend-design-loop-setup --doctor\nfrontend-design-loop-setup --doctor --smoke\n```\n\n## Docs\n\n- [Workflow reference](docs/FRONTEND_DESIGN_LOOP_MCP.md)\n- [Launch checklist](docs/LAUNCH_CHECKLIST.md)\n- [Directory submission copy](docs/MCP_DIRECTORY_SUBMISSIONS.md)\n- [Case studies](docs/case-studies/index.md)\n\n## Distribution State\n\nCurrent public install path:\n\n```bash\npipx install frontend-design-loop-mcp\n```\n", "bytes": 9783, "sha": "1a32104044849e6d8206bb0c93123aa2d9632950a708e96896360f3de2cd857c", "repo_slug": "alexalexalex222/frontend-design-loop-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_alexalexalex222_frontend_desig_74604c62/readme" }