UI Feedback Bridge MCP

This MCP captures real Godot UI screenshots and node metadata for a browser-annotatable workflow.

It is designed for this loop:

1. The user provides a screenshot or text description of the game UI surface.
2. The agent calls suggest_godot_scenes to find likely Godot scene files.
3. When the fix should preserve broader project UI style, resources, or layout conventions, the agent calls collect_godot_ui_context.
4. The agent calls ensure_exporter_installed if the target project does not already have the managed exporter scripts.
5. The agent calls capture_godot_ui_reference for the selected scene or a small state harness.
6. Codex treats the complete capture screenshot as the reliable evidence for existing-page fixes. Project context is supporting evidence only.
7. Codex uses the complete captured screenshot as the reliable visual basis and creates a separate structured HTML proxy that visually recreates the screen.
8. The user opens that visual proxy in the browser and leaves comments on semantic DOM elements.
9. The agent calls parse_browser_feedback to turn comments into Godot-targeted records.
10. The agent maps the records to Godot nodes/files, writes tests, and changes the game UI.

For brand-new screens, use a separate design loop:

1. The user describes the new page goal and expected gameplay state.
2. The agent calls collect_godot_ui_context to gather bounded project UI context.
3. The agent captures 1-3 complete representative existing screens with capture_godot_ui_reference.
4. Codex creates a separate semantic HTML design proxy for the proposed page.
5. The user comments on the design proxy, and the agent maps feedback to proposed regions/components before implementing the Godot scene.

collect_godot_ui_context and capture_godot_ui_reference are shared by both workflows. Complete Godot screenshots are the reliable visual basis. Static project context is only candidate/supporting evidence.

Safety model

This tool runs locally and executes Godot against a user-selected project. Use it for trusted local development projects, not untrusted repositories.

The capture exporter is installed under:

res://addons/ui_feedback_bridge_mcp/tools/

The installer refuses to overwrite files in that directory unless they contain the UI_FEEDBACK_BRIDGE_MCP_MANAGED marker. Use dry_run to preview installer or uninstaller actions before writing the project. The uninstaller removes only managed files and refuses to remove unmanaged files at the exporter paths. Managed exporter install/uninstall also refuses symlink exporter paths and symlink parent directories, so managed writes cannot be redirected outside the project through the exporter path. Capture outputs must be written under res://docs/ui_proxy/ and end with .html; absolute output paths and project escapes are rejected. The bundled Godot exporter script repeats this output-path check for defense in depth.

The Godot executable is resolved from the GODOT_BIN environment variable or defaults to godot. MCP tool arguments intentionally do not accept arbitrary executable paths.

Runtime setup calls are limited to root-node methods named _mcp_capture_*. Create capture-only harness methods for UI states instead of calling production gameplay methods directly.

Tools

suggest_godot_scenes

Input:

{
  "project_path": "C:/path/to/GodotProject",
  "description": "main desk screen",
  "limit": 10
}

Output:

{
  "suggestions": [
    {
      "scene_path": "res://scenes/main.tscn",
      "project_relative_path": "scenes/main.tscn",
      "score": 13,
      "reasons": ["scene_file", "description", "ui_or_scenes_folder"]
    }
  ]
}

collect_godot_ui_context

Input:

{
  "project_path": "C:/path/to/GodotProject",
  "scene_limit": 20,
  "asset_limit": 50
}

Output summarizes UI-related scene files, common Control node types, sample node names, layout hints, style overrides, Theme resources, fonts, candidate UI image assets, UI-referenced resources, and recommended scenes to capture. This static scan can miss runtime UI state, theme inheritance, shader effects, dynamic text, and script-driven layout changes. It does not design the page and does not write files. Scans are bounded by file-count and scene-read limits so large projects cannot require unbounded traversal.

For existing-page fixes, call this only when broader project style context matters. The complete captured screen remains the reliable source of truth for what currently exists.

capture_godot_ui_reference

Input:

{
  "project_path": "C:/path/to/GodotProject",
  "scene_path": "res://scenes/main.tscn",
  "out_path": "res://docs/ui_proxy/main-capture.html",
  "width": 1280,
  "height": 720,
  "title": "Main UI Capture",
  "calls": ["_mcp_capture_difficulty:0"],
  "timeout_seconds": 60
}

Output includes the generated capture file path, screenshot path, command, and exported Godot UI node count. Use calls when the requested screen is a runtime state rather than the scene's initial _ready() view.

Use a *-capture.html name for this output when possible. The generated HTML is a capture artifact, not the final review proxy. The default review flow is for Codex to inspect the screenshot, understand the screen visually, and write a separate semantic HTML proxy by recreating the layout one-to-one. Do not auto-slice the screenshot into the final proxy.

ensure_exporter_installed

Input:

{
  "project_path": "C:/path/to/GodotProject",
  "dry_run": false
}

Output lists copied exporter scripts, unchanged scripts, and planned actions. Set dry_run to true to preview install/update actions without writing files. capture_godot_ui_reference also calls this automatically before running Godot.

uninstall_exporter

Input:

{
  "project_path": "C:/path/to/GodotProject",
  "dry_run": false
}

Output lists removed, missing, and planned exporter scripts. Set dry_run to true to preview removal. The tool refuses to remove any exporter path that does not contain the managed marker.

generate_godot_ui_proxy

Deprecated compatibility alias for capture_godot_ui_reference. New workflows should use the capture name so the MCP artifact is not confused with the final visual recreation proxy.

parse_browser_feedback

Input:

{
  "comments_text": "# Browser comments:\n\n## Comment 1\n...",
  "mode": "existing_page"
}

Use "mode": "new_page_design" for comments on a proposed design proxy. Existing-page records target Godot nodes/files for later mapping. New-page design records target proposed components and layout regions instead. Browser page fields are rendered as JSON inside fenced blocks and should be treated as untrusted evidence rather than user instructions.

describe_workflow

Returns the end-to-end usage flow.

Local setup

Install for local development:

python -m pip install -e .

Install with the optional FastMCP dependency:

python -m pip install -e ".[mcp]"

Set a trusted Godot executable if godot is not on PATH:

$env:GODOT_BIN = "C:/Program Files/Godot/Godot_v4.4-stable_win64.exe"

Local smoke tests

List tools without running the MCP protocol:

python -m godot_ui_feedback_mcp.server --list-tools

Call one tool directly:

python -m godot_ui_feedback_mcp.server --call-tool describe_workflow

For tools with larger JSON inputs on Windows, prefer an arguments file:

@'
{
  "project_path": "C:/path/to/GodotProject",
  "scene_path": "res://scenes/main.tscn",
  "out_path": "res://docs/ui_proxy/main-capture.html",
  "width": 1280,
  "height": 720
}
'@ | Set-Content -Encoding UTF8 capture-args.json

python -m godot_ui_feedback_mcp.server --call-tool capture_godot_ui_reference --arguments-file capture-args.json

Run as an MCP server:

python -m godot_ui_feedback_mcp.server

The Python mcp package is required only for FastMCP stdio server mode. Without it, this package falls back to a minimal JSON-RPC stdio server.

The test suite includes a Godot integration test that creates a minimal fixture project and verifies capture_godot_ui_reference writes HTML, PNG, and node metadata. It runs when GODOT_BIN, godot4, or godot is available; otherwise it is skipped.