web-gui-mcp

web-gui-mcp is a Python MCP server that compiles compact GUI2 ArtifactSpec JSON into design-system-aware HTML artifacts.

The v0.3 pipeline is:

ArtifactSpec
-> studio model compiler
-> CompilerOutput { strategy, view_tree }
-> validated ViewTree + derived legacy RenderPlan metadata
-> DesignSystemPack resolver
-> deterministic HTML compiler
-> static HTML or ui:// resource

The remote model sends compact semantic specs by default. The studio compiler chooses composition, while the server owns validation, design-system tokens, escaping, CSP, and deterministic runtime code.

Setup

uv sync
uv run pytest
uv run ruff check .
uv run python scripts/render_example.py examples/v0_3/implementation_plan.json /tmp/web-gui-plan.html
uv run python scripts/render_artifact_library_pages.py

Without uv:

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .
python scripts/render_example.py examples/v0_3/implementation_plan.json /tmp/web-gui-plan.html
python scripts/render_artifact_library_pages.py

Run The MCP Server

uv run web-gui-mcp

The server exposes:

• render_artifact

• get_artifact

• patch_artifact

• list_artifacts

• export_artifact

• get_artifact_schema

• compile_view_tree

• lint_view_tree

• list_design_systems

• get_design_system_summary

• get_local_model_status

• recommend_studio_model

• download_studio_model

• cancel_model_download

• list_themes

• preview_theme

• retheme_artifact

• rerender_artifact

It serves:

• ui://gui2/runtime/v0.3.css

• ui://gui2/runtime/v0.3.js

• ui://gui2/artifacts/{artifact_id}

Render An Artifact

render_artifact accepts compact semantic v0.3 specs:

{
  "spec": {
    "v": "0.3",
    "artifact": "implementation_plan",
    "title": "Queue Backpressure Plan",
    "audience": "engineer",
    "density": "compact",
    "sections": [
      {
        "kind": "summary",
        "items": [
          { "label": "Risk", "value": "Medium", "tone": "warning" }
        ]
      },
      {
        "kind": "checklist",
        "title": "Acceptance",
        "items": [
          { "text": "Default response returns a ui:// resource" }
        ]
      }
    ]
  },
  "quality": "studio",
  "delivery": "mcp_app_resource"
}

Default delivery returns compact metadata plus a ui://gui2/artifacts/{artifact_id} resource URI. Use delivery = "static_html" or return_html_to_model = true only when the caller explicitly needs full HTML in the tool response.

Studio Compiler

v0.3 is studio-only. The configured model provider receives the compact ArtifactSpec plus a design-system summary and produces CompilerOutput: compact strategy metadata plus the authoritative view_tree. The server validates and lints the ViewTree, derives deprecated RenderPlan metadata only for compatibility, then renders deterministic HTML. There is no deterministic fallback in normal rendering: if the model provider is unavailable or validation fails after one repair retry, the render fails closed.

Model providers:

• stub: test provider that returns known valid CompilerOutput.

• openai: default provider; uses gpt-5.5 with medium reasoning via the OpenAI API.

• ollama: optional local provider; posts to /api/generate and validates CompilerOutput JSON.

• auto: resolves to OpenAI unless WEB_GUI_RENDERER_PROVIDER overrides it.

OpenAI configuration:

export OPENAI_API_KEY=...

The server also reads .env.local in the repo root. Do not commit that file.

Optional local fallback model:

ollama pull qwen2.5-coder:14b

recommend_studio_model also lists larger quality targets for stronger hardware: qwen3.6:27b and qwen3-coder-next:q4_K_M.

Design Systems

The bundled gui2.default pack includes:

• light/dark modes

• compact/normal/comfortable/presentation density layers

• neutral_pro, dense_engineering, executive_brief, and editorial_research themes

• editorial_gallery for reference-library pages with numbered sections and demo cards

• component contracts for the built-in ViewTree nodes

• recipes for plans, reviews, design-variant grids, research, dashboards, and editors

Figma import and Code Connect ingestion are intentionally out of scope for this pass. The design-system schemas keep provenance fields so those importers can be added later.

Connect To Codex

[mcp_servers.web_gui_mcp]
command = "uv"
args = ["run", "web-gui-mcp"]
cwd = "/Users/hzuo/src/gui-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Without uv:

[mcp_servers.web_gui_mcp]
command = "python"
args = ["-m", "web_gui_mcp.server"]
cwd = "/Users/hzuo/src/gui-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Safety

• All model-provided text is escaped before rendering.

• ViewTree nodes are allowlisted and validated with Pydantic.

• Props named like raw HTML, CSS, scripts, srcdoc, or event handlers are rejected.

• Bind paths must resolve against the validated ArtifactSpec.

• Semantic data nodes such as timeline, checklist, and summary_strip must bind to compatible non-empty artifact data.

• JSON state embedded in <script type="application/json"> escapes <, >, &, U+2028, and U+2029.

• The renderer never executes model-generated JavaScript.

• The only runtime script is deterministic server-owned code for copy/export and tabs.