# mail-mcp — assistant mail personnel via IA locale + serveur MCP

Projet en 3 parties, conforme au sujet:

1. **Collecte de donnees externes, sans IA** ([src/email_client.py](src/email_client.py))
   Connexion IMAP a une vraie boite mail (Gmail, Outlook, ou tout fournisseur IMAP),
   recuperation des derniers mails, sauvegarde en JSON brut dans `data/raw/`.

2. **Structuration des donnees via IA** ([src/ai_structurer.py](src/ai_structurer.py))
   Chaque mail brut est envoye a un modele qui tourne **en local dans Ollama**
   (via le client `openai-python`, pointe sur l'API compatible OpenAI d'Ollama),
   avec une sortie JSON strictement contrainte par un schema
   ([src/schema.py](src/schema.py)) pour extraire un maximum d'informations:
   categorie, resume, sentiment, priorite, actions a faire (avec echeance),
   personnes/organisations/lieux cites, dates mentionnees, montants (avec devise
   et contexte), liens, tags, langue, caractere automatique/newsletter, etc.
   Le contenu des mails ne quitte jamais la machine: seul Ollama y a acces.

3. **Serveur MCP** ([src/mcp_server.py](src/mcp_server.py))
   Expose les mails structures a n'importe quel client MCP (Claude Desktop, un
   autre agent...) via 5 outils: `list_emails`, `get_email`, `search_emails`,
   `get_action_items`, `get_stats`. Transport `streamable-http`, deployable avec
   une URL publique, protege par un token Bearer.

```
Boite mail (IMAP)  -->  data/raw/*.json  -->  IA locale (Ollama)  -->  data/structured/emails.jsonl  -->  Serveur MCP (public)
   partie 1 (sans IA)                            partie 2                                                    partie 3
```

## Installation

```bash
cd mail-mcp
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt
cp .env.example .env
```

Remplis `.env`:
- `IMAP_*`: identifiants de ta boite mail. Pour Gmail, active la validation en
  2 etapes puis cree un "mot de passe d'application" (myaccount.google.com/apppasswords)
  — n'utilise jamais ton mot de passe principal.
- `OLLAMA_MODEL`: un modele deja present en local (`ollama list`), par exemple
  `qwen2.5:7b-instruct`.
- `MCP_AUTH_TOKEN`: un token que tu inventes, pour proteger le serveur MCP une
  fois deploye (les donnees servies sont personnelles).

Verifie qu'Ollama tourne (`ollama serve`, generalement deja lance en arriere-plan
sous Windows) et que le modele choisi est bien telecharge (`ollama pull qwen2.5:7b-instruct`).

## Utilisation

Recuperer les nouveaux mails et les structurer avec l'IA locale:

```bash
python -m src.pipeline
```

Le script est idempotent: relance-le plus tard, il ne retelecharge et ne
re-structure que ce qui est nouveau (base sur le Message-ID IMAP). Pas besoin
de cron: un import initial suffit, et tu peux relancer la commande a la main
quand tu veux mettre a jour les donnees.

Lancer le serveur MCP en local (http://localhost:8000/mcp):

```bash
python -m src.mcp_server
```

Le tester avec l'inspecteur MCP officiel:

```bash
npx @modelcontextprotocol/inspector
```

## Deploiement (URL publique pour le MCP)

Le serveur MCP (partie 3) doit etre accessible en ligne. La collecte (partie 1)
et la structuration IA (partie 2) restent locales par design (l'IA tourne sur
ta machine) — seules les donnees deja structurees sont servies publiquement.

1. Construit et pousse l'image Docker vers la plateforme de ton choix (Render,
   Railway, Fly.io...). Le `Dockerfile` fourni ne contient **aucune donnee mail
   personnelle** (le dossier `data/` est vide dans l'image, et `data/` est dans
   `.gitignore`) — seul le code est publie.
2. Configure les variables d'environnement sur la plateforme: `MCP_AUTH_TOKEN`
   (obligatoire pour un deploiement public), `OLLAMA_*` (non utilises par le
   serveur MCP lui-meme, seulement par le pipeline local).
3. Une fois deploye, pousse tes donnees structurees locales vers l'instance
   deployee:

```bash
python scripts/upload_data.py https://ton-serveur.exemple.com
```

   A refaire apres chaque `python -m src.pipeline` local pour garder le serveur
   distant a jour (l'upload remplace `data/structured/emails.jsonl` cote serveur).

4. Un client MCP (Claude Desktop, etc.) se connecte alors a
   `https://ton-serveur.exemple.com/mcp` avec le header
   `Authorization: Bearer <MCP_AUTH_TOKEN>`.

## Tests

```bash
pip install -r requirements-dev.txt
python -m pytest tests/ -v
```

`tests/test_ai_structurer.py` fait un vrai appel a Ollama en local (saute
automatiquement si aucun serveur Ollama n'est joignable, par ex. en CI).

## Limitations connues

- **Stockage JSONL**: les donnees structurees sont dans un fichier JSONL unique,
  relu integralement a chaque appel MCP. Suffisant pour quelques milliers de mails;
  au-dela, envisager une base (SQLite, PostgreSQL).
- **Filesystem ephemere (PaaS)**: sur Render/Railway le disque est reinitialise a
  chaque deploy — les donnees doivent etre repoussees via `scripts/upload_data.py`.
- **Traitement sequentiel Ollama**: les mails sont envoyes un par un a l'IA locale.
  Un traitement parallele (asyncio) accelererait les gros imports.
- **Double representation du schema**: le JSON Schema (pour Ollama) et le modele
  Pydantic (pour la validation Python) sont definis separement dans `schema.py`.
  Ils doivent rester synchronises manuellement.

## Structure du projet

```
mail-mcp/
  src/
    config.py          configuration (.env)
    schema.py           schema JSON + modeles Pydantic de la donnee structuree
    email_client.py      partie 1: IMAP -> JSON brut
    ai_structurer.py     partie 2: IA locale -> JSON structure
    pipeline.py           CLI qui enchaine les deux
    mcp_server.py         partie 3: serveur MCP (streamable-http)
  scripts/
    upload_data.py         pousse les donnees locales vers le serveur deploye
  data/
    raw/                    mails bruts (JSON, non commite)
    structured/             mails structures (JSONL, non commite)
  tests/
  Dockerfile
```