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`
- 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 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. `default`

Les credentials IMAP sont résolus ensuite via le résolveur multi-sources du framework (RC3) :

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.

### 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 pointe vers l’endpoint Gitea :

```toml
[update]
source_name = "email-mcp releases"
base_url = "https://gitea.lclr.dev"
latest_release_url = "https://gitea.lclr.dev/api/v1/repos/AI/email-mcp/releases/latest"
```

## 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.

## Installation

### 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`
- `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
```