health4ai

health4.ai — Apple Health × IA

Pergunte à sua IA sobre seu sono, VFC, recuperação e condicionamento físico — em linguagem natural.
App iOS gratuito · Seu próprio banco de dados · Funciona com qualquer cliente MCP

O que ele faz

iPhone HealthKit → Your Supabase project → MCP server → Any AI

O Apple Health guarda anos de seus dados biométricos — estágios do sono, VFC, frequência cardíaca, treinos, VO₂ máx. e mais de 150 outras métricas. O health4.ai torna tudo isso consultável pelo Claude, ChatGPT, Cursor, Ollama ou qualquer cliente compatível com MCP por meio de ferramentas MCP criadas especificamente para isso.

Você controla os dados. Eles são sincronizados para um projeto Supabase que você cria e possui. O health4.ai não executa backend e nunca armazena nem tem acesso aos seus dados de saúde.

Por que ele existe

Demonstração

Vídeo de demonstração em breve. Veja como é uma conversa típica:

You:     How was my recovery this week? Anything standing out?

Claude:  Your recovery this week was mixed but trending positive.
         • HRV averaged 58ms (Tue–Thu strong at 64–68ms; Monday low at 44ms after Saturday's long run)
         • Sleep averaged 7h 12m — Wednesday and Thursday were your best nights (7h 40m+)
         • Resting HR dropped from 54bpm Monday to 49bpm Friday — a good sign
         Recommendation: today looks like a solid day for a moderate-intensity session.

Início rápido

O health4ai precisa de um projeto Supabase que você possua. O app faz login com o Supabase Auth e grava por meio de uma Supabase Edge Function, portanto Postgres puro (Neon, um contêiner Docker local) não é um backend compatível. Tutorial completo: docs/SETUP.md.

1. Crie o esquema. Crie um projeto em supabase.com, abra o editor SQL e execute web/public/schema.sql (também em https://health4.ai/schema.sql). Ele é gerado a partir de supabase/bootstrap/: tabelas, segurança em nível de linha e permissões que negam acesso direto aos clientes. Não use supabase db push — as migrações numeradas não se aplicam a um projeto novo.

2. Implante a função de ingestão (requer a Supabase CLI):

git clone https://github.com/jefflitt1/health4ai.git
cd health4ai
supabase functions deploy healthkit-ingest --project-ref <your-project-ref> --no-verify-jwt

--no-verify-jwt é proposital: a função verifica o token do usuário conectado por conta própria e grava somente sob o ID desse usuário.

3. Crie seu usuário. No painel, Authentication → Users → adicione um usuário e copie o UID dele. O app faz login; ele não faz cadastro.

Em seguida, configure o servidor MCP (a partir do mesmo checkout):

cp mcp-server/.env.example mcp-server/.env

Edite mcp-server/.env:

DATABASE_URL=postgresql://...  # your project's pooler connection string (database password, not a key)
HEALTHKIT_USER_ID=...           # your Supabase Auth user's UID (see mcp-server/.env.example)

Adicione ao seu cliente de IA:

{
  "mcpServers": {
    "health4ai": {
      "command": "python",
      "args": ["/path/to/health4ai/mcp-server/main.py"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "HEALTHKIT_USER_ID": "<your auth user UID>"
      }
    }
  }
}

mcphost --model ollama/llama3.2 \
  --mcp-server "health4ai:python /path/to/health4ai/mcp-server/main.py"

Instale o app iOS: conecte-o a esse projeto Supabase (URL do projeto + chave anônima), faça login como o usuário que você criou e toque em Iniciar sincronização. Para um beta privado no TestFlight, siga o guia de isolamento de testadores; nunca use o backend ou as credenciais de outra pessoa.

Ferramentas MCP

Se uma métrica estiver vazia, leia data_status antes de acreditar nela

O iOS nunca informa a um app que uma permissão de Saúde foi negada. Um tipo que você não compartilhou retorna um resultado vazio, idêntico byte a byte a um dia em que você realmente não fez nada. Nada na API do HealthKit consegue distinguir os dois casos, então um assistente que lê um 0 simples dirá com confiança que você não deu nenhum passo.

As ferramentas que podem retornar um resultado vazio, portanto, anexam um bloco data_status:

• never_recorded — esta métrica nunca produziu uma amostra para você. Para passos, frequência cardíaca, energia ativa ou distância percorrida, isso não é possível se os dados estivessem sendo compartilhados, então quase certamente não estão. Abra Saúde → Compartilhamento → Apps → health4ai, ative a métrica e execute novamente a importação na aba Início do app.
• empty_window — nada no intervalo que você perguntou, mas a métrica tem dados em outros momentos. Uma lacuna real, não um problema de permissão.

Isso não é hipotético. Na conta do próprio autor, contagem de passos, frequência cardíaca, energia ativa e distância percorrida ficaram silenciosamente não compartilhadas por quase três meses enquanto todas as outras métricas sincronizavam normalmente, e o app exibia um "Concluído" verde o tempo todo.

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│  iPhone                                                      │
│  HKObserverQuery + BGTaskScheduler                          │
│  → continuous background sync                               │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS → your healthkit-ingest Edge Function
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Your Supabase project (you own it)                         │
│  healthkit_metrics · healthkit_daily_summaries              │
│  row-level security on · no direct client access            │
└──────────────────────────┬──────────────────────────────────┘
                           │ Postgres connection (database password, from your machine)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  FastMCP server  (mcp-server/main.py)                       │
│  FastMCP tools · stdio transport                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP
                           ▼
              Claude · ChatGPT · Cursor · Ollama · any client

Níveis de dados: consultas nos últimos 30 dias retornam amostras brutas. Dias mais antigos usam uma linha pré-agregada de healthkit_daily_summaries quando ela existe e, caso contrário, são agregados por dia dentro do Postgres a partir das amostras brutas, então os resultados são completos independentemente de o resumidor já ter sido executado no seu projeto (em um projeto auto-hospedado novo, ele nunca foi). As respostas trazem um bloco tier informando quantos dias cada nível atendeu. Os dias do calendário seguem HEALTH4AI_TZ (padrão UTC; defina em mcp-server/.env).

Estrutura do repositório

health4ai/
├── ios/                         # Swift/SwiftUI iOS app (iOS 17+)
│   └── Health4AI/               # HealthKit sync engine, auth, settings
├── mcp-server/
│   ├── main.py                  # FastMCP server entry point
│   ├── tools.py                 # MCP tool implementations
│   └── .env.example             # Required environment variables
├── web/
│   ├── public/schema.sql        # Generated from supabase/bootstrap (Supabase only)
│   └── src/                     # Astro marketing site
├── scripts/
│   ├── import_health_export.py  # One-time XML backfill from Apple Health export
│   └── summarize_historical.py  # Backfill daily summaries table
└── docs/
    └── SETUP.md                 # Detailed setup guide

Privacidade

Seus dados de saúde vão diretamente do seu iPhone para o seu próprio projeto Supabase. O health4.ai nunca recebe, armazena ou tem acesso a eles. O servidor MCP roda localmente com suas próprias credenciais — seus dados nunca tocam nossa infraestrutura.

Consulte a Política de Privacidade para detalhes completos.

Contribuição

Licença MIT. Pull requests são bem-vindos.

Boas áreas para começar: agregações adicionais de métricas, suporte a múltiplos usuários com JWT/RLS, Android e mais guias de integração com clientes MCP.

Licença

MIT — consulte LICENSE.