168 lines
3.8 KiB
Markdown
168 lines
3.8 KiB
Markdown
# 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 config` : configure un profil IMAP
|
||
- `email-mcp setup` : alias de compatibilité vers `config`
|
||
- `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
|
||
|
||
## 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`
|
||
|
||
### Configurer un profil
|
||
|
||
```sh
|
||
./email-mcp config
|
||
```
|
||
|
||
Pour un profil nommé :
|
||
|
||
```sh
|
||
./email-mcp config --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 config`
|
||
```
|
||
|
||
## 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 config`.
|
||
|
||
### 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
|
||
```
|