@imenam/mcp-messenger 1.0.1

package/dist/src/client/messenger-client.js

@@ -0,0 +1,183 @@
+/** Échec d'un appel au serveur boîte aux lettres (réseau, authentification ou métier). */
+export class MessengerClientError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "MessengerClientError";
+    }
+}
+/**
+ * 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 class MessengerClient {
+    config;
+    /** Boîte courante. Modifiable en cours de session par `attach_to_mailbox`. */
+    currentAgentId;
+    /** Boîte allouée à cette session : on peut toujours y revenir après un rattachement. */
+    ownAgentId;
+    constructor(config) {
+        this.config = config;
+        this.currentAgentId = config.agentId;
+        this.ownAgentId = config.agentId;
+    }
+    get agentId() {
+        if (!this.currentAgentId) {
+            throw new MessengerClientError("no mailbox attached yet: the session has no address.");
+        }
+        return this.currentAgentId;
+    }
+    /** Adresse fixée par la configuration, s'il y en a une. */
+    get pinnedAgentId() {
+        return this.config.agentId;
+    }
+    /** `own: true` désigne la boîte de la session, celle sur laquelle on peut revenir. */
+    setAgentId(agentId, options = {}) {
+        this.currentAgentId = agentId;
+        if (options.own)
+            this.ownAgentId = agentId;
+    }
+    /** Adresse de la boîte propre à cette session. */
+    get sessionAgentId() {
+        return this.ownAgentId;
+    }
+    /** true si la session lit une boîte autre que la sienne. */
+    get isAttachedElsewhere() {
+        return this.ownAgentId !== null && this.currentAgentId !== this.ownAgentId;
+    }
+    get serverUrl() {
+        return this.config.serverUrl;
+    }
+    async health() {
+        return this.request("GET", "/health");
+    }
+    /** Enregistre la boîte courante. `fresh` exige une adresse encore inconnue du serveur. */
+    async register(options = {}) {
+        const { agent } = await this.request("POST", "/api/agents/register", {
+            body: {
+                display_name: this.config.displayName,
+                description: this.config.description,
+                fresh: options.fresh ?? false,
+            },
+        });
+        return agent;
+    }
+    /** Renomme la boîte courante, pour la rendre reconnaissable dans l'annuaire. */
+    async updateProfile(profile) {
+        const { agent } = await this.request("PATCH", "/api/agents/me", { body: profile });
+        return agent;
+    }
+    async getAgent(agentId) {
+        const { agent } = await this.request("GET", `/api/agents/${encodeURIComponent(agentId)}`);
+        return agent;
+    }
+    async listAgents() {
+        const { agents } = await this.request("GET", "/api/agents");
+        return agents;
+    }
+    async stats() {
+        return this.request("GET", "/api/mailbox");
+    }
+    async sendMessage(input) {
+        return this.request("POST", "/api/messages", { body: input });
+    }
+    async listMessages(options = {}) {
+        const { messages } = await this.request("GET", "/api/messages", {
+            query: { ...options },
+        });
+        return messages;
+    }
+    async getMessage(messageId, markRead = true) {
+        return this.request("GET", `/api/messages/${encodeURIComponent(messageId)}`, {
+            query: { mark_read: markRead },
+        });
+    }
+    async markMessages(messageIds, state) {
+        const { updated } = await this.request("POST", "/api/messages/mark", {
+            body: { message_ids: messageIds, ...state },
+        });
+        return updated;
+    }
+    async moveMessages(messageIds, folder) {
+        const { updated } = await this.request("POST", "/api/messages/move", {
+            body: { message_ids: messageIds, folder },
+        });
+        return updated;
+    }
+    async deleteMessages(messageIds, permanent = false) {
+        const { deleted } = await this.request("POST", "/api/messages/delete", {
+            body: { message_ids: messageIds, permanent },
+        });
+        return deleted;
+    }
+    async getThread(threadId) {
+        const { messages } = await this.request("GET", `/api/threads/${encodeURIComponent(threadId)}`);
+        return messages;
+    }
+    async listFolders() {
+        const { folders } = await this.request("GET", "/api/folders");
+        return folders;
+    }
+    async createFolder(name) {
+        const { folder } = await this.request("POST", "/api/folders", { body: { name } });
+        return folder;
+    }
+    async deleteFolder(name) {
+        const { moved } = await this.request("DELETE", `/api/folders/${encodeURIComponent(name)}`);
+        return moved;
+    }
+    async waitForMessage(timeoutSeconds, folder) {
+        // L'attente longue peut dépasser le délai HTTP par défaut : on l'étend d'une marge.
+        return this.request("GET", "/api/wait", {
+            query: { timeout_seconds: timeoutSeconds, folder },
+            timeoutMs: timeoutSeconds * 1000 + this.config.timeoutMs,
+        });
+    }
+    async request(method, routePath, options = {}) {
+        const url = new URL(this.config.serverUrl + routePath);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const headers = { "x-agent-id": this.agentId, accept: "application/json" };
+        if (this.config.token)
+            headers.authorization = `Bearer ${this.config.token}`;
+        if (options.body !== undefined)
+            headers["content-type"] = "application/json";
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? this.config.timeoutMs),
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new MessengerClientError(`cannot reach the messenger server at ${this.config.serverUrl}: ${reason}`);
+        }
+        const text = await response.text();
+        const payload = text ? safeParse(text) : null;
+        if (!response.ok) {
+            const detail = payload && typeof payload === "object" && "error" in payload
+                ? String(payload.error)
+                : text.slice(0, 300) || response.statusText;
+            throw new MessengerClientError(detail, response.status);
+        }
+        return payload;
+    }
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: text };
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,36 @@
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Le serveur n'écoute jamais ailleurs : la boîte aux lettres reste locale à la machine. */
+export declare const SERVER_HOST = "127.0.0.1";
+export interface ServerConfig {
+    port: number;
+    /** Toujours `127.0.0.1` — non configurable. */
+    host: string;
+    dbPath: string;
+    /** Jeton partagé accepté pour tous les agents (ignoré si `agentTokens` est renseigné). */
+    token: string | null;
+    /** Jeton dédié par agent : `agent_id -> token`. Prioritaire sur `token`. */
+    agentTokens: Map<string, string>;
+    /** Jeton de l'interface de supervision. À défaut, `token` fait office. Jamais nul. */
+    adminToken: string;
+    rateLimit: {
+        max: number;
+        windowMs: number;
+    };
+    trashRetentionDays: number;
+    /** Plafond d'attente d'un `wait_for_message` (secondes). */
+    maxWaitSeconds: number;
+}
+export interface AgentConfig {
+    /** null = une boîte propre à cette session est allouée au démarrage. */
+    agentId: string | null;
+    serverUrl: string;
+    token: string | null;
+    displayName: string | null;
+    description: string | null;
+    timeoutMs: number;
+}
+export declare function isLoopbackHost(host: string): boolean;
+export declare function loadServerConfig(env?: NodeJS.ProcessEnv): ServerConfig;
+export declare function loadAgentConfig(env?: NodeJS.ProcessEnv): AgentConfig;

package/dist/src/config.js

@@ -0,0 +1,110 @@
+import path from "node:path";
+/** Adresses sur lesquelles le serveur peut tourner sans authentification. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost", "0:0:0:0:0:0:0:1"]);
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/** Le serveur n'écoute jamais ailleurs : la boîte aux lettres reste locale à la machine. */
+export const SERVER_HOST = "127.0.0.1";
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host.trim().toLowerCase().replace(/^\[|\]$/g, ""));
+}
+export function loadServerConfig(env = process.env) {
+    const port = parseIntEnv(env.MESSENGER_PORT, 3600, "MESSENGER_PORT");
+    // L'interface d'écoute n'est pas un réglage : la boîte aux lettres reste sur la machine.
+    // Une valeur non-loopback est refusée plutôt qu'ignorée en silence.
+    const requestedHost = nonEmpty(env.MESSENGER_HOST);
+    if (requestedHost && !isLoopbackHost(requestedHost)) {
+        throw new ConfigError(`MESSENGER_HOST=${requestedHost} is refused: the mailbox always listens on ${SERVER_HOST}. ` +
+            "To reach it from another machine, put a reverse proxy in front of it.");
+    }
+    const dbPath = env.MESSENGER_DB_PATH?.trim()
+        ? path.resolve(env.MESSENGER_DB_PATH.trim())
+        : path.resolve(process.cwd(), "data", "messenger.db");
+    const token = nonEmpty(env.MESSENGER_TOKEN);
+    const agentTokens = parseAgentTokens(env.MESSENGER_AGENT_TOKENS);
+    // Aucun démarrage sans jeton : un serveur qui tourne est un serveur authentifié.
+    if (!token && agentTokens.size === 0) {
+        throw new ConfigError("a token is required: set MESSENGER_TOKEN (shared) or MESSENGER_AGENT_TOKENS (one token per agent).");
+    }
+    const adminToken = nonEmpty(env.MESSENGER_ADMIN_TOKEN) ?? token;
+    if (!adminToken) {
+        throw new ConfigError("MESSENGER_ADMIN_TOKEN is required when only MESSENGER_AGENT_TOKENS is set: the web console needs its own token.");
+    }
+    return {
+        port,
+        host: SERVER_HOST,
+        dbPath,
+        token,
+        agentTokens,
+        adminToken,
+        rateLimit: {
+            max: parseIntEnv(env.MESSENGER_RATE_LIMIT_MAX, 600, "MESSENGER_RATE_LIMIT_MAX"),
+            windowMs: parseIntEnv(env.MESSENGER_RATE_LIMIT_WINDOW_MINUTES, 15, "MESSENGER_RATE_LIMIT_WINDOW_MINUTES") * 60_000,
+        },
+        trashRetentionDays: parseIntEnv(env.MESSENGER_TRASH_RETENTION_DAYS, 30, "MESSENGER_TRASH_RETENTION_DAYS"),
+        maxWaitSeconds: parseIntEnv(env.MESSENGER_MAX_WAIT_SECONDS, 300, "MESSENGER_MAX_WAIT_SECONDS"),
+    };
+}
+export function loadAgentConfig(env = process.env) {
+    // Adresse fixe optionnelle. Sans elle, chaque session reçoit sa propre boîte : deux
+    // sessions ouvertes sur le même projet ne partagent donc pas leur courrier.
+    const agentId = nonEmpty(env.MESSENGER_AGENT_ID);
+    if (agentId && /\s/.test(agentId)) {
+        throw new ConfigError(`MESSENGER_AGENT_ID must not contain whitespace (got "${agentId}").`);
+    }
+    const rawUrl = nonEmpty(env.MESSENGER_SERVER_URL);
+    if (!rawUrl) {
+        throw new ConfigError("MESSENGER_SERVER_URL is required in MCP mode (e.g. http://127.0.0.1:3600).");
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`MESSENGER_SERVER_URL is not a valid URL: ${rawUrl}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ConfigError(`MESSENGER_SERVER_URL must use http or https (got ${url.protocol}).`);
+    }
+    return {
+        agentId,
+        serverUrl: rawUrl.replace(/\/+$/, ""),
+        token: nonEmpty(env.MESSENGER_TOKEN),
+        displayName: nonEmpty(env.MESSENGER_AGENT_NAME),
+        description: nonEmpty(env.MESSENGER_AGENT_DESCRIPTION),
+        timeoutMs: parseIntEnv(env.MESSENGER_TIMEOUT_MS, 15_000, "MESSENGER_TIMEOUT_MS"),
+    };
+}
+function parseAgentTokens(raw) {
+    const map = new Map();
+    if (!raw?.trim())
+        return map;
+    for (const pair of raw.split(",")) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const separator = trimmed.indexOf(":");
+        if (separator <= 0 || separator === trimmed.length - 1) {
+            throw new ConfigError(`MESSENGER_AGENT_TOKENS entry must look like "agent_id:token" (got "${trimmed}").`);
+        }
+        map.set(trimmed.slice(0, separator).trim(), trimmed.slice(separator + 1).trim());
+    }
+    return map;
+}
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}
+function parseIntEnv(value, fallback, name) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new ConfigError(`${name} must be a non-negative number (got "${value}").`);
+    }
+    return Math.trunc(parsed);
+}

package/dist/src/core/ids.d.ts

@@ -0,0 +1,2 @@
+/** Identifiants courts, lisibles dans une conversation d'agent : `msg_a1b2c3d4e5f6a7b8`. */
+export declare function newId(prefix: string): string;

package/dist/src/core/ids.js

@@ -0,0 +1,5 @@
+import { randomBytes } from "node:crypto";
+/** Identifiants courts, lisibles dans une conversation d'agent : `msg_a1b2c3d4e5f6a7b8`. */
+export function newId(prefix) {
+    return `${prefix}_${randomBytes(8).toString("hex")}`;
+}

package/dist/src/core/store.d.ts

@@ -0,0 +1,93 @@
+import { EventEmitter } from "node:events";
+import { type Agent, type DeliveryRole, type FolderInfo, type ListMessagesOptions, type MailboxStats, type Message, type MessageSummary, type SendMessageInput, type SendMessageResult } from "./types.js";
+/** Erreur métier : traduite en 4xx par la couche HTTP, en message d'outil côté MCP. */
+export declare class MessengerError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export interface StoreEvents {
+    /** Émis pour chaque destinataire d'un message, y compris la copie « sent » de l'expéditeur. */
+    message: [{
+        agent_id: string;
+        message_id: string;
+        folder: string;
+        role: DeliveryRole;
+    }];
+}
+/**
+ * Boîte aux lettres persistée en SQLite.
+ *
+ * Un message est stocké une seule fois (table `messages`) puis « livré » via une ligne
+ * par couple (agent, rôle) dans `deliveries`. C'est cette ligne qui porte l'état propre
+ * à chaque agent : dossier, lu/non lu, suivi. Un agent ne voit que ses propres livraisons.
+ */
+export declare class MessageStore extends EventEmitter<StoreEvents> {
+    private readonly db;
+    constructor(dbPath: string);
+    private migrate;
+    close(): void;
+    /** Crée la fiche au besoin. `registered: false` = agent connu seulement comme destinataire. */
+    ensureAgent(id: string, opts?: {
+        registered?: boolean;
+        display_name?: string | null;
+        description?: string | null;
+    }): Agent;
+    touchAgent(id: string): void;
+    getAgent(id: string): Agent | null;
+    listAgents(): Agent[];
+    sendMessage(input: SendMessageInput): SendMessageResult;
+    listMessages(agentId: string, opts?: ListMessagesOptions): MessageSummary[];
+    getMessage(agentId: string, messageId: string, markRead?: boolean): Message;
+    /** Tous les messages d'un fil visibles par l'agent, du plus ancien au plus récent. */
+    getThread(agentId: string, threadId: string): Message[];
+    markMessages(agentId: string, messageIds: string[], state: {
+        read?: boolean;
+        starred?: boolean;
+    }): number;
+    moveMessages(agentId: string, messageIds: string[], folder: string): number;
+    /** Sans `permanent`, le message part à la corbeille et reste récupérable. */
+    deleteMessages(agentId: string, messageIds: string[], permanent?: boolean): number;
+    listFolders(agentId: string): FolderInfo[];
+    createFolder(agentId: string, name: string): FolderInfo;
+    /** Les messages du dossier retournent dans `inbox` (ou `sent` pour les copies d'envoi). */
+    deleteFolder(agentId: string, name: string): number;
+    stats(agentId: string): MailboxStats;
+    /** Purge les livraisons restées en corbeille au-delà de `days`. Renvoie le nombre supprimé. */
+    purgeTrash(days: number): number;
+    /** Vue globale : tous les messages du serveur, indépendamment des boîtes. */
+    listAllMessages(opts?: {
+        search?: string;
+        agent?: string;
+        thread_id?: string;
+        limit?: number;
+        offset?: number;
+    }): MessageSummary[];
+    /** Message complet vu du serveur, avec l'état de lecture de chaque destinataire. */
+    getMessageAdmin(messageId: string): Message & {
+        deliveries: {
+            agent_id: string;
+            role: DeliveryRole;
+            folder: string;
+            read: boolean;
+        }[];
+    };
+    overview(): {
+        messages: number;
+        threads: number;
+        agents: (Agent & {
+            sent: number;
+            received: number;
+            unread: number;
+        })[];
+    };
+    private updateDeliveries;
+    /** Filtre les ids fournis sur ceux réellement livrés à cet agent (isolation des boîtes). */
+    private ownedMessageIds;
+    private assertFolderExists;
+    private recipientsFor;
+    private toSummary;
+    private toMessage;
+    /** Un message sans aucune livraison n'est plus lisible par personne : on le supprime. */
+    private dropOrphanMessages;
+}
+export declare function normalizeAgentId(id: string): string;