health-records

个人健康记录网页 + MCP。饮食、实际训练、体重和目标保存在你自己的 WebDAV，网页与 Agent 读写同一份 JSON。

可以用网页记一餐、修改份量、记训练和体重；也可以让支持 MCP 的客户端代记，再回到网页核对。修改携带版本、保存后读回，重复请求不会重复新增。记录不足时展示缺失信息，不把“没有记录”当作“没有发生”。

本地启动

需要 Node.js 22 或更新版本。

npm ci
npm run build
npm start

打开 http://127.0.0.1:18740。设置 WebDAV URL 为 http://127.0.0.1:18740/dav/，用户名 demo，密码 demo-only。这是明确公开的本地开发账号，服务只监听回环地址；数据落在 .local-data/，重启保留。它不是生产通用 WebDAV 服务，也不是多用户系统。不要把这个端口转发到公网。

首次没有任何真实记录，也没有默认营养数据。设置个人资料后，可记录训练、体重和目标。食品名称查询需要导入食物库；未知食品的文字/照片估算需要配置下方可选识别服务。没有库或模型时，MCP 仍可保存用户明确提供的饮食数值。

开发前端：另一个终端运行 npm run dev，访问 http://127.0.0.1:5173；本地存储/识别服务仍需 npm start。浏览器凭据存于该 origin 的 localStorage，请使用独立最小权限账号，不在不可信共用设备保存凭据。

Related MCP server: health-mcp

正式存储：你自己的 WebDAV

网页设置和 MCP 配置使用相同 URL、用户名与密码。外部服务使用 HTTPS，支持强 ETag、If-Match、If-None-Match: * 和读回；浏览器直连需正确配置 CORS 并暴露 ETag。不满足版本条件的服务会拒绝记录写入。

先创建 personal/<username>/body/ 和 bills/ 目录。用户名只允许英文字母、数字、下划线和短横线。保留已有的文件契约：

• personal/<username>/body/food.json、workouts.json、weights.json、health-goals.json、profile.json

• bills/_settings.json 为兼容的存储选择文件，缺省时使用上述个人目录；显式 body: "shared" 时使用 bills/body/。本地开发适配器只提供个人目录。

MCP、网页对食物和健康记录使用条件写入、完整原快照校验及读回确认。资料页 profile.json 沿用单人配置的整文件保存，尚不提供并发编辑合并。请在服务器侧限制账号可访问目录，备份实际数据；本项目不提供托管服务。

食物库

源码不附带来源授权不明的第三方营养表，也不把测试数据当作真实营养值。可导入自己有权使用、已核对的每 100g 数据。页面支持搜索、份量换算和识别结果的库值校准。

从设置页下载模板，或编辑 模板文件：填写来源、名称，把 null 替换成包装标注或授权数据的非负数字，再导入。未填写数值的模板会被拒绝。可选字段与校验见 food-library.ts。导入库只存当前浏览器；MCP 接收已经确认的具体营养数值，不自动代查浏览器食物库。

可选照片与口述识别

照片上传和文字口述入口保留。识别服务使用 OpenAI-compatible /chat/completions，密钥只由本地服务运行时读取，不进入前端构建。HEALTH_AI_BASE_URL 例如 https://api.openai.com/v1；分别配置支持文本/图片输入的模型：

# 通过你的运行环境或密钥管理器注入，勿提交真实值：
# HEALTH_AI_BASE_URL, HEALTH_AI_KEY, HEALTH_AI_TEXT_MODEL, HEALTH_AI_VISION_MODEL
npm start

未配置时明确显示识别不可用，不会伪造识别结果。口述解析后先审核可编辑草稿，再保存；照片识别后可核对名称和份量。手动输入未命中库时会按所填名称/份量请求估算并保存，结果应随后核对。图片会发送到你配置的模型服务，可能产生费用；仅上传你愿意发送的图片。这里只做估算与个人回顾，不是医疗工具。

MCP stdio

支持本地 MCP 的客户端可配置：

{
  "mcpServers": {
    "health-records": {
      "command": "node",
      "args": ["/absolute/path/to/health-records/scripts/mcp-stdio.mjs"],
      "env": {
        "HEALTH_WEBDAV_URL": "http://127.0.0.1:18740/dav/",
        "HEALTH_WEBDAV_USER": "demo",
        "HEALTH_WEBDAV_PASSWORD": "demo-only"
      }
    }
  }
}

上面仅为本地开发例子。正式凭据由客户端运行时注入，不提交到仓库。14 个工具包括饮食查询/新增/修改，训练查询/新增/修改、体重查询/新增/修改、目标读取/设置以及 health_context。

Agent 必须只记录用户报告的实际行为；稳定 id 和 mutation_id 用于重试，修改前读取完整 expected。保存结果不确定时先读原 ID，再重放同一请求，不能换 ID 重记。工具返回结构化错误及 write_may_have_succeeded。

OAuth HTTP MCP

npm run mcp:http 复用同一存储。运行时必须设置：

• HEALTH_MCP_PUBLIC_BASE：外部 HTTPS 基址（带路径），例如 https://health.example.org/agent。

• HEALTH_MCP_STATE_DIR：独立持久授权状态目录。

• HEALTH_WEBDAV_URL、HEALTH_WEBDAV_USER、HEALTH_WEBDAV_PASSWORD。

• 可选 HEALTH_MCP_PORT（默认 18725）。

服务只监听 127.0.0.1，外部访问需自备 HTTPS 反向代理。MCP 地址为基址加 /mcp；OAuth 使用 PKCE、一次性 owner 同意、分别授予 food/health 的 read/write scope、令牌轮换与撤销。未授权请求返回 401，不提供公开免鉴权模式。完整健康能力须在授权时显式请求 food:read food:write health:read health:write；未指定 scope 时为兼容客户端仅默认授权饮食，不自动扩展训练、体重和目标权限。内部保留 food profile 键，但支持上述全部健康 scope。一个授权状态目录只允许一个进程使用。

测试与边界

npm test
npm run build

单元与集成测试使用合成记录、本地 DAV 和模拟 provider，无真实用户记录、密钥或付费请求。验收记录 区分真实协议/浏览器流程与真实模型质量。

时间口径沿用 Asia/Shanghai；记录和统计只反映已记录内容。能量、营养差值及体重目标时间为启发式估计，缺少资料时不应补造。食品库与模型可能有误，不能据此诊断疾病或制定治疗。

本地开发服务锁恢复

同一个数据目录只允许一个服务进程。端口被占用时启动失败并释放本次创建的锁，可换 HEALTH_LOCAL_PORT 后重试。正常退出会移除 .writer.lock。

进程被强制结束或机器断电后，锁可能残留。先确认没有任何进程仍使用该数据目录，再备份数据，手动删除该目录内的 .writer.lock 后重启。不要在服务运行时删除锁。启动日志会明确提示锁占用，服务不会自动绕过它。

其他开发参数：HEALTH_LOCAL_DATA_DIR、HEALTH_LOCAL_USER、HEALTH_LOCAL_PASSWORD。若改变端口或账号，网页与 MCP 需同步更新。不要使用真实生产凭据运行演示。

License

MIT，见 LICENSE。只许可本仓原创/获授权源码；用户导入的数据和模型服务分别遵守其授权。依赖许可见依赖包，本仓不分发原工作台历史、私人配置、真实记录或未授权食品数据。