Browser-MCP-Server

Definition

Ein Browser-MCP-Server ist eine Variante eines MCP-Servers, die Tools bereitstellt, die nur im Browser-Kontext Sinn ergeben — Lese-/Schreib-Zugriff auf den DOM, Local-Storage, Geolocation, Clipboard etc. Der LLM-Host kann damit die Seite veraendern, auf der er selbst eingebettet ist, oder andere Browser-spezifische Daten lesen.

Mechanik

Pyground laedt Pyodide in einem WebWorker — Worker haben keinen direkten DOM-Zugriff. Wir bauen daher eine postMessage-Bruecke vom Worker zum Main-Thread:

[runnable-Block]
       |
       v
WebWorker (Pyodide)
+-- Python: pyground.dom.add_class("h2", "highlight")
|        |
|        v  postMessage({type:'dom:add_class', selector, name})
|        |
|        v  await response
|
Main-Thread:
+-- document.querySelectorAll('h2').forEach(el => el.classList.add('highlight'))
    +-- postMessage({type:'dom:result', value: 5})

Aus dem Pyodide-Snippet sind 19 DOM-Tools nutzbar (alle async):

Lesen: read(selector) (Text — bei <input>/<textarea> der .value), html(selector) (innerHTML), attr(selector, name), query_all(selector) (Liste mit text/href/attrs/tag/id), exists(selector)

Schreiben: set_text, set_html, add_class, remove_class, set_style(selector, dict), inject(selector, position, html) (beforebegin/afterbegin/beforeend/afterend), remove

Interaktiv: scroll_to, click, focus

Magic: create_widget(selector, position, code, opts) — fuegt ein neues runnable-Pyodide-Widget direkt in die Seite ein. show_modal(title, code, opts) — oeffnet das gleiche, aber als zentriertes Modal mit Schliessen-Button (genau das, was die Demo unten nutzt). show_fallback_snake_modal(reason) — Hardcoded-Snake im Modal, fuer Faelle wo der LLM-Output nicht parsbar war.

Reset: reset() triggert location.reload() — alle Modifikationen weg.

Hinweis JsProxy: query_all() liefert ein JS-Array von JS-Objekten zurueck. In den Snippets nutze Attribut-Zugriff (link.text, link.href), nicht Item-Zugriff (link['text'] schlaegt fehl mit „JsProxy object is not subscriptable"). Wenn du echte Python-Dicts willst: link.to_py() pro Eintrag.

Magisches Spiel-Modal — LLM-generiert

Tippe einen Spielnamen in das Feld unten, klicke Spiel generieren. Llama-3.1-8B (aus dem MCP-Eintrag, ~5 GB OPFS-Cache) schreibt ein Pygame-aehnliches Snippet, das anschliessend als spielbares Mini-Widget in einem Modal-Fenster ueber dem Content erscheint — der Agent ruft das Tool show_game(name, code) auf, das intern dom.show_modal(...) triggert.

Das ist die magische Verbindung: das LLM erzeugt nicht nur Text, sondern eine Aktion — die Seite veraendert sich live, das Ergebnis ist sofort spielbar, und mit dem ×-Button (oder ESC) ist es genauso schnell wieder weg.

Pyodide laedt… Strg/⌘+Enter zum Ausführen

Nach dem Run erscheinen hier die Top-Level-Variablen.

import ast, json, re
from pyground import dom, llm

# 1) Spielname aus dem Eingabefeld lesen.
game = (await dom.read("#mcp-game-prompt") or "snake").strip()
print(f"Gewaehltes Spiel: {game}")

# 2) Llama-3.1-8B laden (vom MCP-Eintrag bereits gecacht).
print("Lade Llama-3.1-8B (~4.7 GB beim 1. Mal, danach Cache)...")
m = await llm.load("llama-8b")

# 3) Tool-Definition + Few-Shot Bouncing-Ball-Beispiel.
SYSTEM_PROMPT = (
    "You generate small playable games for the pyground browser sandbox.\n"
    "\n"
    "You have ONE tool:\n"
    "  show_game(name: str, code: str)\n"
    "\n"
    "The code MUST start with these imports and use this API:\n"
    "  from pyground import ctx, canvas, keyboard\n"
    "  import asyncio\n"
    "\n"
    "  # ctx is a 2D canvas context (like CanvasRenderingContext2D).\n"
    "  # canvas.width=640, canvas.height=400.\n"
    "  # ctx methods: fillRect(x,y,w,h), beginPath(), arc(x,y,r,0,6.283),\n"
    "  #              fill(), strokeRect, fillText(text,x,y).\n"
    "  # ctx properties: fillStyle='#hex', strokeStyle, font='16px monospace'.\n"
    "  # keyboard.is_pressed('ArrowUp'/'ArrowDown'/'ArrowLeft'/'ArrowRight'/'Space') -> bool.\n"
    "  # keyboard.next_event() -> {kind:'down'/'up', code:'ArrowUp'} or None.\n"
    "  # Use 'await asyncio.sleep(0.05)' inside your loop for ~20 fps.\n"
    "  # End the loop with a fixed iteration count (e.g. range(2000)).\n"
    "\n"
    "When asked for a game, respond EXACTLY with:\n"
    "<tool_call>{\"name\":\"show_game\",\"arguments\":{\"name\":\"GAME_NAME\",\"code\":\"PYTHON_CODE\"}}</tool_call>\n"
    "\n"
    "Example for 'bouncing ball':\n"
    "<tool_call>{\"name\":\"show_game\",\"arguments\":{\"name\":\"Bouncing Ball\",\"code\":\"from pyground import ctx, canvas\\nimport asyncio\\n\\nx, y, vx, vy = 100, 100, 4, 3\\nfor _ in range(600):\\n    ctx.fillStyle = '#1a1a1a'\\n    ctx.fillRect(0, 0, canvas.width, canvas.height)\\n    ctx.fillStyle = '#ffcb6b'\\n    ctx.beginPath()\\n    ctx.arc(x, y, 12, 0, 6.283)\\n    ctx.fill()\\n    x += vx; y += vy\\n    if x < 12 or x > canvas.width-12: vx = -vx\\n    if y < 12 or y > canvas.height-12: vy = -vy\\n    await asyncio.sleep(0.033)\\n\"}}</tool_call>\n"
    "\n"
    "NEVER output anything except the <tool_call>...</tool_call> block."
)
USER_PROMPT = f"Generate a small playable {game} game."

print("\nGeneriere Code (~30-60 Sek)...")
raw = await m.chat([
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user",   "content": USER_PROMPT},
])

# 4) Tool-Call parsen + Code validieren. (Fallback-Snake lebt nicht hier,
#    sondern im Main-Thread-JS via dom.show_fallback_snake_modal.)
def parse_tool_call(text):
    mm = re.search(r'<tool_call>\s*(\{.*?\})\s*</tool_call>', text, re.S)
    if not mm:
        return None
    try:
        return json.loads(mm.group(1))
    except Exception as exc:
        print(f"[debug] JSON-Parse-Fail: {exc}")
        return None

call = parse_tool_call(raw)
code = None; name = None; reason = None
if not call:
    reason = "Kein <tool_call>-Block gefunden"
elif call.get("name") != "show_game":
    reason = f"Falsches Tool: {call.get('name')!r}"
else:
    args = call.get("arguments") or {}
    code = args.get("code")
    name = args.get("name") or game
    if not code:
        reason = "Tool-Call ohne 'code'-Argument"
    else:
        # Top-Level-await im LLM-Code erlauben (asyncio.sleep im Game-Loop):
        # Pyodide.runPythonAsync setzt dieses Flag intern auch, also ist's
        # zur Laufzeit ok. Ohne das Flag wirft compile() faelschlich
        # 'await outside function' und der Fallback springt unnoetig ein.
        try:
            compile(code, "<llm>", "exec", flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT)
        except SyntaxError as exc:
            reason = f"Syntax-Error im LLM-Code: {exc}"
            code = None

# 5) Modal oeffnen — entweder mit LLM-Code oder Fallback.
if code:
    print(f"\n[OK] LLM hat {len(code)} Zeichen Code generiert.")
    await dom.show_modal(f"Spiel: {name}", code)
    print("\n>>> Spiel-Modal geoeffnet — viel Spass! <<<")
    print("    Klick auf den Canvas, spiel mit Pfeiltasten. ESC oder × zum Schliessen.")
else:
    print(f"\n[!] LLM-Output unbrauchbar: {reason}")
    print("[i] Hartkodierter Fallback-Snake oeffnet sich.")
    await dom.show_fallback_snake_modal(reason)

Tipp: Was funktioniert zuverlaessig? Llama-3.1-8B kennt snake, pong, breakout und einfache bouncing ball-Variationen. Komplexere Spiele wie tetris oder pacman klappen mal, mal nicht — dann springt der Fallback-Snake ein.

Sicherheitsmodell

Aktuell loose: jeder Selector ist erlaubt, Schreibzugriff auf das ganze document. Das ist bewusst Tueftler-Default — Pyground ist kein Security-Sandbox-Tool, der User entscheidet ob er Snippets vertraut. Wenn der gleiche Mechanismus in produktiven Apps deployt werden soll, sind drei Stufen denkbar:

Loose (was wir haben): voller document-Zugriff. Maximal magisch.
Strict-Sandbox: Schreibzugriff nur in einer <div data-mcp-sandbox>-Container, Lesen ueberall.
Hybrid: Lesen frei, Schreiben erfordert explizites dom.enable_writes() als User-Gesture.

In Cloud-LLM-Hosts wie Claude oder GPT mit Browser-Tool-Use ist das Sandboxing typischerweise strikter — der LLM sieht eine isolierte Page-Capture, nicht die Live-DOM des Hosts.

In der Praxis

Browser-MCP-Server in der freien Wildbahn:

Anthropic Browser-Tool: Claude kann Webseiten via Headless-Browser-Sandbox ansteuern, mit Screenshots + Element-Tree als Input
OpenAI Operator: aehnlicher Ansatz, mit eigenem virtuellen Browser
browser-use (Open-Source): Library, die einen Playwright-Browser an einen LLM koppelt
Pyground.dom (was du gerade siehst): Pyodide-Pyground-spezifisch, aber das gleiche Pattern auf Browser-Worker-Bridge runtergebrochen

Die DOM-Bridge-Architektur ist nicht spezifisch fuer pyground — jeder Pyodide-im-Browser-Stack kann das nachbauen. Was pyground hier zeigt: dass die Komponenten (Pyodide + WebLLM + DOM-Bridge) ohne Cloud-Backend kombinierbar sind.

Definition

Mechanik

Magisches Spiel-Modal — LLM-generiert

Sicherheitsmodell

In der Praxis

Quellen