@imenam/mcp-messenger 1.0.7 → 1.0.8

package/README.md

@@ -248,6 +248,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

@@ -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: {
@@ -297,7 +300,12 @@ export async function callTool(client, name, rawArgs) {
             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)"}`,
+                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 +377,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 +391,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.8";

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.8";

package/package.json

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