google-health-hermes-agent-mcp

谷歌健康每日脉搏 一个用于谷歌健康 API v4 的自托管健康服务。它同步 Fitbit、Pixel Watch 和兼容的健康数据，在本地保留带有时间戳的记录，计算可重复的 7 天和 28 天比较，并通过只读 MCP 服务器向 Hermes Agent 公开摘要和完整数据。 您可以对这个仓库做任何您想做的事情。**Codex 用于编写它。** 请自担风险。对于 Mac 用户，应该不会有太大的区别。我稍后会在 Mac 上测试并在出现问题时更新仓库。 ## 架构 ```text 谷歌健康 API → OAuth 2.0 + 加密令牌 → FastAPI / healthctl → SQLCipher 加密数据库 + 加密敏感负载 → 确定性基线 → 本地只读 MCP 服务器 → Hermes（可选） → Discord ``` 核心健康服务在没有 Hermes 的情况下也能工作。如果 Hermes、订阅或速率限制不可用，服务可以生成确定性的英文模板消息。 ## 快速开始 要求：Python 3.11 或更新版本。 ```powershell python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e ".[dev]" Copy-Item .env.example .env healthctl seed-demo healthctl daily-pulse --no-hermes ``` 或者，`healthctl setup` 交互式地创建 `.env` 而不显示客户端密钥。OAuth 客户端凭证存储在 `data/credentials.enc` 中，而不是 `.env`。 现有安装应在升级后运行此命令： ```powershell healthctl migrate-security ``` 这会将现有的明文 SQLite 数据库转换为 SQLCipher，将谷歌 OAuth 客户端凭证移出 `.env`，使用 Windows DPAPI 保护主密钥，并限制本地文件权限。 对于真实数据： 1. [配置谷歌云](docs/google-cloud-setup.md)。 2. 运行 `healthctl serve`。 3. 在第二个终端中，运行 `healthctl authorize`。 4. 运行 `healthctl sync`。 5. 运行 `healthctl daily-pulse --no-hermes`。 参见 [docs/windows-setup.md](docs/windows-setup.md) 了解完整的 Windows、Hermes、Codex、Discord、MCP 和调度器设置。 ## 需要保持运行的服务？ `healthctl serve` 和 MCP 服务器是分开的： - `healthctl serve` 在 `127.0.0.1:8765` 上启动本地 FastAPI 服务。需要它来进行谷歌 OAuth 回调，并且仅当您想要使用 REST 端点时才需要。 - 本地 MCP 服务器使用 stdio。Hermes 在加载配置的 `google-health` MCP 连接时自动启动 `google-health-mcp`。 - 您不需要保持 `healthctl serve` 运行以访问 MCP、通过 CLI 进行同步或生成每日脉搏。 - 要连续使用 Discord 的健康工具，必须运行 Hermes 网关。 - 要刷新本地数据库，请手动运行 `healthctl sync` 或调度 `healthctl run-daily`。 ## REST API 服务默认仅绑定到 `127.0.0.1:8765`。 ```powershell healthctl serve ``` | 方法 | 路径 | 目的 | |---|---|---| | `GET` | `/healthz` | 配置和同步状态（无密钥） | | `GET` | `/oauth/google/start` | 启动谷歌 OAuth | | `GET` | `/oauth/google/callback` | 接收 OAuth 回调 | | `DELETE` | `/oauth/google` | 撤销谷歌访问权限 | | `POST` | `/v1/sync` | 同步日期范围 | | `POST` | `/v1/daily-pulse` | 生成事实 | 示例： ```powershell Invoke-RestMethod -Method -Uri http://localhost:8765/v1/sync ` -ContentType application/json ` -Body '{"start_date":"2026-05-15","end_date":"2026-06-20"}' Invoke-RestMethod -Method Post ` -Uri http://localhost:8765/v1/daily-pulse ` -ContentType application/json ` -Body '{"use_hermes":true,"send":false}' ``` Uvicorn 访问日志被 CLI 服务器禁用，因此 OAuth 代码不会出现在查询字符串日志中。 ## 数据模型 数据库存储两个互补层。 标准化每日值： - 睡眠时长、睡眠周期、清醒时间和清醒次数以及效率 - 浅睡、深睡和 REM 睡眠（如果有） - 步数 - 轻度、中度和剧烈活动分钟数 - 运动次数、时长和类型 - 每日静息心率 - 每日 HRV/RMSSD 完整记录保留完整的结构化谷歌负载和时间戳，适用于配置的活动、健康指标和睡眠范围内的每个支持的流。这包括： - 完整的睡眠会话、阶段段和离床段 - 每日心率、HRV、血氧饱和度和呼吸测量 - 心率区、活动间隔、久坐不动时间和运动细节 - 能量、距离、楼层、VO2 最大值、身体测量和温度记录 - 总热量和心率区热量的每日汇总 完整的 SQLite 数据库，包括标准化指标、时间戳、索引、OAuth 状态和令牌，都使用 SQLCipher 加密。敏感负载和 OAuth 令牌保留额外的 Fernet 加密层。谷歌 OAuth 客户端凭证存储在加密的凭证文件中，而不是 `.env` 中。 在 Windows 上，`data/token.key` 处的本地主密钥使用 DPAPI 包装当前 Windows 账户。数据目录、数据库、密钥、凭证存储和 `.env` 使用 ACL 限制到该账户和 SYSTEM。机密必须在使用时在应用程序内存中解密；如果恶意软件已作为同一已登录用户运行，则无法保护它们。 默认每日同步使用 35 天的紧凑基线指标和最近 2 天的完整分辨率记录。这样可以避免每天早上重新下载数十万个一秒心率样本。随着调度同步的进行，详细记录会在本地累积。配置 `HEALTH_DETAILED_SYNC_LOOKBACK_DAYS` 为 1 到 90 之间的值，以获得更大的初始回填。 ## 命令行界面 ```text healthctl setup healthctl migrate-security healthctl serve healthctl authorize healthctl sync healthctl facts [--date YYYY-MM-DD] healthctl daily-pulse [--send] [--no-hermes] healthctl run-daily [--send] healthctl seed-demo healthctl doctor ``` ## 本地 MCP 服务器 该项目包含一个用于 Hermes 和其他本地 MCP 客户端的只读 stdio MCP 服务器： ```powershell google-health-mcp --project-dir C:\path\to\Google-Health ``` 它公开： - 计算出的每日事实和 7 天/28 天基线 - 确定性英文每日脉搏 - 选定的标准化历史记录，最多 90 天 - 所有详细数据类型及其本地覆盖范围的目录 - 日期范围内的完整记录，具有有限分页 - 用于日历和锻炼关联的精确时间窗口查询 - 授权、同步和本地数据覆盖状态 它不公开 OAuth 令牌、谷歌凭证、同步、撤销或数据库写入操作。详细健康负载故意可用于本地代理，但每个调用都是日期限定、限制为最多 500 条记录且可分页。 Hermes 通常会自动启动此可执行文件。 除非您正在测试 MCP 客户端，否则不应手动运行它。 ## Hermes 技能 仓库中包含 [skills/google-health/SKILL.md](skills/google-health/SKILL.md)。它教会 Hermes 如何选择正确的健康工具，将精确的时间窗口与日历事件关联，处理时区和个人基线，并在不复制原始健康数据到内存中的情况下使用内存。 将其安装到活动 Hermes 配置文件中： ```powershell $SkillsRoot = if (Test-Path "$env:LOCALAPPDATA\hermes\skills") { "$env:LOCALAPPDATA\hermes\skills" } else "$HOME\.hermskills" } $Target = Join-Path $SkillsRoot "personal\google-health" New-Item Directory -Force | Out-Null Copy-Item .\skills\google-health\SKILL.md $Target\SKILL.md -Force ``` 在安装或更改技能后启动新的 Hermes 会话。 ## 安全性和产品边界 - 将机密信息放入问题、聊天消息或 Git 中 仅请求只读范围。 - 数据库使用 SQLCipher 在静止加密。 -客户端凭证在 `.env` 外加密；令牌在 SQLCipher 数据库中使用额外的 Fernet 层加密。 - Hermes Discord 访问权限通过 `DISCORD_ALLOWED_USERS` 限制。 - FastAPI 服务默认绑定到 localhost，不提供公共多用户身份验证。 - 健康指导描述趋势；它不提供诊断或治疗。 - 集中式托管服务需要不同的安全架构、隐私审查、谷歌 OAuth 验证和循环受安全审查。 ## 测试powershell pytest . ``` ## 官方参考 - [谷歌健康 API 设置](https://developers.google.com/health/setup) - [谷歌健康 API 范围](developers.google.com/health/scopes) - [谷歌健康 API 应用验证](https://developers.google.com/health/app-verification) - [谷歌健康 API REST v4](https://developers.google.com/health/reference/rest) - [OpenAI Codex 身份验证](https://developers.openai.com/codex/auth) - [Hermes MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [Hermes Discord 设置](https://hermes-agent.nousresearch.com/docs/user-guide/discord)