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 projet expose trois outils :

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

Le stockage des credentials repose sur **KDE Wallet** via **D-Bus**. La V1 cible Linux avec session KDE Wallet disponible.

## Sommaire

- [Prérequis](#prérequis)
- [Configuration](#configuration)
  - [Étape 1 : enregistrer les credentials](#étape-1--enregistrer-les-credentials)
  - [Étape 2 : lancer le serveur MCP](#étape-2--lancer-le-serveur-mcp)
- [Installation](#installation)
  - [Claude Code CLI](#claude-code-cli)
  - [Configuration JSON manuelle](#configuration-json-manuelle)
- [Compiler depuis les sources](#compiler-depuis-les-sources)
- [Outils](#outils)
  - [list_mailboxes](#list_mailboxes)
  - [list_messages](#list_messages)
  - [get_message](#get_message)

## Prérequis

- Linux
- une session D-Bus utilisateur active
- KDE Wallet accessible sur cette session
- Go 1.25+
- un compte IMAP fonctionnel

## Configuration

### Étape 1 : enregistrer les credentials

Le setup est interactif :

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

Le binaire demande ensuite :

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

Les credentials sont stockés dans KDE Wallet sous le profil `default`.

Si KDE Wallet n'est pas disponible, le setup échoue explicitement et n'écrit rien ailleurs.

### Étape 2 : lancer le serveur MCP

Le serveur MCP s'exécute sur `stdin/stdout` avec le handshake MCP standard :

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

Si aucun credential n'a été configuré, le serveur renvoie l'erreur :

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

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

Le `setup` doit être exécuté une fois séparément avant d'utiliser le serveur.

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

Exemple pour démarrer en `v1.0` :

```sh
git tag v1.0
git push origin v1.0
```

Le workflow build alors `email-mcp` pour `linux/amd64` et joint le binaire `build/email-mcp-linux-amd64` comme asset de la release.

## Compiler depuis les sources

```sh
make build
```

Le binaire est généré dans `build/email-mcp-<goos>-<goarch>`.

Pour cross-compiler :

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

Pour lancer les tests :

```sh
make test
```

## Outils

### list_mailboxes

Liste les boîtes IMAP visibles pour le compte configuré. Aucun paramètre.

### list_messages

Liste les messages récents d'une boîte.

| Paramètre | Type | Description |
|---|---|---|
| `mailbox` | string | **Requis.** Nom de la boîte IMAP |
| `limit` | number | Nombre maximum de messages à retourner. Par défaut : `20` |

Retourne des résumés de messages avec un `uid` IMAP stable, le sujet et l'expéditeur.

### get_message

Récupère un message précis à partir de sa boîte et de son UID IMAP.

| Paramètre | Type | Description |
|---|---|---|
| `mailbox` | string | **Requis.** Nom de la boîte IMAP |
| `uid` | number | **Requis.** UID IMAP du message |

Retourne :

- les métadonnées du message
- les headers dans l'ordre d'origine
- un body texte décodé de manière conservative pour les contenus MIME courants