{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.svg\" width=\"120\" alt=\"proxy-doctor logo\">\n</p>\n\n<h1 align=\"center\">proxy-doctor</h1>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/proxy-doctor/\"><img src=\"https://img.shields.io/pypi/v/proxy-doctor\" alt=\"PyPI\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/github/license/Jiansen/proxy-doctor\" alt=\"License\"></a>\n  <img src=\"https://img.shields.io/badge/platform-macOS-blue\" alt=\"Platform\">\n  <img src=\"https://img.shields.io/badge/python-%3E%3D3.9-blue\" alt=\"Python\">\n  <a href=\"https://github.com/Jiansen/proxy-doctor/stargazers\"><img src=\"https://img.shields.io/github/stars/Jiansen/proxy-doctor?style=social\" alt=\"GitHub Stars\"></a>\n</p>\n\n**Diagnose proxy misconfigurations that break AI coding tools.**\n\nWhen your browser works fine but Cursor / VS Code / Windsurf AI features don't — proxy-doctor tells you exactly why and how to fix it.\n\n## The Problem\n\nAI coding tools (Cursor, VS Code with Copilot, Windsurf) rely on long-lived streaming connections (SSE/HTTP2) that break when:\n\n- Your system proxy points to a localhost port where nothing is listening\n- A VPN/proxy app was closed but its settings linger in macOS system preferences\n- Your editor inherited stale proxy environment variables from `launchctl`\n- The proxy is running but buffers streaming responses, breaking AI completions\n\nThe result: **\"browser works, AI editor doesn't\"** — the most common and frustrating developer experience.\n\n## What It Checks\n\nproxy-doctor inspects 5 layers of your macOS proxy configuration:\n\n| Layer | What | How |\n|-------|------|-----|\n| 1. System Proxy | Web/HTTPS/SOCKS proxy across all network services | `networksetup` |\n| 2. Residual Values | Disabled proxies with stale localhost addresses | Parse disabled-but-set entries |\n| 3. Port Health | Whether referenced proxy ports are actually listening | `socket.connect()` |\n| 4. Editor Config | `settings.json`, `argv.json`, recent error logs | File read + pattern match |\n| 5. GUI Environment | `http_proxy`/`https_proxy` in GUI app context | `launchctl getenv` |\n\n## Quick Start\n\n### CLI\n\n```bash\n# Install\npip install proxy-doctor\n\n# Run diagnosis (JSON output — default, optimized for AI agents)\nproxy-doctor check\n\n# Run diagnosis (human-readable output)\nproxy-doctor check --human\n\n# Show recommended fixes\nproxy-doctor fix\n\n# Check a different editor\nproxy-doctor check --editor vscode\n```\n\n### As an MCP Tool (for AI agents)\n\nproxy-doctor ships as an MCP server that AI agents can call directly:\n\n```bash\n# Install with MCP support\npip install proxy-doctor[mcp]\n\n# Run MCP server\npython -m proxy_doctor.mcp_server\n```\n\nAdd to your MCP configuration (e.g., Cursor `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"proxy-doctor\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"proxy_doctor.mcp_server\"]\n    }\n  }\n}\n```\n\n> **Note:** `\"command\"` must point to the Python where `proxy-doctor[mcp]` is installed. If `python3` doesn't work, use the full path (run `which python3` or `python3 -c \"import sys; print(sys.executable)\"` to find it).\n\nYour AI agent can then call:\n- `diagnose_proxy(editor=\"cursor\")` — full 5-layer diagnosis with evidence\n- `list_fixes(editor=\"cursor\")` — recommended fixes with executable commands\n- `supported_editors()` — list available editors\n\n### For AI Agents: Quick Install\n\n**One-liner** (paste this to your AI agent):\n\n> Install proxy-doctor (`pip install proxy-doctor[mcp]`) and add it to your MCP config with command `python -m proxy_doctor.mcp_server`. Then use the `diagnose_proxy` tool to check proxy health.\n\nIf you are an AI agent setting up proxy-doctor for your user:\n\n```bash\n# 1. Install\npip install proxy-doctor[mcp]\n\n# 2. Find the Python path\npython3 -c \"import sys; print(sys.executable)\"\n\n# 3. Add to ~/.cursor/mcp.json (use the path from step 2)\n# {\n#   \"mcpServers\": {\n#     \"proxy-doctor\": {\n#       \"command\": \"<python-path-from-step-2>\",\n#       \"args\": [\"-m\", \"proxy_doctor.mcp_server\"]\n#     }\n#   }\n# }\n\n# 4. If MCP is not available, use CLI directly (zero dependencies):\nproxy-doctor check          # JSON output\nproxy-doctor check --human  # human-readable\nproxy-doctor fix            # show fixes (read-only)\nproxy-doctor fix --apply    # apply fixes (asks for confirmation)\n```\n\n### Daemon Mode (v0.2+)\n\nRun proxy-doctor as a persistent background service with automatic health monitoring:\n\n```bash\n# Start daemon (installs as macOS launchd service)\nproxy-doctor daemon start\n\n# Check daemon status\nproxy-doctor daemon status\n\n# Stop daemon\nproxy-doctor daemon stop\n\n# Check for updates\nproxy-doctor update\n```\n\nThe daemon runs every 5 minutes, compares results with the previous check, and sends a macOS notification when status changes (e.g. healthy → unhealthy).\n\n### Menu Bar (SwiftBar)\n\n```bash\n# If SwiftBar is installed\ncp plugins/swiftbar/proxy-doctor.5m.sh ~/Library/Application\\ Support/SwiftBar/Plugins/\nchmod +x ~/Library/Application\\ Support/SwiftBar/Plugins/proxy-doctor.5m.sh\n```\n\nShows a green/red/orange indicator in your menu bar with one-click diagnosis.\n\n## Example Output\n\n### Unhealthy (Case A: dead proxy port)\n\n```json\n{\n  \"status\": \"unhealthy\",\n  \"diagnosis\": {\n    \"case\": \"A\",\n    \"root_cause\": \"Editor is configured to use proxy at 127.0.0.1:10903, but no process is listening on that port.\",\n    \"confidence\": \"high\",\n    \"source\": \"system proxy (Wi-Fi (http))\",\n    \"browser_explanation\": \"Browser may use a different proxy path (e.g. browser-only mode) or fall back to a direct connection.\"\n  },\n  \"fixes\": [\n    {\n      \"fix_id\": \"clear-system-http-wi-fi\",\n      \"description\": \"Disable http proxy on Wi-Fi\",\n      \"command\": \"networksetup -setwebproxystate \\\"Wi-Fi\\\" off\",\n      \"risk\": \"low\"\n    }\n  ]\n}\n```\n\n### Healthy\n\n```\nproxy-doctor v0.2.0\nEditor: cursor | Platform: Darwin\n\nStatus: HEALTHY\n\nNo proxy contamination detected.\n```\n\n## Supported Editors\n\n| Editor | Config Detection | Log Scanning | Status |\n|--------|-----------------|-------------|--------|\n| Cursor | yes | yes | **supported** |\n| VS Code | yes | yes | supported |\n| Windsurf | yes | yes | supported |\n| Claude Desktop | planned | — | future |\n| Zed | planned | planned | future |\n\n## How It Works\n\nproxy-doctor identifies three failure patterns:\n\n**Case A — Dead proxy port (high confidence):** Your system or editor points to `127.0.0.1:port` but nothing is listening. This happens when a VPN/proxy app is closed but its settings remain.\n\n**Case B — Streaming broken (medium confidence):** A proxy is running, but it buffers SSE/streaming connections that AI editors depend on. Common with browser-only proxy modes.\n\n**Case C — Path mismatch (medium confidence):** Browser and editor use different proxy paths. Browser works via a dedicated proxy route; editor inherits a stale or incompatible one.\n\n## Platform Support\n\n- **macOS**: Full support (system proxy, launchctl, networksetup)\n- **Linux**: Partial (editor config + environment variables; no networksetup)\n- **Windows**: Not yet supported\n\n## Trust & Permissions\n\nproxy-doctor follows a **read-only by default** design. No system changes are made unless you explicitly opt in.\n\n### Default Behavior (read-only)\n\n| Access | What | Why |\n|--------|------|-----|\n| **Reads** | System proxy settings, editor config files, launchctl env vars, local port status | Core diagnostic functionality |\n| **Writes** | `~/.proxy-doctor/` only (cache, logs, update state) | Daemon state persistence |\n| **Network** | `pypi.org` (version check only) | Auto-update feature |\n| **Does NOT** | Modify proxy settings, change editor config, send telemetry, access credentials | By design |\n\n### Opt-in Fix Application\n\n`proxy-doctor fix` shows the recommended commands but **does not execute them**.\n\nTo apply fixes, use `proxy-doctor fix --apply`:\n- Each fix is shown with its command and risk level\n- You are prompted **individually** for each fix (`[y/N]`)\n- Default is **No** — nothing runs unless you type `y`\n- You can abort at any time with Ctrl+C\n\nThis two-step model lets AI agents safely call `list_fixes()` via MCP to see what needs fixing, then present the commands to users for approval.\n\n## Feedback\n\nFound a bug? Have a suggestion? Diagnosis didn't help?\n\n- **GitHub Issues**: https://github.com/Jiansen/proxy-doctor/issues/new\n- **For AI agents**: The JSON output includes a `feedback.report_issue` URL — include the full JSON when filing issues.\n\nFor AI agents providing feedback programmatically (zero dependencies):\n\n```bash\n# Create a GitHub issue via CLI (requires gh)\nproxy-doctor check | gh issue create --repo Jiansen/proxy-doctor \\\n  --title \"Diagnosis report: [describe issue]\" --body-file -\n\n# Or simply: copy the JSON output into a new issue at\n# https://github.com/Jiansen/proxy-doctor/issues/new\n```\n\n## Development\n\n```bash\ngit clone https://github.com/Jiansen/proxy-doctor.git\ncd proxy-doctor\n\n# Install in development mode\npip install -e \".[dev,mcp]\"\n\n# Run tests\nmake test\n\n# Run linter\nmake lint\n```\n\n---\n\nIf proxy-doctor helped you fix a proxy issue, consider giving it a star on GitHub — it helps others discover the tool.\n\n[![Star on GitHub](https://img.shields.io/github/stars/Jiansen/proxy-doctor?style=social)](https://github.com/Jiansen/proxy-doctor)\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.Jiansen/proxy-doctor -->\n",
  "bytes": 9309,
  "sha": "33ce04991d380dad3b00495bca3c70fa3fece4294a1f8be0de0fe862104f2474",
  "repo_slug": "jiansen/proxy-doctor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jiansen_proxy_doctor_43b6fa3f/readme"
}