proxy-doctor

Diagnostica configuraciones incorrectas de proxy que rompen herramientas de IA de codificación.

Cuando tu navegador funciona bien pero las funciones de IA de Cursor / VS Code / Windsurf no — proxy-doctor te dice exactamente por qué y cómo solucionarlo.

El problema

Las herramientas de IA de codificación (Cursor, VS Code con Copilot, Windsurf) dependen de conexiones de streaming de larga duración (SSE/HTTP2) que se rompen cuando:

• Tu proxy del sistema apunta a un puerto localhost donde no hay nada escuchando

• Una aplicación VPN/proxy fue cerrada pero su configuración persiste en las preferencias del sistema macOS

• Tu editor heredó variables de entorno de proxy obsoletas de launchctl

• El proxy está funcionando pero almacena en búfer las respuestas de streaming, rompiendo las completaciones de IA

El resultado: "el navegador funciona, el editor de IA no" — la experiencia de desarrollador más común y frustrante.

Related MCP server: Inksnow MCP Proxy

Qué comprueba

proxy-doctor inspecciona 5 capas de tu configuración de proxy en macOS:

Inicio rápido

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

Como herramienta MCP (para agentes de IA)

proxy-doctor incluye un servidor MCP que los agentes de IA pueden llamar directamente:

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

# Run MCP server
python -m proxy_doctor.mcp_server

Añádelo a tu configuración MCP (por ejemplo, Cursor ~/.cursor/mcp.json):

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

Nota: "command" debe apuntar al Python donde esté instalado proxy-doctor[mcp]. Si python3 no funciona, usa la ruta completa (ejecuta which python3 o python3 -c "import sys; print(sys.executable)" para encontrarlo).

Tu agente de IA puede entonces llamar:

• diagnose_proxy(editor="cursor") — diagnóstico completo de 5 capas con evidencia

• list_fixes(editor="cursor") — correcciones recomendadas con comandos ejecutables

• supported_editors() — listar editores disponibles

Para agentes de IA: Instalación rápida

En una línea (pégalo en tu agente de IA):

Instala proxy-doctor (pip install proxy-doctor[mcp]) y agrégalo a tu configuración MCP con el comando python -m proxy_doctor.mcp_server. Luego usa la herramienta diagnose_proxy para comprobar el estado del proxy.

Si eres un agente de IA configurando proxy-doctor para tu usuario:

# 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)

Modo demonio (v0.2+)

Ejecuta proxy-doctor como un servicio de fondo persistente con monitoreo automático de salud:

# 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

El demonio se ejecuta cada 5 minutos, compara los resultados con la comprobación anterior y envía una notificación de macOS cuando el estado cambia (p. ej., saludable → no saludable).

Barra de menú (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

Muestra un indicador verde/rojo/naranja en tu barra de menú con diagnóstico con un solo clic.

Ejemplo de salida

No saludable (Caso A: puerto proxy muerto)

{
  "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"
    }
  ]
}

Saludable

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

Status: HEALTHY

No proxy contamination detected.

Editores compatibles

Cómo funciona

proxy-doctor identifica tres patrones de fallo:

Caso A — Puerto proxy muerto (alta confianza): Tu sistema o editor apunta a 127.0.0.1:puerto pero no hay nada escuchando. Esto ocurre cuando una aplicación VPN/proxy se cierra pero su configuración permanece.

Caso B — Streaming roto (confianza media): Un proxy está funcionando, pero almacena en búfer las conexiones SSE/streaming de las que dependen los editores de IA. Común con modos de proxy solo para navegador.

Caso C — Ruta no coincide (confianza media): El navegador y el editor usan diferentes rutas de proxy. El navegador funciona a través de una ruta proxy dedicada; el editor hereda una obsoleta o incompatible.

Soporte de plataformas

• macOS: Soporte completo (proxy del sistema, launchctl, networksetup)

• Linux: Parcial (configuración del editor + variables de entorno; sin networksetup)

• Windows: Aún no compatible

Confianza y permisos

proxy-doctor sigue un diseño de solo lectura por defecto. No se realizan cambios en el sistema a menos que optes explícitamente.

Comportamiento por defecto (solo lectura)

Aplicación de correcciones con consentimiento

proxy-doctor fix muestra los comandos recomendados pero no los ejecuta.

Para aplicar correcciones, usa proxy-doctor fix --apply:

• Cada corrección se muestra con su comando y nivel de riesgo

• Se te solicita individualmente para cada corrección ([y/N])

• El valor por defecto es No — nada se ejecuta a menos que escribas y

• Puedes abortar en cualquier momento con Ctrl+C

Este modelo de dos pasos permite que los agentes de IA llamen de forma segura a list_fixes() a través de MCP para ver qué necesita corrección, y luego presenten los comandos a los usuarios para su aprobación.

Comentarios

¿Encontraste un error? ¿Tienes una sugerencia? ¿El diagnóstico no ayudó?

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

• Para agentes de IA: La salida JSON incluye una URL feedback.report_issue — incluye el JSON completo al informar problemas.

Para agentes de IA que proporcionan comentarios programáticamente (sin dependencias):

# 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

Desarrollo

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

Si proxy-doctor te ayudó a solucionar un problema de proxy, considera darle una estrella en GitHub — ayuda a que otros descubran la herramienta.

Licencia

MIT