Web Gui

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.