Lukiluki
DEEN
Menu

Ambience

Language
DEEN
KI & Agents
WebMCPChrome CanaryAI AgentsJSON-RPC
🌐 English translation in progress – displaying original German guide.

Web MCP – Lokale KI-Agenten im Browser

WebMCP-Leitfaden: Deklarative HTML- & imperative JavaScript-Tools für KI-Agenten im Browser mit Annotation-Hints und Origin-Sicherheit implementieren.

LKLukas Kopischke
Last updated on

Bisher interagieren KI-Agenten mit Webseiten vor allem über fehleranfälliges Screen-Scraping und simulierte Mausklicks (Actuation). Bricht ein CSS-Selektor oder ändert sich das Layout, scheitert der Agent. WebMCP (Web Model Context Protocol) schlägt die Brücke: Webseiten deklarieren ihre Fähigkeiten als strukturierte Werkzeuge für Browser- und Extensions-Agenten – wahlweise deklarativ im HTML oder imperativ via JavaScript.

WebMCP ist ein offener Web-Standard (W3C / Chrome Origin Trial ab Version 149), der Web-Applikationen befähigt, semantische Werkzeuge über document.modelContext oder annotierte HTML-Formulare bereitzustellen. Mit standardisierten Annotation-Hints (consequentialHint, readOnlyHint), Character-Budgets und Origin-Gating ermöglicht WebMCP sichere, zuverlässige und deterministische Agenten-Aktionen direkt im Browser.

Die goldene Regel

WebMCP ersetzt unzuverlässiges DOM-Scraping durch semantische Tool-Schnittstellen: Der Browser wird vom passiven Anzeigemedium zur steuerbaren Werkbank für autonome Agenten.

Was brauche ich? (Prerequisites & Setup)

  • Browser & Flags: Chrome 149+ (Origin Trial) oder lokal über chrome://flags/#enable-webmcp-testing aktivieren.
  • Typdefinitionen: @types/webmcp bzw. das npm-Paket webmcp-types (oder usewebmcp für React).
  • Permissions Policy: Standardmäßig self; Cross-Origin-Iframes erfordern das Attribut allow="tools".

Wie kann ich das prüfen? (Verification & Audit)

  • Konsole: 'modelContext' in document prüfen und verfügbare Tools mit await document.modelContext.getTools() auflisten.
  • Inspektion: Die offizielle Chrome-Erweiterung Model Context Tool Inspector für manuelle Tool-Aufrufe nutzen.
  • Events: Auf document.modelContext.addEventListener("toolchange", ...) lauschen, um dynamische Updates zu verifizieren.

Typische Anwendungsfälle (Use Cases)

  • Strukturierte Formular-Befüllung: Agent mappt Konversationsdaten fehlerfrei auf Pflicht- und Optionsfelder.
  • Sichere Buchungs- & Kaufprozesse: Sensible Aktionen mit consequentialHint: true und Nutzer-Bestätigung.
  • App-Diagnose & Deep-Links: Agent führt Diagnose- oder Filterfunktionen ohne Menü-Odyssee im DOM aus.

Kriterien-Katalog: Was bei der Implementierung beachtet werden muss

Statt dem KI-Agenten eine starre Dateistruktur oder feste Pfade aufzuzwingen, folgt eine saubere WebMCP-Integration den acht offiziellen Spezifikations- und Sicherheitskriterien:

1. API-Wahl: Deklarativ vs. Imperativ

Architektur

Formulare mit reinen Eingabefeldern nutzen deklarative HTML-Attribute (toolname, tooldescription) – Zero-JS! Komplexe Logik, State-Management und Navigationen nutzen document.modelContext.registerTool().

2. Verbindliche Annotation-Hints

Sicherheit

Jedes imperative Tool muss Sicherheits-Hints deklarieren: consequentialHint: true erzwingt Bestätigungsdialoge bei Käufen/Löschungen, readOnlyHint: true markiert Leseoperationen, untrustedContentHint: true schützt vor Prompt Injections.

3. Offizielle Character Budgets

Token-Schutz

Tool- und Parameter-Namen $\le 30$ Zeichen, Parameter-Beschreibungen $\le 150$ Zeichen, Tool-Beschreibung $\le 500$ Zeichen und Tool-Output $\le 1.500$ Zeichen, um Agenten-Kontextfenster nicht zu sprengen.

4. Graceful Failure & Recovery

Resilienz

Fehler dürfen keine generischen 500er sein. Sie müssen als Wegweiser formuliert sein, damit das Modell sich selbst korrigieren kann (z. B. „Ungültiges Format. Erwartet: YYYY-MM-DD“ statt „Error“).

5. Kognitive Entlastung (Raw Input)

Pragmatik

Akzeptiere rohen Nutzer-Input (z. B. Zeitangaben als String, keine Kopfrechnung vom LLM verlangen). Semantische Enums nutzen statt kryptischer IDs (shipping="Express" statt shipping_id=1).

6. Lifecycle & AbortSignal

Ressourcen

Tools dynamisch mit controller.abort() deregistrieren, wenn der Zustand verlassen wird. In execute(params, { signal }) das signal an fetch() übergeben, um abgebrochene Aktionen sofort zu stoppen.

7. Permissions Policy & Origin Gating

Isolation

Tools sind standardmäßig nur für dieselbe Origin sichtbar. Cross-Origin-Iframes benötigen allow="tools" und explizite Freigabe über das exposedTo-Array.

8. Validate in Code, loosely in Schema

Typsicherheit

Das JSON-Schema definiert Basistypen; die harte Geschäftslogik und Randfälle validiert der Code (z. B. Zod) mit präzisen, konstruktiven Fehlermeldungen.

Architektonische Best Practices

Empfohlen (Best Practice)
  • consequentialHint: true für alle Käufe, Buchungen und Löschungen setzen
  • untrustedContentHint: true bei Nutzerbewertungen oder externem Content
  • AbortSignal für Tool-Deregistrierung und Request-Abbrüche weiterreichen
  • Character Budgets einhalten (max. 500 Zeichen Beschreibung, 1.500 Output)
  • Konstruktive Fehlermeldungen formulieren, die dem Modell den Ausweg zeigen
Zu vermeiden (Anti-Pattern)
  • Kryptische Parameter-IDs ohne semantische Klarheit fordern (type_id=3)
  • Generische Exceptions werfen ("Error 500"), an denen der Agent scheitert
  • Überlappende Tools deklarieren, die um dieselbe Nutzerabsicht konkurrieren
  • Tools dauerhaft im DOM belassen, wenn die Aktion im aktuellen Viewport ungültig ist

Agent System Prompts

Kopiere diese Prompts in deinen Coding-Agenten (Cursor, Claude Code, Antigravity). Sie instruieren die KI anhand der 8 Spezifikationskriterien, ohne starre Dateipfade vorzugeben:

Setup Prompt
WebMCP Implementation & Integration PromptZiel: Cursor / Claude Code / Antigravity
Instruiert deinen Agenten, die bestehende Applikationsstruktur zu analysieren und WebMCP kriterienkonform einzubinden.

Du bist ein erfahrener Frontend-Architekt. Implementiere WebMCP in dieser Web-Anwendung.

Analysiere zuerst die bestehende Projektarchitektur (Framework, Routing, Formulare, State-Management) und wähle den passendsten Integrationsweg. Beachte dabei strikt folgende Kriterien der WebMCP-Spezifikation:

  1. API-Entscheidung: Nutze die Deklarative API (toolname / tooldescription auf HTML-Forms) für Standardformulare ohne JS-Overhead. Nutze document.modelContext.registerTool() für dynamische Logik.
  2. Annotation-Hints: Setze consequentialHint: true für alle Aktionen mit Seiteneffekten (Kauf, Buchung, Löschung). Setze readOnlyHint: true für reine Datenabfragen und untrustedContentHint: true für nutzergenerierte Inhalte.
  3. Character Budgets: Halte Tool-Namen unter 30 Zeichen, Parameter-Beschreibungen unter 150 Zeichen und Tool-Beschreibungen unter 500 Zeichen. Begrenze Tool-Outputs auf maximal 1.500 Zeichen.
  4. Error Recovery: Formuliere Fehlermeldungen konstruktiv als Wegweiser, damit sich das Modell selbst korrigieren kann.
  5. Lifecycle: Reiche in der execute-Funktion das AbortSignal an asynchrone Requests weiter und nutze AbortController zum Deregistrieren von Tools bei Zustandswechseln.
  6. Kognitive Entlastung: Akzeptiere rohe Nutzereingaben und nutze selbsterklärende Enums statt numerischer IDs.

Präsentiere nach der Implementierung eine Übersicht der registrierten Tools samt ihrer Schemas und Annotation-Hints.

Audit Prompt
WebMCP Security & Evals-AuditorZiel: Cursor / Claude Code / Antigravity
Auditiert eine WebMCP-Implementierung auf Sicherheitsrisiken, Annotation-Hints, Character Budgets und Evals-Fähigkeit.

Überprüfe die WebMCP-Werkzeuge in diesem Projekt auf Einhaltung der Spezifikation und Sicherheitsrichtlinien:

  1. Annotation-Audit: Sind consequentialHint und readOnlyHint korrekt gesetzt? Werden sensible Aktionen durch Nutzer-Bestätigung abgesichert?
  2. Prompt-Injection-Schutz: Sind Werkzeuge mit dynamischen oder externen Inhalten mit untrustedContentHint versehen? Gibt es ungeprüfte DOM-Manipulationen (innerHTML)?
  3. Character-Budget-Check: Überschreiten Tool-Beschreibungen (500 Zeichen) oder Outputs (1.500 Zeichen) die empfohlenen Grenzen?
  4. Permissions Policy: Werden Cross-Origin-Iframes explizit über allow="tools" und exposedTo kontrolliert?
  5. Cancellation: Wird das AbortSignal in long-running Werkzeugen korrekt bis zum fetch() durchgereicht?
  6. Eval-Fähigkeit: Sind Tool-Aufrufe deterministisch testbar und liefern klare Status-Rückmeldungen für Test-Suiten?

Gib einen priorisierten Prüfbericht mit konkreten Code-Optimierungen aus.

Checkliste: WebMCP in der Praxis

  • API-Form gewählt: Deklarative Formulare für Zero-JS Eingaben; document.modelContext für App-Logik.
  • Annotation-Hints deklariert: consequentialHint für Buchungen/Käufe, readOnlyHint für Lesezugriffe aktiv.
  • Character Budgets eingehalten: Beschreibung $\le 500$ Zeichen, Output $\le 1.500$ Zeichen pro Tool.
  • Graceful Failure implementiert: Fehler liefern konstruktive Korrekturhinweise statt unleserlicher Exceptions.
  • AbortSignal durchgereicht: Asynchrone fetch()-Aufrufe brechen bei Agenten-Abbruch sauber ab.
  • Cross-Origin abgesichert: Iframes nutzen allow="tools" und explizite exposedTo-Origins.