easy-ui-mcp

Ein Dockerisierter MCP-Server (Model Context Protocol) für lokale UI-Tests. Er stellt Playwright-basierte Browser-Automatisierungswerkzeuge über HTTP/SSE bereit, sodass ein KI-Agent (wie Claude Code) Web-UI-Abläufe Schritt für Schritt steuern und einen JSON- und HTML-Bericht mit Screenshots zurückbekommen kann – ohne serverseitiges LLM, ohne Testskripte schreiben zu müssen.

Schnellstart

docker compose up -d --build
curl http://localhost:8765/health
# {"status":"ok"}

Claude Code verbinden:

claude mcp add --transport http easy-ui-mcp http://localhost:8765/mcp

Bitten Sie dann Claude Code, zu einer Seite zu navigieren und einen Screenshot zu machen – es wird die untenstehenden Werkzeuge aufrufen und Bericht erstatten.

Verwenden Sie dies aus einem anderen Repository? Die MCP-Registrierung ist pro Projekt – führen Sie claude mcp add auch aus dem Stammverzeichnis dieses Repos aus (der Container oben muss nur einmal laufen, wird aber von mehreren Repos gemeinsam genutzt). Siehe AGENTS.md → Using easy-ui-mcp From Another Repo für die vollständigen erforderlichen Schritte.

Related MCP server: Playwright MCP Server

Netzwerk

Der Container läuft mit network_mode: host in docker-compose.yml (nicht über einen veröffentlichten Port auf einem Bridge-Netzwerk). Dies ist erforderlich, nicht optional: Der Browser, den Playwright in diesem Container steuert, muss localhost:<port> auf Ihrem Host-Rechner erreichen, wo der Dev-Server der Ziel-App (das Repo, das Sie testen) tatsächlich läuft. Ein Standard-Bridge-Netzwerk gibt dem Container einen eigenen isolierten Netzwerk-Namespace ohne Route zurück zum Host – Ziel-URLs wie http://localhost:8766 hängen oder schlagen mit ERR_CONNECTION_REFUSED fehl, und http://<Host-LAN-IP>:8766 läuft einfach in einen Timeout, selbst wenn der Zielserver lauscht und über curl von der Host-Shell erreichbar ist.

Wenn Sie diesen Container irgendwo forken/neu bereitstellen, wo network_mode: host nicht verfügbar ist (z. B. Docker Desktop auf macOS/Windows, wo die Host-Netzwerkunterstützung eingeschränkt oder nicht vorhanden ist), verwenden Sie host.docker.internal als Ziel-Hostname anstelle von localhost, wenn Sie ui_navigate aufrufen, und fügen Sie einen network_mode: host-Fallback von extra_hosts: ["host.docker.internal:host-gateway"] zu docker-compose.yml hinzu.

Werkzeuge

ui_start_session, ui_end_session, ui_step, ui_navigate, ui_click, ui_fill, ui_assert, ui_check, ui_wait_for, ui_get_page_state, ui_take_screenshot – plus einen REST-Wrapper unter POST /api/run-test für Nicht-MCP-Aufrufer.

Beschriften Sie Ihre Schritte

ui_step(label) gruppiert alles, was danach folgt, unter einer Überschrift in einfacher Sprache, bis zum nächsten ui_step. Das Label ist die einzige vom Aufrufer verfasste Absichtserklärung im Bericht. Der Server verwendet deterministische Vorlagen wie „Geöffnet …“, „Geklickt …“ und „Ausgefüllt …“ für einzelne Aktionen – kein LLM läuft im Container –, sodass eine unbeschriftete Sitzung dennoch lesbare Aktionsbeschreibungen unter einer impliziten Gruppe rendert.

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

Sitzungen ohne ui_step-Aufrufe werden weiterhin korrekt gerendert, unter einer einzigen impliziten Gruppe.

Verifizieren vs. Warten – wählen Sie das Richtige

Eine Sitzung wird als failed markiert, wenn eine harte Aktion fehlschlägt. Wie Sie verifizieren, entscheidet also darüber, ob der Bericht die Wahrheit sagt.

Rufen Sie ui_assert niemals in einer Wiederholungsschleife auf, um auf etwas zu warten – das erste falsche Ergebnis lässt den Lauf dauerhaft fehlschlagen, selbst wenn die App in Ordnung ist. Dafür ist ui_wait_for da.

Für sowohl ui_check als auch ui_wait_for gilt: Eine Bedingung, die nicht ausgeführt werden kann (keine Seite geöffnet oder der Ausdruck wirft eine Ausnahme), ist immer ein harter Fehler: Das ist ein Harness-Fehler, keine Beobachtung.

Auto-Fehler-Screenshots sind pro Sitzung budgetiert (FAILURE_SCREENSHOT_BUDGET, Standard 3). Identischer Screenshot-Inhalt wird im HTML-Bericht nur einmal eingebettet.

Was der Bericht zeigt

Ein Urteilsfeld (Status, Ziel, Schritt-/Aktions-/Fehleranzahl, Dauer), dann der Lauf als beschriftete Schritte mit Ergebnissen und verstrichener Zeit pro Schritt, dann etwaige Browserprobleme und schließlich das rohe Aktionsprotokoll hinter einer Aufklappfläche.

Konsolenfehler, nicht abgefangene Seitenfehler und Netzwerkfehler bei Anfragen werden automatisch erfasst und unter Browserprobleme aufgelistet – ein Ablauf, der besteht, während die Konsole wirft, ist ein falsches Grün, das man sehen sollte. HTTP-Fehlerantworten wie 404 oder 500 lösen Playwrights requestfailed-Ereignis nicht aus und werden nicht automatisch aufgelistet. Erfasste Probleme sind informativ und ändern niemals das Urteil. Bis zu 50 werden pro Sitzung aufbewahrt; darüber hinaus sagt der Bericht, dass der Rest verworfen wurde.

Siehe AGENTS.md für die Architektur und die vollständige MCP-Verbindungsanleitung sowie HARNESS.md für die REST-API-Referenz. Bereitstellungs-/Rollback-Verfahren finden Sie in RUNBOOK.md.

Umfang (v1)

Nur Web (Chromium), nur lokal, noch keine mobile Unterstützung. Siehe PRD.md für die vollständige Produktabsicht und PROJECT_SPEC.md für Architekturentscheidungen.