web-bridge – MCP-Werkzeug, mit dem KI-Editoren beliebige statische Webseiten steuern können

web-bridge ist ein MCP-Server (Node-Einzelprozess, zwei Schnittstellen), der es KI-Editoren ermöglicht, auf statischen Webseiten, die client.js eingebunden haben, JavaScript auszuführen, die Konsole zu lesen und Klicks/Eingaben zu simulieren. Es eignet sich für lokales Cross-Browser- und Multi-Tab-Debugging und unterstützt auch die Bereitstellung auf einem externen Server (--transport http, siehe „Remote-Bereitstellung“ unten).

   AI 编辑器                ┌───────────────────┐              浏览器页面
┌──────────────┐           │    MCP Server     │           ┌──────────────────┐
│  MCP Client  │           │  （Node 单进程）    │           │ <script src=     │
│              │ stdio 或   │ · 接口B: MCP       │  WebSocket │  :3210/client.js">│
│  AI 只到这里  │◄─────────►│   (stdio / http)  │◄──────────►│  client.js       │
└──────────────┘  Streamable│ · 接口A: WebSocket │  接口A     │  （eval 执行/     │
      HTTP(远程)           │ · HTTP /client.js │            │   console 捕获）  │
                           └───────────────────┘            └──────────────────┘

KI-Editor und Browser sind nicht direkt verbunden: Beide Verbindungen enden am MCP-Server (server.js); die KI steuert die Seite indirekt über Tool-Aufrufe.

Schnellstart

cd web-bridge
npm install          # 首次

1. Skript in die statische Webseite einbinden (beliebige Webseite, beliebiger Port, Cross-Origin ist freigegeben):

<script src="http://127.0.0.1:3210/client.js"></script>

2. MCP-Dienst im KI-Editor konfigurieren: Ersetzen Sie <REPO>/server.js in mcp.json durch den absoluten Pfad dieses Repositorys und fügen Sie es wie unten für Ihren Editor beschrieben ein. Sobald der Editor server.js startet, ist der WebSocket-Dienst (standardmäßig 127.0.0.1:3210) bereit.

3. Sagen Sie der KI: „Schauen Sie mit list_pages von web-bridge, welche Seiten verbunden sind, und klicken Sie dann mit eval_js für mich auf #btn und lesen Sie die Konsole.“

Hinweis zur Einbindungsreihenfolge: Es ist auch in Ordnung, wenn die Seite das Skript zuerst einbindet; client.js verbindet sich automatisch neu (Backoff 1s→2s→5s→10s). Nach dem Start des Editors verbindet sich die Seite automatisch wieder. Hub-Statusseite: http://127.0.0.1:3210/

MCP-Tools

pageId-Regel: Wenn nur eine Seite verbunden ist, kann sie weggelassen werden; wenn mehrere Seiten verbunden sind und keine angegeben wird, gibt das Tool einen Fehler und die Seitenliste zurück, und die KI ergänzt pageId und versucht es erneut.

Einbindung in Editoren

Die folgenden Beispiele gehen von einem absoluten Repository-Pfad /path/to/web-bridge aus; bitte bei Bedarf anpassen.

ZCode / Claude Code (Projektwurzel .mcp.json oder claude mcp add):

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["/path/to/web-bridge/server.js"],
      "env": { "PORT": "3210" }
    }
  }
}

Cursor (.cursor/mcp.json): Format wie oben.

Claude Desktop (claude_desktop_config.json): Format wie oben.

Kommandozeilenargumente: node server.js --port 3210 --host 127.0.0.1 --token <secret> (alternativ die Umgebungsvariablen PORT / HOST / TOKEN).

Remote-Bereitstellung (externer Server)

Der Standardmodus stdio erfordert, dass der Editor den Prozess lokal startet; wenn Sie web-bridge auf einem externen Server bereitstellen, verwenden Sie den HTTP-Transportmodus – der Editor muss in der MCP-Konfiguration nur eine URL angeben:

1. Auf dem Server starten (Empfehlung: mit systemd / pm2 verwalten, bei öffentlichem Netz muss ein Token aktiviert sein):

node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>

2. Editor-Konfiguration (Claude Code / Cursor / ZCode usw., an der ursprünglichen Konfigurationsstelle einfügen):

{
  "mcpServers": {
    "web-bridge": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

Bei direkter Verbindung (ohne Reverse-Proxy/TLS) tragen Sie http://<服务器IP>:3210/mcp als URL ein. Hinweis: Claude Desktop unterstützt nur den lokalen stdio-Modus, keine Remote-URL.

3. Skript auf der Seite so ändern, dass es auf den Server zeigt:

<script src="https://your-domain.com/client.js?token=<secret>"></script>

Hinweise:

• HTTPS-Seiten können nur https/wss verbinden (Mixed-Content-Einschränkung). Empfohlen wird ein Reverse-Proxy wie nginx/caddy für TLS-Terminierung und Weiterleitung an diesen Dienst; beim Ausliefern erkennt client.js automatisch X-Forwarded-Proto / X-Forwarded-Host und erzeugt die korrekte wss://-Adresse – keine zusätzliche Konfiguration nötig. Caddy-Beispiel (automatisches Zertifikat):

  your-domain.com {
    reverse_proxy 127.0.0.1:3210
  }

• Der /mcp-Endpunkt unterstützt nach Aktivierung des Tokens drei Authentifizierungsmethoden: Authorization: Bearer <secret> (empfohlen, in der Editor-Konfiguration als headers eintragen), X-Web-Bridge-Token: <secret> und den URL-Parameter ?token=.

• Der HTTP-Transport ist das offizielle Streamable HTTP-Protokoll (stateless-Modus); jede Anfrage wird unabhängig verarbeitet, alle teilen sich denselben Hub, und mehrere Editoren können gleichzeitig verbunden sein.

• Bei öffentlicher Bereitstellung unbedingt: --token setzen, TLS verwenden, in der Firewall nur benötigte Ports freigeben.

Sicherheitshinweise

• Standardmäßig lauscht er nur auf 127.0.0.1. Jede auf diesem Rechner geöffnete Webseite (einschließlich von Ihnen besuchter Drittanbieter-Websites) kann versuchen, eine Verbindung zum lokalen Port herzustellen – im Standardmodus ohne Token können sie den von der KI gesendeten Code empfangen und auch Ergebnisse fälschen.

• In einer nicht vertrauenswürdigen Netzwerkumgebung oder wenn Sie Geräte im LAN wie Mobiltelefone anschließen möchten (--host 0.0.0.0), müssen Sie --token aktivieren: Dann erfordert das Abrufen von client.js ?token=<secret>, und auch das erste WebSocket-Paket prüft das Token.

WebSocket-Nachrichtenprotokoll (interne Referenz)

Die WS-Nachrichten zwischen Browser und MCP-Server sind JSON-Textframes; Referenz bei der Wartung von lib/hub.mjs / client.js:

eval-Ausführungskonvention (client.js): Zuerst wird der Code als Ausdruck in async () => ( code ) umschlossen; bei SyntaxError wird auf einen Anweisungsblock zurückgegriffen (mit return); $ / $$ sind vordefiniert; das Timeout wird von der Hub-Seite gemessen (Standard 30s, Maximum 120s); das Ergebnis wird sicher als String-Vorschau serialisiert (Error→stack, DOM→outerHTML-Zusammenfassung, Markierung zyklischer Referenzen, Tiefe ≤ 6, ≤ 50k Zeichen).

Entwicklung

• Tests: npm test (Node-e2e: Prozess starten + simulierte Seite + Tool-Aufrufe über stdio/HTTP-Dualtransport); npm run test:browser (Playwright-Realbrowser-Pfad: Chromium lädt test/test-page.html, validiert die 6 Tools über echtes WebSocket; vor dem ersten Mal npx playwright install chromium ausführen). Der Realbrowser-Pfad kann auch durch Öffnen der Testseite manuell verifiziert werden.

• Abhängigkeiten: ws (WebSocket), @modelcontextprotocol/sdk (MCP), zod (Parametervalidierung); Entwicklungsabhängigkeit @playwright/test. Node ≥ 18.