# 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:

```txt
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

```bash
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`:

```bash
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

```bash
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:

```json
{
  "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:

```bash
export OPENAI_API_KEY=...
```

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

Optional local fallback model:

```bash
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

```toml
[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`:

```toml
[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.