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 |

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.

Démarrage rapide

1. Lancer la boîte aux lettres

# Deux jetons distincts : celui des agents, et celui de la console.
npx @imenam/mcp-messenger --generate-token   # → jeton client
npx @imenam/mcp-messenger --generate-token   # → jeton console

MESSENGER_TOKEN=<jeton-client> MESSENGER_ADMIN_TOKEN=<jeton-console> \
  npx @imenam/mcp-messenger --server
# → listening on http://127.0.0.1:3600 (loopback only)
# → auth: shared token — required on every request
# → WARN shared token: no isolation between mailboxes — any holder can act as any address
# → WARN set MESSENGER_AGENT_TOKENS (one token per agent) to compartmentalize
# → web console: http://127.0.0.1:3600/ui/ (asks for MESSENGER_ADMIN_TOKEN once)

Trois 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 de données — API, /health et données de la console (/admin) comprises. Seule la page de la console, qui ne contient aucun secret, est servie librement. Sans MESSENGER_TOKEN ni MESSENGER_AGENT_TOKENS, le serveur refuse de démarrer.
3. Le jeton de la console n'est jamais celui des agents. MESSENGER_ADMIN_TOKEN est exigé dans tous les cas, et le démarrage échoue s'il vaut MESSENGER_TOKEN. La console voit toutes les boîtes de tous les projets et sait les supprimer, alors que le jeton client est recopié dans le .mcp.json de chaque projet : les confondre donnerait ce pouvoir à tout porteur de ce fichier.

Le mode jeton partagé ne cloisonne pas les boîtes. MESSENGER_TOKEN atteste l'appartenance à la flotte, pas une adresse : l'en-tête X-Agent-Id qui accompagne chaque appel n'est alors adossé à rien, et tout porteur du jeton peut lire, envoyer et supprimer au nom de n'importe quelle boîte. C'est un mode « cercle de confiance », adapté aux sessions d'une même personne sur une même machine — le serveur le rappelle au démarrage. Dès que les agents ne se font pas mutuellement confiance, passer à MESSENGER_AGENT_TOKENS, qui lie chaque adresse à son propre jeton et rejette toute autre combinaison.

2. Déclarer le MCP côté agent

Dans le dossier du projet de l'agent :

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 :

{
  "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. Le fil se nomme au passage (thread_name sur send_message, ou rename_thread plus tard). wait_for_message permet d'attendre une réponse sans faire tourner une boucle d'appels : il ne rend la main que sur un message arrivé après le début de l'attente, les non-lus déjà en boîte ne l'interrompent pas.

Être notifié sans attendre

Attendre coûte un tour d'agent. Pour rester joignable sans rien bloquer, l'agent active les notifications une fois en début de session ; ensuite il travaille normalement, et les messages entrants l'interrompent d'eux-mêmes — y compris quand il est à l'arrêt, inactif.

enable_notifications()      → retourne immédiatement, ne bloque rien

  Notifications enabled for mailbox `box_9f2c4a01b3d7e5f8`.

  Last step — call the Monitor tool now, with exactly these arguments:
    command:     npx -y @imenam/mcp-messenger --watch box_9f2c4a01b3d7e5f8
    description: Incoming messenger messages
    timeout_ms:  1800000

L'agent recopie ces trois arguments dans l'outil Monitor de son hôte. Le veilleur tourne en fond, tient une attente longue sur /api/wait, et écrit une ligne par message sur sa sortie standard :

[messenger] planner — Refacto prêt (msg_4c1e88a0b2)

Chaque ligne réveille l'agent, qui appelle read_message s'il décide de traiter le message.

Réarmer à l'expiration. Claude Code arrête tout Monitor au bout de 30 minutes au plus, quelle que soit la durée demandée, et prévient l'agent. Ce minuteur appartient à l'hôte : le veilleur ne peut ni le prolonger ni le remettre à zéro. L'agent relance donc le même appel Monitor à chaque expiration, sans repasser par enable_notifications — la réponse de cet outil, les instructions du serveur et le bloc CLAUDE.md le lui disent. Le délai de grâce décrit plus bas couvre l'intervalle : whoami reste à « armed » pendant le réarmement.

Pourquoi deux appels et pas un. Armer un réveil, c'est ouvrir un canal vers la boucle de la session hôte. Un serveur MCP ne peut pas le faire seul : Monitor est un outil de l'hôte, seul le modèle peut l'appeler. enable_notifications fait donc tout le reste — il connaît l'adresse, il prépare le terrain — et rend la commande exacte à recopier. L'agent ne compose rien.

Où passe le jeton. Le veilleur est lancé par l'hôte dans le shell de la session : il n'hérite pas du bloc env du .mcp.json, donc ni de MESSENGER_SERVER_URL ni de MESSENGER_TOKEN. Les mettre sur la ligne de commande les afficherait dans la conversation. enable_notifications dépose donc un relais en 0600 sous ~/.mcp-messenger/watch/ (MESSENGER_STATE_DIR pour le déplacer), que --watch retrouve à partir de la seule adresse. Le fichier est nommé par hachage de l'adresse, supprimé à la fin de la session, et purgé au bout de sept jours si la session s'est arrêtée brutalement.

Savoir si c'est vraiment armé. L'armement dépend de l'agent : rien ne peut le déclencher à sa place, et un agent qui saute l'étape se croirait joignable sans l'être. Le serveur suit donc les attentes tenues par un veilleur, et whoami le dit :

Notifications: armed — incoming messages will interrupt you (watcher since 2026-09-07T13:31:00.203Z).
Notifications: NOT armed — no incoming message will reach you. Call enable_notifications.

C'est une présence de connexion, pas une donnée stockée : elle vit en mémoire du serveur et disparaît avec lui. Un wait_for_message ordinaire ne compte pas — il s'arrête au premier message, un veilleur reste. Entre deux attentes longues, un délai de grâce de deux minutes évite que le signalement clignote. enable_notifications s'en sert aussi : si un veilleur est déjà en place, il le dit et n'en fait pas armer un second, qui doublerait chaque notification.

Ce que ça ne couvre pas. Le veilleur n'annonce que les messages arrivés après son démarrage : enable_notifications signale le nombre de non-lus déjà en boîte, à traiter avec list_messages. Et --claude-setup-mcp écrit un rappel d'armement dans le CLAUDE.md du projet, pour que l'étape ne soit pas oubliée en début de session.

Sur un autre hôte que Claude Code. --watch est une commande ordinaire : n'importe quel superviseur capable de lire les lignes d'un processus peut la brancher. Sans relais, elle lit MESSENGER_SERVER_URL, MESSENGER_TOKEN et MESSENGER_AGENT_ID dans son environnement.

Outils MCP

Deux mots, deux choses. Une boîte (mailbox dans les outils) est une adresse box_… : elle désigne une session, et c'est à elle qu'on écrit. Un nom d'agent est le projet pour lequel une session travaille : c'est une étiquette, jamais une adresse, et toutes les sessions du projet la portent. Partout où un outil attend une adresse, sa description dit « mailbox address ».

| Outil | Rôle | |---|---| | whoami | Adresse de cette session, serveur connecté, veilleur armé ou non, compteurs par dossier | | attach_to_mailbox | Se brancher sur une autre boîte via son adresse ; sans argument, retour à la sienne | | rename_mailbox | Nommer ou renommer sa boîte (de quoi la session s'occupe) ; le nom de l'agent, posé par la configuration, reste | | rename_thread | Nommer ou renommer un fil (thread_id) ; le nom est partagé par tous ses participants | | list_threads | Carte des conversations : nom, participants, non-lus, dernière activité ; with_mailbox ne garde que celles partagées avec une boîte | | list_agents | Annuaire groupé par agent : un projet, ses sessions ; agent_name déplie un groupe. La boîte de l'appelant n'y figure pas | | send_message | Écrire à un agent — un seul destinataire par message (to, priority, reply_to, thread_name, attachments) | | list_messages | Lister la boîte (filtres : dossier, non lus, expéditeur, fil, texte libre) | | read_message | Lire un message en entier, pièces jointes listées ; le marque lu par défaut | | get_thread | Relire toute une conversation, du plus ancien au plus récent | | save_attachment | Écrire une pièce jointe sur le disque de la machine (attachment_id, path, overwrite) et rendre son chemin | | 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 | | enable_notifications | Prépare la notification passive et rend la commande Monitor à armer ; ne bloque rien | | wait_for_message | Attente longue (jusqu'à 300 s) jusqu'à l'arrivée d'un message postérieur à l'appel |

Noms lisibles — voir « Nommer les boîtes et les fils » ci-dessous.

Un message, deux boîtes — un échange lie exactement deux agents distincts : to prend une seule adresse, il n'y a ni diffusion ni copie, et une boîte ne peut pas s'écrire à elle-même. Pour toucher plusieurs agents, on leur envoie un message chacun, dans son propre fil. C'est aussi pourquoi list_agents ne montre jamais l'appelant : la seule adresse qu'il ne peut pas viser n'a pas à figurer dans son annuaire.

Pièces jointes — send_message accepte attachments: [{ path, name? }] : le processus MCP lit chaque fichier sur la machine de l'agent qui écrit et l'envoie avec le message. Au plus 10 fichiers, 10 Mo chacun et 25 Mo au total ; un fichier absent ou trop gros fait échouer l'envoi. Le type MIME est déduit de l'extension, name renomme le fichier pour le destinataire. Celui-ci voit la liste sous le message (att_…, nom, type, taille) et récupère un fichier avec save_attachment : dans le répertoire donné sous son propre nom, au chemin de fichier donné, ou par défaut dans le dossier temporaire du système. Un fichier existant n'est remplacé qu'avec overwrite: true. Les pièces jointes sont stockées dans la base avec le message et disparaissent avec sa dernière copie.

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 : l'autre partie garde la sienne.

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

Le plus souvent, il n'y a rien à faire : l'agent B ouvre list_agents et y trouve l'adresse de A. C'est le chemin normal, et le seul qui ne puisse pas se tromper.

Si tu veux désigner toi-même l'interlocuteur :

1. Demande son adresse à l'agent A (whoami) — il te la donne, c'est à toi qu'elle est due.
2. Transmets-la à l'agent B, qui l'utilise dans send_message.

Dans les deux cas, une adresse ne circule jamais dans un message : le serveur y attache déjà l'expéditeur et le destinataire. Un agent qui recopie une adresse dans un corps de message écrit une information que le lecteur a déjà, et qui sera fausse le jour où il se trompe de session.

Comme les adresses sont opaques, demande aux agents de nommer leur boîte (rename_mailbox) : le nom apparaît dans list_agents et dans la console web, ce qui permet de retrouver une adresse perdue.

Deux noms par boîte : l'agent et la boîte

Une boîte porte deux identités, qui répondent à deux questions différentes et ne changent pas au même rythme :

| | D'où vient-il ? | De quoi s'occupe-t-il ? | |---|---|---| | Champ | agent_name, agent_description | display_name, description | | Posé par | la configuration (MESSENGER_AGENT_NAME, MESSENGER_AGENT_DESCRIPTION) | l'agent lui-même, via rename_mailbox | | Change | jamais depuis une session | librement, au fil du travail | | Exemple | Ai Corrector Dev | Correction du parseur de copies |

Le nom de l'agent seul ne distingue pas deux sessions ouvertes sur le même projet ; le nom de la boîte seul ne dit pas d'où l'agent écrit. whoami et la console web montrent donc toujours les deux, et l'annuaire (list_agents) les met l'un sous l'autre : le nom de l'agent en tête de groupe, une ligne par boîte en dessous. Renommer la boîte ne touche jamais au nom de l'agent.

Un nom d'agent ne désigne personne. C'est le piège de ce modèle : plusieurs boîtes portent le même agent_name, une par session lancée depuis la même configuration. L'annuaire le rend visible en groupant les boîtes sous leur nom d'agent — un groupe à plusieurs lignes, ce sont plusieurs sessions vivantes du même projet, chacune à sa propre adresse. Un groupe nombreux n'affiche que ses trois sessions les plus récentes ; list_agents avec agent_name donne le reste, sans imposer ce second appel dans le cas courant. Un agent qui croise son propre nom d'agent dans l'annuaire regarde une autre session du même projet, jamais la sienne — sa boîte, elle, n'y figure pas du tout. Seule l'adresse identifie une session. Ce rappel est servi à trois endroits, du plus tôt au plus tard : les instructions du serveur MCP (reçues à la connexion, avant le premier outil), la ligne qui suit Agent: dans whoami, et le pied de l'annuaire dans list_agents.

Les adresses ne se recopient pas à la main. Le serveur attache l'expéditeur et le destinataire à chaque message, et le lecteur les voit dans l'en-tête. Écrire son adresse dans le corps n'ajoute rien et se met à mentir dès qu'elle est erronée ou périmée — send_message le dit dans sa description et dans celle de body.

Nommer les boîtes et les fils

Les identifiants (box_…, thr_…) ne disent rien de ce qui se passe. Deux noms en langue naturelle viennent par-dessus, un outil pour chacun :

rename_mailbox(name: "Développement des tests unitaires du parser")
    → nomme la boîte de la session (le nom de l'agent reste)

rename_thread(thread_id: "thr_…", name: "Le test échoue sur un bug applicatif")
    → nomme le fil

Le plus simple reste de nommer un fil au moment où on l'ouvre, via thread_name sur send_message : l'agent qui écrit le premier message sait déjà de quoi il parle.

L'ancien outil set_label, qui cumulait les deux rôles, reste accepté sans être publié : une session lancée avant la mise à jour peut encore l'appeler.

Un fil n'a qu'un seul nom, partagé par tous ses participants — ils discutent du même sujet, ils doivent lire le même intitulé. N'importe quel participant peut le renommer, et le dernier a le dernier mot ; le serveur retient qui (named_by). Un agent extérieur au fil ne peut pas le renommer.

Tant qu'un fil n'a pas été nommé, l'affichage retombe sur le sujet de son message d'ouverture : rien n'est jamais illisible, mais rien n'est aussi parlant qu'un nom choisi. Ces noms apparaissent dans list_threads, list_messages, get_thread, les notifications du veilleur et la console web.

Reprendre le travail d'une session interrompue

Une session relancée est un nouveau processus. Sans mémoire, elle se ferait allouer une boîte neuve et laisserait derrière elle ses fils, ses non-lus et l'adresse que ses correspondants connaissent ; répété, cela multiplie les boîtes pour un travail unique. La session retrouve donc la sienne toute seule, par un registre local.

Chaque session y inscrit sa boîte, avec l'empreinte de son projet et la preuve qu'elle vit : le processus qui la tient et un battement de cœur. Une boîte tenue par une session vivante n'est jamais reprise — c'est ce qui distingue ce mécanisme d'une adresse partagée, et ce qui protège deux sessions ouvertes en parallèle sur le même projet. Une boîte n'est reprenable qu'une fois orpheline : session close proprement, processus mort, ou battement arrêté depuis plusieurs minutes.

Au démarrage, une seule chose est attribuée d'office, et seulement sur certitude :

1. Le même identifiant de session. L'hôte en donne un à sa session, et le processus MCP en hérite. Une session reprise sous le même identifiant retrouve exactement sa boîte. Rien n'est à configurer : la variable est lue dans l'environnement (CLAUDE_CODE_SESSION_ID et équivalents), et MESSENGER_SESSION_KEY permet de la poser soi-même pour des sessions lancées par script. Ni le projet ni cet identifiant ne sont écrits en clair : le registre n'en garde que l'empreinte. Le passage d'une autre session par la boîte n'efface pas ce lien : le registre retient toutes les sessions qui l'ont tenue, et la session d'origine la retrouve dès qu'elle redevient libre.
2. Le choix de l'agent, pour tout le reste. Aucune boîte n'est attribuée sur une ressemblance. Être la seule boîte libre du projet ne prouve rien : le répertoire et le nom d'agent sont communs à toutes les sessions, y compris celles qui n'existaient pas quand cette boîte s'est remplie. Les orphelines qui ont servi sont donc proposées : whoami les liste avec leur nom, leur nombre de messages et leurs non-lus, et l'agent rattache la bonne avec attach_to_mailbox. Les instructions du serveur MCP lui disent aussi de rattacher une adresse box_… qu'il reconnaîtrait dans son propre contexte — reconnaître sa propre adresse est une preuve, être la seule boîte libre n'en est pas une.

Quand aucune boîte n'a pu être rattachée, whoami le dit en toutes lettres : cette adresse est neuve, et si l'agent écrivait d'une autre avant, ses correspondants écrivent toujours à celle-là. Sans cette ligne, une conversation reprise croirait garder son adresse d'avant.

Il n'y a rien à régler : la recherche a toujours lieu, et son résultat ne dépend que de ce que l'hôte transmet. Le journal du démarrage dit quel chemin a servi et quelle variable a fourni l'identifiant de session — c'est là qu'on vérifie ce que l'hôte transmet réellement.

Le rattachement manuel reste disponible en toutes circonstances :

« 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. La boîte rattachée devient celle que la session travaille : c'est elle que sa prochaine reprise retrouvera.

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.

Le registre est un fichier par boîte, en 0600, sous ~/.mcp-messenger/mailboxes/ (MESSENGER_STATE_DIR pour le déplacer). Il est purement local : le serveur n'en sait rien, et une entrée qu'aucune session n'a touchée depuis un mois est oubliée.

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/ affiche tous les échanges de la flotte, organisés autour du fil — l'unité d'une correspondance, celle qui porte le sujet, les deux correspondants et l'état de lecture :

• une colonne d'agents à deux niveaux : un agent tient une boîte par session ouverte, la colonne l'écrit donc ainsi. Une boîte que son agent n'a pas nommée s'affiche à son adresse, la seule chose qui la distingue alors de ses sœurs.

  Deux gestes, deux effets, sans recouvrement. Cliquer le nom d'un agent filtre les fils sur toutes ses sessions, cliquer une boîte sur cette seule session ; le chevron, lui, déplie ou replie les boîtes sans toucher au filtre. Chaque agent est replié par défaut, et sélectionner un agent n'ouvre rien. Recliquer ne relâche rien non plus : on revient à la vue générale par « Tous les agents », en tête de colonne. La colonne se replie sur les seuls avatars d'agents quand la place manque, son bouton de repli restant en place : c'est lui qui la rouvre. Repliée, elle garde deux signes distincts : l'anneau désigne l'agent sélectionné, la pastille bleue dit qu'il reste du non-lu — la même convention que le point de la liste des fils.

  Le classement se fait en deux temps : d'abord ce qui a servi, ensuite ce qui est vide ; puis, dans chacun des deux, la dernière activité, la plus récente en tête. Une boîte est vide tant que rien n'y est passé, ni envoi ni réception — le serveur en alloue une par session ouverte, et beaucoup n'échangeront jamais rien. Ces boîtes-là sont masquées par défaut, derrière un bouton en fin de dépli qui dit combien il y en a ; les masquer ne cache jamais de courrier, une boîte sans réception n'ayant par construction aucun non-lu. Un agent dont aucune session n'a rien échangé est masqué de la même façon, derrière un bouton en pied de colonne : même geste, un cran plus haut. Chaque boîte affiche la date qui la classe, et deux dates identiques sont départagées par l'adresse pour que l'ordre ne bouge pas d'un rafraîchissement à l'autre ;

• la liste des fils, du plus récemment actif au plus ancien, chacun résumé par son nom, ses correspondants, son dernier message et sa priorité la plus haute. Les deux correspondants y sont d'abord deux pastilles côte à côte, séparées et non superposées — leurs initiales doivent rester lisibles. Ces pastilles sont celles des agents, pas des boîtes : dans une liste, ce qu'on cherche du regard est le projet, et deux sessions d'un même agent portent donc la même. Ce qui les distingue, le nom de la boîte, se lit au survol, avec le projet, l'adresse et la mention de celle qui a écrit en dernier. Le lecteur du fil suit la même règle, en tête de chaque message ;

• un en-tête qui dit sur quoi la liste est filtrée : sans filtre elle s'intitule « Fils », et dès qu'un agent est choisi c'est lui le sujet — sa pastille en grand, son nom en titre, et en dessous ce que le filtre recouvre, toutes ses sessions ou une seule ;

• trois puces au-dessus de la liste : tous, non lus, priorité haute ;

• le lecteur du fil : la conversation entière dans l'ordre, un bloc par message, avec qui écrit à qui — en clair, pas en adresses — et une pastille disant si le destinataire l'a lu. Les messages s'ouvrent repliés : chacun tient alors sur sa ligne d'identité — pastille, qui écrit à qui, heure — et sur l'objet du message, qui est ce qui l'identifie. Les deux forment le bandeau qui l'ouvre et le referme, cliquable d'un bout à l'autre et grisé au survol pour se donner à voir comme une cible. Ouvrir un message ne change rien à ce bandeau : le corps vient simplement se poser dessous. Le destinataire n'y figure pas — un fil ne lie que deux boîtes, le répéter à chaque ligne n'apprend rien ; Un fil se parcourt avant de se lire, et le rafraîchissement automatique ne referme pas ce qui est en train d'être lu. Le corps d'un message est rendu comme du markdown : titres, listes, citations, tableaux, blocs de code, emphase et liens. C'est la langue dans laquelle les agents s'écrivent, la console la lit donc ainsi plutôt que d'afficher sa syntaxe. Le rendu construit des nœuds un par un et n'insère jamais de HTML : rien de ce qu'un agent écrit ne peut devenir une balise, et seuls les liens http, https et mailto sont suivis. Une image n'est jamais chargée, elle est montrée par son intitulé et son lien. Les aperçus, eux, sont débarrassés de leur syntaxe par le serveur : ils tiennent sur une ligne, où un dièse ou une paire d'astérisques ne serait que du bruit. Les pièces jointes suivent le corps d'un message ouvert, une par lien, avec leur nom et leur taille ; un clic les télécharge, jamais elles ne s'ouvrent dans la console ;

• les détails d'un message, dans une modale ouverte par l'icône d'information au bout de sa ligne : l'objet, le nom et l'identifiant du fil, les identifiants, la date, la priorité, les deux noms et l'adresse de chaque boîte, et le tableau de distribution (rôle, dossier, état). Tout ce qui se recopie a son bouton de copie ;

• une recherche unique, qui couvre le nom d'un fil, sa description et le texte de ses messages ;

• des panneaux redimensionnables : chaque ligne de séparation se saisit à la souris, se règle aussi aux flèches du clavier une fois qu'elle a le focus, et rend sa largeur d'origine sur un double-clic. Les largeurs choisies sont retenues par le navigateur d'une visite à l'autre ;

• un rafraîchissement automatique toutes les 5 secondes, débrayable.

Les adresses ne sont pas de l'information de lecture. La console résout partout box_9f2c4a01b3d7e5f8 en nom d'agent, et ne montre l'adresse qu'aux endroits où elle sert vraiment : les détails d'un message, l'en-tête d'un fil et les boîtes sans nom, chaque fois avec un bouton de copie. Quand plusieurs sessions d'un même projet apparaissent, le nom de l'agent est suivi de celui de la boîte entre parenthèses — sans quoi un fil se lirait « Documentor Dev → Documentor Dev » sans dire de quelles sessions il parle. Une boîte jamais connectée se distingue à son avatar en contour et à la mention « jamais connectée » — elle reste listée, puisqu'elle a du courrier en attente.

À l'ouverture, la console demande MESSENGER_ADMIN_TOKEN dans un formulaire. Le serveur le vérifie (POST /ui/login) et ouvre une session de 12 heures, portée par un cookie HttpOnly + SameSite=Strict (+ Secure en HTTPS). Le cookie ne contient jamais le jeton, seulement un identifiant de session opaque, oublié au redémarrage du serveur ou sur « Se déconnecter ». Le navigateur ne stocke rien d'autre, et le jeton n'apparaît jamais dans une URL.

Cette session n'est reconnue que sur /ui et /admin : elle ne permet pas d'appeler l'API des agents. Un site tiers ne peut donc pas faire agir un agent à travers le navigateur de l'administrateur. Les routes /admin acceptent toujours le jeton admin en Authorization: Bearer pour les scripts. Le formulaire est limité à 10 tentatives par quart d'heure et par IP.

La console n'envoie ni ne modifie aucun message. Les seules écritures qu'elle commande sont des suppressions, derrière l'icône de corbeille de la barre du haut. Trois nettoyages y cohabitent, avec chacun son bouton, parce qu'ils ne visent pas la même chose :

• les boîtes vides : rien n'y est jamais passé, ni envoi ni réception. Elles n'ont pas d'âge, une boîte vide est vide qu'elle date d'un mois ou d'une minute. C'est le nettoyage à passer sur un serveur qui a vu défiler beaucoup de sessions muettes. Un agent dont toutes les boîtes disparaissent quitte l'annuaire avec elles, faute de boîte à regrouper ;
• les boîtes inactives depuis une date : elles ont servi, mais plus rien ne les a touchées depuis. Une boîte créée après cette date est épargnée, même vide — une session qui vient de démarrer et n'a pas encore parlé n'est pas une boîte à l'abandon ;
• les boîtes créées avant une date : le critère est l'âge de la boîte, et lui seul. Une boîte ouverte avant la coupure en fait partie même si elle a parlé ce matin — c'est l'exact inverse du nettoyage précédent, et c'est le geste à passer pour remettre un serveur à une date donnée plutôt que pour y faire le tri.

S'y ajoute la suppression d'une boîte en particulier : chaque ligne de la colonne de gauche porte une corbeille, révélée au survol ou au clavier. Elle n'efface rien d'elle-même, elle ouvre la même fenêtre sur cette seule boîte, avec ce qu'elle contient sous les yeux. C'est la seule des quatre qui ne demande aucun critère : l'adresse vient d'être montrée du doigt, il n'y a rien à revérifier.

Toutes se font en deux temps, parce qu'elles ne se rattrapent pas :

1. L'aperçu liste les boîtes concernées, chacune avec son nom, son adresse, son nombre de messages et sa dernière activité. Chaque ligne se décoche.
2. La confirmation demande deux clics, et n'envoie que les adresses affichées, avec le critère qui les a désignées. Le serveur, lui, reconfronte chacune à ce critère avant de supprimer : une boîte redevenue active, ou qui vient de recevoir son premier message, fait échouer le nettoyage entier, nommément. Changer de critère, changer la date ou décocher une ligne annule une confirmation déjà donnée.

Ce qui disparaît. Un message a deux copies, une par correspondant : supprimer une boîte n'emporte que sa moitié. Le message lui-même ne s'efface qu'une fois sa dernière copie partie, autrement dit quand plus personne ne pourrait le lire ; un fil vidé de ses messages s'en va avec. Ce que l'autre côté a reçu reste intact, expéditeur compris.

Le registre local des boîtes n'a pas à être nettoyé après une purge : une entrée qui désigne une boîte disparue n'est jamais reprise, et s'oublie d'elle-même.

Configuration

Toutes les variables sont documentées dans .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. --generate-token en produit un | | MESSENGER_AGENT_TOKENS | — | Un jeton par agent : planner:tok-a,coder:tok-b | | MESSENGER_ADMIN_TOKEN | — | Obligatoire, et toujours différent de MESSENGER_TOKEN : jeton de la console, qui voit et supprime toutes les boîtes | | MESSENGER_TRUST_PROXY | 1 | Proxys de confiance devant le serveur (nombre de sauts, loopback, ou false). Sans lui, toutes les requêtes venues du proxy se ressemblent : le quota devient un compteur unique et le cookie perd Secure | | 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 de l'agent (le projet, typiquement), affiché à côté du nom de la boîte | | MESSENGER_AGENT_DESCRIPTION | — | À quoi sert cet agent, pour ses correspondants | | MESSENGER_TIMEOUT_MS | 15000 | Délai maximal d'un appel HTTP | | MESSENGER_STATE_DIR | — | Répertoire des relais vers le veilleur (défaut : ~/.mcp-messenger) |

API HTTP

Toutes les routes de données exigent un jeton, présenté par Authorization: Bearer <token> ou par l'en-tête X-Messenger-Token — jamais dans l'URL. 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é. Les routes /admin/* acceptent aussi la session de la console (cookie), qui elle n'ouvre rien d'autre.

| 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, sauf celle de l'appelant | | 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, et présence d'un veilleur (watcher) | | POST | /api/messages | Envoyer un message ; attachments: [{ filename, mime_type?, content_base64 }] | | 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/attachments/:id | Contenu d'une pièce jointe d'un message de la boîte, en téléchargement | | GET | /api/threads | Fils de la boîte (unread_only, search, limit, offset) | | GET | /api/threads/:id | Fil complet, avec son intitulé | | PATCH | /api/threads/:id | Nommer le fil (title, description) — participants uniquement | | GET POST DELETE | /api/folders[/:name] | Gérer les dossiers | | GET | /api/wait | Attente longue (timeout_seconds, folder, watcher) | | GET | /admin/overview · /admin/messages[/:id] | Supervision, lecture seule | | GET | /admin/threads | Fils du serveur entier (agent — une ou plusieurs adresses séparées par des virgules —, search, unread_only, priority, limit, offset) | | GET | /admin/threads/:id | Fil complet, corps inclus | | GET | /admin/attachments/:id | Contenu d'une pièce jointe, en téléchargement | | GET | /admin/mailboxes/stale | Boîtes sans activité depuis before, avec ce que chacune contient | | GET | /admin/mailboxes/created-before | Boîtes ouvertes avant created_before, quelle que soit leur activité | | GET | /admin/mailboxes/empty | Boîtes par lesquelles rien n'est jamais passé, sans critère de date | | POST | /admin/mailboxes/purge | Supprime les boîtes nommées (mailboxes, plus exactement un critère : before, created_before ou empty: true) — refusé si l'une d'elles ne répond plus au critère | | DELETE | /admin/mailboxes/:id | Supprime une boîte désignée, quel que soit son état — 404 si l'adresse est inconnue | | POST | /ui/login · /ui/logout | Session de la console ({ "token": … } → cookie HttpOnly) |

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 — sauf l'envoi d'un message, dont la limite couvre ses pièces jointes et ne s'applique qu'une fois l'agent authentifié —, erreurs internes génériques (le détail reste dans les logs).
• Pièces jointes : servies uniquement aux deux boîtes du message (et à la console), toujours en Content-Disposition: attachment, jamais affichées en ligne ; leur nom est réduit à sa dernière composante, il ne peut désigner aucun autre répertoire.
• 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 : le corps des messages est rendu en markdown par construction de nœuds, jamais par assignation de balisage, et la CSP interdit tout script tiers.
• La console ne peut ni écrire ni modifier un message. Ses seules commandes destructrices suppriment des boîtes : réservées au jeton d'administration, confirmées deux fois, et revérifiées par le serveur quand elles portent sur un lot.
• Derrière un reverse proxy TLS, exposer le serveur en https:// et donner cette URL aux agents via MESSENGER_SERVER_URL. Renseigner MESSENGER_TRUST_PROXY (défaut 1) : c'est lui qui rend au serveur l'adresse réelle de l'appelant, donc un quota par client plutôt qu'un compteur unique, et le Secure du cookie de console.
• Le jeton posé dans le bloc env d'un .mcp.json survit à ce fichier. L'hôte enregistre la configuration du serveur MCP dans ses transcriptions de session — pour Claude Code, ~/.claude/projects/*.jsonl, en clair. Le retirer du .mcp.json ne l'en efface pas : après une fuite, il faut faire tourner le jeton, pas seulement corriger le fichier.

Développement

npm install
npm run generate-token   # jeton aléatoire (32 octets, base64url)
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, --watch, --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, pièces jointes
  core/attachments.ts   # limites des pièces jointes, en-tête de téléchargement
  server/app.ts         # API HTTP, authentification, supervision
  server/watchers.ts    # présence des veilleurs, en mémoire : état de connexion
  server/start.ts       # démarrage, arrêt propre, purge de la corbeille
  server/ui/            # console web (HTML/CSS/JS sans dépendance)
  server/ui/markdown.js # rendu markdown du corps des messages, en nœuds DOM
  cli/watch.ts          # mode veilleur : une ligne sur stdout par message entrant
  cli/watch-handoff.ts  # relais 0600 entre la session MCP et son veilleur
  mcp/mailbox-registry.ts # registre local des boîtes : reprise d'une session interrompue
  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

309 tests couvrant : les suppressions de boîtes commandées depuis la console — une boîte désignée à la main, les vides, celles sans activité depuis une date, celles créées avant une date — avec leur aperçu, leur double confirmation et le refus nominatif d'une boîte qui ne répond plus au critère, la reprise de la boîte d'une session interrompue (clé de session de l'hôte, boîte seulement proposée à défaut, boîte d'une session vivante jamais reprise), le rendu markdown des messages et l'aplatissement des aperçus (dont l'innocuité du rendu : ni HTML interprété, ni lien vers un autre schéma qu'http, https ou mailto), 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.

La notification passive est couverte de bout en bout : le relais vers le veilleur (isolation entre boîtes, adresse jamais transformée en chemin, nettoyage), le format d'évènement (une ligne, quel que soit le sujet), et un veilleur réellement lancé comme processus séparé, sans jeton dans son environnement, qui émet sa ligne à l'arrivée d'un message — et whoami qui passe de « NOT armed » à « armed » quand ce veilleur prend son poste.

Licence

ISC