proxy-doctor

Диагностика неправильных настроек прокси, которые ломают AI-инструменты для кодинга.

Когда ваш браузер работает нормально, а функции Cursor / VS Code / Windsurf AI — нет, proxy-doctor точно скажет, в чём причина и как это исправить.

Проблема

AI-инструменты для кодинга (Cursor, VS Code с Copilot, Windsurf) полагаются на долгоживущие потоковые соединения (SSE/HTTP2), которые ломаются, если:

• Системный прокси указывает на порт localhost, где никто не слушает

• VPN/прокси-приложение было закрыто, но его настройки остались в системных настройках macOS

• Ваш редактор унаследовал устаревшие переменные окружения прокси от launchctl

• Прокси работает, но буферизирует потоковые ответы, ломая AI-завершения

Результат: «браузер работает, AI-редактор — нет» — самый частый и раздражающий опыт разработчика.

Related MCP server: Inksnow MCP Proxy

Что проверяется

proxy-doctor проверяет 5 уровней конфигурации прокси в macOS:

Быстрый старт

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

Как MCP-инструмент (для AI-агентов)

proxy-doctor поставляется как MCP-сервер, который AI-агенты могут вызывать напрямую:

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

# Run MCP server
python -m proxy_doctor.mcp_server

Добавьте в вашу конфигурацию MCP (например, Cursor ~/.cursor/mcp.json):

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

Примечание: "command" должен указывать на Python, где установлен proxy-doctor[mcp]. Если python3 не работает, используйте полный путь (выполните which python3 или python3 -c "import sys; print(sys.executable)", чтобы его найти).

Ваш AI-агент затем может вызывать:

• diagnose_proxy(editor="cursor") — полная диагностика 5 уровней с доказательствами

• list_fixes(editor="cursor") — рекомендуемые исправления с исполняемыми командами

• supported_editors() — список доступных редакторов

Для AI-агентов: быстрая установка

Однострочник (вставьте это вашему AI-агенту):

Установите proxy-doctor (pip install proxy-doctor[mcp]) и добавьте его в конфигурацию MCP с командой python -m proxy_doctor.mcp_server. Затем используйте инструмент diagnose_proxy для проверки здоровья прокси.

Если вы AI-агент, настраивающий proxy-doctor для вашего пользователя:

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

Режим демона (v0.2+)

Запустите proxy-doctor как фоновый сервис с автоматическим мониторингом здоровья:

# 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

Демон запускается каждые 5 минут, сравнивает результаты с предыдущей проверкой и отправляет уведомление macOS при изменении статуса (например, здоров → нездоров).

Строка меню (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

Показывает зелёный/красный/оранжевый индикатор в строке меню с диагностикой в один клик.

Пример вывода

Нездоров (Случай A: мёртвый порт прокси)

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

Здоров

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

Status: HEALTHY

No proxy contamination detected.

Поддерживаемые редакторы

Как это работает

proxy-doctor определяет три шаблона сбоев:

Случай A — Мёртвый порт прокси (высокая уверенность): Ваша система или редактор указывают на 127.0.0.1:port, но никто не слушает. Это происходит, когда VPN/прокси-приложение закрыто, но его настройки остались.

Случай B — Нарушение потоковой передачи (средняя уверенность): Прокси работает, но буферизирует SSE/потоковые соединения, от которых зависят AI-редакторы. Часто встречается в режимах прокси только для браузера.

Случай C — Несоответствие пути (средняя уверенность): Браузер и редактор используют разные пути прокси. Браузер работает через выделенный маршрут прокси; редактор наследует устаревший или несовместимый.

Поддержка платформ

• macOS: Полная поддержка (системный прокси, launchctl, networksetup)

• Linux: Частичная (конфиг редактора + переменные окружения; без networksetup)

• Windows: Пока не поддерживается

Доверие и разрешения

proxy-doctor следует принципу только чтение по умолчанию. Никаких изменений в системе не производится, если вы явно не согласитесь.

Поведение по умолчанию (только чтение)

Применение исправлений с согласия

proxy-doctor fix показывает рекомендуемые команды, но не выполняет их.

Чтобы применить исправления, используйте proxy-doctor fix --apply:

• Каждое исправление показывается с командой и уровнем риска

• Для каждого исправления запрашивается индивидуальное подтверждение ([y/N])

• По умолчанию — Нет — ничего не запускается, пока вы не введёте y

• Вы можете прервать процесс в любой момент с помощью Ctrl+C

Эта двухэтапная модель позволяет AI-агентам безопасно вызывать list_fixes() через MCP, чтобы увидеть, что нужно исправить, а затем представить команды пользователям для утверждения.

Обратная связь

Нашли ошибку? Есть предложение? Диагностика не помогла?

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

• Для AI-агентов: Вывод JSON содержит URL feedback.report_issue — при создании обращений прикладывайте полный JSON.

Для программной обратной связи от AI-агентов (без зависимостей):

# 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

Разработка

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

Если proxy-doctor помог вам исправить проблему с прокси, поставьте ему звезду на GitHub — это поможет другим пользователям найти инструмент.

Лицензия

MIT