ローカルエージェントとヘルスコンテキスト

Health.mdでは、ローカルのコーディングエージェントや自動化エージェントがApple Healthデータを扱う方法を2つ用意しています。

明示的なターミナルコマンドと正規抽出に使用するhealthmd CLI
型付きツール、ネイティブ可視化、承認済みの生成ファイルエクスポートに使用するhealthmd mcp serveと、そのMCP App

ポータブルMCPサーバーは、前面表示中のiPhoneと直接通信し、Health.md for Macを必要としません。CLIは、生データや正規データのエクスポートに同じ直接接続を使用できます。または、Macでのインデックス処理にMacアプリのループバックAPIを使用できます。HealthKitの読み取りは常にiPhone上で行われ、healthmd.health_data v8が公開ソースコントラクトとして維持されます。

local agent -> healthmd mcp serve -> authenticated encrypted port 17647 -> foreground iPhone
local agent -> healthmd CLI -> direct iPhone or optional Mac loopback workflow

エージェントができること

ヘルスデータの値を読み取らず、直接ペアリングと前面表示中のiPhoneの準備状況を確認する
正規メトリックIDとカテゴリを一覧表示する
指標、ソース、日付、詳細レベルを正確に指定してiPhoneから取得する
正規の日次ドキュメントまたはソースレコードを抽出する
エビデンスとカバレッジを含む型付き指標時系列を照会する
安定した睡眠セッションと固定の睡眠時間枠を構築する
ワークアウトを前後の睡眠セッションと対応付ける
ワークアウトを一覧表示し、カバレッジを確認する
集計方法を明示して正確な期間を比較する
事実に基づくトレーニングエビデンスパケットを作成する
上限付きリクエストを使い、論理的には上限のないコーパスをページ単位で取得する
指標、睡眠、ワークアウト、比較、カバレッジ、エビデンスのビューをMCP Apps内にレンダリングする
明示した既存のデスクトップ保存先へ、承認済みの生成ファイルをエクスポートする
永続エクスポートジョブを確認、再開、キャンセルする

Health.mdは、診断、治療の推奨、因果関係の推定を行いません。また、結果を健康、有害、良い、悪いと評価しません。

ローカルヘルパーを設定する

公開プレビュー · まだ認定済み安定版ではありません

クロスプラットフォームパッケージは、明示的に未認定のプレビューとして公開されています。リリース証拠に記載された正確なモバイルビルドを使用してください。署名済みMacヘルパーはエージェントを設定から引き続き利用できます。

macOSまたはLinuxでbrew install CodyBontecou/tap/healthmdを実行し、続いてhealthmd --versionを確認します。
healthmd setup codexを実行します。Codexが設定され、まだ信頼済みのiPhoneがない場合はペアリングが開始されます。
iPhone版Health.mdのDirect CLI Accessでペアリングを完了し、アプリを前面に表示したままにします。
Claudeまたは手動でホストを設定する場合は、Health.md MCPサーバーとAppを参照し、healthmdの絶対パスに引数mcp serveを指定します。
設定が変更されたと表示された場合はホストを再起動し、healthmd_doctorを呼び出します。

エージェントスキルをインストールする

Health.mdのMacアプリは、Macユーザー向けの任意のインストール経路およびスキル配布経路です。ポータブルMCPの依存関係ではありません。

ほとんどのユーザーは、skills.shの一般ユーザー向けHealth.md CLIスキルのみをインストールしてください。

npx skills add CodyBontecou/health-md@healthmd-cli

公開リポジトリには、タスク別に4つのスキルがあります。

スキル	用途
`healthmd-cli`	ユーザーが許可した範囲内でのCLI/MCPクエリとエクスポート
`healthmd-cli-operator`	iPhone直接接続の操作と永続ジョブの復旧
`healthmd-cli-development`	CLI、MCP、プロトコル、iPhoneサービスの開発
`healthmd-cli-qa`	自動検証と実機検証

コントリビューター向けスキルをインストールするには、@以降の名前を置き換えます。通常の健康データの依頼には、開発用またはQA用のガイダンスをインストールしないでください。npx skills add CodyBontecou/health-md --listを使用すると、スキルをインストールせずにリポジトリを確認できます。npx skills update healthmd-cli --project --yesを使用すると、プロジェクト用の一般ユーザースキルを更新できます。すべてのコマンドと公開契約については、リポジトリのインストールガイドを参照してください。

スキルは指示のセットです。healthmdやhealthmd-mcpのインストール、MCPの設定、電話のペアリング、健康データへのアクセス許可は行わず、自動更新もされません。インストール前にソースを確認してください。

アプリのスキルインストーラーは、承認したディレクトリにhealthmd-cli/SKILL.mdを作成します。置き換えるのはHealth.md自身のスキルフォルダだけです。このスキルは、範囲と上限を明示したコマンド、構造化された結果の扱い、プライバシー規則、モデルプロバイダーへの開示境界、結果が不明な場合の安全な復旧方法をエージェントへ伝えます。

エージェントにシンボリックリンクを作成させる場合は、Macアプリ内の設定用プロンプトを使用してください。Health.mdが、シェルの起動ファイルや/usr/local/binを暗黙に変更することはありません。

まず準備状況を確認する

ポータブルMCPクライアントでは、healthmd_doctorを呼び出します。ヘルスデータの値を読み取らずに、ローカルの直接接続の信頼状態と、接続中で前面表示されているiPhoneを確認し、対処方法を含むヘルスデータ非依存のエラーを返します。その後、型付きMCPクエリごとに、そのiPhoneへ明示的な新規リクエストを送ります。要求したスコープだけを取得し、デバイス上で型付きクエリを評価して、上限付きのページを返します。

MacループバックCLIのユーザーは、引き続きhealthmd doctorを実行し、healthmd.cli_doctor v1の準備状況、暗号化コンテキストのカバレッジ、次に必要な操作を確認できます。

すべてのリクエストが独自のスコープを持つ

Health.mdは、保存済みアクセスプロファイル、呼び出し元登録、権限レコード、CLI認証情報を使用しません。各リクエストには、必要なデータスコープをすべて指定します。

メトリックIDまたはカテゴリ
Apple Healthと、任意のプロバイダのソースセレクター
正確な日付または利用可能なすべての日付
サマリーまたはロスレスの詳細レベル
クエリ操作
上限付きのページ制御

新規取得では、現在のカタログに照らしてスコープを検証し、永続ジョブとともに保持して、保存済みのエクスポート設定を変更せずにiPhoneへ適用します。

取得対象を明示していないリクエストは、ユーザーの通常のエクスポート設定を引き継がず、拒否されます。

認証境界

ポータブルMCPは、ペアリング済みの直接接続プロトコルを使用します。ネイティブの認証情報ストレージ、相互のトランスクリプト認証、暗号化パケット、リプレイ保護、コンピューター上で明示されたアドレスへの前面表示中のiPhone接続を備えています。任意で使用するMacクエリAPIは、IPv4とIPv6のループバックだけで待ち受け、ピアがループバックであることを検証します。

任意のMacループバックモードでは、Health.mdが開いている間にポート17645へ到達できるローカルプロセスなら、同じクエリリクエストを送信できます。ローカルマシンへのアクセスをクエリ権限として扱ってください。

ポートをLANインターフェースへバインドまたはプロキシしない
別のマシンへトンネルしない
前段にHTTPリバースプロキシを置かない
ループバック以外のURLをMCPに設定しない
どのローカルエージェントがヘルパーを実行できるか確認する

廃止されたプロファイルルートとアクティビティルートは、互換性のため410 removed_endpointを返します。

正規データと派生ビュー

エージェントがソースに近い形式のデータや、検証済みの大きな生データ／正規データ本文を必要とする場合は、healthmd extractを使用します。

healthmd extract --metric workouts --last 14 \
  --object records --detail lossless --output workout-records.json

派生ビューとホスト内の可視化には、クエリコマンドまたはMCPツールを使用します。

healthmd query --metric resting_heart_rate --last 30 --all-pages
healthmd sleep sessions --last-nights 14 --window first:4h
healthmd training align --last 14 --workout running --sleep-window first:4h

この区別には明確な意図があります。

サーフェス	コントラクト上の役割
`healthmd.health_data` v8	公開の日次ソースドキュメント
`healthmd.healthkit_records` v1	ロスレス日次ドキュメント内の正規ソースレコードアーカイブ
`healthmd.extract_receipt`	抽出スコープと完了メタデータ
`healthmd.query_context_day` v1	破棄可能な暗号化インデックスレコード
`healthmd.query_response` v1	型付きでページ分割された派生結果
`healthmd.evidence_packet` v1	ソースエビデンスに紐づく事実パケット
ジョブおよび走査のレシート	転送、永続性、完了のメタデータ

プロジェクションや型付き結果が、完全な日次ソースドキュメントを装うことはありません。

新規取得

高レベルクエリは、既定で新しいデータを取得します。

healthmd query --category Sleep --last 14

Health.mdは、専用の暗号化コンテキストリクエストを作成します。エクスポートファイルを書き込まず、ファイルエクスポートの利用枠も消費しません。iPhoneは明示されたスコープを読み取り、決定論的なコンパクト所有者日を構築して、上限付きで再開可能なパーティションを送信します。Macは暗号化された各日をコミットしてから確認応答します。

新規取得の完了判定では、要求したすべての指標、ソースまたはプロバイダ、所有者日について、更新開始後にblobが置き換えられたかを確認します。古いキャッシュ値や別のプロバイダのデータで、取得失敗を隠すことはできません。

プロバイダだけを対象とするリクエストでは、HealthKitを省略できます。プロバイダ履歴の走査では、結果総数に固定上限を設けず、プロバイダ固有のカーソルをたどります。

Macの暗号化コンテキスト

Macは、所有者日ごとに独立して暗号化した1つの世代を保存します。ランダムな256ビットキーは、「このデバイスのみ」かつ「ロック解除時」のKeychain項目として保存されます。

日ごとのblobとマニフェストにAES-256-GCMを使用
ファイル名は日付や指標名ではなく、ランダムなUUID
所有者日とインデックス項目も暗号化
ファイルには所有者だけの権限とバックアップ除外を設定
暗号化マニフェストを置き換える前に、新しい変更不能な世代を書き込み
キーがない、認証に失敗した、日付が不正、マニフェストが一致しない場合は、安全側に倒して読み取りを失敗させる

ストアには、指標数、日数、履歴、結果数の合計に設定上の上限はありません。コマンドは1日ずつ復号し、結果をページ分割することでリソースを制限します。

インデックスは破棄できます。正規エクスポートが引き続き信頼できる情報源です。

保持と削除

Health.mdは、暗黙の保持スケジュールに基づいてクエリコンテキストを削除しません。Macの「設定」には、保存済みの所有者日数と日付範囲が表示されます。

次の操作を使用できます。

古いコンテキストを削除：選択した境界より前の所有者日だけを削除
暗号化されたコンテキストをすべて削除：暗号化されたすべての世代と専用Keychainキーを削除

キーまたは暗号文が破損している場合でも、完全削除は実行できます。キーを削除すると、削除しきれなかった暗号文の残片も暗号学的に消去されます。

クエリコンテキストを削除しても、エクスポートファイル、接続済みプロバイダの認証情報、Apple Healthデータは削除されません。

型付き値と欠損

クエリ値には型タグが付きます。結果には、数量と正規単位、期間、符号付き件数、文字列、カテゴリ、真偽値、UTCタイムスタンプ、暦日、ネストした配列、将来追加される未知の型付きペイロードを含めることができます。

欠損データは明示されたままです。

complete_emptyは、表現されたスコープに該当する観測値がなかったことを意味します。
partialは、要求スコープの一部だけが完了したことを意味します。
failed、unsupported、skipped、cancelledは、それぞれの意味を維持します。
not_requested、legacy_unavailable、redacted、not_synchronizedは区別されます。

Health.mdは、存在しない値を数値のゼロへ変換しません。実際のゼロは、利用可能な型付き値としてエンコードされます。

エビデンスと中立的な表現

結果は、次のようなソースエビデンスに事実を紐づけます。

日次サマリーキー
正規HealthKit UUID
外部ID
クエリマニフェストの結果
整合性の警告
部分的な失敗

エビデンスの解決では、エビデンスID、ロケーター、ソーススキーマ、ソースバージョン、ソースダイジェストをまとめて確認します。

期間比較の方向は、increased、decreased、unchanged、not_comparableだけです。トレーニングの対応付けではタイムスタンプと時間差を報告し、因果的な影響は示しません。エビデンスパケットは、保存された観測値とカバレッジを報告し、医学的な結論は示しません。

エージェント自身の回答でも、これらの制限を維持する必要があります。データがない場合は明示し、相関関係を因果関係に変えず、医療上の質問については有資格の医療専門家へ相談するよう案内してください。

上限付きページによる論理的に完全なアクセス

クエリページではmax_items、max_bytes、不透明なnext_cursorを使用します。保存されている日数、ワークアウト数、指標数、結果項目数の合計に、コントラクト上の上限はありません。

カーソルは整合性が保護され、意味的なクエリと暗号化コーパスのリビジョンに紐づきます。Health.mdは次のカーソルを拒否します。

変更されたカーソル
別のクエリに使用されたカーソル
コーパスが変更される前に発行されたカーソル
自動走査中に繰り返されたカーソル

上限付きの自動走査には、--all-pagesまたはMCPのall_pages: trueを使用します。1回の呼び出しが全体の安全上限に達した場合は、スコープを狭めるか、手動でページを取得してください。

エージェントの報告チェックリスト

結果を要約するときは、次の情報を報告します。

使用したコマンドまたはツール
要求した正確な日付、指標、ソース、詳細レベル
新規取得、キャッシュ、カバレッジ再利用のいずれのモードか
要求スコープのステータスとコーパスのステータスを別々に
ページまたは走査の完了状態
記載する各値の単位とソースエビデンス
欠損期間、制限事項、無関係なスキップ
処理が一時停止中または再開可能な場合はジョブID

ユーザーがそれらの値を明示的に要求し、開示内容を理解している場合を除き、生レコード、経路、臨床テキスト、服薬の詳細、気分の記録、添付ファイルを含めないでください。