docs: expand readme and add makefile
This commit is contained in:
thibaud-leclere
parent
aa459db435
commit
35a38f52a0
2 changed files with 159 additions and 14 deletions
24
Makefile
Normal file
24
Makefile
Normal file
|
|
@ -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 ./...
|
||||
149
README.md
149
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue