proxy-doctor

Diagnostiziere Proxy-Fehlkonfigurationen, die KI-Programmierwerkzeuge lahmlegen.

Wenn dein Browser einwandfrei funktioniert, aber die KI-Funktionen von Cursor / VS Code / Windsurf nicht – proxy-doctor sagt dir genau, woran es liegt und wie du es behebst.

Das Problem

KI-Programmierwerkzeuge (Cursor, VS Code mit Copilot, Windsurf) sind auf langlebige Streaming-Verbindungen (SSE/HTTP2) angewiesen, die brechen, wenn:

• Dein System-Proxy auf einen Localhost-Port zeigt, auf dem nichts lauscht

• Eine VPN-/Proxy-App geschlossen wurde, ihre Einstellungen aber in den macOS-Systemeinstellungen verblieben sind

• Dein Editor veraltete Proxy-Umgebungsvariablen von launchctl geerbt hat

• Der Proxy läuft, aber Streaming-Antworten puffert und damit KI-Vervollständigungen unterbricht

Die Folge: „Browser funktioniert, KI-Editor nicht“ – die häufigste und frustrierendste Entwicklererfahrung.

Related MCP server: Inksnow MCP Proxy

Was wird geprüft

proxy-doctor durchleuchtet 5 Ebenen deiner macOS-Proxy-Konfiguration:

Schnellstart

CLI

# Install
pip install proxy-doctor

# Run diagnosis (JSON output — default, optimized for AI agents)
proxy-doctor check

# Run diagnosis (human-readable output)
proxy-doctor check --human

# Show recommended fixes
proxy-doctor fix

# Check a different editor
proxy-doctor check --editor vscode

Als MCP-Tool (für KI-Agenten)

proxy-doctor wird als MCP-Server ausgeliefert, den KI-Agenten direkt ansprechen können:

# Install with MCP support
pip install proxy-doctor[mcp]

# Run MCP server
python -m proxy_doctor.mcp_server

Füge Folgendes zu deiner MCP-Konfiguration hinzu (z. B. Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "proxy-doctor": {
      "command": "python3",
      "args": ["-m", "proxy_doctor.mcp_server"]
    }
  }
}

Hinweis: "command" muss auf das Python verweisen, in dem proxy-doctor[mcp] installiert ist. Falls python3 nicht funktioniert, verwende den vollständigen Pfad (führe which python3 oder python3 -c "import sys; print(sys.executable)" aus, um ihn zu finden).

Dein KI-Agent kann dann aufrufen:

• diagnose_proxy(editor="cursor") – vollständige 5-Ebenen-Diagnose mit Belegen

• list_fixes(editor="cursor") – empfohlene Korrekturen mit ausführbaren Befehlen

• supported_editors() – Liste der verfügbaren Editoren

Für KI-Agenten: Schnellinstallation

Einzeiler (fge dies in deinen KI-Agenten ein):

Installiere proxy-doctor (pip install proxy-doctor[mcp]) und füge es mit dem Befehl python -m proxy_doctor.mcp_server zu deiner MCP-Konfiguration hinzu. Verwende dann das Werkzeug diagnose_proxy, um die Proxy-Gesundheit zu prüfen.

Falls du ein KI-Agent bist, der proxy-doctor für deinen Benutzer einrichtet:

# 1. Install
pip install proxy-doctor[mcp]

# 2. Find the Python path
python3 -c "import sys; print(sys.executable)"

# 3. Add to ~/.cursor/mcp.json (use the path from step 2)
# {
#   "mcpServers": {
#     "proxy-doctor": {
#       "command": "<python-path-from-step-2>",
#       "args": ["-m", "proxy_doctor.mcp_server"]
#     }
#   }
# }

# 4. If MCP is not available, use CLI directly (zero dependencies):
proxy-doctor check          # JSON output
proxy-doctor check --human  # human-readable
proxy-doctor fix            # show fixes (read-only)
proxy-doctor fix --apply    # apply fixes (asks for confirmation)

Daemon-Modus (v0.2+)

Führe proxy-doctor als persistenten Hintergrunddienst mit automatischer Gesundheitsüberwachung aus:

# Start daemon (installs as macOS launchd service)
proxy-doctor daemon start

# Check daemon status
proxy-doctor daemon status

# Stop daemon
proxy-doctor daemon stop

# Check for updates
proxy-doctor update

Der Daemon läuft alle 5 Minuten, vergleicht die Ergebnisse mit der vorherigen Prüfung und sendet eine macOS-Benachrichtigung, wenn sich der Status ändert (z. B. gesund → ungesund).

Menüleiste (SwiftBar)

# If SwiftBar is installed
cp plugins/swiftbar/proxy-doctor.5m.sh ~/Library/Application\ Support/SwiftBar/Plugins/
chmod +x ~/Library/Application\ Support/SwiftBar/Plugins/proxy-doctor.5m.sh

Zeigt einen grünen/roten/orangen Indikator in deiner Menüleiste an, mit einem Klick zur Diagnose.

Beispielausgabe

Ungesund (Fall A: toter Proxy-Port)

{
  "status": "unhealthy",
  "diagnosis": {
    "case": "A",
    "root_cause": "Editor is configured to use proxy at 127.0.0.1:10903, but no process is listening on that port.",
    "confidence": "high",
    "source": "system proxy (Wi-Fi (http))",
    "browser_explanation": "Browser may use a different proxy path (e.g. browser-only mode) or fall back to a direct connection."
  },
  "fixes": [
    {
      "fix_id": "clear-system-http-wi-fi",
      "description": "Disable http proxy on Wi-Fi",
      "command": "networksetup -setwebproxystate \"Wi-Fi\" off",
      "risk": "low"
    }
  ]
}

Gesund

proxy-doctor v0.2.0
Editor: cursor | Platform: Darwin

Status: HEALTHY

No proxy contamination detected.

Unterstützte Editoren

So funktioniert es

proxy-doctor identifiziert drei Fehlermuster:

Fall A – Toter Proxy-Port (hohe Sicherheit): Dein System oder Editor zeigt auf 127.0.0.1:port, aber dort lauscht nichts. Dies passiert, wenn eine VPN-/Proxy-App geschlossen wurde, ihre Einstellungen aber bestehen bleiben.

Fall B – Gestörtes Streaming (mittlere Sicherheit): Ein Proxy läuft, puffert aber SSE/Streaming-Verbindungen, auf die KI-Editoren angewiesen sind. Häufig bei Browser-Proxy-Modi.

Fall C – Pfadkonflikt (mittlere Sicherheit): Browser und Editor verwenden unterschiedliche Proxy-Pfade. Der Browser funktioniert über einen dedizierten Proxy-Route; der Editor erbt eine veraltete oder inkompatible.

Plattformunterstützung

• macOS: Vollständige Unterstützung (System-Proxy, launchctl, networksetup)

• Linux: Teilweise (Editor-Konfiguration + Umgebungsvariablen; kein networksetup)

• Windows: Noch nicht unterstützt

Vertrauen & Berechtigungen

proxy-doctor folgt einem standardmäßig schreibgeschützten Design. Es werden keine Systemänderungen vorgenommen, es sei denn, du stimmst ausdrücklich zu.

Standardverhalten (schreibgeschützt)

Optionale Korrekturübernahme

proxy-doctor fix zeigt die empfohlenen Befehle an, führt sie aber nicht aus.

Um Korrekturen zu übernehmen, verwende proxy-doctor fix --apply:

• Jede Korrektur wird mit ihrem Befehl und Risikostufe angezeigt

• Du wirst für jede Korrektur einzeln aufgefordert ([j/N])

• Standardmäßig ist Nein – nichts läuft, es sei denn, du gibst j ein

• Du kannst jederzeit mit Strg+C abbrechen

Dieses Zweistufenmodell erlaubt KI-Agenten, sicher list_fixes() über MCP aufzurufen, um zu sehen, was behoben werden muss, und dann die Befehle dem Benutzer zur Genehmigung vorzulegen.

Feedback

Einen Fehler gefunden? Hast du einen Vorschlag? Die Diagnose hat nicht geholfen?

• GitHub Issues: https://github.com/Jiansen/proxy-doctor/issues/new

• Für KI-Agenten: Die JSON-Ausgabe enthält eine feedback.report_issue-URL – füge bei der Meldung von Problemen das vollständige JSON bei.

Für KI-Agenten, die programmatisch Feedback geben (keine Abhängigkeiten):

# Create a GitHub issue via CLI (requires gh)
proxy-doctor check | gh issue create --repo Jiansen/proxy-doctor \
  --title "Diagnosis report: [describe issue]" --body-file -

# Or simply: copy the JSON output into a new issue at
# https://github.com/Jiansen/proxy-doctor/issues/new

Entwicklung

git clone https://github.com/Jiansen/proxy-doctor.git
cd proxy-doctor

# Install in development mode
pip install -e ".[dev,mcp]"

# Run tests
make test

# Run linter
make lint

Falls dir proxy-doctor bei der Behebung eines Proxy-Problems geholfen hat, denk bitte daran, ihm einen Stern auf GitHub zu geben – das hilft anderen, das Werkzeug zu entdecken.

Lizenz

MIT