Proxy Doctor

proxy-doctor

AI コーディングツールを動作不能にするプロキシ設定の誤りを診断します。

ブラウザーは正常に動作するのに、Cursor ／ VS Code ／ Windsurf の AI 機能が動作しない場合、proxy-doctor が原因と解決方法を正確に知らせます。

問題

AI コーディングツール（Cursor、Copilot を搭載した VS Code、Windsurf）は、次のような場合に問題が発生する、長時間維持されるストリーミング接続（SSE／HTTP2）に依存しています。

• システムプロキシの接続先が、何も待ち受けていない localhost ポートになっている
• VPN ／プロキシアプリを終了した後も、その設定が macOS のシステム環境設定に残っている
• エディターが launchctl の古いプロキシ環境変数を引き継いでいる
• プロキシは動作しているものの、ストリーミング応答をバッファリングするため、AI による補完が中断される

その結果、**「ブラウザーは動作するのに、AI エディターは動作しない」**という、開発者によくある非常に厄介な状況になります。

チェック項目

proxy-doctor は macOS のプロキシ設定を 5 つのレイヤーで調べます。

レイヤー	内容	方法
1. システムプロキシ	すべてのネットワークサービスの Web ／ HTTPS ／ SOCKS プロキシ	networksetup
2. 残存値	無効化されているが、古い localhost アドレスが残っているプロキシ	無効なのに値が設定されている項目を解析
3. ポートの状態	参照先のプロキシポートが実際に待ち受けているか	socket.connect()
4. エディター設定	settings.json、argv.json、最近のエラーログ	ファイルの読み取り＋パターン照合
5. GUI 環境	GUI アプリのコンテキストにおける http_proxy／https_proxy	launchctl getenv

クイックスタート

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 は、AI エージェントから直接呼び出せる MCP サーバーとして提供されています。

# 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" には、proxy-doctor[mcp] がインストールされている Python のパスを指定する必要があります。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]）し、コマンド python -m proxy_doctor.mcp_server を指定して MCP 設定に追加してください。その後、diagnose_proxy ツールを使ってプロキシの状態を確認してください。

ユーザーのために proxy-doctor を設定する AI エージェントの場合：

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

対応エディター

エディター	設定の検出	ログのスキャン	状態
Cursor	あり	あり	対応済み
VS Code	あり	あり	対応済み
Windsurf	あり	あり	対応済み
Claude Desktop	予定	—	今後対応
Zed	予定	予定	今後対応

仕組み

proxy-doctor は、次の3つの障害パターンを特定します。

ケース A — プロキシポートが応答しない（高い確度）： システムまたはエディターが 127.0.0.1:port を参照していますが、何も待ち受けていません。VPN／プロキシアプリを終了しても、その設定が残っている場合に発生します。

ケース B — ストリーミングが機能しない（中程度の確度）： プロキシは稼働していますが、AI エディターが依存する SSE／ストリーミング接続をバッファリングしています。ブラウザーのみを対象とするプロキシモードでよく見られます。

ケース C — パスの不一致（中程度の確度）： ブラウザーとエディターで異なるプロキシパスが使われています。ブラウザーは専用のプロキシ経路を使って動作していますが、エディターは古い、または互換性のないプロキシ設定を引き継いでいます。

プラットフォームのサポート

• macOS：完全サポート（システムプロキシ、launchctl、networksetup）
• Linux：部分サポート（エディター設定と環境変数。networksetup は非対応）
• Windows：未対応

信頼と権限

proxy-doctor は、デフォルトで読み取り専用の設計を採用しています。明示的に許可しない限り、システムに変更は加えません。

デフォルトの動作（読み取り専用）

アクセス	内容	理由
読み取り	システムプロキシ設定、エディター設定ファイル、launchctl 環境変数、ローカルポートの状態	コアとなる診断機能
書き込み	~/.proxy-doctor/ のみ（キャッシュ、ログ、更新状態）	デーモンの状態を永続化
ネットワーク	pypi.org（バージョン確認のみ）	自動更新機能
実行しないこと	プロキシ設定の変更、エディター設定の変更、テレメトリーの送信、認証情報へのアクセス	設計上の仕様

オプトインによる修正の適用

proxy-doctor fix は推奨コマンドを表示しますが、実行はしません。

修正を適用するには、proxy-doctor fix --apply を使用します。

• 各修正について、コマンドとリスクレベルが表示されます
• 修正ごとに個別に確認を求められます（[y/N]）
• デフォルトはNoです。y と入力しない限り、何も実行されません
• Ctrl+C を押せば、いつでも中止できます

この2段階の仕組みにより、AI エージェントは MCP 経由で list_fixes() を安全に呼び出して必要な修正を確認し、ユーザーの承認を得るためにコマンドを提示できます。

フィードバック

バグを見つけましたか？改善案がありますか？診断が役に立ちませんでしたか？

• GitHub Issues：https://github.com/Jiansen/proxy-doctor/issues/new
• AI エージェント向け：JSON 出力には feedback.report_issue の URL が含まれます。問題を報告する際は、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