@imenam/mcp-messenger 1.0.1

package/dist/src/logger.js

@@ -0,0 +1,22 @@
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const threshold = LEVELS[process.env.MESSENGER_LOG_LEVEL in LEVELS ? process.env.MESSENGER_LOG_LEVEL : "info"];
+function write(level, message, extra) {
+    if (LEVELS[level] < threshold)
+        return;
+    const detail = extra instanceof Error ? ` ${extra.stack ?? extra.message}` : extra !== undefined ? ` ${safeStringify(extra)}` : "";
+    process.stderr.write(`[messenger] ${new Date().toISOString()} ${level.toUpperCase()} ${message}${detail}\n`);
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export const logger = {
+    debug: (message, extra) => write("debug", message, extra),
+    info: (message, extra) => write("info", message, extra),
+    warn: (message, extra) => write("warn", message, extra),
+    error: (message, extra) => write("error", message, extra),
+};

package/dist/src/mcp/start.d.ts

@@ -0,0 +1,16 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type AgentConfig } from "../config.js";
+import { MessengerClient } from "../client/messenger-client.js";
+/** Serveur MCP prêt à être branché sur n'importe quel transport (stdio en production, mémoire en test). */
+export declare function createMcpServer(client: MessengerClient): Server;
+/**
+ * Donne son adresse à la session.
+ *
+ * Avec `MESSENGER_AGENT_ID`, l'adresse est fixe et partagée par toutes les sessions qui
+ * utilisent cette configuration. Sans elle — le cas normal — une boîte neuve est allouée
+ * pour cette session : deux agents lancés dans le même projet ne se marchent pas dessus.
+ * L'identifiant est opaque : c'est une adresse à transmettre, pas un rôle à deviner.
+ */
+export declare function resolveIdentity(client: MessengerClient, config: AgentConfig): Promise<string>;
+/** Point d'entrée du mode MCP (mode par défaut, sans argument). */
+export declare function runMcpMode(): Promise<void>;

package/dist/src/mcp/start.js

@@ -0,0 +1,76 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { loadAgentConfig } from "../config.js";
+import { MessengerClient, MessengerClientError } from "../client/messenger-client.js";
+import { newId } from "../core/ids.js";
+import { logger } from "../logger.js";
+import { APP_VERSION } from "../version.js";
+import { TOOLS, callTool } from "./tools.js";
+/** 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: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const text = await callTool(client, name, args);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`tool ${name} failed: ${message}`);
+            // Une erreur d'outil est une réponse, pas un plantage : l'agent doit pouvoir la lire.
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    });
+    return server;
+}
+/**
+ * Donne son adresse à la session.
+ *
+ * Avec `MESSENGER_AGENT_ID`, l'adresse est fixe et partagée par toutes les sessions qui
+ * utilisent cette configuration. Sans elle — le cas normal — une boîte neuve est allouée
+ * pour cette session : deux agents lancés dans le même projet ne se marchent pas dessus.
+ * L'identifiant est opaque : c'est une adresse à transmettre, pas un rôle à deviner.
+ */
+export async function resolveIdentity(client, config) {
+    if (config.agentId) {
+        client.setAgentId(config.agentId, { own: true });
+        await client.register();
+        return config.agentId;
+    }
+    // `fresh` fait échouer l'enregistrement si l'adresse existe déjà : la collision, même
+    // improbable sur 64 bits d'aléa, ne peut pas faire atterrir deux sessions au même endroit.
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const candidate = newId("box");
+        client.setAgentId(candidate, { own: true });
+        try {
+            await client.register({ fresh: true });
+            return candidate;
+        }
+        catch (error) {
+            if (error instanceof MessengerClientError && error.status === 409)
+                continue;
+            throw error;
+        }
+    }
+    throw new Error("could not allocate a mailbox: too many id collisions");
+}
+/** Point d'entrée du mode MCP (mode par défaut, sans argument). */
+export async function runMcpMode() {
+    const config = loadAgentConfig();
+    const client = new MessengerClient(config);
+    // Un serveur momentanément injoignable ne doit pas empêcher la session MCP de démarrer :
+    // l'agent verra l'erreur au premier outil appelé, et pourra réessayer.
+    try {
+        const agentId = await resolveIdentity(client, config);
+        logger.info(`mailbox \`${agentId}\` ready on ${config.serverUrl}`);
+    }
+    catch (error) {
+        logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const server = createMcpServer(client);
+    await server.connect(new StdioServerTransport());
+    logger.info(`mcp-messenger v${APP_VERSION} ready (${TOOLS.length} tools)`);
+}

package/dist/src/mcp/tools.d.ts

@@ -0,0 +1,14 @@
+import type { MessengerClient } from "../client/messenger-client.js";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOLS: ToolDefinition[];
+/**
+ * Exécute un outil et renvoie le texte présenté à l'agent.
+ *
+ * Les erreurs (validation, réseau, refus du serveur) remontent en exception : c'est la
+ * couche MCP qui les transforme en réponse `isError`.
+ */
+export declare function callTool(client: MessengerClient, name: string, rawArgs: unknown): Promise<string>;

package/dist/src/mcp/tools.js

@@ -0,0 +1,403 @@
+import { z } from "zod";
+import { PRIORITIES, SYSTEM_FOLDERS } from "../core/types.js";
+const FOLDER_HINT = `Folder name. System folders: ${SYSTEM_FOLDERS.join(", ")}. Custom folders come from list_folders.`;
+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.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "attach_to_mailbox",
+        description: "Read and write from another mailbox, given its address — typically to resume the work of an earlier session whose address the user hands over. Call it with no argument to go back to this session's own mailbox.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mailbox_id: {
+                    type: "string",
+                    description: "Mailbox address to attach to. Omit to return to this session's own mailbox.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_mailbox_label",
+        description: "Give this mailbox a human-readable label and description, so the user can recognise it in the directory and in the web console. Addresses are opaque: a label is what makes a mailbox findable later.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                label: { type: "string", description: "Short name, e.g. 'Refactor du parser'." },
+                description: { type: "string", description: "What this session is working on." },
+            },
+            required: ["label"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_agents",
+        description: "List the agents known to the mailbox server, with their description and last activity. Use it to find the address of the agent you want to write to.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "send_message",
+        description: "Send a message to one or more agents, identified by their mailbox address. Set reply_to to answer an existing message and keep the thread together.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to: {
+                    type: "array",
+                    items: { type: "string" },
+                    minItems: 1,
+                    description: "Recipient agent ids (mailbox addresses).",
+                },
+                cc: { type: "array", items: { type: "string" }, description: "Agents to keep in copy." },
+                subject: { type: "string", description: "Short subject line." },
+                body: { type: "string", description: "Message body, plain text or markdown." },
+                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." },
+            },
+            required: ["to", "subject", "body"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_messages",
+        description: "List messages in this agent's mailbox, newest first, with a short preview. Filter by folder, unread state, sender, thread or free text.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                folder: { type: "string", description: FOLDER_HINT + " Defaults to inbox." },
+                unread_only: { type: "boolean", description: "Keep only unread messages." },
+                from: { type: "string", description: "Only messages sent by this agent id." },
+                thread_id: { type: "string", description: "Only messages of this thread." },
+                search: { type: "string", description: "Free text matched against subject and body." },
+                limit: { type: "number", description: "1-100, defaults to 25." },
+                offset: { type: "number", description: "Pagination offset, defaults to 0." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "read_message",
+        description: "Read one message in full. Marks it as read unless mark_read is false.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message_id: { type: "string", description: "Id returned by list_messages." },
+                mark_read: { type: "boolean", description: "Defaults to true." },
+            },
+            required: ["message_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_thread",
+        description: "Read every message of a thread visible to this agent, oldest first — the full conversation.",
+        inputSchema: {
+            type: "object",
+            properties: { thread_id: { type: "string", description: "Thread id shown on any message." } },
+            required: ["thread_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "mark_messages",
+        description: "Mark messages as read or unread, and/or star or unstar them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message_ids: { type: "array", items: { type: "string" }, minItems: 1 },
+                read: { type: "boolean", description: "true = read, false = unread." },
+                starred: { type: "boolean", description: "true = starred, false = unstarred." },
+            },
+            required: ["message_ids"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "move_messages",
+        description: "Move messages to another folder, the way an email client files a conversation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message_ids: { type: "array", items: { type: "string" }, minItems: 1 },
+                folder: { type: "string", description: FOLDER_HINT },
+            },
+            required: ["message_ids", "folder"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_messages",
+        description: "Send messages to the trash folder, or erase them from this mailbox for good when permanent is true. Other recipients keep their own copy.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message_ids: { type: "array", items: { type: "string" }, minItems: 1 },
+                permanent: { type: "boolean", description: "Defaults to false (moves to trash)." },
+            },
+            required: ["message_ids"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_folders",
+        description: "List this mailbox's folders with their total and unread counts.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "create_folder",
+        description: "Create a custom folder in this mailbox, to sort messages by topic or by correspondent.",
+        inputSchema: {
+            type: "object",
+            properties: { name: { type: "string", description: "1-40 chars: lowercase letters, digits, space, - or _." } },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_folder",
+        description: "Delete a custom folder. Its messages go back to inbox (or sent for your own copies).",
+        inputSchema: {
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wait_for_message",
+        description: "Block until a new message lands in the mailbox, or until the timeout expires. Use it to wait for another agent's answer instead of polling list_messages.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeout_seconds: { type: "number", description: "1-300, defaults to 30." },
+                folder: { type: "string", description: "Folder to watch, defaults to inbox." },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+const schemas = {
+    send_message: z.object({
+        to: z.union([z.string(), z.array(z.string()).min(1)]),
+        cc: z.union([z.string(), z.array(z.string())]).optional(),
+        subject: z.string().min(1),
+        body: z.string().min(1),
+        priority: z.enum(PRIORITIES).optional(),
+        reply_to: z.string().optional(),
+    }),
+    list_messages: z.object({
+        folder: z.string().optional(),
+        unread_only: z.boolean().optional(),
+        from: z.string().optional(),
+        thread_id: z.string().optional(),
+        search: z.string().optional(),
+        limit: z.number().int().optional(),
+        offset: z.number().int().optional(),
+    }),
+    read_message: z.object({ message_id: z.string().min(1), mark_read: z.boolean().optional() }),
+    get_thread: z.object({ thread_id: z.string().min(1) }),
+    mark_messages: z.object({
+        message_ids: z.array(z.string().min(1)).min(1),
+        read: z.boolean().optional(),
+        starred: z.boolean().optional(),
+    }),
+    move_messages: z.object({ message_ids: z.array(z.string().min(1)).min(1), folder: z.string().min(1) }),
+    delete_messages: z.object({ message_ids: z.array(z.string().min(1)).min(1), permanent: z.boolean().optional() }),
+    attach_to_mailbox: z.object({ mailbox_id: z.string().trim().min(1).optional() }),
+    set_mailbox_label: z.object({ label: z.string().trim().min(1).max(200), description: z.string().max(2000).optional() }),
+    create_folder: z.object({ name: z.string().min(1) }),
+    delete_folder: z.object({ name: z.string().min(1) }),
+    wait_for_message: z.object({ timeout_seconds: z.number().int().optional(), folder: z.string().optional() }),
+};
+/**
+ * Exécute un outil et renvoie le texte présenté à l'agent.
+ *
+ * Les erreurs (validation, réseau, refus du serveur) remontent en exception : c'est la
+ * couche MCP qui les transforme en réponse `isError`.
+ */
+export async function callTool(client, name, rawArgs) {
+    const args = (rawArgs ?? {});
+    switch (name) {
+        case "whoami": {
+            const stats = await client.stats();
+            const health = await client.health().catch(() => null);
+            const folders = stats.folders.map((f) => `  ${f.name.padEnd(12)} ${f.total} message(s), ${f.unread} unread`);
+            const lines = [
+                `Mailbox address: ${client.agentId}`,
+                "  ↳ give this address to another agent so it can write to you.",
+            ];
+            if (client.isAttachedElsewhere) {
+                lines.push(`Attached to another mailbox. This session's own mailbox is ${client.sessionAgentId}.`);
+            }
+            lines.push(`Mailbox server: ${client.serverUrl}${health ? ` (v${health.version}, ${health.agents} mailbox(es))` : " (unreachable health endpoint)"}`, `Unread (excluding trash): ${stats.unread_total}`, "Folders:", ...folders);
+            return lines.join("\n");
+        }
+        case "attach_to_mailbox": {
+            const input = schemas.attach_to_mailbox.parse(args);
+            if (!input.mailbox_id) {
+                const own = client.sessionAgentId;
+                if (!own)
+                    throw new Error("this session has no mailbox of its own to return to");
+                client.setAgentId(own);
+                return `Back to this session's own mailbox: ${own}`;
+            }
+            // Vérifie que la boîte existe avant de basculer : une faute de frappe créerait
+            // silencieusement une boîte vide, et l'agent croirait avoir repris le travail.
+            const target = await client.getAgent(input.mailbox_id);
+            client.setAgentId(target.id);
+            const attachedStats = await client.stats();
+            return [
+                `Attached to mailbox ${target.id}${target.display_name ? ` (${target.display_name})` : ""}.`,
+                target.description ? `Description: ${target.description}` : null,
+                `Unread (excluding trash): ${attachedStats.unread_total}`,
+                client.sessionAgentId && client.sessionAgentId !== target.id
+                    ? `This session's own mailbox remains ${client.sessionAgentId} — attach_to_mailbox with no argument goes back to it.`
+                    : null,
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        case "set_mailbox_label": {
+            const input = schemas.set_mailbox_label.parse(args);
+            const agent = await client.updateProfile({ display_name: input.label, description: input.description ?? null });
+            return `Mailbox ${agent.id} labelled "${agent.display_name}".`;
+        }
+        case "list_agents": {
+            const agents = await client.listAgents();
+            if (agents.length === 0)
+                return "No agent registered yet on this server.";
+            return agents
+                .map((agent) => {
+                const flags = [agent.id === client.agentId ? "you" : null, agent.registered ? null : "never connected"]
+                    .filter(Boolean)
+                    .join(", ");
+                const title = agent.display_name ? `${agent.id} — ${agent.display_name}` : agent.id;
+                const seen = agent.last_seen_at ? `last seen ${agent.last_seen_at}` : "never seen";
+                return [`• ${title}${flags ? ` (${flags})` : ""}`, `  ${agent.description ?? "no description"}`, `  ${seen}`].join("\n");
+            })
+                .join("\n");
+        }
+        case "send_message": {
+            const input = schemas.send_message.parse(args);
+            const result = await client.sendMessage({
+                to: asArray(input.to),
+                cc: asArray(input.cc),
+                subject: input.subject,
+                body: input.body,
+                priority: input.priority,
+                reply_to: input.reply_to ?? null,
+            });
+            const lines = [
+                `Message sent: ${result.message_id}`,
+                `Thread: ${result.thread_id}`,
+                `Delivered to: ${result.delivered_to.join(", ")}`,
+            ];
+            if (result.unknown_recipients.length > 0) {
+                lines.push(`Warning — never connected to this server, the message will wait in their mailbox: ${result.unknown_recipients.join(", ")}`);
+            }
+            return lines.join("\n");
+        }
+        case "list_messages": {
+            const input = schemas.list_messages.parse(args);
+            const folder = input.folder ?? "inbox";
+            const messages = await client.listMessages({ ...input, folder });
+            if (messages.length === 0)
+                return `No message in \`${folder}\` matching these filters.`;
+            return [`${messages.length} message(s) in \`${folder}\`:`, "", ...messages.map(formatSummary)].join("\n");
+        }
+        case "read_message": {
+            const input = schemas.read_message.parse(args);
+            const message = await client.getMessage(input.message_id, input.mark_read ?? true);
+            return formatMessage(message);
+        }
+        case "get_thread": {
+            const input = schemas.get_thread.parse(args);
+            const messages = await client.getThread(input.thread_id);
+            return [`Thread ${input.thread_id} — ${messages.length} message(s):`, "", ...messages.map(formatMessage)].join("\n\n---\n\n");
+        }
+        case "mark_messages": {
+            const input = schemas.mark_messages.parse(args);
+            if (input.read === undefined && input.starred === undefined) {
+                throw new Error("provide `read` and/or `starred`");
+            }
+            const updated = await client.markMessages(input.message_ids, { read: input.read, starred: input.starred });
+            const changes = [
+                input.read === undefined ? null : input.read ? "read" : "unread",
+                input.starred === undefined ? null : input.starred ? "starred" : "unstarred",
+            ].filter(Boolean);
+            return `${updated} message(s) marked ${changes.join(" + ")}.`;
+        }
+        case "move_messages": {
+            const input = schemas.move_messages.parse(args);
+            const updated = await client.moveMessages(input.message_ids, input.folder);
+            return `${updated} message(s) moved to \`${input.folder}\`.`;
+        }
+        case "delete_messages": {
+            const input = schemas.delete_messages.parse(args);
+            const deleted = await client.deleteMessages(input.message_ids, input.permanent ?? false);
+            return input.permanent
+                ? `${deleted} message(s) permanently removed from this mailbox.`
+                : `${deleted} message(s) moved to trash.`;
+        }
+        case "list_folders": {
+            const folders = await client.listFolders();
+            return folders
+                .map((f) => `${f.name.padEnd(14)} ${String(f.total).padStart(4)} message(s), ${f.unread} unread${f.system ? "  (system)" : ""}`)
+                .join("\n");
+        }
+        case "create_folder": {
+            const input = schemas.create_folder.parse(args);
+            const folder = await client.createFolder(input.name);
+            return `Folder \`${folder.name}\` created.`;
+        }
+        case "delete_folder": {
+            const input = schemas.delete_folder.parse(args);
+            const moved = await client.deleteFolder(input.name);
+            return `Folder \`${input.name}\` deleted; ${moved} message(s) moved back to inbox.`;
+        }
+        case "wait_for_message": {
+            const input = schemas.wait_for_message.parse(args);
+            const timeout = Math.min(Math.max(input.timeout_seconds ?? 30, 1), 300);
+            const result = await client.waitForMessage(timeout, input.folder);
+            if (result.timed_out || !result.message) {
+                return `No new message after ${timeout}s.`;
+            }
+            return ["New message:", "", formatMessage(result.message)].join("\n");
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+function asArray(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function formatSummary(message) {
+    const flags = [message.read ? " " : "•", message.starred ? "★" : " "].join("");
+    const priority = message.priority === "normal" ? "" : ` [${message.priority}]`;
+    return [
+        `${flags} ${message.subject}${priority}`,
+        `   from ${message.from} to ${message.to.join(", ") || "—"}${message.cc.length ? ` (cc ${message.cc.join(", ")})` : ""} · ${message.created_at}`,
+        `   ${message.preview}`,
+        `   id ${message.message_id} · thread ${message.thread_id}`,
+    ].join("\n");
+}
+function formatMessage(message) {
+    const header = [
+        `Subject: ${message.subject}`,
+        `From: ${message.from}`,
+        `To: ${message.to.join(", ") || "—"}`,
+        message.cc.length ? `Cc: ${message.cc.join(", ")}` : null,
+        `Date: ${message.created_at}`,
+        `Priority: ${message.priority}`,
+        `Folder: ${message.folder}${message.read ? "" : " (unread)"}${message.starred ? " ★" : ""}`,
+        `Id: ${message.message_id} · Thread: ${message.thread_id}${message.in_reply_to ? ` · reply to ${message.in_reply_to}` : ""}`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return `${header}\n\n${message.body}`;
+}

package/dist/src/server/app.d.ts

@@ -0,0 +1,15 @@
+import express from "express";
+import type { ServerConfig } from "../config.js";
+import { MessageStore } from "../core/store.js";
+declare global {
+    namespace Express {
+        interface Request {
+            agentId?: string;
+        }
+    }
+}
+export interface AppOptions {
+    store: MessageStore;
+    config: ServerConfig;
+}
+export declare function createApp({ store, config }: AppOptions): express.Express;