Skip to main content
Glama
web-gui-mcp

web-gui-mcp

by thehzuo

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

Related MCP server: Artifacts

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.

Available Tools

7 tools
export_artifactD

Inputs: input (required). Returns: artifact_id, format, content

get_artifact_schemaD

Inputs: input (required). Returns: pattern_id, schema, example_minimal, guidance

lint_artifactD

Inputs: input (required). Returns: ok, issues

list_artifactsD

Inputs: input (required). Returns: artifacts

patch_artifactD

Inputs: input (required). Returns: artifact_id, delivery, title, html, +4 more

render_artifactD

Inputs: input (required). Returns: artifact_id, delivery, title, html, +3 more

search_artifact_patternsD

Inputs: input (required). Returns: patterns

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct action (export, get schema, lint, list, patch, render, search) with no overlap, making it easy for an agent to select the correct one.

    Naming Consistency5/5

    All tools follow a consistent verb_artifact pattern (e.g., export_artifact, patch_artifact), with minor variations in the second part (artifact_schema, artifact_patterns) that are still clear.

    Tool Count5/5

    Seven tools is a well-scoped number for managing artifacts in a web GUI context, covering essential operations without being overwhelming.

    Completeness3/5

    The set includes list, get schema, patch, export, lint, render, and search, but lacks create and delete operations, which are notable gaps in a typical artifact lifecycle.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that lets AI agents publish markdown/HTML to a browser viewer with session management, revision diffs, and live updates via a single tool call.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that fetches remote or local HTML resources and converts them to Markdown, enabling AI clients to summarize or process web content.
      5 npm
      MIT