@imenam/mcp-messenger 1.0.1

package/.env.example

@@ -0,0 +1,59 @@
+# ---------------------------------------------------------------------------
+# MCP Messenger — configuration
+# Deux modes, deux jeux de variables. Une même installation peut servir aux deux.
+# ---------------------------------------------------------------------------
+
+# === Mode serveur (boîte aux lettres) : `mcp-messenger --server` ===========
+
+# Port d'écoute. L'interface, elle, n'est pas configurable : le serveur écoute
+# toujours sur 127.0.0.1 et refuse de démarrer si MESSENGER_HOST vaut autre chose.
+# Pour l'atteindre depuis une autre machine, placer un reverse proxy devant.
+MESSENGER_PORT=3600
+
+# Chemin du fichier SQLite (défaut : <cwd>/data/messenger.db).
+# MESSENGER_DB_PATH=/var/lib/mcp-messenger/messenger.db
+
+# Jeton exigé sur TOUTE requête entrante (API, /health, console web).
+# OBLIGATOIRE : sans MESSENGER_TOKEN ni MESSENGER_AGENT_TOKENS, le serveur refuse
+# de démarrer. Générer par exemple avec : node -e "console.log(crypto.randomUUID())"
+MESSENGER_TOKEN=change-me
+
+# Alternative plus stricte : un jeton par agent (prioritaire sur MESSENGER_TOKEN).
+# Un jeton d'agent ne permet pas d'écrire sous l'identité d'un autre agent.
+# Format : agent_id:token,agent_id:token
+# MESSENGER_AGENT_TOKENS=planner:tok-planner,coder:tok-coder
+
+# Jeton de la console web. À défaut, MESSENGER_TOKEN fait office ; il devient
+# obligatoire si seul MESSENGER_AGENT_TOKENS est utilisé.
+# MESSENGER_ADMIN_TOKEN=change-me-too
+
+# Rate limiting (par IP).
+MESSENGER_RATE_LIMIT_MAX=600
+MESSENGER_RATE_LIMIT_WINDOW_MINUTES=15
+
+# Purge automatique de la corbeille (0 = désactivée).
+MESSENGER_TRASH_RETENTION_DAYS=30
+
+# === Mode MCP (côté agent) : `mcp-messenger` ==============================
+
+# Adresse FIXE de l'agent — à laisser vide dans la plupart des cas.
+# Vide : chaque session reçoit sa propre boîte (`box_…`), allouée au démarrage. Deux
+#   sessions ouvertes sur le même projet ne partagent donc pas leur courrier. L'agent
+#   donne son adresse avec `whoami`, et reprend une boîte existante avec
+#   `attach_to_mailbox`.
+# Renseignée : toutes les sessions utilisant cette configuration partagent cette boîte.
+# MESSENGER_AGENT_ID=
+
+# Adresse du serveur boîte aux lettres (http ou https, local ou distant).
+MESSENGER_SERVER_URL=http://127.0.0.1:3600
+
+# Jeton envoyé au serveur — obligatoire (doit correspondre à MESSENGER_TOKEN ou au
+# jeton de cet agent dans MESSENGER_AGENT_TOKENS).
+MESSENGER_TOKEN=change-me
+
+# Métadonnées publiées dans l'annuaire des agents (facultatif).
+# MESSENGER_AGENT_NAME=Planner
+# MESSENGER_AGENT_DESCRIPTION=Agent de planification, répond aux demandes de découpage de tâches.
+
+# Délai maximal d'un appel HTTP vers le serveur (ms).
+MESSENGER_TIMEOUT_MS=15000

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Matthieu Pesnot-Pin
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# MCP Messenger
+
+Boîte aux lettres pour agents IA : un **serveur** central reçoit et conserve les messages,
+et un **client MCP** donne à chaque agent — quelle que soit sa plateforme — les outils pour
+écrire, lire, classer et attendre des réponses.
+
+Le même paquet joue les deux rôles :
+
+| | Mode serveur (`--server`) | Mode MCP (sans argument) |
+|---|---|---|
+| Rôle | Boîte aux lettres : stockage, distribution, annuaire | Client stdio branché sur un agent |
+| Exposé sur | HTTP/HTTPS (API + console web) | stdin/stdout (JSON-RPC MCP) |
+| Consommé par | Les MCP des agents, la console web | Claude Code, Cursor, tout client MCP |
+| Variables clés | `MESSENGER_PORT`, `MESSENGER_TOKEN` | `MESSENGER_AGENT_ID`, `MESSENGER_SERVER_URL`, `MESSENGER_TOKEN` |
+| Processus | 1 pour toute la flotte | 1 par agent |
+
+```mermaid
+flowchart LR
+    A["Agent A (Claude Code)"] -- "stdio" --> MA["mcp-messenger (MCP)"]
+    B["Agent B (Cursor)"] -- "stdio" --> MB["mcp-messenger (MCP)"]
+    C["Agent C (autre plateforme)"] -- "stdio" --> MC["mcp-messenger (MCP)"]
+    MA -- "HTTP(S)" --> S
+    MB -- "HTTP(S)" --> S
+    MC -- "HTTP(S)" --> S
+    S["mcp-messenger --server\nSQLite + API + console"] --> U["Console web /ui"]
+```
+
+Les agents n'ont pas besoin d'être sur la même machine ni sur la même plateforme : ils
+partagent seulement l'adresse du serveur. **Chaque session d'agent reçoit sa propre boîte**,
+identifiée par une adresse opaque du type `box_9f2c4a01b3d7e5f8` — voir
+[Adresses et sessions](#adresses-et-sessions).
+
+---
+
+## Démarrage rapide
+
+### 1. Lancer la boîte aux lettres
+
+```bash
+MESSENGER_TOKEN=$(node -e "console.log(crypto.randomUUID())") npx @imenam/mcp-messenger --server
+# → listening on http://127.0.0.1:3600 (loopback only)
+# → auth: shared token — required on every request
+# → web console: http://127.0.0.1:3600/ui/?token=<MESSENGER_ADMIN_TOKEN>
+```
+
+Deux invariants, non négociables et vérifiés par les tests :
+
+1. **Le serveur écoute toujours sur `127.0.0.1`.** `MESSENGER_HOST` n'est pas un réglage :
+   toute autre valeur fait échouer le démarrage. Pour joindre la boîte depuis une autre
+   machine, il faut placer un reverse proxy (TLS) devant.
+2. **Un jeton est obligatoire et vérifié sur chaque requête entrante** — API, `/health` et
+   console web comprises. Sans `MESSENGER_TOKEN` ni `MESSENGER_AGENT_TOKENS`, le serveur
+   refuse de démarrer.
+
+### 2. Déclarer le MCP côté agent
+
+Dans le dossier du projet de l'agent :
+
+```bash
+npx -y @imenam/mcp-messenger --claude-setup-mcp
+```
+
+La commande écrit l'entrée `mcp-messenger` dans le `.mcp.json` du répertoire courant (les
+autres serveurs sont préservés ; `--force` pour remplacer une entrée existante), avec un
+`MESSENGER_AGENT_ID` pré-rempli d'après le nom du dossier. Il ne reste qu'à coller le jeton
+du serveur dans `MESSENGER_TOKEN`.
+
+Le bloc généré, à écrire à la main si tu préfères :
+
+```json
+{
+  "mcpServers": {
+    "messenger": {
+      "command": "npx",
+      "args": ["@imenam/mcp-messenger"],
+      "env": {
+        "MESSENGER_AGENT_ID": "planner",
+        "MESSENGER_SERVER_URL": "http://127.0.0.1:3600",
+        "MESSENGER_TOKEN": "le-jeton-du-serveur",
+        "MESSENGER_AGENT_NAME": "Planner",
+        "MESSENGER_AGENT_DESCRIPTION": "Découpe les tâches et répartit le travail"
+      }
+    }
+  }
+}
+```
+
+Chaque agent reçoit le même bloc avec **son propre** `MESSENGER_AGENT_ID`. Au démarrage, le
+MCP s'enregistre dans l'annuaire du serveur ; si le serveur est momentanément injoignable,
+la session MCP démarre quand même et l'enregistrement se fera au premier appel réussi.
+
+### 3. Écrire à un autre agent
+
+L'agent A appelle `send_message` avec `to: ["coder"]`, l'agent B voit le message via
+`list_messages` puis `read_message`, et répond avec `reply_to` pour rester dans le fil.
+`wait_for_message` permet d'attendre une réponse sans faire tourner une boucle d'appels.
+
+---
+
+## Outils MCP
+
+| Outil | Rôle |
+|---|---|
+| `whoami` | Adresse de cette session, serveur connecté, compteurs par dossier |
+| `attach_to_mailbox` | Se brancher sur une autre boîte via son adresse ; sans argument, retour à la sienne |
+| `set_mailbox_label` | Nommer sa boîte, pour la reconnaître dans l'annuaire et la console |
+| `list_agents` | Annuaire : qui est joignable, avec quelle description |
+| `send_message` | Envoyer à un ou plusieurs agents (`to`, `cc`, `priority`, `reply_to`) |
+| `list_messages` | Lister la boîte (filtres : dossier, non lus, expéditeur, fil, texte libre) |
+| `read_message` | Lire un message en entier ; le marque lu par défaut |
+| `get_thread` | Relire toute une conversation, du plus ancien au plus récent |
+| `mark_messages` | Marquer lu / non lu, suivi / non suivi |
+| `move_messages` | Classer dans un dossier |
+| `delete_messages` | Corbeille, ou suppression définitive (`permanent: true`) |
+| `list_folders` | Dossiers avec totaux et non-lus |
+| `create_folder` / `delete_folder` | Organiser l'espace comme une messagerie |
+| `wait_for_message` | Attente longue (jusqu'à 300 s) jusqu'à l'arrivée d'un message |
+
+**Dossiers système** — toujours présents, non supprimables : `inbox`, `sent`, `archive`,
+`trash`. Les dossiers personnalisés sont propres à chaque boîte.
+
+**Ce que voit un agent** : uniquement les livraisons de la boîte à laquelle il est attaché. Un message adressé à `coder`
+est invisible pour tout autre agent, y compris via son identifiant. Supprimer un message ne
+touche que sa propre copie : les autres destinataires gardent la leur.
+
+---
+
+## Adresses et sessions
+
+Une adresse n'est pas un rôle, c'est une **boîte**. Au démarrage, chaque processus MCP —
+donc chaque session d'agent — s'en fait allouer une, avec un identifiant opaque et unique :
+
+```
+box_9f2c4a01b3d7e5f8
+```
+
+Conséquence directe : deux sessions ouvertes dans le même projet, avec le même `.mcp.json`,
+ont deux boîtes distinctes et ne se volent pas leur courrier.
+
+### Faire communiquer deux agents
+
+1. Demande son adresse à l'agent A (`whoami`) — il te la donne.
+2. Transmets-la à l'agent B, qui l'utilise dans `send_message`.
+
+Comme les adresses sont opaques, demande aux agents de nommer leur boîte
+(`set_mailbox_label`) : le libellé apparaît dans `list_agents` et dans la console web, ce
+qui permet de retrouver une adresse perdue.
+
+### Reprendre le travail d'une session terminée
+
+Les boîtes survivent aux sessions. Après un redémarrage :
+
+> « Reprends le travail de la session précédente, sa boîte est `box_9f2c4a01b3d7e5f8`. »
+
+L'agent appelle `attach_to_mailbox` avec cette adresse : il lit alors le courrier de cette
+boîte, y compris les messages arrivés pendant l'interruption, et écrit sous cette adresse.
+`attach_to_mailbox` sans argument le ramène à sa propre boîte. Plusieurs sessions peuvent
+être attachées à la même boîte — c'est volontaire, et c'est ce qui permet la reprise.
+
+L'adresse est vérifiée avant le basculement : une faute de frappe renvoie
+`mailbox not found` au lieu de créer silencieusement une boîte vide.
+
+### Adresse fixe (cas particulier)
+
+Renseigner `MESSENGER_AGENT_ID` fige l'adresse : toutes les sessions utilisant cette
+configuration partagent alors la même boîte. Utile pour un service unique et stable, à
+éviter pour des sessions interactives multiples.
+
+---
+
+## Console web
+
+`http://127.0.0.1:3600/ui/?token=<MESSENGER_ADMIN_TOKEN>` affiche, en lecture seule,
+**tous les échanges** de la flotte :
+
+- la liste des agents avec leurs compteurs (envoyés, reçus, non lus) ;
+- tous les messages, filtrables par agent, par fil ou par recherche texte ;
+- le contenu d'un message et son état de distribution (qui l'a reçu, dans quel dossier, lu ou non) ;
+- le fil complet d'une conversation ;
+- un rafraîchissement automatique toutes les 5 secondes.
+
+Un navigateur ne peut pas poser d'en-tête sur une navigation : le jeton passe donc par
+`?token=` dans l'URL, et le serveur le propage aux ressources de la page (`styles.css`,
+`app.js`), elles aussi protégées. Ouvrir `/ui/` sans jeton renvoie un `401`. En dernier
+recours, la console propose un champ pour saisir le jeton et le conserve dans le
+`localStorage` du navigateur.
+
+> Le jeton apparaissant dans l'URL, il se retrouve dans l'historique du navigateur. C'est
+> le prix du « jeton exigé sur absolument tout », y compris la page elle-même.
+
+La console n'écrit jamais : elle ne peut ni envoyer, ni supprimer, ni modifier.
+
+---
+
+## Configuration
+
+Toutes les variables sont documentées dans [`.env.example`](.env.example). L'essentiel :
+
+### Serveur
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `MESSENGER_PORT` | `3600` | Port d'écoute |
+| `MESSENGER_HOST` | `127.0.0.1` (figé) | Non configurable ; une valeur non-loopback fait échouer le démarrage |
+| `MESSENGER_DB_PATH` | `./data/messenger.db` | Fichier SQLite |
+| `MESSENGER_TOKEN` | — | **Obligatoire** (sauf si `MESSENGER_AGENT_TOKENS`) : jeton exigé sur toute requête |
+| `MESSENGER_AGENT_TOKENS` | — | Un jeton par agent : `planner:tok-a,coder:tok-b` |
+| `MESSENGER_ADMIN_TOKEN` | `MESSENGER_TOKEN` | Jeton de la console ; obligatoire si seul `MESSENGER_AGENT_TOKENS` est défini |
+| `MESSENGER_RATE_LIMIT_MAX` | `600` | Requêtes par IP et par fenêtre |
+| `MESSENGER_RATE_LIMIT_WINDOW_MINUTES` | `15` | Durée de la fenêtre |
+| `MESSENGER_TRASH_RETENTION_DAYS` | `30` | Purge automatique de la corbeille (`0` = jamais) |
+| `MESSENGER_MAX_WAIT_SECONDS` | `300` | Plafond d'une attente longue |
+
+### Agent (mode MCP)
+
+| Variable | Requis | Rôle |
+|---|---|---|
+| `MESSENGER_AGENT_ID` | — | Adresse **fixe**. Vide (recommandé) = une boîte par session |
+| `MESSENGER_SERVER_URL` | ✅ | `http://` ou `https://`, local ou distant |
+| `MESSENGER_TOKEN` | ✅ | Jeton présenté au serveur, sur chaque appel |
+| `MESSENGER_AGENT_NAME` | — | Nom affiché dans l'annuaire |
+| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour ses correspondants |
+| `MESSENGER_TIMEOUT_MS` | `15000` | Délai maximal d'un appel HTTP |
+
+---
+
+## API HTTP
+
+**Toutes** les routes exigent un jeton, présenté au choix par `Authorization: Bearer
+<token>`, l'en-tête `X-Messenger-Token`, ou `?token=` (réservé à la navigation navigateur).
+Les routes `/api/*` exigent en plus l'en-tête `X-Agent-Id`, et le jeton doit correspondre à
+cet agent lorsque `MESSENGER_AGENT_TOKENS` est utilisé.
+
+| Méthode | Route | Rôle |
+|---|---|---|
+| `GET` | `/health` | État du service |
+| `POST` | `/api/agents/register` | S'inscrire à l'annuaire (`fresh: true` = exige une adresse neuve) |
+| `GET` | `/api/agents` | Annuaire des boîtes |
+| `GET` | `/api/agents/:id` | Une boîte, ou 404 |
+| `PATCH` | `/api/agents/me` | Renommer la boîte courante |
+| `GET` | `/api/mailbox` | Compteurs de la boîte |
+| `POST` | `/api/messages` | Envoyer un message |
+| `GET` | `/api/messages` | Lister (`folder`, `unread_only`, `from`, `thread_id`, `search`, `limit`, `offset`) |
+| `GET` | `/api/messages/:id` | Lire (`?mark_read=false` pour ne pas marquer) |
+| `POST` | `/api/messages/mark` | Marquer lu / suivi |
+| `POST` | `/api/messages/move` | Déplacer vers un dossier |
+| `POST` | `/api/messages/delete` | Corbeille ou suppression définitive |
+| `GET` | `/api/threads/:id` | Fil complet |
+| `GET` `POST` `DELETE` | `/api/folders[/:name]` | Gérer les dossiers |
+| `GET` | `/api/wait` | Attente longue (`timeout_seconds`, `folder`) |
+| `GET` | `/admin/overview` · `/admin/messages[/:id]` · `/admin/threads/:id` | Supervision, lecture seule |
+
+---
+
+## Sécurité
+
+- **Écoute exclusivement sur `127.0.0.1`** : l'interface n'est pas configurable, et une
+  valeur non-loopback fait échouer le démarrage plutôt que d'être ignorée en silence.
+- **Refus de démarrage sans jeton** : un serveur qui tourne est un serveur authentifié.
+- **Jeton vérifié sur chaque requête entrante**, avant tout traitement — y compris
+  `/health` et les fichiers de la console.
+- **Jetons par agent** (`MESSENGER_AGENT_TOKENS`) : un jeton valide ne permet pas
+  d'emprunter l'identité d'un autre agent. À préférer au jeton partagé dès que les agents
+  ne se font pas mutuellement confiance.
+- Comparaison des jetons à **temps constant**, en-têtes de sécurité (`helmet`), **rate
+  limiting** par IP, corps JSON limité à 2 Mo, erreurs internes génériques (le détail reste
+  dans les logs).
+- **Isolation des boîtes** garantie côté serveur : les identifiants de messages fournis par
+  un agent sont systématiquement filtrés sur ses propres livraisons.
+- La console web n'insère jamais de HTML fourni par un agent (`textContent` uniquement) et
+  la CSP interdit tout script tiers.
+- Derrière un reverse proxy TLS, exposer le serveur en `https://` et donner cette URL aux
+  agents via `MESSENGER_SERVER_URL`.
+
+---
+
+## Développement
+
+```bash
+npm install
+npm run build        # tsc + copie des fichiers de la console web
+npm test             # build puis suite Vitest complète
+npm run test:watch
+npm run typecheck
+npm run serve        # serveur local sur le port 3600
+```
+
+### Structure
+
+```
+src/
+  index.ts              # point d'entrée : --server, --help, --version, sinon mode MCP
+  config.ts             # lecture et validation des variables d'environnement
+  logger.ts             # journalisation sur stderr (stdout est réservé au JSON-RPC)
+  core/store.ts         # SQLite : agents, messages, livraisons, dossiers
+  server/app.ts         # API HTTP, authentification, supervision
+  server/start.ts       # démarrage, arrêt propre, purge de la corbeille
+  server/ui/            # console web (HTML/CSS/JS sans dépendance)
+  client/               # client HTTP utilisé par le mode MCP
+  mcp/                  # définition des outils et serveur MCP stdio
+test/                   # store, config, API HTTP, outils MCP, binaire réel
+```
+
+### Tests
+
+81 tests couvrant : le stockage et l'isolation des boîtes, la validation de configuration,
+l'API HTTP et son authentification (refus systématique sans jeton, jeton partagé, jetons par
+agent, jeton de console distinct), les outils MCP de bout en bout (deux agents qui
+conversent à travers un vrai serveur), l'allocation des boîtes par session — deux processus
+MCP lancés avec la même configuration obtiennent deux adresses différentes, et une
+troisième session reprend la boîte de l'une d'elles — et le binaire publié lui-même.
+
+---
+
+## Licence
+
+ISC

package/dist/src/cli/setup-mcp.d.ts

@@ -0,0 +1,6 @@
+export interface SetupMcpOptions {
+    cwd: string;
+    force: boolean;
+}
+/** Écrit l'entrée `mcp-messenger` dans le `.mcp.json` du répertoire courant. */
+export declare function runSetupMcp({ cwd, force }: SetupMcpOptions): number;

package/dist/src/cli/setup-mcp.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+const SERVER_NAME = "mcp-messenger";
+const PACKAGE_NAME = "@imenam/mcp-messenger";
+const DEFAULT_SERVER_URL = "http://127.0.0.1:3600";
+/** "Mon Projet_2" -> "mon-projet-2" : un identifiant d'agent lisible et sans espace. */
+function toAgentId(folder) {
+    const slug = folder
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "agent";
+}
+/** "mon-projet" -> "Mon Projet" */
+function toDisplayName(folder) {
+    return toAgentId(folder)
+        .split("-")
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+function buildServerEntry(cwd) {
+    // Le dossier courant donne une adresse d'agent par défaut : deux projets différents
+    // ne se retrouvent pas avec la même boîte aux lettres.
+    const folder = path.basename(cwd) || "agent";
+    return {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+            MESSENGER_SERVER_URL: DEFAULT_SERVER_URL,
+            MESSENGER_TOKEN: "",
+            // Laissé vide : chaque session reçoit sa propre boîte. Le renseigner force au
+            // contraire toutes les sessions de ce projet à partager une même adresse.
+            MESSENGER_AGENT_ID: "",
+            MESSENGER_AGENT_NAME: toDisplayName(folder),
+            MESSENGER_AGENT_DESCRIPTION: "",
+            MESSENGER_TIMEOUT_MS: "15000",
+        },
+    };
+}
+const REQUIRED_VARS = [
+    ["MESSENGER_SERVER_URL", `URL du serveur boîte aux lettres (défaut : ${DEFAULT_SERVER_URL})`],
+    ["MESSENGER_TOKEN", "jeton du serveur — À REMPLIR, le MCP ne peut rien faire sans lui"],
+];
+const OPTIONAL_VARS = [
+    ["MESSENGER_AGENT_ID", "adresse fixe : à laisser vide pour une boîte par session"],
+    ["MESSENGER_AGENT_NAME", "nom affiché dans l'annuaire des agents"],
+    ["MESSENGER_AGENT_DESCRIPTION", "à quoi sert cet agent, pour ses correspondants"],
+    ["MESSENGER_TIMEOUT_MS", "délai maximal d'un appel HTTP (défaut : 15000)"],
+];
+/** Écrit l'entrée `mcp-messenger` dans le `.mcp.json` du répertoire courant. */
+export function runSetupMcp({ cwd, force }) {
+    const target = path.join(cwd, ".mcp.json");
+    let config = {};
+    const exists = fs.existsSync(target);
+    if (exists) {
+        const raw = fs.readFileSync(target, "utf-8").trim();
+        if (raw !== "") {
+            try {
+                config = JSON.parse(raw);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Erreur : ${target} contient du JSON invalide (${message}).`);
+                console.error("Corrigez le fichier ou supprimez-le, puis relancez la commande.");
+                return 1;
+            }
+        }
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            console.error(`Erreur : ${target} ne contient pas un objet JSON.`);
+            return 1;
+        }
+    }
+    if (typeof config.mcpServers !== "object" || config.mcpServers === null || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    const alreadyPresent = Object.prototype.hasOwnProperty.call(config.mcpServers, SERVER_NAME);
+    if (alreadyPresent && !force) {
+        console.error(`Le serveur "${SERVER_NAME}" est déjà configuré dans ${target}.`);
+        console.error("Relancez avec --force pour écraser cette entrée (les autres serveurs sont préservés).");
+        return 1;
+    }
+    config.mcpServers[SERVER_NAME] = buildServerEntry(cwd);
+    fs.writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    const action = alreadyPresent ? "remplacée" : exists ? "ajoutée" : "créée";
+    console.log(`Configuration ${SERVER_NAME} ${action} dans ${target}`);
+    console.log("");
+    console.log('À vérifier dans le champ "env" :');
+    for (const [name, description] of REQUIRED_VARS) {
+        console.log(`  ${name.padEnd(28)} ${description}`);
+    }
+    console.log("");
+    console.log("Variables optionnelles :");
+    for (const [name, description] of OPTIONAL_VARS) {
+        console.log(`  ${name.padEnd(28)} ${description}`);
+    }
+    console.log("");
+    console.log("Le serveur boîte aux lettres doit tourner à part, avec le même jeton :");
+    console.log(`  MESSENGER_TOKEN=<votre-jeton> npx -y ${PACKAGE_NAME} --server`);
+    console.log(`  console web : ${DEFAULT_SERVER_URL}/ui/?token=<votre-jeton>`);
+    console.log("");
+    console.log("Chaque session d'agent reçoit sa propre boîte : demandez son adresse à l'agent");
+    console.log("(outil whoami) pour la transmettre à un autre agent, ou pour la reprendre plus tard.");
+    return 0;
+}

package/dist/src/client/messenger-client.d.ts

@@ -0,0 +1,78 @@
+import type { AgentConfig } from "../config.js";
+import type { Agent, FolderInfo, ListMessagesOptions, MailboxStats, Message, MessageSummary, Priority, SendMessageResult } from "../core/types.js";
+/** Échec d'un appel au serveur boîte aux lettres (réseau, authentification ou métier). */
+export declare class MessengerClientError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface WaitResult {
+    timed_out: boolean;
+    message: Message | null;
+}
+/**
+ * Client HTTP du serveur boîte aux lettres.
+ *
+ * L'identité de l'agent voyage dans `X-Agent-Id` ; le serveur ne l'accepte que si le
+ * jeton présenté correspond à sa configuration. C'est l'unique point de sortie réseau
+ * du mode MCP : les outils n'appellent jamais `fetch` directement.
+ */
+export declare class MessengerClient {
+    private readonly config;
+    /** Boîte courante. Modifiable en cours de session par `attach_to_mailbox`. */
+    private currentAgentId;
+    /** Boîte allouée à cette session : on peut toujours y revenir après un rattachement. */
+    private ownAgentId;
+    constructor(config: AgentConfig);
+    get agentId(): string;
+    /** Adresse fixée par la configuration, s'il y en a une. */
+    get pinnedAgentId(): string | null;
+    /** `own: true` désigne la boîte de la session, celle sur laquelle on peut revenir. */
+    setAgentId(agentId: string, options?: {
+        own?: boolean;
+    }): void;
+    /** Adresse de la boîte propre à cette session. */
+    get sessionAgentId(): string | null;
+    /** true si la session lit une boîte autre que la sienne. */
+    get isAttachedElsewhere(): boolean;
+    get serverUrl(): string;
+    health(): Promise<{
+        status: string;
+        version: string;
+        agents: number;
+        messages: number;
+    }>;
+    /** Enregistre la boîte courante. `fresh` exige une adresse encore inconnue du serveur. */
+    register(options?: {
+        fresh?: boolean;
+    }): Promise<Agent>;
+    /** Renomme la boîte courante, pour la rendre reconnaissable dans l'annuaire. */
+    updateProfile(profile: {
+        display_name?: string | null;
+        description?: string | null;
+    }): Promise<Agent>;
+    getAgent(agentId: string): Promise<Agent>;
+    listAgents(): Promise<Agent[]>;
+    stats(): Promise<MailboxStats>;
+    sendMessage(input: {
+        to: string[];
+        cc?: string[];
+        subject: string;
+        body: string;
+        priority?: Priority;
+        reply_to?: string | null;
+    }): Promise<SendMessageResult>;
+    listMessages(options?: ListMessagesOptions): Promise<MessageSummary[]>;
+    getMessage(messageId: string, markRead?: boolean): Promise<Message>;
+    markMessages(messageIds: string[], state: {
+        read?: boolean;
+        starred?: boolean;
+    }): Promise<number>;
+    moveMessages(messageIds: string[], folder: string): Promise<number>;
+    deleteMessages(messageIds: string[], permanent?: boolean): Promise<number>;
+    getThread(threadId: string): Promise<Message[]>;
+    listFolders(): Promise<FolderInfo[]>;
+    createFolder(name: string): Promise<FolderInfo>;
+    deleteFolder(name: string): Promise<number>;
+    waitForMessage(timeoutSeconds: number, folder?: string): Promise<WaitResult>;
+    private request;
+}