web-debug-mcp

web-debug-mcp ist ein lokaler, agenten-nativer Web-Debugging-Server für Codex und andere MCP-Clients. Er bietet eine kleine Tool-Oberfläche, die eine Browser-Sitzung, JavaScript-Debugger, begrenzte Laufzeit-Evidenz und reproduzierbare Ablauf-Verifikation koordiniert.

Das aktuelle Inkrement unterstützt framework-neutrale Browser-Ziele, Chromium/CDP, Safari WebDriver mit WebDriver-BiDi-Evidenz, eine automatisch injizierte React-Development-Bridge, einen Vite-Modulgraph/HMR-Endpunkt und Next.js-Development-Server-Metadaten mit begrenzten Server-Logs, Routenkompilierung, Server-Action-Lookup und beobachteter Request-Ausführungs-Evidenz. Browserspezifische Grenzen bleiben explizit. Dadurch bleibt frameworkspezifischer Kontext hinter derselben MCP-Fassade, anstatt separate Tool-Kataloge hinzuzufügen.

Was enthalten ist

• Projekterkennung ohne Prozessstart.

• Lokaler Chromium-Attach-Modus über einen expliziten CDP-Endpunkt.

• Expliziter Remote-CDP-Attach wird nur mit allowRemote: true unterstützt; Ziele werden als nicht isoliert markiert und nie automatisch erkannt.

• Lokaler Chromium-Startmodus über einen expliziten ausführbaren Pfad.

• Safari-WebDriver-Modus über lokales safaridriver oder einen expliziten WebDriver-Endpunkt, mit BiDi-Konsolenereignissen und Netzwerkereignissen, wenn das installierte Safari diese bereitstellt.

• Browser-Aktionen mit gleicher Herkunft: Navigieren, Klicken, Ausfüllen, Warten und Neuladen.

• JavaScript-Breakpoints, Pausensteuerung, begrenzte Aufruf-Frames und standardmäßig schreibgeschützte Auswertung.

• Konsolen-, Netzwerk-Metadaten, DOM-Zusammenfassung, Screenshot und Debugger-Evidenz in einem geschwärzten Bündel.

• React-Komponentenbaum, Hook-Werte, Quellpositionen, Render-Zähler, begrenzte Commit-Zusammenfassungen, Profiler-Dauern, eine flache Flamegraph-Ansicht und abgeleitete Render-Ursachen, wenn der Development-Build React-Commits bereitstellt.

• Vite-Modul/Importer-Graph, HMR-Status, Diff des transformierten Codes und Source-Map-Zusammenfassungen über das Development-Plugin webDebugVitePlugin().

• Begrenzte, geschwärzte Next.js-Development-Log-Tails, wenn das Log innerhalb des erkannten Projektstamms bleibt.

• Explizite Next.js-Routenkompilierung und Server-Action-Lookup über web_next_inspect, plus normalisierte Server-Request-Traces und request-verknüpfte Ausführungs-Evidenz, wenn der Browser eine Next-Action-Anfrage sendet.

• Begrenzte Replay-Zeitleiste in Aufnahmen und Frame-Lookup über web_replay_seek; restore: true spielt nur sichere beibehaltene Aktionen ab und lehnt bereinigte Formulareingaben ab.

• Reproduzierbare Aktionsszenarien mit einfachen Post-Fix-Prüfungen.

• Eine deterministische Vanilla-Fixture und eine projektnative Harness-Prüfung.

• Eine Live-React/Vite-Fixture, automatische React-Bridge und Modulgraph/HMR-Smoke.

• Eine Live-Next.js-App-Router-Fixture und /_next/mcp-Laufzeit-Smoke.

Related MCP server: Kaboom Browser AI Devtools MCP

Anforderungen

• Node.js 20 oder neuer. Safari BiDi erfordert Node 20.10+ mit --experimental-websocket oder Node 21+; ältere Laufzeiten behalten Safari-WebDriver-Aktionen und den dokumentierten Netzwerk-Fallback bei, melden jedoch BiDi-Konsolen-Einschränkungen.

• Ein Chromium-basierter Browser für eine Live-Sitzung.

• Entweder ein expliziter WEB_DEBUG_CHROME_EXECUTABLE_PATH oder ein expliziter cdpEndpoint, der an web_session_start übergeben wird.

Entwicklungsbefehle

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

Führen Sie die Fixture mit npm run serve:fixture aus. Der Server bindet an 127.0.0.1 und verwendet standardmäßig Port 4173; setzen Sie WEB_DEBUG_FIXTURE_PORT, um einen anderen Port zu verwenden.

Führen Sie npm run smoke:live aus, nachdem Sie WEB_DEBUG_CHROME_EXECUTABLE_PATH gesetzt haben, wenn der standardmäßige macOS-Chrome-Pfad nicht verfügbar ist. Es startet die Vanilla-Fixture, setzt einen Breakpoint in app.js, klickt auf den Button, erfasst einen pausensicheren Evidenzpfad und räumt die eigenen Browser- und Fixture-Prozesse auf.

Führen Sie npm run smoke:react-vite aus, um die Vite-Fixture zu starten, React-Komponenten/State-Evidenz zu verifizieren, bei fixtures/react-vite/src/App.jsx zu pausieren und den Zahlungsablauf erneut abzuspielen.

Fügen Sie für eine Vite-Anwendung das nur für die Entwicklung vorgesehene Plugin zu vite.config.ts hinzu:

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

Das Plugin stellt den lokalen, schreibgeschützten Modulgraph-Endpunkt bereit, der während einer Debug-Sitzung verwendet wird. Es sollte nicht in einem Produktionsserver aktiviert werden.

Führen Sie npm run smoke:next aus, um die Next.js-App-Router-Fixture zu starten, den integrierten /_next/mcp-Endpunkt abzufragen, Routen-/Projekt-/Kompilierungs-Metadaten und ein begrenztes Server-Log-Tail zu verifizieren und den Client-Routen-Handler-Ablauf zu üben.

Führen Sie npm run smoke:safari aus, um die Vanilla-Fixture über Safari WebDriver zu testen. Aktivieren Sie zuerst Safari-Einstellungen → Entwickler → Remote-Automatisierung erlauben; Safari läuft sichtbar, erfasst BiDi-Konsolen-Evidenz und meldet, ob Netzwerk-Evidenz von BiDi oder dem begrenzten Performance-Resource-Timing-Fallback stammt. Safaris JavaScript-Debugger bleibt über diesen Adapter nicht verfügbar.

Safari 27 und Safari Technology Preview 247 enthalten Apples offiziellen Safari-MCP-Server. Verwenden Sie diesen offiziellen Server, wenn dessen browser-native DOM-, Netzwerk-, Konsolen- und Screenshot-Tools die gewünschte Oberfläche sind; dieses Repository fügt keinen doppelten öffentlichen Safari-MCP-Katalog hinzu. Der WebDriver-Adapter bleibt als Single-Facade-Kompatibilitätspfad der Suite für ältere Safari-Versionen und für gemeinsame Sitzungs-/Evidenz-Orchestrierung nützlich.

Führen Sie den MCP-Server während der Entwicklung mit npm run dev oder nach npm run build mit node dist/index.js aus. MCP-Protokollnachrichten verwenden stdout; Diagnosen müssen auf stderr bleiben.

MCP-Workflow

1. Rufen Sie web_project_detect mit dem Projektstamm auf.

2. Rufen Sie web_session_start mit einer Loopback-URL und einer expliziten Browser-Verbindung oder ausführbaren Datei auf.

3. Verwenden Sie web_browser_action und web_breakpoint_set, um das Problem zu reproduzieren.

4. Rufen Sie web_issue_capture für ein begrenztes Evidenz-Bündel auf.

5. Rufen Sie für Next.js web_next_inspect auf, um eine Route zu kompilieren oder eine Server-Action-ID aufzulösen.

6. Speichern Sie einen Ablauf mit web_repro_record und führen Sie ihn später mit web_fix_verify aus.

7. Verwenden Sie web_replay_seek, um einen beibehaltenen erfassten Frame zu untersuchen; übergeben Sie restore: true nur, wenn der Frame sichere, nicht sensible Aktionen enthält.

8. Rufen Sie web_session_close auf, wenn die Sitzung nicht mehr benötigt wird.

Der Server schreibt während einer normalen Sitzung nicht in das Projekt. Screenshots werden in einem temporären, sitzungsbezogenen Artefaktverzeichnis gespeichert und als Pfade zurückgegeben.

Sicherheitsstandards

• Browser-URLs sind nur Loopback, es sei denn, allowRemote ist explizit aktiviert.

• Die Browser-Navigation bleibt auf der Sitzungs-Herkunft.

• Externe CDP-Anbindung wird als nicht isoliert markiert.

• Konsolen-, Netzwerk-, Debugger-Lokale und ausgewertete Werte werden geschwärzt und begrenzt.

• Rohe Antwortkörper, Cookies, Autorisierungswerte und Browser-Speicher werden vom Kern-Adapter nicht erfasst.

• Die Auswertung lehnt Nebenwirkungen ab, es sei denn, allowSideEffects ist explizit true.

Aktuelle Grenze

Dieses Repository ist ein lokales Entwicklerwerkzeug, kein gehosteter Dienst. Es gibt keine Produktionsbereitstellung, keinen CI-Workflow, keine unauthentifizierte/automatisch erkannte Remote-Browser-Steuerung und keine vollständige Parität mit dem React-DevTools-Profiler/Flamegraph. React-Dauern und Render-Ursachen-Details sind begrenzt und werden aus dem DevTools-Hook abgeleitet; Vite-Provenienz und Source Maps sind Zusammenfassungen und kein vollständiger Source-Map-Debugger; Next-Ausführungs-Evidenz ist auf request-verknüpfte Server-Action-Metadaten, Request-Einblicke und begrenzte Logs beschränkt; Safari-Debugger-Parität ist nicht verfügbar und Safari 26 erfordert möglicherweise den Performance-Resource-Timing-Netzwerk-Fallback; die Replay-Wiederherstellung ist auf sichere beibehaltene Aktionen beschränkt und keine Zeitreise durch den Anwendungszustand. Explizite Remote-CDP-Anbindung, Safari-WebDriver-Aktionen/DOM/Screenshots, explizite Fähigkeitswarnungen und begrenzte Replay-Wiederherstellung sind verfügbar. Ein genehmigter externer Remote-Host und vom Aufrufer gelieferte Harness-Zertifizierungsnachweise sind für diese jeweiligen Behauptungen weiterhin erforderlich.