# Yummy Health MCP

私人、只读的健康数据桥：

```text
华为手表
   ↓
华为运动健康
   ↓（当前可用）                    ↓（拿到华为 Health Service Kit 权限后）
Android Health Connect  ← 手机同步器 →  Huawei Health Source
                         ↓ HTTPS
                    Zeabur 私人存储
                         ↓ OAuth 2.1 + MCP
                       ChatGPT
```

当前版本已经实现：

- Android Health Connect 读取：心率、静息心率、步数、睡眠、运动、血氧、体重
- 手机到 Zeabur 的独立 `SYNC_TOKEN` 认证
- SQLite 持久化和重复记录更新
- ChatGPT 动态 OAuth 客户端注册、PKCE、access token、refresh token
- 只读 MCP 工具：
  - `get_latest_health_status`
  - `get_health_records`
  - `get_heart_rate`
  - `get_sleep`
  - `get_daily_activity`
- 华为直连数据源接口已预留；尚未填入 Health Service Kit SDK，因为需要你自己的
  App ID、签名证书、`agconnect-services.json` 和已批准 scopes

## 1. 部署后端到 Zeabur

1. 新建一个 Service，源码目录选本项目根目录，让 Zeabur 使用 `Dockerfile`。
2. 给 Service 挂载持久卷到 `/data`。不挂卷会在重建后丢记录和 OAuth token。
3. 设置环境变量：

   ```dotenv
   PUBLIC_BASE_URL=https://你的域名
   APP_PASSWORD=只在ChatGPT授权页输入的长密码
   SYNC_TOKEN=只填进手机同步器的另一条长随机字符串
   DATA_DIR=/data
   ACCESS_TOKEN_TTL_SECONDS=3600
   ```

4. 部署后检查：

   ```text
   https://你的域名/healthz
   ```

   应返回：

   ```json
   {"ok":true,"version":"0.1.1"}
   ```

不要把 `APP_PASSWORD`、`SYNC_TOKEN` 或 `/data/health.sqlite3` 提交到 GitHub。

## 2. 编译手机同步器

### 不安装 Android Studio：用 GitHub Actions

1. 打开 GitHub 仓库的 `Actions`。
2. 左侧选择 `Build Android APK`。
3. 点右侧 `Run workflow`，再确认运行。
4. 等任务变绿，点进该次运行。
5. 页面底部 `Artifacts` 下载 `yummy-health-sync-debug`。
6. 解压后把 `app-debug.apk` 安装到手机。

仓库中已包含 `.github/workflows/build-apk.yml`，不需要 Gradle Wrapper。

### 用 Android Studio

1. 用 Android Studio 打开 `android-sync`。
2. 等 Gradle 同步完成，连接手机并运行 `app`。
3. 在应用里填：
   - Zeabur 地址：`https://你的域名`
   - `SYNC_TOKEN`：与 Zeabur环境变量完全一致
4. 点“授权并同步最近 14 天”，在系统 Health Connect 页面允许需要的数据类型。

目前是手动同步，便于先验证数据是否完整；确认稳定后再加 WorkManager 定时后台同步，
避免手机省电策略导致“看似成功、实际没更新”。

如果华为数据没有出现在 Health Connect：

- 先确认华为运动健康到 Health Connect 的共享开关；
- 确认 Health Connect 中“应用权限/数据和访问权限”能看见对应记录；
- 华为运动健康和同步器都允许后台运行；
- 第一次可先只同步 1–14 天，避免记录量太大被手机杀后台。

## 3. 连接 ChatGPT

ChatGPT 需要远程 HTTPS MCP；本项目地址是：

```text
https://你的域名/mcp
```

在 ChatGPT 的 Developer mode / Apps 中创建自定义 MCP：

1. 填上面的 MCP 地址。
2. 选择 OAuth。
3. 扫描工具。
4. 浏览器会打开本项目的授权页，输入 `APP_PASSWORD`。
5. 授权后应扫描到 5 个只读工具。

服务端会动态接受 ChatGPT 提供的 HTTPS callback，因此没有写死 Claude callback。
OAuth metadata：

```text
/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server
```

## 4. 华为运动健康直连

华为官方允许应用在用户授权后读取华为运动健康数据，但需要：

1. 注册 HUAWEI Developer；
2. 在 AppGallery Connect 创建 Android 应用；
3. 固定包名（当前为 `love.yummy.healthsync`）；
4. 配置签名证书指纹；
5. 申请 Health Service Kit 和所需读取 scopes；
6. 下载 `agconnect-services.json`；
7. 审核通过后补全 `HuaweiHealthSource`。

基础数据可供个人开发者申请；部分高级健康数据只开放企业开发者。测试 scopes 也需要
华为审核，所以 Health Connect 是今天就能运行的入口，华为直连作为无缝升级路径。

## 5. 本地测试

```bash
python -m venv .venv
.venv/bin/pip install -r requirements.txt pytest
PYTHONPATH=. .venv/bin/pytest -q
```

测试覆盖 SQLite 往返、动态客户端注册、OAuth PKCE、refresh token、MCP 初始化与工具扫描。

## 隐私边界

- MCP 工具全部只读，不提供写回或删除手机健康记录的能力。
- ChatGPT token 与手机同步 token 分离。
- 原始数据只保存在你的 Zeabur 持久卷。
- 这套工具用于陪伴和趋势观察，不把输出包装成医疗诊断。