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 文件夹包含一个 schema 为 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 表示成功，1 表示领域错误或 IO 错误，2 表示用法错误。每个子命令都支持 --dir。

MCP 服务

npx -y @reneturcios/healthfolder mcp

MCP 客户端配置：

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

将 "--dir", "<absolute path>" 添加到 args，即可跳过文件夹搜索。

工具（13 个）

工具	功能
list_workouts	从索引中获取锻炼记录（去重，最新记录在前），每条记录一行摘要
get_workout	完整获取一条锻炼记录：文档、摘要、分段文本、区间、心脏负荷
get_vitals	获取过去 N 天的静息心率、HRV、体重、睡眠、步数、VO2max、血压
training_summary	每个 ISO 周一条记录：从每日文件汇总训练量、区间、努力程度、心脏负荷和圆环
rate_workout	将运动员自己的努力程度评分（1–10）保存到锻炼文件中
push_plan	验证训练计划，并写入 plans/<id>.json，供应用推送到 Watch
get_plan_status	获取计划状态：pending、scheduled、failed 或 cancelled
list_plans	列出所有计划及其状态和计划距离／时长
get_day	获取一个每日文件及其中包含的所有 Health 分组
get_days	获取指定范围内的每日文件（最多 366 天），可选择仅返回指定分组
get_catalog	获取 catalog.json 和导出覆盖情况检查结果
get_profile	获取原样写入的 profile.json
list_ecgs	列出 ecg/ 中的所有 ECG 摘要，最新记录在前

所有结果均为格式化的 JSON 文本，浮点数四舍五入到小数点后一位。格式错误的参数会返回 JSON-RPC InvalidParams 错误；领域问题（未知 ID、验证失败、拒绝操作）会作为 isError 结果返回，并以通俗文字说明原因。

内置两项安全规则：

• rate_workout 只会保存运动员亲口提供的数字。如果锻炼记录已包含 Apple 自带评分（effort_source: "apple"），则除非调用时传入 override: true，否则会拒绝操作；拒绝信息会指出文件、现有评分和解决方法，且不会写入任何内容。
• push_plan 会在一条消息中报告所有验证问题（运动类型、名称长度、区块／步骤结构、目标类型和值、区间、标签长度），因此可一次性修正计划。

资源：healthaccess://index（去重后的索引）和模板 healthaccess://workout/{id}（包含心率序列的一条锻炼记录）。此版本未实现 MCP 提示词。

派生数值

• 区域。 四个界限，五个区域。界限来自 config.toml， 否则根据 profile.json 中的年龄估算：最大心率 = 208 − 0.7 × 年龄，界限为其 72/79/86/92%（年龄 34 岁 → [133, 146, 158, 169]）。区域秒数根据心率 序列计算：每个样本到下一个样本之间的时间计入该 样本所属的区域，只统计锻炼期间的时间，超过 60 秒的 间隔按 60 秒计算。如果未知界限，则显示文件自身的旧版区域， 并标记为 bounds_source: "file"。
• 心脏负荷（仅游泳）= 平均心率 × 最佳自由泳 100 米配速 （秒）/ 60 = 每 100 米心跳次数；数值越低越好。最佳 100 米是 距离至少 95 米的最快训练步骤，且其重叠圈数中至少一半为自由泳， 并换算为 100 米；如果没有符合条件的步骤，且游泳距离至少为 100 米， 则使用整次锻炼的配速。
• 摘要行格式如下： 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 — 仅在存在相应数据时才显示各个部分。

在线握手

初始化时，以及工具调用后（每分钟最多一次），服务会在该文件夹中写入 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.