# Servidor MCP para Google Fit (Google Takeout)

Este projeto contém um **Servidor MCP (Model Context Protocol)** modular desenvolvido em Python com a biblioteca `FastMCP`. O servidor descompacta, lê, filtra e analisa automaticamente as pastas exportadas do Google Fit (extraídas do Google Takeout em Português) colocadas na pasta `./data`.

---

## Estrutura Modular do Projeto

```text
cli_project/
├── data/                                # Ignorada no .gitignore (dados privados)
│   ├── Atividades/                      # Ficheiros de registo de treinos e sessões
│   ├── Métricas de atividade diária/   # Ficheiros de passos, calorias e minutos ativos
│   ├── Todas as sessões/               # Histórico completo de sessões de exercício
│   └── Todos os dados/                  # Ficheiros JSON derived_com.google.*
├── src/                                 # Pacote Python com arquitetura modular
│   ├── models/                          # Schemas e estruturas de dados Pydantic
│   │   └── fitness_schemas.py
│   ├── parsers/                         # Parsers de ficheiros (ZIP, CSV, JSON)
│   │   ├── zip_extractor.py
│   │   ├── csv_parser.py
│   │   └── json_parser.py
│   ├── services/                        # Regras de negócio e agregação de dados
│   │   └── fitness_service.py
│   ├── server/                          # Componentes registados no FastMCP
│   │   ├── tools.py                     # Definição das Ferramentas (@mcp.tool)
│   │   ├── resources.py                 # Definição dos Recursos (@mcp.resource)
│   │   └── prompts.py                   # Definição dos Prompts (@mcp.prompt)
│   └── app.py                           # Inicialização e configuração do FastMCP
├── mcp_server.py                        # Ponto de entrada leve do Servidor MCP
├── pyproject.toml                       # Configuração e dependências
├── .gitignore                           # Proteção dos seus dados privados (data/)
└── README.md                            # Documentação de integração
```

---

## Instalação

1. **Criar e ativar o ambiente virtual**:
   ```powershell
   uv venv
   .venv\Scripts\activate
   uv pip install -e .
   ```

---

## Como Integrar o Servidor MCP em Qualquer IA

Adicione o servidor no ficheiro de configuração MCP do seu cliente de IA (`mcp_config.json` ou `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "google-fit-server": {
      "command": "uv",
      "args": [
        "run",
        "mcp_server.py"
      ]
    }
  }
}
```

---

## Como Testar no MCP Inspector

Para testar o servidor e inspecionar as pastas do Google Fit no ambiente gráfico de desenvolvimento:

```powershell
uv run mcp dev mcp_server.py
```

---

## Guia Detalhado de Utilização dos Componentes MCP

### 1. Ferramentas (Tools)

As ferramentas permitem que os assistentes de IA executem funções de consulta e manutenção de dados.

#### `clean_empty_data_files`
- **Descrição**: Analisa e deteta ficheiros JSON ou CSV na pasta `./data` que contêm zero pontos de dados ou apenas valores vazios `""`.
- **Parâmetros**:
  - `dry_run` (boolean, opcional, padrão: `true`): Se `true`, apenas lista os ficheiros vazios sem apagar. Se `false`, elimina fisicamente os ficheiros vazios do disco.
- **Exemplos de Valores e Chamadas**:
  - Simulação (listar sem apagar): `clean_empty_data_files(dry_run=true)`
  - Eliminação física: `clean_empty_data_files(dry_run=false)`

#### `scan_google_fit_data`
- **Descrição**: Percorre a pasta `./data`, deteta as pastas exportadas (`Atividades`, `Métricas de atividade diária`, `Todas as sessões`, `Todos os dados`) e devolve uma contagem das pastas e ficheiros válidos.
- **Parâmetros**: Nenhum argumento necessário.
- **Exemplo de Chamada**: `scan_google_fit_data()`

#### `get_daily_activity`
- **Descrição**: Extrai registos diários de contagem de passos (`step_count`), calorias despendidas (`calories.expended`), minutos ativos (`active_minutes`) e distância percorrida, ignorando ficheiros vazios.
- **Parâmetros**: Nenhum argumento necessário.
- **Exemplo de Chamada**: `get_daily_activity()`

#### `get_workout_logs`
- **Descrição**: Extrai sessões de treino, exercícios e segmentos de atividade física a partir das pastas `Atividades` e `Todas as sessões`.
- **Parâmetros**: Nenhum argumento necessário.
- **Exemplo de Chamada**: `get_workout_logs()`

#### `get_sleep_records`
- **Descrição**: Extrai registos e horários de sono dos ficheiros `derived_com.google.internal.sleep`.
- **Parâmetros**: Nenhum argumento necessário.
- **Exemplo de Chamada**: `get_sleep_records()`

#### `read_fitness_file`
- **Descrição**: Lê e interpreta o conteúdo bruto ou parseado de qualquer ficheiro localizado na pasta `./data`.
- **Parâmetros**:
  - `file_path` (string, obrigatório): Caminho relativo do ficheiro dentro da pasta `./data`.
- **Exemplos de Valores de Parâmetro**:
  - `file_path="Métricas de atividade diária/Daily activity metrics.csv"`
  - `file_path="Todos os dados/derived_com.google.step_count.delta_com.google.android.fit.json"`
  - `file_path="Atividades/Atividades.csv"`
- **Exemplo de Chamada**: `read_fitness_file(file_path="Métricas de atividade diária/Daily activity metrics.csv")`

---

### 2. Recursos e Templates de Recursos (Resources & Resource Templates)

Os recursos fornecem aos assistentes de IA leitura direta de dados através de URIs padrão.

#### `fitness://summary` (URI Direta)
- **Descrição**: Devolve um resumo executivo em JSON com o estado da ligação, total de ficheiros e ficheiros válidos detetados.
- **Exemplo de URI de Acesso**: `fitness://summary`

#### `docs://documents` (URI Direta)
- **Descrição**: Devolve uma lista JSON com os caminhos de todos os ficheiros disponíveis na pasta `./data`.
- **Exemplo de URI de Acesso**: `docs://documents`

#### `docs://documents/{doc_id}` (Template de Recurso)
- **Descrição**: Template de URI parametrizado para aceder ao conteúdo de qualquer ficheiro individual.
- **Parâmetro do Template**: `{doc_id}` (Caminho relativo do ficheiro).
- **Exemplos de URIs Completas para Acesso**:
  - `docs://documents/Métricas de atividade diária/Daily activity metrics.csv`
  - `docs://documents/Todos os dados/derived_com.google.calories.expended.json`
  - `docs://documents/Todas as sessões/Sessões.csv`

---

### 3. Prompts

Os prompts são rotinas de análise pré-definidas que orientam a IA para tarefas específicas de coaching e análise.

#### `analyze_progress`
- **Descrição**: Orienta a IA a analisar a evolução de passos, distância, minutos ativos e calorias.
- **Parâmetros**:
  - `period` (string, opcional, padrão: `"all"`): Período temporal de análise.
- **Exemplos de Valores de Parâmetro**: `"7_dias"`, `"30_dias"`, `"tudo"`
- **Exemplos de Utilização no Cliente de IA**:
  - `/analyze_progress period="7_dias"`
  - `/analyze_progress period="30_dias"`

#### `generate_workout_plan`
- **Descrição**: Orienta a IA a criar um plano semanal de treinos e descanso adaptado ao histórico de atividades do utilizador.
- **Parâmetros**:
  - `fitness_goal` (string, opcional, padrão: `"fitness_geral"`): Objetivo de treino pretendido.
- **Exemplos de Valores de Parâmetro**: `"hipertrofia"`, `"perda_peso"`, `"resistencia"`
- **Exemplos de Utilização no Cliente de IA**:
  - `/generate_workout_plan fitness_goal="hipertrofia"`
  - `/generate_workout_plan fitness_goal="perda_peso"`

#### `give_coaching_feedback`
- **Descrição**: Orienta a IA a fornecer comentários e recomendações práticas diárias sobre o nível de atividade física e qualidade de sono.
- **Parâmetros**:
  - `date` (string, opcional, padrão: `"mais_recente"`): Data alvo para avaliação.
- **Exemplos de Valores de Parâmetro**: `"hoje"`, `"mais_recente"`, `"2026-08-05"`
- **Exemplos de Utilização no Cliente de IA**:
  - `/give_coaching_feedback date="hoje"`
  - `/give_coaching_feedback date="2026-08-05"`