architect-mcp

An MCP server that designs websites.

Hand it a business name, category, and a few details about the vibe — get back an opinionated, section-by-section design blueprint with palette, typography, layout DNA, and CSS specs. Designed to be the first step in an AI website pipeline: blueprint here, code generation downstream.

Runs entirely against a local Ollama instance. No API keys, no cloud calls, no per-request cost.

Why

Most AI website generators produce the same five-section template every time: hero, services grid, gallery, CTA band, contact form. They look identical because the model has nothing pushing it toward differentiation.

architect-mcp is the opinionated counterweight. It gives the model strong instructions about asymmetric layouts, industry-appropriate visual vocabulary, and section-by-section specificity — and it refuses to play it safe. The output is a design brief, not a website — but the brief is detailed enough that a downstream code-generation step (Claude, Cursor, another agent) can build a working single-file HTML demo from it directly.

What it generates

Each blueprint includes:

• Page Structure — every section in scroll order, with purpose, layout type, background treatment, and exact content
• Typography System — Google Font picks for headings + body, sizes, rationale
• Color System — primary / secondary / accent / text / background hex values with rationale
• Unique Design Elements — at least 3 specific CSS techniques that make the site not look like a template
• Section-by-Section CSS Specs — padding, grid templates, transforms, clip-paths, hover states, mobile adaptation
• What NOT to Do — industry-specific anti-patterns to avoid

Sample output

Two real blueprints generated by gemma4:26b, unedited:

• examples/sample-blueprint-barber.md — Ironclad Barber Co., old-school masculine.
• examples/sample-blueprint-coffee.md — Hollow Stump Coffee Roasters, craft-focused warm.

Each file's top comment shows the exact tool arguments that produced it. Both runs took roughly four minutes on a single mid-range GPU.

Demo

What a call to generate_blueprint looks like from inside Claude Code:

> Use architect to draft a blueprint for Ironclad Barber Co., a small-town barber.
  Services: haircuts, beard trims, hot towel shaves. Vibe: old-school masculine.

● architect:generate_blueprint(
    business_name = "Ironclad Barber Co.",
    category      = "barbershop",
    services      = "haircuts, beard trims, hot towel shaves",
    vibe          = "old-school masculine, classic chair vibe"
  )

  ⎿  # Ironclad Barber Co. — Site Architecture Blueprint

     _Generated by architect-mcp using gemma4:26b — prompt v1_

     This design moves away from the "Modern Tech Startup" template and leans
     into "The Heritage Ledger" concept. The website shouldn't feel like a
     digital landing page; it should feel like a heavy, high-quality, printed
     shop manual or a vintage newspaper.

     ## Site Architecture

     ### Page Structure

     1. The Split-Screen Entry (The Impression)
        - Purpose: Immediate brand positioning. No scrolling required.
        - Layout: 50/50 Vertical Split.
        - Background: Left #1A1A1A. Right: B&W photo of a straight razor.
        - Content: Massive H1 "IRONCLAD." Subtext "No nonsense. Just tradition."

     [...continues for ~3,000 more words across typography, color, CSS specs,
      unique design elements, and what-not-to-do sections...]

> Now critique that blueprint and tell me what's weak.

● architect:critique_blueprint(...)
  ⎿  # Critique — Ironclad Barber Co.
     Industry fit: 9/10. Differentiation: 8/10. Visual specificity: 9/10. [...]

The full markdown the tool returns is the barber sample. Runtime is ~60–90s per call on a desktop-class GPU.

Why not just use Claude directly?

Claude can write a website brief from a single chat message. So why ship an MCP server whose entire job is to wrap one prompt? Three reasons:

1. The prompt is the product. Wrapping it as a tool makes it reusable across conversations and machines, without anyone copy-pasting the canonical version. When the prompt improves, every caller gets the improvement on the next call.
2. It runs on your hardware. No API key, no per-call cost, no client details shipped to a third-party. Generate 50 blueprints to pick the best one — the constraint is your own GPU time, not API budget.
3. It frees the conversation context. The blueprint never lives in the Claude transcript; Claude sees the result, then you discard it (or write it to disk with output_path). Generate ten variants without bloating the working context.

Long version: docs/why-not-just-claude.md.

Install

Prerequisites

1. Go 1.26+ for building from source.

2. Ollama running with at least one model pulled. The defaults assume gemma4:26b:

   # Install Ollama: https://ollama.com/download
   ollama serve &            # if not already running
   ollama pull gemma4:26b    # ~16 GB; takes a while

   If gemma4:26b isn't available in your Ollama registry, any local model works — see Models for tested alternatives. Pass model=<name> per-call or set ARCHITECT_DEFAULT_MODEL=<name> to switch defaults.

3. Chrome or Chromium — only needed for the generate_blueprint_from_url tool. The plain generate_blueprint tool has no Chrome dependency.

   • macOS: brew install --cask google-chrome
   • Debian/Ubuntu: apt install chromium-browser

Build

git clone https://github.com/jasondillingham/architect-mcp
cd architect-mcp
make build
# binary lands at bin/architect-mcp

Configure your MCP client

Claude Desktop / Claude Code

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "architect": {
      "command": "/absolute/path/to/architect-mcp/bin/architect-mcp",
      "env": {
        "ARCHITECT_OLLAMA_URL": "http://localhost:11434",
        "ARCHITECT_DEFAULT_MODEL": "gemma4:26b"
      }
    }
  }
}

See examples/claude-desktop-config.json for a starter.

Optional config file

Drop a YAML file at ~/.config/architect-mcp/config.yaml:

ollama_url: http://localhost:11434
default_model: gemma4:26b
# Optional. Required if you want to use the `output_path` argument on
# blueprint tools. Any tool-supplied output_path is resolved relative to
# this directory and must remain inside it (path-traversal attempts and
# absolute paths outside the root are rejected). Leave unset to disable
# disk writes entirely — tools will still return blueprints inline.
output_root: ~/.architect-mcp/blueprints

Environment variables override the YAML:

• ARCHITECT_OLLAMA_URL — overrides ollama_url
• ARCHITECT_DEFAULT_MODEL — overrides default_model
• ARCHITECT_OUTPUT_ROOT — overrides output_root

Tools

Six tools. All run against the same local Ollama instance; the prompt is what differs.

Tool	What it does
generate_blueprint	Build a blueprint from text-only inputs (business name, category, optional vibe/services/colors/audience). Pass preset=<industry> to auto-fill missing fields from a per-industry bundle. Pass output_path to write the blueprint to disk (requires output_root configured — see below) and get back a short summary instead of the full ~3-8KB inline.
generate_blueprint_from_url	Like generate_blueprint, but also screenshots a competitor URL via headless Chrome and feeds the image to a vision-capable model so the differentiation guidance is visual, not just textual. Adds ~10–20s for the screenshot.
multi_blueprint	Generate 1-3 variants in one call using a fixed temperature ladder (0.7, 0.95, 1.2). Use this when you want options to compare — feed the two strongest into compare_blueprints for a head-to-head.
critique_blueprint	Pass an existing blueprint markdown + business context, get back a structured critique: 1–10 scores across industry-fit, differentiation, visual specificity, CSS feasibility, and audience fit, with three concrete weaknesses and one thing the blueprint nails.
compare_blueprints	Head-to-head comparison of two blueprints for the same business. Per-dimension winners + overall winner + a "hybrid suggestion" naming specific elements to graft from the loser into the winner.
improve_blueprint	Take an existing blueprint plus a critique of it, return a revised blueprint that addresses the weaknesses while preserving the strengths. Natural pair to critique_blueprint — call critique first, then feed the original + critique here. Output ends with a "What Changed From v1" section spelling out what got addressed.

generate_blueprint

Field	Required	Description
business_name	yes	Name of the business
category	yes	Industry — dentist, plumber, restaurant, manufacturer, etc.
preset	no	Auto-fill missing vibe / services / audience / colors from a built-in bundle. Available: dentist, plumber, hvac, lawn-care, auto-repair, salon, restaurant, manufacturer, attorney, chiropractor. Explicit fields always win over preset values.
services	no	Comma-separated list of services
vibe	no	Brand descriptors — premium, rugged, family-owned, industrial
colors	no	Known brand colors as hex, comma-separated
audience	no	Who the site is for
competitor_url	no	Competitor site to mention textually (use generate_blueprint_from_url if you want the model to actually see it)
model	no	Override default Ollama model
ollama_url	no	Override default Ollama URL
output_path	no	If set, write the blueprint to this path and return a short summary instead of the full markdown. Requires output_root to be configured in config.yaml or via ARCHITECT_OUTPUT_ROOT — the path resolves relative to that root and must stay inside it. See Configure your MCP client.

generate_blueprint_from_url

Same fields as generate_blueprint, but with a required url for the competitor site to screenshot. The screenshot is fed alongside the prompt to a vision-capable model (gemma4:26b is the recommended default since it supports vision). Requires Chrome/Chromium installed locally.

critique_blueprint

Field	Required	Description
business_name	yes	Name of the business the blueprint is for
category	yes	Industry category (same vocabulary as generate_blueprint)
blueprint	yes	The full blueprint markdown to review — typically copied from a prior generate_blueprint result
model	no	Override default Ollama model
ollama_url	no	Override default Ollama URL

compare_blueprints

Field	Required	Description
business_name	yes	Name of the business both blueprints are for
category	yes	Industry category (same vocabulary as generate_blueprint)
blueprint_a	yes	First blueprint markdown to compare
blueprint_b	yes	Second blueprint markdown to compare
model	no	Override default Ollama model
ollama_url	no	Override default Ollama URL

multi_blueprint

Same fields as generate_blueprint, plus an n parameter (default 2, max 3). Each variant runs at a different temperature (0.7, 0.95, 1.2) for diversity. Variants run sequentially since a single GPU can only host one model load at a time, so total runtime is n × ~60-90s.

improve_blueprint

Field	Required	Description
business_name	yes	Name of the business the blueprint is for
category	yes	Industry category (same vocabulary as generate_blueprint)
original_blueprint	yes	The blueprint markdown to revise — typically the output of a prior generate_blueprint call
critique	yes	The critique markdown to address — typically the output of critique_blueprint against the same original
model	no	Override default Ollama model
ollama_url	no	Override default Ollama URL

Example calls

Use architect to draft a blueprint for Bill's Barber Shop, a small-town barber. Services: haircuts, beard trims, hot towel shaves. Vibe: old-school masculine, classic chair vibe.

→ calls generate_blueprint with those fields. Returns a multi-page markdown spec.

Build me an HVAC site for TempCo Heating & Cooling — just use the hvac preset.

→ calls generate_blueprint preset=hvac business_name="TempCo Heating & Cooling" category=hvac. The preset auto-fills vibe/services/audience/colors with HVAC-appropriate defaults.

Build a dentist site for Bright Smile that's specifically not like https://aspendental.com.

→ calls generate_blueprint_from_url url=https://aspendental.com business_name="Bright Smile" category=dentist. The competitor's screenshot is attached to the prompt; the resulting blueprint counter-programs Aspen Dental's design choices.

Now critique that blueprint and tell me what's weak.

→ pass the blueprint markdown to critique_blueprint. Returns 5 scored dimensions, three fixable weaknesses, and one thing the blueprint nails.

Fix the weaknesses the critique surfaced.

→ pass the original blueprint plus the critique to improve_blueprint. Returns a revised blueprint with a "What Changed From v1" section spelling out which weaknesses were addressed.

Generate two HVAC variants for TempCo and pick the stronger one.

→ calls multi_blueprint preset=hvac business_name="TempCo" n=2, then compare_blueprints with both variants. The compare response names a winner per dimension and a hybrid suggestion of which elements from the loser to graft into the winner — useful when neither variant is perfect.

Models

• gemma4:26b (default) — best quality, ~60-90s per blueprint on a single GPU
• qwen2.5-coder:14b — faster (~25-40s), still solid for blueprints
• llama3.1:8b — fastest (~10-15s), output quality drops noticeably

You can pass model per-call to swap models without restarting the server.

License

MIT — see LICENSE.

Acknowledgments

Extracted from an in-house toolchain where it generated website blueprints for local-business pitches before being open-sourced.