proxy-doctor 0.1.0__tar.gz

proxy_doctor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiansen He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proxy_doctor-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.2
+Name: proxy-doctor
+Version: 0.1.0
+Summary: Diagnose proxy misconfigurations that break AI coding tools (Cursor, VS Code, Windsurf)
+Author: Jiansen He
+License: MIT
+Keywords: proxy,cursor,vscode,windsurf,network,diagnostic,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# proxy-doctor
+
+**Diagnose proxy misconfigurations that break AI coding tools.**
+
+When your browser works fine but Cursor / VS Code / Windsurf AI features don't — proxy-doctor tells you exactly why and how to fix it.
+
+## The Problem
+
+AI coding tools (Cursor, VS Code with Copilot, Windsurf) rely on long-lived streaming connections (SSE/HTTP2) that break when:
+
+- Your system proxy points to a localhost port where nothing is listening
+- A VPN/proxy app was closed but its settings linger in macOS system preferences
+- Your editor inherited stale proxy environment variables from `launchctl`
+- The proxy is running but buffers streaming responses, breaking AI completions
+
+The result: **"browser works, AI editor doesn't"** — the most common and frustrating developer experience.
+
+## What It Checks
+
+proxy-doctor inspects 5 layers of your macOS proxy configuration:
+
+| Layer | What | How |
+|-------|------|-----|
+| 1. System Proxy | Web/HTTPS/SOCKS proxy across all network services | `networksetup` |
+| 2. Residual Values | Disabled proxies with stale localhost addresses | Parse disabled-but-set entries |
+| 3. Port Health | Whether referenced proxy ports are actually listening | `socket.connect()` |
+| 4. Editor Config | `settings.json`, `argv.json`, recent error logs | File read + pattern match |
+| 5. GUI Environment | `http_proxy`/`https_proxy` in GUI app context | `launchctl getenv` |
+
+## Quick Start
+
+### CLI
+
+```bash
+# 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
+```
+
+### As an MCP Tool (for AI agents)
+
+proxy-doctor ships as an MCP server that AI agents can call directly:
+
+```bash
+# Install with MCP support
+pip install proxy-doctor[mcp]
+
+# Run MCP server
+python -m proxy_doctor.mcp_server
+```
+
+Add to your MCP configuration (e.g., Cursor `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "proxy-doctor": {
+      "command": "python",
+      "args": ["-m", "proxy_doctor.mcp_server"]
+    }
+  }
+}
+```
+
+Your AI agent can then call:
+- `diagnose_proxy(editor="cursor")` — full 5-layer diagnosis
+- `list_fixes(editor="cursor")` — just the recommended fixes
+- `supported_editors()` — list available editors
+
+### Menu Bar (SwiftBar)
+
+```bash
+# 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
+```
+
+Shows a green/red/orange indicator in your menu bar with one-click diagnosis.
+
+## Example Output
+
+### Unhealthy (Case A: dead proxy port)
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+### Healthy
+
+```
+proxy-doctor v0.1.0
+Editor: cursor | Platform: Darwin
+
+Status: HEALTHY
+
+No proxy contamination detected.
+```
+
+## Supported Editors
+
+| Editor | Config Detection | Log Scanning | Status |
+|--------|-----------------|-------------|--------|
+| Cursor | yes | yes | **supported** |
+| VS Code | yes | yes | supported |
+| Windsurf | yes | yes | supported |
+| Claude Desktop | planned | — | future |
+| Zed | planned | planned | future |
+
+## How It Works
+
+proxy-doctor identifies three failure patterns:
+
+**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.
+
+**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.
+
+**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.
+
+## Platform Support
+
+- **macOS**: Full support (system proxy, launchctl, networksetup)
+- **Linux**: Partial (editor config + environment variables; no networksetup)
+- **Windows**: Not yet supported
+
+## Development
+
+```bash
+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
+```
+
+## License
+
+MIT

proxy_doctor-0.1.0/README.md

@@ -0,0 +1,171 @@
+# proxy-doctor
+
+**Diagnose proxy misconfigurations that break AI coding tools.**
+
+When your browser works fine but Cursor / VS Code / Windsurf AI features don't — proxy-doctor tells you exactly why and how to fix it.
+
+## The Problem
+
+AI coding tools (Cursor, VS Code with Copilot, Windsurf) rely on long-lived streaming connections (SSE/HTTP2) that break when:
+
+- Your system proxy points to a localhost port where nothing is listening
+- A VPN/proxy app was closed but its settings linger in macOS system preferences
+- Your editor inherited stale proxy environment variables from `launchctl`
+- The proxy is running but buffers streaming responses, breaking AI completions
+
+The result: **"browser works, AI editor doesn't"** — the most common and frustrating developer experience.
+
+## What It Checks
+
+proxy-doctor inspects 5 layers of your macOS proxy configuration:
+
+| Layer | What | How |
+|-------|------|-----|
+| 1. System Proxy | Web/HTTPS/SOCKS proxy across all network services | `networksetup` |
+| 2. Residual Values | Disabled proxies with stale localhost addresses | Parse disabled-but-set entries |
+| 3. Port Health | Whether referenced proxy ports are actually listening | `socket.connect()` |
+| 4. Editor Config | `settings.json`, `argv.json`, recent error logs | File read + pattern match |
+| 5. GUI Environment | `http_proxy`/`https_proxy` in GUI app context | `launchctl getenv` |
+
+## Quick Start
+
+### CLI
+
+```bash
+# 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
+```
+
+### As an MCP Tool (for AI agents)
+
+proxy-doctor ships as an MCP server that AI agents can call directly:
+
+```bash
+# Install with MCP support
+pip install proxy-doctor[mcp]
+
+# Run MCP server
+python -m proxy_doctor.mcp_server
+```
+
+Add to your MCP configuration (e.g., Cursor `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "proxy-doctor": {
+      "command": "python",
+      "args": ["-m", "proxy_doctor.mcp_server"]
+    }
+  }
+}
+```
+
+Your AI agent can then call:
+- `diagnose_proxy(editor="cursor")` — full 5-layer diagnosis
+- `list_fixes(editor="cursor")` — just the recommended fixes
+- `supported_editors()` — list available editors
+
+### Menu Bar (SwiftBar)
+
+```bash
+# 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
+```
+
+Shows a green/red/orange indicator in your menu bar with one-click diagnosis.
+
+## Example Output
+
+### Unhealthy (Case A: dead proxy port)
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+### Healthy
+
+```
+proxy-doctor v0.1.0
+Editor: cursor | Platform: Darwin
+
+Status: HEALTHY
+
+No proxy contamination detected.
+```
+
+## Supported Editors
+
+| Editor | Config Detection | Log Scanning | Status |
+|--------|-----------------|-------------|--------|
+| Cursor | yes | yes | **supported** |
+| VS Code | yes | yes | supported |
+| Windsurf | yes | yes | supported |
+| Claude Desktop | planned | — | future |
+| Zed | planned | planned | future |
+
+## How It Works
+
+proxy-doctor identifies three failure patterns:
+
+**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.
+
+**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.
+
+**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.
+
+## Platform Support
+
+- **macOS**: Full support (system proxy, launchctl, networksetup)
+- **Linux**: Partial (editor config + environment variables; no networksetup)
+- **Windows**: Not yet supported
+
+## Development
+
+```bash
+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
+```
+
+## License
+
+MIT

proxy_doctor-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0,<77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "proxy-doctor"
+version = "0.1.0"
+description = "Diagnose proxy misconfigurations that break AI coding tools (Cursor, VS Code, Windsurf)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "Jiansen He"}]
+keywords = ["proxy", "cursor", "vscode", "windsurf", "network", "diagnostic", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Networking",
+]
+
+[project.optional-dependencies]
+mcp = ["fastmcp>=2.0.0"]
+dev = ["ruff", "pytest"]
+
+[project.scripts]
+proxy-doctor = "proxy_doctor.cli:main"
+
+[project.entry-points."mcp.servers"]
+proxy-doctor = "proxy_doctor.mcp_server:mcp"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

proxy_doctor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

proxy_doctor-0.1.0/src/proxy_doctor/__init__.py

@@ -0,0 +1,3 @@
+"""proxy-doctor: Diagnose proxy misconfigurations that break AI coding tools."""
+
+__version__ = "0.1.0"

proxy_doctor-0.1.0/src/proxy_doctor/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running as: python3 -m proxy_doctor"""
+
+import sys
+
+from proxy_doctor.cli import main
+
+sys.exit(main())

proxy_doctor-0.1.0/src/proxy_doctor/cli.py

@@ -0,0 +1,126 @@
+"""CLI entry point for proxy-doctor.
+
+Usage:
+    proxy-doctor check [--json | --human] [--editor NAME]
+    proxy-doctor fix [--editor NAME]
+    proxy-doctor editors
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from proxy_doctor import __version__
+from proxy_doctor.core import run_diagnosis
+from proxy_doctor.editors import list_editors
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="proxy-doctor",
+        description="Diagnose proxy misconfigurations that break AI coding tools.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"proxy-doctor {__version__}",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # check
+    p_check = sub.add_parser("check", help="Run proxy diagnosis")
+    fmt = p_check.add_mutually_exclusive_group()
+    fmt.add_argument("--json", dest="output_json", action="store_true", default=True,
+                     help="Output JSON (default)")
+    fmt.add_argument("--human", dest="output_json", action="store_false",
+                     help="Output human-readable text")
+    p_check.add_argument("--editor", default="cursor",
+                         help="Editor to check (default: cursor)")
+    p_check.add_argument("--markdown", metavar="FILE",
+                         help="Also write markdown report to FILE")
+
+    # fix
+    p_fix = sub.add_parser("fix", help="Show recommended fixes")
+    p_fix.add_argument("--editor", default="cursor",
+                       help="Editor to check (default: cursor)")
+
+    # editors
+    sub.add_parser("editors", help="List supported editors")
+
+    return parser
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    report = run_diagnosis(args.editor)
+
+    if args.output_json:
+        print(report.to_json())
+    else:
+        print(report.to_human())
+
+    if args.markdown:
+        try:
+            with open(args.markdown, "w", encoding="utf-8") as f:
+                f.write(f"# proxy-doctor report\n\n```\n{report.to_human()}\n```\n\n")
+                f.write(f"## Evidence (JSON)\n\n```json\n{report.to_json()}\n```\n")
+            print(f"\nReport written to {args.markdown}", file=sys.stderr)
+        except OSError as e:
+            print(f"Failed to write report: {e}", file=sys.stderr)
+
+    return 0 if report.diagnosis.status == "healthy" else 1
+
+
+def cmd_fix(args: argparse.Namespace) -> int:
+    report = run_diagnosis(args.editor)
+
+    if not report.diagnosis.fixes:
+        print(json.dumps({"status": "healthy", "fixes": []}, indent=2))
+        return 0
+
+    fixes_out = {
+        "status": report.diagnosis.status,
+        "case": report.diagnosis.case,
+        "fixes": [
+            {
+                "fix_id": f.fix_id,
+                "description": f.description,
+                "command": f.command,
+                "risk": f.risk,
+                "layer": f.layer,
+            }
+            for f in report.diagnosis.fixes
+        ],
+    }
+    print(json.dumps(fixes_out, indent=2))
+    return 0 if report.diagnosis.status == "healthy" else 1
+
+
+def cmd_editors(_args: argparse.Namespace) -> int:
+    editors = list_editors()
+    print(json.dumps({"supported_editors": editors}, indent=2))
+    return 0
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    dispatch = {
+        "check": cmd_check,
+        "fix": cmd_fix,
+        "editors": cmd_editors,
+    }
+    handler = dispatch.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return 2
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())