@imenam/mcp-messenger 1.0.7 → 1.0.9

package/README.md

@@ -224,9 +224,19 @@ 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.
+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.
@@ -248,6 +258,19 @@ de la boîte seul ne dit pas d'où l'agent écrit. L'annuaire (`list_agents`), `
 console web montrent donc toujours les deux, sous la forme `Agent · Boîte`. 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. 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

package/dist/src/mcp/start.js

@@ -8,9 +8,29 @@ import { newId } from "../core/ids.js";
 import { logger } from "../logger.js";
 import { APP_VERSION } from "../version.js";
 import { TOOLS, callTool } from "./tools.js";
+/**
+ * Ce que l'hôte reçoit à la poignée de main, avant le moindre appel d'outil.
+ *
+ * Deux confusions coûtent cher et n'apparaissent qu'au moment d'écrire, trop tard : croire
+ * que le nom d'agent désigne une session (il est partagé par toutes celles du projet), et
+ * recopier une adresse dans le corps d'un message (le serveur la pose déjà, la copie ment
+ * dès qu'elle vieillit). Les dire ici, c'est les dire avant l'erreur.
+ */
+const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
+
+Who you are, and who the others are — read this before writing to anyone:
+- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
+- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
+- So several mailboxes in \`list_agents\` can carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — it is another session of the same project, a different agent, with its own mailbox. Compare addresses, never names.
+- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
+
+Writing:
+- One message goes to exactly one agent, and never to yourself. To reach several agents, send each one its own message.
+- Never write a mailbox address in the body of a message. The server attaches the sender and the recipient to every message, and the reader sees them: an address copied by hand adds nothing and misleads as soon as it is stale or mistaken.
+- Call \`enable_notifications\` once at the start of the session and arm the watcher it hands you. Until then, no incoming message reaches you.`;
 /** Serveur MCP prêt à être branché sur n'importe quel transport (stdio en production, mémoire en test). */
 export function createMcpServer(client) {
-    const server = new Server({ name: "mcp-messenger", version: APP_VERSION }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "mcp-messenger", version: APP_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;

package/dist/src/mcp/tools.js

@@ -7,7 +7,7 @@ const FOLDER_HINT = `Folder name. System folders: ${SYSTEM_FOLDERS.join(", ")}.
 export const TOOLS = [
     {
         name: "whoami",
-        description: "Return this session's mailbox address, the server it is connected to, and unread counts per folder. The address is what another agent needs in order to write here: give it whenever someone asks how to reach you.",
+        description: "Return this session's mailbox address, the server it is connected to, and unread counts per folder. The address is what identifies this session: tell it to the user when they ask how to reach you. Other agents never need you to send it — list_agents gives it to them, and every message you send already carries it.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
@@ -73,13 +73,16 @@ export const TOOLS = [
     },
     {
         name: "send_message",
-        description: "Send a message to one agent, identified by its mailbox address. A message has a single recipient: to reach several agents, send each one its own message. Set reply_to to answer an existing message and keep the thread together.",
+        description: "Send a message to one agent, identified by its mailbox address. A message has a single recipient: to reach several agents, send each one its own message. Set reply_to to answer an existing message and keep the thread together. Never write a mailbox address in the body: the server attaches the sender and the recipient to every message, so an address copied by hand adds nothing and misleads as soon as it is wrong.",
         inputSchema: {
             type: "object",
             properties: {
                 to: { type: "string", description: "Recipient agent id (mailbox address). Exactly one recipient." },
                 subject: { type: "string", description: "Short subject line." },
-                body: { type: "string", description: "Message body, plain text or markdown." },
+                body: {
+                    type: "string",
+                    description: "Message body, plain text or markdown. Do not restate your own address or the recipient's here.",
+                },
                 priority: { type: "string", enum: [...PRIORITIES], description: "Defaults to normal." },
                 reply_to: { type: "string", description: "Id of the message being answered; the reply joins its thread." },
                 thread_name: {
@@ -296,8 +299,16 @@ export async function callTool(client, name, rawArgs) {
             const self = await client.getAgent(client.agentId).catch(() => null);
             const lines = [
                 `Mailbox address: ${client.agentId}`,
-                "  ↳ give this address to another agent so it can write to you.",
-                `Agent: ${self?.agent_name ?? "unnamed (set MESSENGER_AGENT_NAME in the MCP configuration)"}`,
+                // Personne n'a besoin qu'on la lui envoie : l'annuaire la donne, et chaque message
+                // la porte déjà. Le seul destinataire légitime est l'utilisateur, qui le demande.
+                "  ↳ this identifies this session. Other agents read it from list_agents and from the",
+                "    messages you send them — tell it to the user if asked, never inside a message body.",
+                self?.agent_name
+                    ? `Agent: ${self.agent_name}`
+                    : "Agent: unnamed (set MESSENGER_AGENT_NAME in the MCP configuration)",
+                // Le nom vient de la configuration : toutes les sessions du projet le portent. Le
+                // dire ici évite qu'un agent prenne une session homonyme pour la sienne.
+                "  ↳ this name is shared with every session of the same project; only the address above identifies you.",
                 self?.display_name
                     ? `Mailbox name: ${self.display_name}`
                     : "Mailbox name: none — call rename_mailbox so the user can tell this session apart from the others.",
@@ -369,7 +380,7 @@ export async function callTool(client, name, rawArgs) {
             const agents = await client.listAgents();
             if (agents.length === 0)
                 return "No other agent on this server yet.";
-            return agents
+            const directory = agents
                 .map((agent) => {
                 const flags = agent.registered ? "" : "never connected";
                 const names = formatAgentNames(agent);
@@ -383,6 +394,16 @@ export async function callTool(client, name, rawArgs) {
                 ].join("\n");
             })
                 .join("\n");
+            // Un nom d'agent est celui d'un projet, pas d'une session : plusieurs boîtes le
+            // portent, y compris celle de l'appelant. Sans ce rappel, un agent croise son propre
+            // nom d'agent dans cette liste et prend la boîte d'une autre session pour la sienne.
+            return [
+                directory,
+                "",
+                "Addresses identify sessions; agent names do not. Several mailboxes above may carry the same",
+                "agent name as yours — they are other sessions of the same project, never you: your own mailbox",
+                "is never listed here. Always write to an address taken from this list, never to a name.",
+            ].join("\n");
         }
         case "send_message": {
             const input = schemas.send_message.parse(args);

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.7";
+export declare const APP_VERSION = "1.0.9";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Généré par scripts/generate-version.js — ne pas modifier à la main.
-export const APP_VERSION = "1.0.7";
+export const APP_VERSION = "1.0.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-messenger",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "npm run build && vitest run",