@zendou/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Souleymane Diallo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @zendou/mcp
+
+Serveur MCP (Model Context Protocol) pour [Zendou](https://zendou.app), le service d'email
+transactionnel pour la Guinée. Il permet à votre assistant IA (Claude Desktop, Claude Code,
+Cursor, tout client MCP) d'envoyer un email, de consulter votre solde de crédits, de relire le
+journal des envois et de vérifier l'état de vos domaines.
+
+Le serveur tourne **sur votre machine**, avec votre clé API Zendou. Il ne fait que traduire les
+demandes de l'assistant en appels à l'API publique de Zendou : toutes les règles restent
+appliquées par le backend.
+
+## Installation
+
+Aucune installation n'est nécessaire : le client MCP lance le serveur avec `npx`.
+Prérequis : Node.js 18 ou plus.
+
+```bash
+npx -y @zendou/mcp
+```
+
+Le serveur parle MCP sur l'entrée et la sortie standard : lancé à la main, il attend simplement
+des messages. Ses journaux sont écrits sur la sortie d'erreur.
+
+## Variables d'environnement
+
+| Variable | Rôle |
+|---|---|
+| `ZENDOU_API_KEY` | Votre clé API Zendou (`zd_live_...`). Sans elle, le serveur démarre, mais chaque outil répond par une erreur qui explique comment la configurer. |
+| `ZENDOU_API_URL` | Adresse de l'API, facultative. Par défaut `https://api.zendou.app` (sans `/v1`, un slash final est toléré). |
+
+## Créer une clé API
+
+1. Connectez-vous au tableau de bord Zendou, menu **Clés API**.
+2. Créez une clé. Pour que l'assistant puisse lire le journal des envois et les domaines,
+   cochez **Autoriser la lecture**. Sans cette case, la clé ne permet que d'envoyer des emails
+   et de lire le solde.
+3. Copiez la clé : elle n'est affichée qu'une fois.
+
+La permission de lecture se choisit à la création et ne peut pas être ajoutée ensuite : si
+vous avez oublié la case, créez une nouvelle clé.
+
+## Configuration des clients
+
+Formats vérifiés le 23/10/2026 aux documentations officielles. Remplacez `zd_live_VOTRE_CLE`
+par votre clé.
+
+### Claude Desktop
+
+Dans le menu **Claude** de la barre de menus du système (pas dans les réglages de la fenêtre),
+choisissez **Settings...**, onglet **Developer**, puis le bouton **Edit Config**. Le fichier
+`claude_desktop_config.json` se trouve à :
+
+- macOS : `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows : `%APPDATA%\Claude\claude_desktop_config.json`
+
+Ajoutez :
+
+```json
+{
+  "mcpServers": {
+    "zendou": {
+      "command": "npx",
+      "args": ["-y", "@zendou/mcp"],
+      "env": { "ZENDOU_API_KEY": "zd_live_VOTRE_CLE" }
+    }
+  }
+}
+```
+
+Quittez complètement Claude Desktop, puis relancez-le. En cas de souci, consultez les journaux
+`mcp*.log` dans `~/Library/Logs/Claude` (macOS) ou `%APPDATA%\Claude\logs` (Windows).
+
+### Claude Code
+
+```bash
+claude mcp add --env ZENDOU_API_KEY=zd_live_VOTRE_CLE --transport stdio zendou -- npx -y @zendou/mcp
+```
+
+Les options de Claude Code viennent avant le nom du serveur, et `--` sépare la commande du
+serveur. Si une autre option suit `--env`, elle sépare `--env` du nom.
+
+Pour partager la configuration d'un projet, un fichier `.mcp.json` à la racine, au même format
+`mcpServers` (une entrée sans `type` est lue comme stdio). Il accepte `${VAR}` et
+`${VAR:-defaut}` dans `command`, `args` et `env` : la clé est lue dans votre environnement, ne
+la committez pas.
+
+```json
+{
+  "mcpServers": {
+    "zendou": {
+      "command": "npx",
+      "args": ["-y", "@zendou/mcp"],
+      "env": { "ZENDOU_API_KEY": "${ZENDOU_API_KEY}" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Fichier `.cursor/mcp.json` (dans le projet) ou `~/.cursor/mcp.json` (global), avec
+l'interpolation `${env:NOM}` :
+
+```json
+{
+  "mcpServers": {
+    "zendou": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@zendou/mcp"],
+      "env": { "ZENDOU_API_KEY": "${env:ZENDOU_API_KEY}" }
+    }
+  }
+}
+```
+
+## Outils
+
+| Outil | Rôle | Clé requise |
+|---|---|---|
+| `send_email` | Envoie un email (`from`, `to`, `subject`, `html`/`text`, `replyTo`, `headers`) | toute clé active |
+| `get_balance` | Solde de crédits | toute clé active |
+| `list_emails` | Journal des envois, avec filtres (`status`, `channel`, `from`, `to`, `q`) et pagination | clé avec lecture |
+| `get_email` | Détail et état de livraison d'un email | clé avec lecture |
+| `list_domains` | Domaines du compte et leur statut | clé avec lecture |
+| `get_domain` | Statut d'un domaine et enregistrements DNS à créer | clé avec lecture |
+
+Règles de `send_email` : un seul destinataire ; `Nom <adresse>` accepté (nom de 128 caractères
+au plus) ; domaine expéditeur vérifié ; `html` ou `text` requis ; `headers` limités à 20, parmi
+`List-Unsubscribe`, `List-Unsubscribe-Post` et `X-*` (hors `X-SES-*`), en ASCII imprimable.
+
+Le serveur n'écrit rien d'autre que l'envoi : il ne peut ni créer ni supprimer un domaine, une
+clé ou un identifiant SMTP, ni recharger des crédits.
+
+## Sécurité
+
+- **La clé reste sur votre machine.** Elle est lue dans l'environnement du processus, envoyée
+  uniquement à l'API Zendou, et n'apparaît jamais dans les journaux, les erreurs ou les réponses
+  d'outils.
+- **La lecture est facultative.** Elle se décide clé par clé, décochée par défaut. Une clé qui
+  fuit avec la lecture expose les destinataires et les sujets de vos emails : n'activez la
+  lecture que si vous en avez besoin, et préférez une clé dédiée à l'assistant.
+- **Portée par domaine.** Une clé limitée à certains domaines ne peut envoyer, ni lire, que
+  pour ces domaines ; le reste répond comme s'il n'existait pas.
+- **`ZENDOU_API_URL` reçoit votre clé.** Ne la renseignez que pour l'API Zendou, en `https://`.
+  Le serveur refuse `http://` sauf pour `localhost` et `127.0.0.1` (développement), n'accepte
+  pas les redirections et plafonne les réponses lues à 5 Mo.
+- Ne committez jamais une clé. En cas de doute, révoquez-la depuis le tableau de bord.
+
+## Développement
+
+```bash
+npm install
+npm run build       # compile vers dist/
+npm run typecheck
+npm run lint        # tsc + vérifications maison (scripts/lint.mjs)
+npm test            # build puis tests (node:test via tsx), dont un test stdio du binaire
+```
+
+## Licence
+
+MIT, voir [LICENSE](LICENSE).

package/dist/client.js

@@ -0,0 +1,177 @@
+export const DEFAULT_API_URL = 'https://api.zendou.app';
+export const DEFAULT_TIMEOUT_MS = 20_000;
+/** Taille maximale d'une réponse de l'API lue en mémoire. */
+export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+/** Erreur renvoyée à l'assistant : le message ne contient jamais la clé. */
+export class ZendouError extends Error {
+    status;
+    code;
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+        this.name = 'ZendouError';
+    }
+}
+/** Normalise l'URL de base : sans slash final et sans suffixe /v1. */
+export function normalizeApiUrl(raw) {
+    let url = (raw ?? '').trim() || DEFAULT_API_URL;
+    url = url.replace(/\/+$/, '');
+    url = url.replace(/\/v1$/, '');
+    return url;
+}
+/**
+ * Vérifie l'adresse de l'API. Renvoie un message d'erreur français si elle est
+ * inutilisable (sans schéma, ni http ni https, ou http hors localhost).
+ */
+export function checkApiUrl(baseUrl) {
+    const hint = 'Vérifiez la variable ZENDOU_API_URL.';
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return `L'adresse de l'API Zendou (« ${baseUrl} ») n'est pas valide : elle doit commencer par https://. ${hint}`;
+    }
+    if (parsed.protocol === 'https:')
+        return undefined;
+    if (parsed.protocol === 'http:') {
+        const host = parsed.hostname;
+        if (host === 'localhost' || host === '127.0.0.1')
+            return undefined;
+        return `L'adresse de l'API Zendou (${baseUrl}) utilise http:// : votre clé API serait envoyée en clair. Seul https:// est accepté, sauf pour localhost et 127.0.0.1. ${hint}`;
+    }
+    return `L'adresse de l'API Zendou (« ${baseUrl} ») n'est pas valide : elle doit commencer par https://. ${hint}`;
+}
+export class ZendouClient {
+    baseUrl;
+    urlError;
+    apiKey;
+    userAgent;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.apiKey = options.apiKey?.trim() || undefined;
+        this.baseUrl = normalizeApiUrl(options.apiUrl);
+        this.urlError = checkApiUrl(this.baseUrl);
+        this.userAgent = options.userAgent;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    get hasKey() {
+        return this.apiKey !== undefined;
+    }
+    /** Retire toute occurrence de la clé d'un texte. */
+    redact(text) {
+        return this.apiKey ? text.split(this.apiKey).join('[clé masquée]') : text;
+    }
+    async request(method, path, options = {}) {
+        if (!this.apiKey) {
+            throw new ZendouError(MISSING_KEY_MESSAGE);
+        }
+        if (this.urlError) {
+            throw new ZendouError(this.redact(this.urlError));
+        }
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(options.query ?? {})) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'User-Agent': this.userAgent,
+            Accept: 'application/json',
+        };
+        const init = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.timeoutMs),
+            redirect: 'error',
+        };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, init);
+        }
+        catch (err) {
+            const name = err instanceof Error ? err.name : '';
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new ZendouError(`L'API Zendou n'a pas répondu en ${Math.round(this.timeoutMs / 1000)} secondes (${this.baseUrl}). Réessayez dans un instant.`);
+            }
+            throw new ZendouError(this.redact(`Impossible de joindre l'API Zendou (${this.baseUrl}). Vérifiez votre connexion et la variable ZENDOU_API_URL.`));
+        }
+        const tooBig = () => new ZendouError(`La réponse de l'API Zendou dépasse ${MAX_RESPONSE_BYTES / (1024 * 1024)} Mo : elle est refusée. Vérifiez la variable ZENDOU_API_URL.`, response.status);
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+            void response.body?.cancel().catch(() => undefined);
+            throw tooBig();
+        }
+        let raw;
+        try {
+            raw = await readLimited(response, tooBig);
+        }
+        catch (err) {
+            if (err instanceof ZendouError)
+                throw err;
+            throw new ZendouError(`Lecture de la réponse de l'API Zendou interrompue (${this.baseUrl}). Réessayez dans un instant.`);
+        }
+        let data;
+        try {
+            data = raw ? JSON.parse(raw) : undefined;
+        }
+        catch {
+            data = undefined;
+        }
+        if (!response.ok) {
+            throw this.toError(response, data);
+        }
+        if (data === undefined) {
+            throw new ZendouError(`Réponse inattendue de l'API Zendou (HTTP ${response.status}) : le corps n'est pas du JSON.`, response.status);
+        }
+        return data;
+    }
+    toError(response, data) {
+        const body = (data && typeof data === 'object' ? data : {});
+        const rawMessage = typeof body.message === 'string' ? body.message : undefined;
+        const errors = Array.isArray(body.errors)
+            ? body.errors.filter((e) => typeof e === 'string')
+            : [];
+        let message = rawMessage ?? errors[0] ?? `Erreur HTTP ${response.status}.`;
+        // Le backend garantit message === errors.join(' ') : on n'ajoute que ce que message ne contient pas.
+        const extra = errors.filter((e) => !message.includes(e));
+        if (extra.length > 0)
+            message += ` (${extra.join(' ; ')})`;
+        const code = typeof body.code === 'string' ? body.code : undefined;
+        const retryAfter = response.headers.get('retry-after') ?? undefined;
+        return new ZendouError(this.redact(message), response.status, code, retryAfter);
+    }
+}
+/** Lit le corps en flux et s'arrête dès que le plafond est dépassé. */
+async function readLimited(response, tooBig) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > MAX_RESPONSE_BYTES) {
+            await reader.cancel().catch(() => undefined);
+            throw tooBig();
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export const MISSING_KEY_MESSAGE = "La clé API Zendou n'est pas configurée. Créez une clé dans le tableau de bord Zendou (Clés API), " +
+    'puis renseignez-la dans la variable d\'environnement ZENDOU_API_KEY de la configuration MCP de votre assistant ' +
+    '(bloc "env" du serveur zendou), et redémarrez l\'assistant. Pour lire le journal et les domaines, ' +
+    'cochez « Autoriser la lecture » à la création de la clé.';

package/dist/format.js

@@ -0,0 +1,117 @@
+import { ZendouError } from './client.js';
+const str = (v) => (v === null || v === undefined || v === '' ? '-' : String(v));
+const STATUS_LABELS = {
+    QUEUED: "en file d'attente",
+    SENT: 'envoyé',
+    DELIVERED: 'délivré',
+    BOUNCED: 'rejeté par le destinataire (rebond)',
+    COMPLAINED: 'signalé comme indésirable',
+    REJECTED: 'refusé',
+    FAILED: 'échec',
+    SUPPRESSED: 'supprimé (adresse sur liste de suppression)',
+};
+function statusLabel(s) {
+    const key = String(s);
+    return STATUS_LABELS[key] ? `${key} (${STATUS_LABELS[key]})` : str(s);
+}
+export function formatSend(r) {
+    return `Email accepté pour envoi.\nIdentifiant : ${str(r.id)}\nStatut : ${statusLabel(r.status)}\nUtilisez get_email avec cet identifiant pour suivre la livraison (clé avec lecture requise).`;
+}
+export function formatBalance(r) {
+    return [
+        `Crédits disponibles : ${str(r.balance)}`,
+        `Total acheté : ${str(r.totalPurchased)}`,
+        `Total offert : ${str(r.totalGifted)}`,
+        `Total consommé : ${str(r.totalConsumed)}`,
+    ].join('\n');
+}
+export function formatEmailList(r) {
+    const items = Array.isArray(r.items) ? r.items : [];
+    const head = `${str(r.total)} email(s) au total, page ${str(r.page)} sur ${str(r.totalPages)} (${str(r.limit)} par page).`;
+    if (items.length === 0)
+        return `${head}\nAucun email ne correspond.`;
+    const lines = items.map((e) => `- ${str(e.publicId)} | ${statusLabel(e.status)} | de ${str(e.fromAddress)} à ${str(e.toAddress)} | « ${str(e.subject)} » | canal ${str(e.channel)} | mis en file ${str(e.queuedAt)} | dernier événement ${str(e.lastEventAt)}`);
+    return `${head}\n${lines.join('\n')}`;
+}
+export function formatEmail(e) {
+    const lines = [
+        `Email ${str(e.publicId)}`,
+        `Statut : ${statusLabel(e.status)}`,
+        `De : ${str(e.fromAddress)}`,
+        `À : ${str(e.toAddress)}`,
+        `Sujet : ${str(e.subject)}`,
+        `Canal : ${str(e.channel)}`,
+        `Mis en file : ${str(e.queuedAt)}`,
+        `Envoyé : ${str(e.sentAt)}`,
+        `Délivré : ${str(e.deliveredAt)}`,
+        `Dernier événement : ${str(e.lastEventAt)}`,
+    ];
+    if (e.errorMessage)
+        lines.push(`Message d'erreur : ${str(e.errorMessage)}`);
+    if (e.sesMessageId)
+        lines.push(`Identifiant SES : ${str(e.sesMessageId)}`);
+    if (e.smtpCredentialId)
+        lines.push(`Identifiant SMTP : ${str(e.smtpCredentialId)}`);
+    return lines.join('\n');
+}
+export function formatDomainList(r) {
+    const items = Array.isArray(r) ? r : [];
+    if (items.length === 0)
+        return 'Aucun domaine enregistré sur ce compte (ou aucun dans la portée de cette clé).';
+    const lines = items.map((d) => `- ${str(d.name)} | id ${str(d.id)} | statut ${str(d.status)} | vérifié le ${str(d.verifiedAt)} | créé le ${str(d.createdAt)}`);
+    return `${items.length} domaine(s) :\n${lines.join('\n')}`;
+}
+function formatRecords(title, records, withPurpose) {
+    const list = Array.isArray(records) ? records : [];
+    if (list.length === 0)
+        return [`${title} : aucun.`];
+    const out = [`${title} :`];
+    for (const r of list) {
+        const prio = r.priority !== undefined && r.priority !== null ? `, priorité ${str(r.priority)}` : '';
+        out.push(`- Type ${str(r.type)}, nom ${str(r.name)}${prio}`);
+        out.push(`  Valeur : ${str(r.value)}`);
+        if (withPurpose) {
+            if (r.purpose)
+                out.push(`  Rôle : ${str(r.purpose)}`);
+            if (r.note)
+                out.push(`  Note : ${str(r.note)}`);
+        }
+    }
+    return out;
+}
+export function formatDomain(d) {
+    const lines = [
+        `Domaine ${str(d.name)} (id ${str(d.id)})`,
+        `Statut : ${str(d.status)}`,
+        `Vérifié le : ${str(d.verifiedAt)}`,
+        `Créé le : ${str(d.createdAt)}`,
+        `Domaine MAIL FROM : ${str(d.mailFromDomain)} (statut ${str(d.mailFromStatus)})`,
+        ...formatRecords('Enregistrements DNS requis (DKIM)', d.dkimRecords, false),
+        ...formatRecords('Enregistrements DNS recommandés', d.recommendedRecords, true),
+    ];
+    return lines.join('\n');
+}
+const READ_HELP = 'Pour utiliser cet outil, créez une nouvelle clé API dans le tableau de bord Zendou (menu Clés API) en cochant « Autoriser la lecture », ' +
+    'puis mettez-la dans ZENDOU_API_KEY. La lecture se choisit à la création de la clé et ne peut pas être ajoutée ensuite.';
+/** Transforme une erreur en texte d'erreur d'outil lisible, en français. */
+export function describeError(err) {
+    if (!(err instanceof ZendouError)) {
+        return 'Erreur inattendue dans le serveur MCP Zendou. Réessayez ; si le problème persiste, signalez-le.';
+    }
+    if (err.status === undefined)
+        return err.message;
+    const parts = [`Erreur Zendou (HTTP ${err.status}${err.code ? `, code ${err.code}` : ''}) : ${err.message}`];
+    if (err.status === 403 && /lecture/i.test(err.message) && !err.code)
+        parts.push(READ_HELP);
+    if (err.status === 429) {
+        const n = Number(err.retryAfter);
+        parts.push(err.retryAfter !== undefined && Number.isFinite(n)
+            ? `Trop de requêtes : réessayez dans ${n} seconde(s).`
+            : 'Trop de requêtes : patientez un moment avant de réessayer.');
+    }
+    if (err.status === 401)
+        parts.push('Vérifiez ZENDOU_API_KEY : la clé est peut-être erronée ou révoquée.');
+    if (err.status === 402)
+        parts.push('Rechargez vos crédits depuis le tableau de bord Zendou.');
+    return parts.join('\n');
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ZendouClient } from './client.js';
+import { createServer, VERSION } from './server.js';
+async function main() {
+    const client = new ZendouClient({
+        apiKey: process.env.ZENDOU_API_KEY,
+        apiUrl: process.env.ZENDOU_API_URL,
+        userAgent: `zendou-mcp/${VERSION}`,
+    });
+    if (!client.hasKey) {
+        console.error('[zendou-mcp] ZENDOU_API_KEY absente : les outils renverront une erreur de configuration.');
+    }
+    await createServer(client).connect(new StdioServerTransport());
+    console.error(`[zendou-mcp] démarré (v${VERSION}, API ${client.baseUrl}).`);
+}
+main().catch((err) => {
+    console.error('[zendou-mcp] arrêt sur erreur :', err instanceof Error ? err.message : 'inconnue');
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,119 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { describeError, formatBalance, formatDomain, formatDomainList, formatEmail, formatEmailList, formatSend, } from './format.js';
+export const VERSION = '0.1.0';
+async function run(client, fn) {
+    try {
+        return { content: [{ type: 'text', text: client.redact(await fn()) }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: client.redact(describeError(err)) }], isError: true };
+    }
+}
+const READ_NOTE = " Nécessite une clé API créée avec « Autoriser la lecture » ; sinon l'API répond 403.";
+export function createServer(client) {
+    const server = new McpServer({ name: 'zendou', version: VERSION });
+    server.registerTool('send_email', {
+        title: 'Envoyer un email',
+        description: 'Envoie un email transactionnel via Zendou. Règles : un seul destinataire dans `to` (une adresse). ' +
+            "`from` et `to` acceptent `adresse@domaine.com` ou `Nom <adresse@domaine.com>` (nom d'affichage de 128 caractères au plus). " +
+            'Le domaine de `from` (et de `replyTo`) doit être un domaine vérifié de votre compte. ' +
+            'Fournissez `html`, `text` ou les deux (au moins un des deux est requis). ' +
+            '`headers` : 20 en-têtes au plus ; seuls `List-Unsubscribe`, `List-Unsubscribe-Post` et les en-têtes `X-*` (hors `X-SES-*`) sont acceptés, en ASCII imprimable. ' +
+            "Réponse : un identifiant et le statut `queued` (en file d'envoi) ou `suppressed` (destinataire sur la liste de suppression : rien n'est envoyé ni débité) ; un envoi mis en file consomme 1 crédit. Le backend reste l'autorité sur toutes les règles.",
+        inputSchema: {
+            from: z
+                .string()
+                .min(1)
+                .describe('Expéditeur : `adresse@domaine.com` ou `Nom <adresse@domaine.com>` (nom de 128 caractères au plus). Domaine vérifié obligatoire.'),
+            to: z
+                .string()
+                .min(1)
+                .describe('Destinataire unique : `adresse@exemple.com` ou `Nom <adresse@exemple.com>`. Une seule adresse.'),
+            subject: z.string().min(1).max(300).describe("Sujet de l'email (300 caractères au plus)."),
+            html: z.string().optional().describe('Corps HTML (500 Ko au plus). `html` ou `text` est requis.'),
+            text: z.string().optional().describe('Corps texte brut (500 Ko au plus). `html` ou `text` est requis.'),
+            replyTo: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Adresse de réponse. Son domaine doit aussi être un domaine vérifié de votre compte.'),
+            headers: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('En-têtes personnalisés, 20 au plus : `List-Unsubscribe`, `List-Unsubscribe-Post`, `X-*` hors `X-SES-*`. ASCII imprimable.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, (args) => run(client, async () => {
+        const body = { from: args.from, to: args.to, subject: args.subject };
+        if (args.replyTo !== undefined)
+            body.replyTo = args.replyTo;
+        if (args.html !== undefined)
+            body.html = args.html;
+        if (args.text !== undefined)
+            body.text = args.text;
+        if (args.headers !== undefined)
+            body.headers = args.headers;
+        return formatSend(await client.request('POST', '/v1/emails', { body }));
+    }));
+    server.registerTool('get_balance', {
+        title: 'Solde de crédits',
+        description: 'Donne le solde de crédits Zendou (1 crédit = 1 email accepté) : crédits disponibles, achetés, offerts et consommés. Fonctionne avec toute clé API active.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, () => run(client, async () => formatBalance(await client.request('GET', '/v1/billing/balance'))));
+    server.registerTool('list_emails', {
+        title: 'Lister les emails envoyés',
+        description: "Liste le journal des emails envoyés (le plus récent d'abord), avec filtres et pagination : identifiant public, expéditeur, destinataire, sujet, statut, canal, dates." +
+            READ_NOTE,
+        inputSchema: {
+            status: z
+                .enum(['QUEUED', 'SENT', 'DELIVERED', 'BOUNCED', 'COMPLAINED', 'REJECTED', 'FAILED', 'SUPPRESSED'])
+                .optional()
+                .describe('Filtre sur le statut.'),
+            channel: z.enum(['API', 'SMTP']).optional().describe("Filtre sur le canal d'envoi."),
+            page: z.number().int().min(1).optional().describe('Numéro de page, à partir de 1.'),
+            limit: z.number().int().min(1).max(100).optional().describe("Nombre d'éléments par page (1 à 100)."),
+            from: z.string().optional().describe('Début de période, date ISO 8601 (ex. 2026-10-01 ou 2026-10-01T00:00:00Z).'),
+            to: z.string().optional().describe('Fin de période, date ISO 8601.'),
+            q: z.string().optional().describe('Recherche libre (adresse, sujet).'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => run(client, async () => formatEmailList(await client.request('GET', '/v1/emails', {
+        query: {
+            status: args.status,
+            channel: args.channel,
+            page: args.page,
+            limit: args.limit,
+            from: args.from,
+            to: args.to,
+            q: args.q,
+        },
+    }))));
+    server.registerTool('get_email', {
+        title: "Détail d'un email",
+        description: "Donne le détail et l'état de livraison d'un email à partir de son identifiant public (celui renvoyé par send_email ou list_emails) : statut, dates, message d'erreur éventuel." +
+            READ_NOTE,
+        inputSchema: {
+            publicId: z.string().min(1).describe("Identifiant public de l'email."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => run(client, async () => formatEmail(await client.request('GET', `/v1/emails/${encodeURIComponent(args.publicId)}`))));
+    server.registerTool('list_domains', {
+        title: 'Lister les domaines',
+        description: "Liste les domaines d'envoi du compte avec leur statut de vérification (identifiant, nom, statut, dates). Pour les enregistrements DNS, utilisez get_domain." +
+            READ_NOTE,
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, () => run(client, async () => formatDomainList(await client.request('GET', '/v1/domains'))));
+    server.registerTool('get_domain', {
+        title: "Détail d'un domaine",
+        description: "Donne le statut d'un domaine et les enregistrements DNS prêts à copier chez le registrar : enregistrements requis (DKIM, MAIL FROM) et recommandés (type, nom, valeur, priorité, rôle). Utile pour dire ce qui manque pour vérifier un domaine." +
+            READ_NOTE,
+        inputSchema: {
+            id: z.string().min(1).describe('Identifiant du domaine (champ `id` de list_domains).'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, (args) => run(client, async () => formatDomain(await client.request('GET', `/v1/domains/${encodeURIComponent(args.id)}`))));
+    return server;
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@zendou/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Serveur MCP Zendou : envoyer des emails et consulter votre compte depuis votre assistant IA.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Souleymane Diallo",
+  "bin": {
+    "zendou-mcp": "dist/index.js"
+  },
+  "main": "dist/server.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "tsc --noEmit -p tsconfig.json && node scripts/lint.mjs",
+    "test": "npm run build && tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "zendou",
+    "email"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}