proxyman-traffic-debugging

Proxyman のトラフィックデバッグと MCP 操作

Proxyman MCP を、実行中の Proxyman アプリのローカルコントロールプレーンとして使用します。まず読み取り専用で操作し、関連するキャプチャ済みフローまたは現在の状態を特定してから、ユーザーが依頼した変更だけを行います。

Proxyman のツールが利用できない場合は、proxyman-mcp-setup を使用します。Proxyman が存在しない場合は、proxyman-download-setup を使用します。対象固有の HTTPS 設定には、proxyman-https-capture を使用します。製品の最新ドキュメントには、proxyman-debugging-tools を使用します。シェルの自動化には、proxyman-cli を使用します。

信頼できる情報源

情報源の内容が食い違う場合は、次の順序で使用します。

1. 接続されたサーバーの tools/list、resources/list、prompts/list で、利用可能な MCP 機能と正確なスキーマを確認します。
2. Proxyman のステータス／リストツールが返す現在の状態。
3. バージョンに合ったセットアップ、CLI、スクリプト作成のガイダンスを記載した組み込み MCP リソース。
4. 組み込みセットアップインデックスに記載されていない GUI の動作や機能については、proxyman-debugging-tools を通じて参照する公式の最新ドキュメント。
5. このスキルに含まれるリファレンスを、概要を把握するための案内図として使用します。

ツール、列挙値、パラメーター、ルール ID、フロー ID、ファイルパス、コマンドフラグを決して推測しないでください。stdio ブリッジでは厳密なスキーマが使用されます。

基本的な考え方

• MCP クライアントは、Proxyman にバンドルされた mcp-server を stdio 経由で起動します。ブリッジはローカルハンドシェイクを読み取り、実行中のアプリ内にある認証済みの localhost サーバーに呼び出しを転送します。
• HTTP ポートやトークンをハードコードしないでください。各クライアントブリッジは、stdin が開いている間だけ有効です。
• フローツールは、アクティブなワークスペースのサイドバーに紐づくトラフィック全体を対象にします。通常のフォルダーのフローに加え、保存済み、ピン留め済み、インポート済み、Atlantis、リモートデバイスのソースが存在する場合はそれらのフローも含まれます。結果は選択中のフォルダーに限定されず、フォルダー間で重複が排除されます。
• リスト／フィルターの結果はスナップショットです。クリア、インポート、ソースの変更、再起動後には、フロー ID が存在しなくなる場合があります。
• 一部の操作はプラットフォーム固有です。システムプロキシ、Terminal インジェクション、Electron .app インジェクション、アプリの制御は、主に macOS での操作です。Windows と Linux では、実際に検出された情報を優先してください。

すべての MCP セッションで最初に行うこと

1. クライアントで検出機能が公開されている場合は、ツール、リソース、プロンプトを検出します。
2. get_version を呼び出し、ブリッジが Proxyman に接続されていることを確認します。
3. get_proxy_status を呼び出し、記録状態、プロキシポート、SSL Proxying の状態を確認します。
4. 対象を特定できる最小限の読み取り操作（get_flows、filter_flows、ステータス呼び出し、関連するリスト呼び出し）を使用します。
5. 返された識別子を使って詳細を読み取ります。名前や画面上の表示順から ID を推測しないでください。
6. 変更の内容と影響を説明し、必要な場合は同意を得てから実行し、読み取り操作で結果を確認します。

ツールを選ぶ際は、MCP ツールカタログをお読みください。複数の手順を伴うタスクには、MCP ワークフローをお読みください。Breakpoint、Map Local、Map Remote、Scripting、または重複する変更ルールについては、リクエストとレスポンスのルールをお読みください。組み込みのナレッジについては、MCP リソースとプロンプトをお読みください。

プライバシーと同意

Settings > MCP > Redact Sensitive Data Before Sending to AI は、デフォルトで有効にしておいてください。この設定は、MCP の出力に含まれる一般的なシークレットヘッダー、Cookie、クエリ値、JWT、認証情報、シークレットと思われる本文フィールドを対象とします。

マスキングは、export_flows が書き出す元の HAR や Proxyman ログをサニタイズしません。エクスポートしたファイルは機密情報として扱ってください。

次の操作を行う直前には、必ずユーザーの明示的な承認を得てください。

• セッションのクリア、ルールまたは Compose の下書きの削除、WebSocket の切断、Proxyman の終了、証明書のアンインストール。
• ユーザーがその変更を明示的に依頼していない場合の、システムプロキシ、証明書の信頼、記録、SSL Proxying、外部プロキシ、またはグローバルなデバッグツールの状態の変更。
• ガイド付き自動化、Terminal インジェクション、Electron インジェクション、または別のアプリを起動・変更する操作の実行。
• 元の通信データのエクスポート、またはプロキシ認証情報の送信。
• MCP のマスキングの無効化、または未加工のシークレットの開示。

エクスポートには、明示的に承認された保存先を指定してください。MCP のプレビューがマスキングされているという理由だけで、エクスポートもマスキングされていると主張してはいけません。

操作の進め方

通信を調査して診断する

1. get_proxy_status でキャプチャの状態を確認します。
2. get_flows または filter_flows で候補を絞り込みます。ユーザーが送信元を指定した場合は、クライアント／デバイスの識別情報を使用します。
3. 代表的な ID を get_flow_detail で調査します。Summary メタデータ、タイミング、サイズ、接続／TLS の詳細、ヘッダー、クエリ、Cookie、本文のプレビューを確認します。
4. メソッド、URL、ステータス、タイミング、リクエストの順序、クライアント、一致したデバッグツールを関連付けます。
5. 裏付けとなるフロー ID と観察結果を示し、判定を「合格」「疑わしい」「失敗」「判断不能」のいずれかで返します。
6. ユーザーが再現可能な成果物を必要とする場合に限り、エクスポートまたはコード生成を行います。

Proxyman を安全に変更する

1. 現在の状態を読み取り、関連する ID を記録します。
2. 提案する最小限の変更を示し、それがキャプチャ、信頼、通信データ、ディスク、または別のアプリに影響するかを伝えます。
3. 現在の正確なスキーマを使用します。ツールのドキュメントにパッチのセマンティクスが記載されている場合に限り、省略可能なフィールドを省略します。
4. 返されたオブジェクトを確認し、対応する一覧／状態／詳細ツールを呼び出します。
5. 変更された ID と、存在する場合は正確なロールバック操作を報告します。

ツールエラーに対処する

1. MCP エラー全文を確認します。スキーマエラーと検証エラーは、対処方法が分かるように設計されています。
2. アプリの更新後、または tool not found の結果が返された場合は、最新の情報を再取得します。
3. ID が古い場合は、フローまたはルールを再一覧表示します。
4. 無効なフィールドだけを修正し、ユーザーが指定した範囲を狭めないでください。
5. その機能が公開されていない場合は、GUI または proxyman-cli を案内し、このビルドでは MCP で実行できないことを伝えます。

重要なセマンティクス

• get_flows／filter_flows が返す結果は最大 500 件で、本文のプレビューは途中で切り詰められる場合があります。完全なアーカイブデータが必要な場合は、ユーザーの承認を得てエクスポートしてください。
• filter_flows では client で絞り込めます。デバイス、シミュレーター、Atlantis、アプリの各ソースを区別する場合は、こちらを優先してください。
• Breakpoint、Map Local、Map Remote、Block List、Scripting、Allow List、Network Condition、DNS Spoofing には list_rules を使用してください。Reverse Proxy には専用の一覧取得ツールがあります。
• 作成／更新操作には、返された ID を使用してください。更新しても ID は保持されます。
• ルールの CRUD、ルールの切り替え、グローバル機能の切り替えが成功すると、対応する Proxyman の開いているリスト／エディターが更新されます。編集中のルールを削除すると、そのエディターは閉じます。
• ルールのメソッドでは大文字の QUERY がサポートされています。すべてのメソッドを対象にする場合に限り ANY を使用してください。デフォルト値はルールの種類によって異なるため、include_paths は意図を明確にして設定してください。
• Scripting、Allow List、Network Condition、DNS Spoofing、Reverse Proxy を作成すると、対応する機能が有効になります。その他の機能の状態は list_tool_status で確認してください。
• 同時に有効にできる Network Condition は 1 つだけです。
• Network Condition のプロファイル名とサポートされる適用範囲は、実際のスキーマに従ってください。プリセットのみが公開されている場合、独自の帯域幅値を作り出さないでください。
• Map Local のリテラルレスポンスを更新する場合は、response_body、status_code、content_type をまとめて送信してください。
• レビュー済みの MCP では Breakpoint ルールを管理できますが、現在一時停止中のブレークポイントの編集や実行／キャンセル／中止はできません。これらの操作は引き続き Proxyman GUI で行う必要があります。
• レビュー済みの MCP の Map Local では、リテラルレスポンスまたはキャプチャしたフローのレスポンスを作成できますが、任意のファイル／ディレクトリのルールは作成できません。Map Remote のレビュー済み MCP スキーマでは、CLI にある「元の URL を保持する」個別のオプションは公開されていません。
• Map Local、Map Remote、Scripting、Breakpoint のルールが重複する場合は、一致したすべてのルールが実行されると決めつけず、順序付きの Debugging Tools サマリーを確認してください。
• 外部プロキシの変更時は、選択した種類に必要な設定一式を送信してください。値を省略しても、既存設定が確実に維持されるとは限りません。認証情報を渡す前に確認してください。
• Compose ID はメモリ内にのみ保持されます。send_compose_http は HTTP 専用であり、WebSocket URL は拒否されます。
• レビュー済みの MCP には、ワンクリックの Repeat 操作はありません。フローから Compose の下書きを作成する機能は Edit & Repeat に相当しますが、GUI の Repeat／履歴と完全に同等ではありません。
• MCP では、Proxyman がデコードした後の Protobuf コンテンツを表示できますが、Protobuf のスキーマ／ルールは設定できません。レビュー済みの MCP では、TLS Key Logging も GUI 専用です。
• WebSocket のペイロードプレビューには制限があり、情報がマスキングされます。close_websocket_session が適用されるのは、Compose で作成したアクティブな WebSocket セッションのみです。
• Scripting のハンドラーでは、Proxyman の位置引数シグネチャを使用する必要があります。複雑なスクリプトを生成する前に docs://scripting/snippet-code を読んでください。
• get_proxyman_cli_help が返すのは、安全でバージョンに一致したヘルプのみです。実行系の CLI コマンドを実行することはありません。

期待される結果

次の内容を含めてください。

• 調査または変更した内容；
• 関連するフロー／ルール／下書きの ID；
• 検証時の読み取りで得られた根拠；
• プライバシー、エクスポート、またはプラットフォーム上の制限；
• 必要に応じて、ロールバックまたは次の診断手順。

キャプチャの状態、時間範囲、クライアントソース、またはプレビューの切り詰めによって結果が確定できない場合、トラフィックをすべて確認できたと主張しないでください。

トラブルシューティング

• ハンドシェイクが見つかりません：Proxyman を起動して「Settings > MCP」を有効にするか、proxyman-mcp-setup を使用してください。
• ハンドシェイクが無効、または 401 エラーが発生します：Proxyman を再起動し、MCP クライアントを再読み込みしてください。
• フローがありません：記録、対象のプロキシルーティング、ルート証明書の信頼、SSL プロキシ、クライアントソースを確認し、proxyman-https-capture で対象固有の設定を行ってください。
• HTTPS の内容が引き続き不明瞭です：変更する前に、証明書の状態と SSL プロキシの対象に含める項目／除外する項目を確認してください。
• localhost が表示されません：多くのクライアントはシステムプロキシをバイパスします。リバースプロキシのワークフローを使用するか、対象の明示的なプロキシ設定を使用してください。
• VPN がデバイスのキャプチャをブロックします：対応している iOS アプリでは、Atlantis の判断手順を使用してください。
• 自動化が失敗します：再試行する前に、OS の権限プロンプトが表示されているか、対象が利用可能か、証明書の状態、および必要なユーザーの同意を確認してください。