# Serveur MCP

Le serveur MCP donne à un agent conversationnel treize outils pour piloter VaEmail. Il
n'a aucune dépendance : Node 18 et rien d'autre. Un paquet qu'un agent installe seul ne
devrait pas tirer un arbre de dépendances derrière lui, et devrait pouvoir se lire en
entier avant qu'on lui confie une clé d'API.

## Installation

Avec Claude Code :

```
claude mcp add vaemail --env VAEMAIL_API_KEY=swm_votre_cle -- npx -y vaemail mcp
```

Avec n'importe quel client MCP :

```json
{
  "mcpServers": {
    "vaemail": {
      "command": "npx",
      "args": ["-y", "vaemail", "mcp"],
      "env": { "VAEMAIL_API_KEY": "swm_votre_cle" }
    }
  }
}
```

Variables lues : `VAEMAIL_API_KEY`, et `VAEMAIL_BASE_URL` pour pointer ailleurs que la
production.

## Les outils

| Outil | Ce qu'il fait |
| --- | --- |
| `vaemail_capabilities` | Ce que le service sait faire. Sans clé. |
| `vaemail_send_email` | Met un email en file, rend son identifiant. |
| `vaemail_validate_email` | Essai à blanc : dit si l'envoi passerait. N'envoie rien. |
| `vaemail_get_message` | Statut de remise et événements d'un message. |
| `vaemail_list_messages` | Messages récents, filtrés. |
| `vaemail_list_domains` | Domaines d'envoi et état de leur authentification. |
| `vaemail_create_domain` | Déclare un domaine, rend les enregistrements DNS. |
| `vaemail_verify_domain` | Relit le DNS et dit ce qui est authentifié. |
| `vaemail_dns_requirements` | Ce qui manque à un domaine déclaré. |
| `vaemail_diagnose_deliverability` | Pourquoi le courrier arrive mal, et quoi faire. |
| `vaemail_list_bounces` | Adresses sorties du circuit, et pourquoi. |
| `vaemail_get_usage` | Quota, plafond de la clé, ce qu'il reste. |
| `vaemail_get_audit_log` | Ce que cette clé a fait. |

Les outils de lecture portent l'annotation `readOnlyHint`, ce qui permet à un agent de
savoir lesquels il peut appeler sans demander la permission.

## Ce que le serveur dit à l'agent

Les instructions renvoyées à l'initialisation tiennent en quatre phrases, et elles
comptent autant que les outils :

- un envoi est accepté, pas remis ; l'issue se lit sur `vaemail_get_message` ;
- avant le premier envoi réel, passer par `vaemail_validate_email` ;
- quand le courrier arrive mal, appeler `vaemail_diagnose_deliverability` plutôt que de
  supposer ;
- publier des enregistrements DNS et payer un abonnement sont des étapes humaines : les
  signaler, jamais les déclarer faites.

## Erreurs

Une erreur de l'API ne remonte pas comme un échec de transport, mais comme un résultat
d'outil marqué en erreur, avec le code, l'action corrective et la mention de ce qui peut
être retenté. L'agent voit le motif et peut corriger, au lieu de recevoir un échec opaque.

Exemple de ce que reçoit l'agent :

```
RECIPIENT_SUPPRESSED: Destinataire dans la liste de suppression.
Action corrective : remove_from_suppression_list (/v3/smtp/blockedContacts)
Réessayer à l'identique ne changera rien.
```

## Ligne de commande

Le même paquet fournit `vaemail`, utile pour vérifier une configuration ou pour un agent
qui exécute des commandes plutôt que d'appeler des outils.

```
vaemail init
vaemail doctor
vaemail send --to client@exemple.fr --subject Bonjour --html '<p>Salut</p>'
vaemail status 2841
```

`--json` sur n'importe quelle commande donne une sortie exploitable par un programme.