Mi Band  →  Mi Fitness (phone)  →  Xiaomi cloud
                                      ↓
                              health sync (this project)
                                      ↓
                                   SQLite
                                      ↓
                         MCP tools (OAuth or API key)
                                      ↓
                              Grok answers with real data

git clone <this-repo> health-vault && cd health-vault

# Option A: uv
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .

# Option B: plain venv
python3.12 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .

.venv/bin/health login    # QR → scan with Xiaomi Account app
# QR is also saved as data/qr_login.png if you cannot see the terminal
.venv/bin/health sync --days 7
.venv/bin/health status   # expect sync_health: ok
.venv/bin/health show --days 14

.venv/bin/health key create --name grok   # prints Bearer token ONCE — save it
.venv/bin/health serve --host 127.0.0.1 --port 8787

[mcp_servers.health]
url = "http://127.0.0.1:8787/mcp"
headers = { Authorization = "Bearer hlt_PASTE_YOUR_TOKEN" }

curl -sS http://127.0.0.1:8787/healthz
# → ok

curl -sS -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8787/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{}'
# → 401  (auth required)

.venv/bin/health tool health_status
.venv/bin/health tool health_context --hint sleep --days 7

.venv/bin/health login
.venv/bin/health sync --days 7
.venv/bin/health oauth set-password    # password for the browser login page

# brew install cloudflared   # if needed
.venv/bin/health serve --host 127.0.0.1 --port 8787 --tunnel

# Terminal 1
.venv/bin/health serve --host 127.0.0.1 --port 8787 --public-url https://PLACEHOLDER

# Terminal 2 — after Uvicorn is up
cloudflared tunnel --url http://127.0.0.1:8787
# copy https://xxxx.trycloudflare.com

# Restart terminal 1 with the real public URL (OAuth issuer must match HTTPS host):
.venv/bin/health serve --host 127.0.0.1 --port 8787 \
  --public-url https://xxxx.trycloudflare.com

curl -sS https://xxxx.trycloudflare.com/healthz
curl -sS https://xxxx.trycloudflare.com/.well-known/oauth-authorization-server | head
curl -sS -o /dev/null -w '%{http_code}\n' -X POST https://xxxx.trycloudflare.com/mcp \
  -H 'Content-Type: application/json' -d '{}'
# → 401 without token

sudo mkdir -p /opt/health-vault/data
sudo chown "$USER:$USER" /opt/health-vault /opt/health-vault/data
chmod 700 /opt/health-vault/data

# copy or git clone the project into /opt/health-vault
cd /opt/health-vault
python3.12 -m venv .venv
.venv/bin/pip install -U pip
.venv/bin/pip install -e .

sudo tee /etc/health-vault.env >/dev/null <<'EOF'
HEALTH_ROOT=/opt/health-vault
HEALTH_DATA_DIR=/opt/health-vault/data
PUBLIC_BASE_URL=https://health.example.com
HOST=0.0.0.0
PORT=8002
# Optional: bootstrap owner password once if DB has none yet
OAUTH_LOGIN_PASSWORD=change-me-to-a-long-random-string
EOF
sudo chmod 640 /etc/health-vault.env
# owner should be root + the service user (e.g. root:deploy)

[Unit]
Description=Health Vault MCP server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USER
Group=YOUR_GROUP
WorkingDirectory=/opt/health-vault
EnvironmentFile=/etc/health-vault.env
ExecStart=/opt/health-vault/.venv/bin/python -m health_mcp
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/health-vault/data

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now health-vault.service
systemctl is-active health-vault
curl -sS http://127.0.0.1:8002/healthz

health.example.com {
    reverse_proxy 127.0.0.1:8002
}

server {
    listen 443 ssl;
    server_name health.example.com;
    # ssl_certificate ...;
    location / {
        proxy_pass http://127.0.0.1:8002;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

cd /opt/health-vault
# if OAUTH_LOGIN_PASSWORD was not used:
HEALTH_ROOT=/opt/health-vault .venv/bin/health oauth set-password

HEALTH_ROOT=/opt/health-vault .venv/bin/health login
HEALTH_ROOT=/opt/health-vault .venv/bin/health sync --days 7

*/30 * * * * cd /opt/health-vault && HEALTH_ROOT=/opt/health-vault .venv/bin/health sync --days 3 >>/var/log/health-sync.log 2>&1

https://health.example.com/mcp

curl -sS -o /dev/null -w '%{http_code}\n' https://health.example.com/          # 200
curl -sS -o /dev/null -w '%{http_code}\n' https://health.example.com/healthz   # 200
curl -sS https://health.example.com/.well-known/oauth-authorization-server | head
curl -sS -o /dev/null -w '%{http_code}\n' -X POST https://health.example.com/mcp \
  -H 'Content-Type: application/json' -d '{}'                                  # 401

health login                         # Xiaomi QR → data/token.json
health sync [--days N] [--uid …] [--base-url …]
health status
health show [--days N]

health key create|list|revoke
health oauth set-password|status

health serve [--host] [--port] [--public-url] [--tunnel]
health tool <name> [--days N] [--hint …] [--metric …]

src/health_core/       SQLite schema, queries, sync_health
src/health_ingest/     Xiaomi cloud → daily_metrics
src/health_auth/       API keys, owner password, OAuth AS
src/health_mcp/        MCP server, tools, tunnel helper
src/health_cli/        `health` CLI
vendor/mi-fitness-python/   vendored SDK (GPL-3.0)
deploy/                example systemd unit (template only)
docs/GROK_CONNECT.md   Grok connection details
data/                  runtime (gitignored)