Charles Local MCP

charles-local-mcp

macOS 向けのローカル限定、プロファイル駆動型の Charles Proxy 自動化ツールです。同じアプリケーションサービスを、JSON CLI と MCP stdio サーバーを通じて利用できます。

バージョン 0.1.3 は macOS 上の Charles 4.6.8 をサポートします。公開パッケージには汎用の example.com フィクスチャのみが含まれ、組織固有のホストやパスは含まれません。

プロファイル

schemaVersion = 1

[profiles.demo]
sourceHost = "app.example.com"
sourcePath = "/api*" # optional Charles path pattern
destinationUrl = "http://127.0.0.1:8080"
sslHosts = ["app.example.com"]
verificationUrl = "https://app.example.com/health"

destinationUrl を省略すると、Map Remote を無効にし、正確な SSL ホストとオプションの検証 URL を保持するプロキシ専用プロファイルになります。指定する場合、destinationUrl はループバックアドレスに制限されます。

Map Remote の宛先は、ループバックホストに解決される必要があります。verificationUrl は任意です。埋め込み認証情報のない HTTPS を使用し、sourceHost と一致する必要があります。

コマンド

charles-local-mcp doctor --json
charles-local-mcp --profiles-file profiles.toml profiles validate --json
charles-local-mcp --profiles-file profiles.toml --evidence-root /absolute/path/exports session evidence --profile demo --xml-file session.xml --json
charles-local-mcp --profiles-file profiles.toml setup plan --profile demo --platform android --json
charles-local-mcp --profiles-file profiles.toml setup apply --token TOKEN --json
charles-local-mcp setup resume --token TOKEN --json
charles-local-mcp status --json
charles-local-mcp cleanup plan --json
charles-local-mcp cleanup apply --token TOKEN --json
charles-local-mcp serve

状態の既定の保存先は ~/Library/Application Support/charles-local-mcp です。テストやインテグレーターは、CHARLES_LOCAL_MCP_HOME または --state-dir を使って状態を分離できます。CLI の stdout は JSON のみ、MCP の stdout はプロトコルデータのみです。診断情報は stderr に出力されます。

変更コマンドの実行には macOS と Charles 4.6.8 が必要です。セットアップとクリーンアップの計画は 15 分で期限切れとなり、1 回のみ使用できます。また、状態が変更されている場合は拒否されます。状態ディレクトリごとに有効なセッションは 1 つだけです。

ローカル XML セッションの証拠

session evidence は、設定された --evidence-root 内にある、選択されたローカルの .xml ファイルと、選択された不変のプロファイルのみを読み取ります。このオプションを省略した場合、ルートは <state-dir>/evidence が既定値になります。証拠の分析が要求されたときにのみ解決されるため、既存のセットアップおよび検査コマンドでは、そのディレクトリは必要ありません。相対パスによるルート外への移動、およびルート外を指す絶対パスは、ローカルパスを返すことなく拒否されます。証拠ルート、親ディレクトリ、選択されたファイルは、シンボリックリンクであってはなりません。

この操作では、選択されたプロファイルの正確な sourceHost を内部フィルターとしてのみ使用します。返されるバンドルには、プロファイル名、hostScope: "exact"、固定の HTTP メソッド列挙値、route-001 などのバンドルごとの不透明なルート参照、クエリパラメーター数、数値のステータスと所要時間、およびそれらの属性が存在する場合はリクエスト／レスポンスのサイズが含まれます。同じバンドル内では、同じ生のパスに同じ不透明なルート参照が割り当てられます。その他のホストは除外され、件数のみが報告されます。

この操作では、生のホスト、パス、クエリ名、クエリ値、ヘッダー、Cookie、認証情報、本文は決して返されません。不明なリクエストメソッドは、固定値 OTHER に変換されます。ソースセッションをアップロードまたは保存せず、証拠台帳も書き込みません。 ファイルサイズは 10 MiB、トランザクション数は 1,000 件までに制限されます。出力はリクエスト 100 件、失敗 50 件までです。DTD、DOCTYPE、エンティティ参照は拒否されます。 Charles のエクスポートには DOCTYPE 宣言が含まれる場合があります。分析の前に、信頼できるローカルコピーを作成し、宣言全体を削除してください。仕様、安全境界、制限、安定したエラーコードについては、 docs/session-evidence.md を参照してください。

実機での手順は、意図的に手動としています。詳しくは docs/manual-smoke.md を参照してください。

インストール

ローカルで Rust ツールチェーンを利用できる場合は、crates.io からビルドします。

cargo install charles-local-mcp --locked

macOS で MCP クライアントにワンクリックでインストールするには、該当する GitHub Release のユニバーサル .mcpb アセットを使用してください。ネイティブバイナリとバンドルは Apple による署名も公証も受けていないため、ダウンロードしたアセットを開く際に macOS がセキュリティ警告を表示する場合があります。インストール前に、そのリリースの SHA256SUMS を確認してください。バンドルは TOML プロファイルファイルを求め、charles-local-mcp serve を起動します。プロファイルは MCP ツールから読み取り専用です。 また、session_evidence ツールが読み取れる唯一のディレクトリとなる XML 証拠フォルダーも求められます。

リリースのメンテナーは、docs/releasing.md に従ってください。