From 35a38f52a0addb3f3d2c59095a7e37954da92b60 Mon Sep 17 00:00:00 2001
From: thibaud-leclere <thibaud.leclere@lundimatin.fr>
Date: Fri, 10 Apr 2026 14:31:38 +0200
Subject: [PATCH] docs: expand readme and add makefile

---
 Makefile  |  24 +++++++++
 README.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 159 insertions(+), 14 deletions(-)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..c9c5f03
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,24 @@
+BINARY_NAME := email-mcp
+BUILD_DIR   := build
+GOCACHE     ?= /tmp/$(BINARY_NAME)-gocache
+
+GOOS   ?= $(shell go env GOOS)
+GOARCH ?= $(shell go env GOARCH)
+
+ifeq ($(GOOS),windows)
+	EXT := .exe
+else
+	EXT :=
+endif
+
+OUTPUT := $(BUILD_DIR)/$(BINARY_NAME)-$(GOOS)-$(GOARCH)$(EXT)
+
+.PHONY: build test
+
+build:
+	@mkdir -p $(BUILD_DIR) $(GOCACHE)
+	GOCACHE=$(GOCACHE) GOOS=$(GOOS) GOARCH=$(GOARCH) go build -o $(OUTPUT) ./cmd/email-mcp
+
+test:
+	@mkdir -p $(GOCACHE)
+	GOCACHE=$(GOCACHE) go test ./...
diff --git a/README.md b/README.md
index 9905a3e..e468d22 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,145 @@
 # email-mcp
 
-`email-mcp` is a local Go CLI for configuring one IMAP account in KDE Wallet and exposing read-only mailbox access over MCP.
+Serveur MCP local pour lire une boîte mail via IMAP. Le projet expose trois outils :
 
-## Requirements
+- **`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
-- A D-Bus session with KDE Wallet available
-- Go 1.25 or newer
-- IMAP account credentials
+- une session D-Bus utilisateur active
+- KDE Wallet accessible sur cette session
+- Go 1.25+
+- un compte IMAP fonctionnel
 
-## Commands
+## Configuration
 
-- `email-mcp setup` to store IMAP credentials
-- `email-mcp mcp` to start the MCP stdio server
+### Étape 1 : enregistrer les credentials
 
-If you build the binary locally from this repo, run it as `./email-mcp` from the project root.
+Le setup est interactif :
 
-## Build and Test
-
-```bash
-go test ./...
-go build ./cmd/email-mcp
+```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` :
+
+```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"]
+    }
+  }
+}
+```
+
+## 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