healthfolder

healthfolder

Apple Watch のワークアウトとバイタル情報が入った Health Access フォルダーを読み込み、トレーニングプランをプレーンファイルとして書き戻します。アプリが Apple Health から書き出すフォルダー（ワークアウト、日ごとのファイル、インデックス、プロフィール）が API のすべてです。このパッケージは、そのフォルダーを扱うローカルの stdio MCP サーバーと CLI です。アカウントもネットワーク接続も不要で、データがマシンの外に送られることはありません。

フォルダーの検索方法

最初に見つかったものが使われます。

1. コマンドラインの --dir <folder>
2. HEALTHACCESS_DIR 環境変数（別名：TIDE_DIR）
3. ~/.config/healthaccess/config.toml 内の dir = "..."（パスは HEALTHACCESS_CONFIG で上書きできます。ゾーン境界も zones = [133, 146, 158, 169] として設定できます）
4. 検出順：iCloud Drive、次に ~/Library/CloudStorage/*、~/Dropbox、~/Google Drive、~/OneDrive*、~/Box、最後に ~/Documents。Health Access フォルダーには、スキーマが healthaccess.index.v1 の index.json と workouts/ ディレクトリが含まれます。検出されたフォルダーが複数ある場合、サーバーは推測で選ばず、候補を一覧表示します。

healthfolder --check を実行すると、解決されたフォルダー、その特定元、有効なゾーン境界が表示されます。

CLI

npx -y @reneturcios/healthfolder --check
npx -y @reneturcios/healthfolder list --sport swim --limit 5
npx -y @reneturcios/healthfolder show 7A1C3E90
npx -y @reneturcios/healthfolder vitals --days 14
npx -y @reneturcios/healthfolder summary --weeks 4
npx -y @reneturcios/healthfolder rate 7A1C3E90 7 "legs heavy, breathing fine"
npx -y @reneturcios/healthfolder plan push ./s30.json
npx -y @reneturcios/healthfolder plan status 2026-10-24T20:22:05Z-s30
npx -y @reneturcios/healthfolder plan list
npx -y @reneturcios/healthfolder day 2026-05-14
npx -y @reneturcios/healthfolder days --from 2026-05-01 --to 2026-05-14 --groups heart,sleep
npx -y @reneturcios/healthfolder catalog
npx -y @reneturcios/healthfolder profile
npx -y @reneturcios/healthfolder ecgs

すべてのコマンドは整形済み JSON を出力します。終了コード：成功は 0、ドメインエラーまたは IO エラーは 1、使用方法のエラーは 2 です。--dir はすべてのサブコマンドで使用できます。

MCP サーバー

npx -y @reneturcios/healthfolder mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "healthfolder": {
      "command": "npx",
      "args": ["-y", "@reneturcios/healthfolder", "mcp"]
    }
  }
}

フォルダーの検索を省略するには、args に "--dir", "<absolute path>" を追加します。

ツール（13）

ツール	機能
list_workouts	インデックス内のワークアウト（重複を除外し、新しい順）を、各ワークアウトにつき要約 1 行で取得します
get_workout	1 件のワークアウトの全情報：ドキュメント、要約、パーツのテキスト、ゾーン、心臓負荷
get_vitals	過去 N 日間の安静時心拍数、HRV、体重、睡眠、歩数、VO2max、血圧
training_summary	ISO 週ごとに 1 件のエントリーを返します。日ごとのファイルから、運動量、ゾーン、運動強度、心臓負荷、リング情報を取得します
rate_workout	アスリート自身の運動強度評価（1～10）をワークアウトファイルに保存します
push_plan	トレーニングプランを検証し、アプリが Watch に登録できるよう plans/<id>.json に書き込みます
get_plan_status	プランの状態：保留中、予定済み、失敗、キャンセル済み
list_plans	すべてのプランと、その状態および予定距離／時間
get_day	1 日分のファイルと、そこに含まれるすべての Health グループ
get_days	指定範囲の日ごとのファイル（最大 366 日）。名前を指定したグループだけに絞り込むこともできます
get_catalog	catalog.json とエクスポート対象範囲のチェック
get_profile	書き出された状態の profile.json
list_ecgs	ecg/ 内のすべての ECG 要約（新しい順）

すべての結果は、浮動小数点数を小数点以下 1 桁に丸めた、整形済み JSON テキストです。不正な引数は JSON-RPC の InvalidParams エラーになります。ドメイン上の問題（不明な ID、検証の失敗、拒否）は、理由を平易な言葉で示す isError の結果として返されます。

安全性を確保するため、次の 2 つのルールが組み込まれています。

• rate_workout が保存するのは、アスリート本人が申告した数値のみです。Apple 独自の評価（effort_source: "apple"）がすでに設定されたワークアウトに対しては、呼び出しで override: true を渡さない限り拒否されます。拒否時にはファイル名、既存の評価、対処方法が示され、何も書き込まれません。
• push_plan は、すべての検証違反（スポーツ、名前の長さ、ブロック／ステップの形式、目標の種類と値、ゾーン、ラベルの長さ）を 1 つのメッセージで報告するため、プランを一度に修正できます。

リソース：healthaccess://index（重複を除いたインデックス）とテンプレート healthaccess://workout/{id}（心拍数の時系列を含む 1 件のワークアウト）。このビルドでは MCP プロンプトは実装されていません。

派生指標

• ゾーン。 4 つの境界値で 5 つのゾーンを設定します。境界値は config.toml から取得し、ない場合は profile.json の年齢から推定します。最大心拍数は 208 − 0.7 × 年齢、境界値はその 72／79／86／92 ％です（34 歳の場合 → [133, 146, 158, 169]）。ゾーンごとの秒数は心拍数の時系列から計算します。各サンプルから次のサンプルまでの時間を、そのサンプルのゾーンに加算します。ワークアウト中の時間のみを対象とし、60 秒を超える間隔は 60 秒として計算します。境界値が不明な場合は、ファイルに記録された従来のゾーンを表示し、bounds_source: "file" と示します。
• 心臓負荷（スイムのみ）＝平均心拍数 × 最速のフリースタイル 100 m ペース（秒）／60 ＝ 100 m あたりの心拍数です。数値が小さいほど良好です。最速の 100 m は、重複するラップの半分以上がフリースタイルで、正規化後に 100 m 以上となる最速のワークステップです。該当するステップがなく、スイムの距離が 100 m 以上の場合は、ワークアウト全体のペースを使用します。
• サマリー行は次のようになります： 2026-05-14 Pool swim "S12" · 1200 m · 36:06 · avg HR 129 (max 162) · Z1–2 93% · effort 6/10 (apple) · best FR 100 2:12 → 284 beats/100 m — 各セグメントは、対応するデータがある場合にのみ表示されます。

プレゼンスハンドシェイク

初期化時と、ツール呼び出し後は最大 1 分に 1 回、サーバーはフォルダー内に mcp/clients/<id>.json を書き込み、アプリに「接続済み」と表示できるようにします。ID は、マシン名とクライアント名を組み合わせた FNV-1a 64 ハッシュです。このファイルには、初期化リクエストのクライアント名／バージョン、マシン名（HEALTHACCESS_MACHINE で上書き可能）、書き込み間で引き継がれる呼び出し回数、最後に使用したツール名が記録されます。引数や結果は記録されません。書き込みに失敗しても、ツール呼び出しは失敗しません。CLI も同じファイルを書き込みます。クライアント名は healthfolder-cli で、フォルダーへの書き込みを行うコマンド（rate、plan push）からのみ書き込みます。

Docker

docker run -i ghcr.io/cloudcorprecords/healthfolder            # stdio MCP server
docker run --rm ghcr.io/cloudcorprecords/healthfolder list --dir /data

Health Access フォルダーをコンテナーにマウントし、サーバーがフォルダーを見つけられるように --dir を渡すか、HEALTHACCESS_DIR を設定してください。

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (synthetic folders, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios.