email-mcp/README.md

# email-mcp

Serveur MCP local pour lire une boîte mail via IMAP. Le serveur parle le protocole MCP standard sur `stdio`, avec des messages **JSON-RPC 2.0** (`initialize`, `notifications/initialized`, `tools/list`, `tools/call`).

Le binaire s’appuie maintenant sur [`mcp-framework`](../mcp-framework) pour :

- la gestion de profils CLI
- le stockage JSON de configuration dans `os.UserConfigDir()`
- le stockage du mot de passe dans le wallet natif de l’OS
- le manifeste `mcp.toml`
- les helpers Go générés depuis `mcp.toml` (`mcpgen/`)
- l’auto-update via `email-mcp update`

## Commandes

- `email-mcp setup` : configure (ou met à jour) un profil IMAP
- `email-mcp config show` : affiche la configuration IMAP résolue et la provenance
- `email-mcp config test` : lance les checks de configuration/connectivité (équivalent de `doctor`)
- `email-mcp config delete` : supprime un profil local et son mot de passe stocké
- `email-mcp mcp` : lance le serveur MCP sur `stdin/stdout`
- `email-mcp doctor` : diagnostique la configuration locale, le wallet, le manifeste et l’accès IMAP
- `email-mcp update` : met à jour le binaire courant depuis la dernière release
- `email-mcp version` : affiche la version du binaire

La commande `email-mcp help` (ou `-h` / `--help`) affiche l’aide globale.

## Outils MCP

- `list_mailboxes` : lister les boîtes IMAP visibles
- `list_messages` : lister les messages récents d’une boîte
- `get_message` : récupérer un message par UID IMAP

## Configuration

La configuration est séparée en deux parties :

- `host` et `username` sont stockés dans `config.json`
- `password` est stocké dans le wallet système

Le profil actif est résolu dans cet ordre :

1. `--profile`
2. `EMAIL_MCP_PROFILE`
3. `current_profile` dans `config.json`
4. `[profiles].default` dans `mcp.toml`
5. `default`

Les credentials IMAP sont résolus ensuite via les champs `[[config.fields]]` du manifeste et les helpers générés par le framework :

1. `host` : `EMAIL_MCP_HOST` puis `config.json`
2. `username` : `EMAIL_MCP_USERNAME` puis `config.json`
3. `password` : `EMAIL_MCP_PASSWORD` puis secret wallet `imap-password/<profile>`

### Configurer un profil

```sh
./email-mcp setup
```

Pour un profil nommé :

```sh
./email-mcp setup --profile work
```

Le binaire demande ensuite :

1. l’hôte IMAP
2. le nom d’utilisateur
3. le mot de passe

Si un mot de passe existe déjà dans le wallet, laisser le champ vide le conserve.

Si le backend de secrets est en lecture seule (`[secret_store].backend_policy = "env-only"`), `setup` ne peut pas persister le mot de passe dans un wallet. Dans ce cas, exporte `EMAIL_MCP_PASSWORD` avant `setup`. La commande sauvegarde alors `host`/`username` et utilise le mot de passe depuis l’environnement.

### Lancer le serveur MCP

```sh
./email-mcp mcp
```

Pour un profil nommé :

```sh
./email-mcp mcp --profile work
```

Si aucun credential n’a été configuré pour le profil résolu, le serveur renvoie l’erreur :

```text
credentials not configured; run `email-mcp setup`
```

### Inspecter la configuration résolue

```sh
./email-mcp config show
./email-mcp config show --profile work
```

### Tester la configuration résolue

```sh
./email-mcp config test
./email-mcp config test --profile work
```

## Auto-update

`email-mcp update` lit `mcp.toml` depuis le répertoire du binaire courant, puis remonte les répertoires parents. Si aucun manifeste n’est trouvé, la commande échoue.

```sh
./email-mcp update
```

Le manifeste de ce repo utilise le driver Gitea du framework :

```toml
binary_name = "email-mcp"

[update]
source_name = "email-mcp releases"
driver = "gitea"
repository = "AI/email-mcp"
base_url = "https://gitea.lclr.dev"
asset_name_template = "{binary}-{os}-{arch}{ext}"
checksum_asset_name = "{asset}.sha256"
checksum_required = true
token_env_names = ["GITEA_TOKEN"]
```

## Diagnostic

`email-mcp doctor` vérifie :

- la lisibilité du fichier de configuration
- le profil IMAP résolu
- la disponibilité du wallet système
- la présence du mot de passe stocké
- la validité du manifeste `mcp.toml`
- la connectivité IMAP avec les credentials résolus

```sh
./email-mcp doctor
./email-mcp doctor --profile work
```

La commande retourne un code de sortie non nul si au moins un check échoue.

Pour l’update, la validation du manifeste accepte :

- soit `update.latest_release_url`
- soit un couple driver/référentiel (`update.driver`, `update.repository`) avec les champs requis (ex. `update.base_url` pour Gitea)

## Installation

### Installateur interactif

Le repo inclut un assistant interactif `install.sh` :

```sh
./install.sh
```

Tu peux aussi l’exécuter directement depuis la branche `main` :

```sh
curl -fsSL https://gitea.lclr.dev/AI/email-mcp/raw/branch/main/install.sh | bash
```

### Claude Code CLI

Ajoute le serveur MCP en pointant vers le binaire et la sous-commande `mcp` :

```sh
claude mcp add email-mcp -- /absolute/path/to/bin/email-mcp mcp
```

La configuration se fait une fois séparément via `email-mcp setup`.

### Configuration JSON manuelle

Ajoute le bloc suivant à ta configuration MCP (`~/.claude.json` côté utilisateur, ou `.mcp.json` dans un projet) :

```json
{
  "mcpServers": {
    "email-mcp": {
      "command": "/absolute/path/to/bin/email-mcp",
      "args": ["mcp"]
    }
  }
}
```

## Releases

Une release est générée automatiquement quand tu pousses un tag `v*` sur le repo Gitea.

Les assets publiés sont :

- `build/email-mcp-linux-amd64`
- `build/email-mcp-linux-amd64.sha256`
- `mcp.toml`

## Compiler depuis les sources

```sh
make build
```

Le binaire est généré dans `build/email-mcp-<goos>-<goarch>` avec une version injectée depuis `git describe`.

Pour cross-compiler :

```sh
make build GOOS=windows GOARCH=amd64
```

Pour lancer les tests :

```sh
make test
```

Pour régénérer la glue framework après une modification de `mcp.toml` :

```sh
make generate
make generate-check
```