@remit/mcp-server 0.11.0 → 0.12.0

package/dist/deps.d.ts

@@ -1,11 +1,11 @@
 import type { RemitClient } from "@remit/backend/client";
-import type { IAccountRepository, IAddressRepository, IFilterRepository, ILabelMailboxRepository, ILabelRepository, IMailboxRepository, IMessageLabelRepository, IMessageRepository, IOrganizeJobRequestRepository, IThreadMessageRepository, OrganizeJobEvent, QueueProducer } from "@remit/data-ports";
+import type { IAccountRepository, IAccountSettingRepository, IAddressRepository, IFilterRepository, ILabelMailboxRepository, ILabelRepository, IMailboxRepository, IMailboxSpecialUseRepository, IMessageLabelRepository, IMessageRepository, IOrganizeJobRequestRepository, IThreadMessageRepository, OrganizeJobEvent, QueueProducer } from "@remit/data-ports";
 import type { BodyPartMaterializer, BodySyncCue, MailboxQueueService, MaterializeLogger, MessageMoveService, OrganizeJobLogger } from "@remit/mailbox-service";
 import type { StorageService } from "@remit/storage-service";
 export declare const FOLDER_SETTLE_TIMEOUT_MS = 20000;
 export declare const FOLDER_POLL_INTERVAL_MS = 500;
 export interface FolderToolDeps {
-    mailboxQueue: Pick<MailboxQueueService, "createMailbox" | "renameMailbox" | "dismissMailboxIntent">;
+    mailboxQueue: Pick<MailboxQueueService, "createMailbox" | "renameMailbox" | "dismissMailboxIntent" | "deleteMailbox">;
     settleTimeoutMs: number;
     pollIntervalMs: number;
     sleep: (ms: number) => Promise<void>;
@@ -16,14 +16,16 @@ export interface FilterToolDeps {
 }
 export interface McpDeps {
     account: Pick<IAccountRepository, "get" | "listAllByAccountConfig" | "listMailSourcesByAccountConfig">;
-    mailbox: Pick<IMailboxRepository, "get" | "listAllByAccount" | "findByPath" | "resolveAccountId">;
+    mailbox: Pick<IMailboxRepository, "get" | "listAllByAccount" | "findByPath" | "findByPathPrefix" | "resolveAccountId">;
+    accountSetting: Pick<IAccountSettingRepository, "get">;
+    mailboxSpecialUse: Pick<IMailboxSpecialUseRepository, "resolveTrashRole">;
     address: Pick<IAddressRepository, "countCategoryOverridesSince">;
     label: Pick<ILabelRepository, "create" | "findByNormalizedName" | "get" | "listByAccountConfig">;
     labelMailbox: Pick<ILabelMailboxRepository, "get" | "put" | "listByAccount" | "listByLabel">;
-    message: Pick<IMessageRepository, "get" | "describe" | "countClassifiedSince">;
+    message: Pick<IMessageRepository, "get" | "describe" | "countClassifiedSince" | "listAllByMailbox" | "listByMailbox" | "listStrandedPlacements">;
     messageLabel: Pick<IMessageLabelRepository, "apply">;
     messageMove: Pick<MessageMoveService, "moveMessages">;
-    threadMessage: Pick<IThreadMessageRepository, "listByMailbox" | "listByThread" | "searchByDate">;
+    threadMessage: Pick<IThreadMessageRepository, "listByThread" | "searchByDate">;
     filter: Pick<IFilterRepository, "listByAccountConfig" | "refreshExpiry" | "create" | "get" | "update">;
     organizeJobRequest: Pick<IOrganizeJobRequestRepository, "create" | "get">;
     storage: Pick<StorageService, "retrieveBodyPart">;

package/dist/deps.js

@@ -3,6 +3,8 @@ export const FOLDER_POLL_INTERVAL_MS = 500;
 export const mcpDepsOf = (client, { logger, settle }) => ({
     account: client.account,
     mailbox: client.mailbox,
+    accountSetting: client.accountSetting,
+    mailboxSpecialUse: client.mailboxSpecialUse,
     address: client.address,
     label: client.label,
     labelMailbox: client.labelMailbox,

package/dist/folder-tools.js

@@ -1,8 +1,12 @@
+import { deletableFolder, deleteFolder } from "@remit/backend/folder-delete";
 import { isNotFoundError } from "@remit/data-ports/errors";
+import { isReservedFolderName } from "@remit/data-ports/folder-role";
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
 import { MailboxSyncStatus } from "@remit/domain-enums";
-import { changeFolderPath, createFolder, settledFolder, } from "@remit/mailbox-service";
+import { changeFolderPath, createFolder, invalid, isRemitRootName, ownedFolder, settledFolder, } from "@remit/mailbox-service";
 import { z } from "zod";
-import { asJson, refused, toolError } from "./tool-result.js";
+import { asJson, notFoundRefusal, refused, toolError } from "./tool-result.js";
+import { trashFolderOf } from "./trash.js";
 const CREATE_DELIMITER = "/";
 const FOLDER_WRITE = {
     readOnlyHint: false,
@@ -10,7 +14,7 @@ const FOLDER_WRITE = {
     idempotentHint: true,
     openWorldHint: false,
 };
-const awaitSettled = async (deps, folders, accountId, mailboxId) => {
+const awaitSettled = async (deps, folders, accountId, mailboxId, inFlight = MailboxSyncStatus.pending) => {
     const deadline = Date.now() + folders.settleTimeoutMs;
     for (;;) {
         const folder = await deps.mailbox
@@ -22,8 +26,7 @@ const awaitSettled = async (deps, folders, accountId, mailboxId) => {
         });
         if (!folder)
             return { state: "Gone" };
-        if (folder.syncStatus !== MailboxSyncStatus.pending ||
-            Date.now() >= deadline) {
+        if (folder.syncStatus !== inFlight || Date.now() >= deadline) {
             return { state: "Present", folder };
         }
         await folders.sleep(folders.pollIntervalMs);
@@ -78,6 +81,81 @@ const renameOutcome = (watched, requested) => {
             return settledOrRefused(folder);
     }
 };
+const deleteOutcome = (watched) => {
+    if (watched.state === "Gone")
+        return asJson({ deleted: true });
+    const { folder } = watched;
+    switch (folder.syncStatus) {
+        case MailboxSyncStatus.deleting:
+            return asJson({
+                ...folderState(folder),
+                message: "The mail server has not confirmed this yet. Call delete_folder again with the same arguments to keep waiting; it will not delete twice.",
+            });
+        case MailboxSyncStatus.failed:
+            return toolError(`The mail server refused to delete “${folder.fullPath}”: ${folder.syncFailureReason || "no reason given"}. Call delete_folder again to retry.`);
+        default:
+            return toolError(`The delete of “${folder.fullPath}” was dropped before the mail server confirmed it. Call list_mailboxes to see what is there now.`);
+    }
+};
+const notFound = notFoundRefusal("");
+// Folders the mail app, the mail server or Remit itself depends on, on top of
+// what the shared delete refuses: INBOX, folders with subfolders and folders a
+// filter or role points at.
+const keptFolderReason = async (deps, accountConfigId, folder) => {
+    const leaf = mailboxLeafName(folder);
+    const specialUse = folder.specialUse ?? [];
+    if (specialUse.length > 0) {
+        return `“${folder.fullPath}” is the account's ${specialUse.join(" and ")} folder, which the mail app relies on.`;
+    }
+    if (isReservedFolderName(leaf)) {
+        return `“${folder.fullPath}” carries a system folder name the mail app relies on.`;
+    }
+    if (isRemitRootName(leaf)) {
+        return `“${folder.fullPath}” holds Remit's label folders.`;
+    }
+    const mapping = (await deps.labelMailbox.listByAccount(folder.accountId)).find((row) => row.mailboxId === folder.mailboxId);
+    if (mapping) {
+        const label = await deps.label.get(accountConfigId, mapping.labelId);
+        return `“${folder.fullPath}” is the folder of the label “${label.name}”. Delete the label instead.`;
+    }
+    return undefined;
+};
+const movingOut = async (deps, mailboxId) => (await deps.message.listStrandedPlacements([mailboxId], Date.now() + 1)).filter((row) => row.originalMailboxId === mailboxId).length;
+// Moves out of the folder settle before it is deleted: the server must hold
+// that mail in Trash before DELETE removes the folder (imap-mutations R2: wait).
+const awaitMovedOut = async (deps, mailboxId) => {
+    const { folders } = deps;
+    const deadline = Date.now() + folders.settleTimeoutMs;
+    for (;;) {
+        const pending = await movingOut(deps, mailboxId);
+        if (pending === 0 || Date.now() >= deadline)
+            return pending;
+        await folders.sleep(folders.pollIntervalMs);
+    }
+};
+// Force never loses mail: it moves what the folder holds to Trash and waits
+// for the server to confirm, and only then does the delete go ahead.
+const trashFolderMail = async (deps, accountConfigId, folder) => {
+    const trash = await trashFolderOf(deps, folder.accountId);
+    if (!trash.ok)
+        return refused(trash.refusal);
+    const held = await deps.message.listAllByMailbox(folder.mailboxId);
+    if (held.length > 0) {
+        await deps.messageMove.moveMessages(accountConfigId, held.map((row) => row.messageId), trash.value, folder.accountId);
+    }
+    const pending = await awaitMovedOut(deps, folder.mailboxId);
+    if (pending > 0) {
+        return asJson({
+            ...folderState(folder),
+            message: `${pending} ${pending === 1 ? "message is" : "messages are"} still moving to Trash. Call delete_folder again with the same arguments to keep waiting; the folder is deleted once they have arrived.`,
+        });
+    }
+    const left = await deps.message.listByMailbox(folder.mailboxId, { limit: 1 });
+    if (left.items.length > 0) {
+        return toolError(`Not all mail in “${folder.fullPath}” could be moved to Trash, so the folder was kept. Call delete_folder again to retry.`);
+    }
+    return undefined;
+};
 export const registerFolderTools = (server, deps, accountConfigId) => {
     server.registerTool("create_folder", {
         description: "Create a folder in one email account and wait until the mail server confirms it. Returns the confirmed path, or the pending state if the server is slow; calling again with the same arguments resumes the wait.",
@@ -122,4 +200,51 @@ export const registerFolderTools = (server, deps, accountConfigId) => {
             return refused(changed.refusal);
         return renameOutcome(await awaitSettled(deps, folders, accountId, mailboxId), fullPath);
     });
+    server.registerTool("delete_folder", {
+        description: "Delete an empty folder on the mail server and in Remit, and wait until the server confirms it. Refuses a folder that still holds messages unless force is true, a folder with subfolders (delete those first), system folders, Remit's label folders and folders a filter or folder role uses. With force, the folder's mail first moves to Trash, and the folder is deleted once the server confirms the moves. Calling again with the same arguments resumes the wait.",
+        inputSchema: {
+            accountId: z.string().min(1).describe("Account from list_mailboxes"),
+            mailboxId: z.string().min(1).describe("Folder from list_mailboxes"),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Move the folder's messages to Trash first, then delete the folder"),
+        },
+        annotations: { ...FOLDER_WRITE, destructiveHint: true },
+    }, async ({ accountId, mailboxId, force }) => {
+        const { folders } = deps;
+        const owned = await ownedFolder(deps, accountConfigId, accountId, mailboxId).catch(notFound);
+        if (!owned.ok)
+            return refused(owned.refusal);
+        const folder = owned.value;
+        if (folder.syncStatus !== MailboxSyncStatus.deleting) {
+            const deleteDeps = { ...deps, mailboxQueue: folders.mailboxQueue };
+            const deletable = await deletableFolder(deleteDeps, accountConfigId, {
+                accountId,
+                mailboxId,
+            });
+            if (!deletable.ok)
+                return refused(deletable.refusal);
+            const kept = await keptFolderReason(deps, accountConfigId, folder);
+            if (kept)
+                return refused(invalid(kept).refusal);
+            const count = folder.messageCount;
+            if (!force && count > 0) {
+                return toolError(`“${folder.fullPath}” still holds ${count} ${count === 1 ? "message" : "messages"}. Move them out first, for example with move_folder_messages, and call delete_folder again once the moves have settled; or pass force: true to move them to Trash and delete the folder.`);
+            }
+            if (force) {
+                const notYet = await trashFolderMail(deps, accountConfigId, folder);
+                if (notYet)
+                    return notYet;
+            }
+            const deleted = await deleteFolder(deleteDeps, accountConfigId, {
+                accountId,
+                mailboxId,
+                requireEmpty: true,
+            });
+            if (!deleted.ok)
+                return refused(deleted.refusal);
+        }
+        return deleteOutcome(await awaitSettled(deps, folders, accountId, mailboxId, MailboxSyncStatus.deleting));
+    });
 };

package/dist/move-tools.js

@@ -2,9 +2,10 @@ import { ORGANIZE_MATCH_LIMIT, organizePredicateRejection, } from "@remit/backen
 import { FILTER_NO_ACTION, FilterRuleV1Schema, filterRuleFromClauses, filterRuleLimitRefusal, } from "@remit/data-ports";
 import { deriveAccountConfigId } from "@remit/data-ports/id";
 import { FilterMatchOperator } from "@remit/domain-enums";
-import { accept, folderInAccount, invalid, moveMessagesTo, ownedAccount, queueOrganizeJob, resolveMoveDestination, } from "@remit/mailbox-service";
+import { accept, folderInAccount, invalid, labelFoldersFor, moveMessagesTo, ownedAccount, ownedMessagesByAccount, queueOrganizeJob, resolveMoveDestination, sentDateRange, } from "@remit/mailbox-service";
 import { z } from "zod";
 import { asJson, notFoundRefusal, refused } from "./tool-result.js";
+import { trashFolderOf } from "./trash.js";
 const MAX_MOVE_MESSAGES = 500;
 const MOVE_WRITE = {
     readOnlyHint: false,
@@ -37,6 +38,14 @@ const oneTarget = (args) => {
         return accept({ labelId: args.labelId });
     return invalid("Send a target: mailboxId for a folder, or labelId.");
 };
+const oneBulkTarget = (args) => {
+    if (!args.trash)
+        return oneTarget(args);
+    if (args.mailboxId || args.labelId) {
+        return invalid("Send trash, mailboxId or labelId, not more than one.");
+    }
+    return accept({ trash: true });
+};
 const jobAction = (destination) => ({
     actionMailboxId: destination.mailboxId,
     actionLabelId: destination.kind === "Label" ? destination.labelId : FILTER_NO_ACTION,
@@ -86,16 +95,137 @@ export const registerMoveTools = (server, deps, userId) => {
             destinations: moved.value.map(({ messageIds: _, ...group }) => group),
         });
     });
+    const sourcesOf = async (args) => {
+        if (args.sourceMailboxId && args.sourceLabelId) {
+            return invalid("Send sourceMailboxId or sourceLabelId, not both.");
+        }
+        if (args.sourceLabelId) {
+            const label = await deps.label.get(accountConfigId, args.sourceLabelId);
+            const [found] = await labelFoldersFor(deps, accountConfigId, [label]);
+            const folders = found?.folders ?? [];
+            const present = folders.flatMap((folder) => folder.state === "Present"
+                ? [{ accountId: folder.accountId, mailboxId: folder.mailboxId }]
+                : []);
+            if (present.length === 0) {
+                return invalid(`Label “${label.name}” has no confirmed folder yet.`);
+            }
+            return accept({
+                present,
+                skipped: folders.flatMap((folder) => folder.state === "Present"
+                    ? []
+                    : [{ accountId: folder.accountId, folderState: folder.state }]),
+            });
+        }
+        if (!args.sourceMailboxId || !args.accountId) {
+            return invalid("Send a source: accountId with sourceMailboxId for a folder, or sourceLabelId.");
+        }
+        const { accountId, sourceMailboxId } = args;
+        const owned = await deps.account
+            .get(accountId)
+            .then((account) => ownedAccount(account, accountConfigId, "act"));
+        if (!owned.ok)
+            return owned;
+        const source = folderInAccount(await deps.mailbox.get(accountId, sourceMailboxId), accountId, "act");
+        if (!source.ok)
+            return source;
+        return accept({
+            present: [{ accountId, mailboxId: sourceMailboxId }],
+            skipped: [],
+        });
+    };
+    const actionFor = async (source, target) => {
+        if ("trash" in target) {
+            const trash = await trashFolderOf(deps, source.accountId);
+            if (!trash.ok)
+                return trash;
+            return accept({
+                actionMailboxId: trash.value,
+                actionLabelId: FILTER_NO_ACTION,
+            });
+        }
+        const destination = await resolveMoveDestination(deps, accountConfigId, source.accountId, target);
+        if (!destination.ok)
+            return destination;
+        return accept(jobAction(destination.value));
+    };
+    server.registerTool("trash_messages", {
+        description: "Move messages to Trash in their own account. A message already in Trash is left untouched and reported. Returns once the moves are recorded; the mail server confirms them shortly after.",
+        inputSchema: {
+            messageIds: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(MAX_MOVE_MESSAGES)
+                .describe("Messages from list_threads, search_threads or get_thread"),
+        },
+        annotations: MOVE_WRITE,
+    }, async ({ messageIds }) => {
+        const ids = [...new Set(messageIds)];
+        const owned = await ownedMessagesByAccount(deps, ids, accountConfigId, "act").catch(notFound);
+        if (!owned.ok)
+            return refused(owned.refusal);
+        const planned = [];
+        for (const [accountId, accountIds] of owned.value) {
+            const trash = await trashFolderOf(deps, accountId);
+            if (!trash.ok)
+                return refused(trash.refusal);
+            planned.push({
+                accountId,
+                trashMailboxId: trash.value,
+                messageIds: accountIds,
+            });
+        }
+        let trashed = 0;
+        const alreadyInTrash = [];
+        for (const { accountId, trashMailboxId, messageIds: accountIds, } of planned) {
+            const rows = await deps.message.get(accountIds);
+            const toMove = rows.flatMap((row) => {
+                if (row.mailboxId !== trashMailboxId)
+                    return [row.messageId];
+                alreadyInTrash.push(row.messageId);
+                return [];
+            });
+            if (toMove.length === 0)
+                continue;
+            await deps.messageMove.moveMessages(accountConfigId, toMove, trashMailboxId, accountId);
+            trashed += toMove.length;
+        }
+        return asJson({
+            trashed,
+            ...(alreadyInTrash.length > 0 ? { alreadyInTrash } : {}),
+        });
+    });
     server.registerTool("move_folder_messages", {
-        description: `Move every message in one folder, or only those matching a filter's rule or a given rule, into another folder or a label's folder. Runs as an organize job: returns its organizeJobId, which get_organize_job reports on. One job moves at most ${ORGANIZE_MATCH_LIMIT} messages; call again while a finished job reports appliedCount above 0.`,
+        description: `Move every message in a folder, or in a label's folders, or only those matching a filter's rule or a given rule, and optionally only those dated within before/after, into another folder, a label's folder, or Trash. Runs as organize jobs, one per account: returns their organizeJobIds, which get_organize_job reports on. One job moves at most ${ORGANIZE_MATCH_LIMIT} messages; call again while a finished job reports appliedCount above 0.`,
         inputSchema: {
-            accountId: z.string().min(1).describe("Account from list_mailboxes"),
+            accountId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Account from list_mailboxes; required with sourceMailboxId"),
             sourceMailboxId: z
                 .string()
                 .min(1)
-                .describe("Folder from list_mailboxes to move messages out of"),
+                .optional()
+                .describe("Folder from list_mailboxes to move messages out of. Send this or sourceLabelId."),
+            sourceLabelId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Label from list_labels: move messages out of its folder in every account. Send this or sourceMailboxId."),
             mailboxId: targetMailboxId,
             labelId: targetLabelId,
+            trash: z
+                .boolean()
+                .optional()
+                .describe("true moves the messages to Trash in their own account. Send this, mailboxId or labelId."),
+            before: z
+                .string()
+                .optional()
+                .describe("Only messages dated before this, an ISO 8601 date-time with zone offset such as 2026-08-13T00:00:00+02:00"),
+            after: z
+                .string()
+                .optional()
+                .describe("Only messages dated at or after this, an ISO 8601 date-time with zone offset"),
             filterId: z
                 .string()
                 .min(1)
@@ -104,47 +234,70 @@ export const registerMoveTools = (server, deps, userId) => {
             rule: FilterRuleV1Schema.optional().describe("Only move messages this rule matches, in the shape create_filter takes. Send this or filterId, or neither to move everything."),
         },
         annotations: { ...MOVE_WRITE, idempotentHint: false },
-    }, async ({ accountId, sourceMailboxId, mailboxId, labelId, ...match }) => {
-        const target = oneTarget({ mailboxId, labelId });
+    }, async ({ accountId, sourceMailboxId, sourceLabelId, mailboxId, labelId, trash, before, after, ...match }) => {
+        const target = oneBulkTarget({ mailboxId, labelId, trash });
         if (!target.ok)
             return refused(target.refusal);
-        const owned = await deps.account
-            .get(accountId)
-            .then((account) => ownedAccount(account, accountConfigId, "act"))
-            .catch(notFound);
-        if (!owned.ok)
-            return refused(owned.refusal);
-        const source = await deps.mailbox
-            .get(accountId, sourceMailboxId)
-            .then((folder) => folderInAccount(folder, accountId, "act"))
-            .catch(notFound);
-        if (!source.ok)
-            return refused(source.refusal);
-        const destination = await resolveMoveDestination(deps, accountConfigId, accountId, target.value).catch(notFound);
-        if (!destination.ok)
-            return refused(destination.refusal);
-        const action = jobAction(destination.value);
-        if (action.actionMailboxId === sourceMailboxId) {
-            return refused(invalid("The target folder is the source folder.").refusal);
+        const sent = sentDateRange({ before, after });
+        if (!sent.ok)
+            return refused(sent.refusal);
+        const sources = await sourcesOf({
+            accountId,
+            sourceMailboxId,
+            sourceLabelId,
+        }).catch(notFound);
+        if (!sources.ok)
+            return refused(sources.refusal);
+        const planned = [];
+        for (const source of sources.value.present) {
+            const action = await actionFor(source, target.value).catch(notFound);
+            if (!action.ok)
+                return refused(action.refusal);
+            if (action.value.actionMailboxId === source.mailboxId) {
+                return refused(invalid("The target folder is the source folder.").refusal);
+            }
+            planned.push({ source, action: action.value });
         }
         const rule = await ruleFor(match).catch(notFound);
         if (!rule.ok)
             return refused(rule.refusal);
-        const rejection = organizePredicateRejection({
-            rule: rule.value,
-            ...action,
-        });
-        if (rejection)
-            return refused(invalid(rejection.message).refusal);
-        const job = await queueOrganizeJob(organizeDeps, {
-            accountConfigId,
-            userId,
-            predicate: {
+        for (const { action } of planned) {
+            const rejection = organizePredicateRejection({
                 rule: rule.value,
-                sourceMailboxId,
                 ...action,
-            },
+            });
+            if (rejection)
+                return refused(invalid(rejection.message).refusal);
+        }
+        const jobs = [];
+        for (const { source, action } of planned) {
+            const job = await queueOrganizeJob(organizeDeps, {
+                accountConfigId,
+                userId,
+                predicate: {
+                    rule: rule.value,
+                    sourceMailboxId: source.mailboxId,
+                    sentAfter: after ?? FILTER_NO_ACTION,
+                    sentBefore: before ?? FILTER_NO_ACTION,
+                    ...action,
+                },
+            });
+            jobs.push({
+                accountId: source.accountId,
+                sourceMailboxId: source.mailboxId,
+                organizeJobId: job.organizeJobId,
+                state: job.state,
+            });
+        }
+        const { skipped } = sources.value;
+        return asJson({
+            jobs,
+            ...(skipped.length > 0
+                ? {
+                    skipped,
+                    message: "These accounts have no confirmed folder for the label yet, so no job was queued for them.",
+                }
+                : {}),
         });
-        return asJson({ organizeJobId: job.organizeJobId, state: job.state });
     });
 };

package/dist/read-tools.js

@@ -1,8 +1,8 @@
 import { NotFoundError } from "@remit/data-ports/errors";
 import { AddressRole, ContentDisposition, MediaType, } from "@remit/domain-enums";
-import { materializeBodyParts, ownedMessages, readClassifierStats, } from "@remit/mailbox-service";
+import { materializeBodyParts, ownedMessages, readClassifierStats, sentDateRange, } from "@remit/mailbox-service";
 import { z } from "zod";
-import { toolError } from "./tool-result.js";
+import { refused, toolError } from "./tool-result.js";
 export const MAX_BODY_BYTES = 20 * 1024;
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 50;
@@ -22,6 +22,14 @@ const continuationToken = z
     .optional()
     .describe("Opaque cursor from a previous response's continuationToken");
 const order = z.enum(["asc", "desc"]).optional().describe("Sort order by date");
+const before = z
+    .string()
+    .optional()
+    .describe("Only messages dated before this, an ISO 8601 date-time with zone offset such as 2026-08-13T00:00:00+02:00");
+const after = z
+    .string()
+    .optional()
+    .describe("Only messages dated at or after this, an ISO 8601 date-time with zone offset");
 const classificationOf = (message, detail) => ({
     classificationState: message.classificationState,
     category: message.category,
@@ -116,22 +124,30 @@ export const registerReadTools = (server, deps, accountConfigId) => {
         return asJson({ accounts: result });
     });
     server.registerTool("list_threads", {
-        description: "List the messages in one folder, newest first, a page at a time.",
+        description: "List the messages in one folder, newest first, a page at a time; before and after narrow it to a date range.",
         inputSchema: {
             mailboxId: z.string().min(1).describe("Folder from list_mailboxes"),
+            before,
+            after,
             limit: pageSize,
             continuationToken,
             order,
         },
         annotations: READ_ONLY,
-    }, async (args) => asJson(await toPage(deps, await deps.threadMessage.listByMailbox(accountConfigId, args.mailboxId, {
-        order: args.order ?? "desc",
-        limit: args.limit ?? DEFAULT_PAGE_SIZE,
-        continuationToken: args.continuationToken,
-        excludeDeleted: true,
-    }), "Confident")));
+    }, async (args) => {
+        const sent = sentDateRange(args);
+        if (!sent.ok)
+            return refused(sent.refusal);
+        return asJson(await toPage(deps, await deps.threadMessage.searchByDate(accountConfigId, sent.value, {
+            order: args.order ?? "desc",
+            limit: args.limit ?? DEFAULT_PAGE_SIZE,
+            continuationToken: args.continuationToken,
+            mailboxIds: new Set([args.mailboxId]),
+            excludeDeleted: true,
+        }), "Confident"));
+    });
     server.registerTool("search_threads", {
-        description: "Search the user's mail by free text, with optional sender, subject and state filters; narrow to one folder with mailboxId.",
+        description: "Search the user's mail by free text, with optional sender, subject, state and date filters; narrow to one folder with mailboxId.",
         inputSchema: {
             query: z.string().trim().min(1).describe("Free-text search"),
             from: z.string().optional().describe("Sender address or name"),
@@ -143,27 +159,35 @@ export const registerReadTools = (server, deps, accountConfigId) => {
                 .boolean()
                 .optional()
                 .describe("Only with, or only without, attachments"),
+            before,
+            after,
             limit: pageSize,
             continuationToken,
             order,
         },
         annotations: READ_ONLY,
-    }, async (args) => asJson(await toPage(deps, await deps.threadMessage.searchByDate(accountConfigId, {
-        query: args.query,
-        from: args.from,
-        subject: args.subject,
-        unread: args.unread,
-        starred: args.starred,
-        attachments: args.attachments,
-    }, {
-        order: args.order ?? "desc",
-        limit: args.limit ?? DEFAULT_PAGE_SIZE,
-        continuationToken: args.continuationToken,
-        mailboxIds: args.mailboxId
-            ? new Set([args.mailboxId])
-            : undefined,
-        excludeDeleted: true,
-    }), "Confident")));
+    }, async (args) => {
+        const sent = sentDateRange(args);
+        if (!sent.ok)
+            return refused(sent.refusal);
+        return asJson(await toPage(deps, await deps.threadMessage.searchByDate(accountConfigId, {
+            ...sent.value,
+            query: args.query,
+            from: args.from,
+            subject: args.subject,
+            unread: args.unread,
+            starred: args.starred,
+            attachments: args.attachments,
+        }, {
+            order: args.order ?? "desc",
+            limit: args.limit ?? DEFAULT_PAGE_SIZE,
+            continuationToken: args.continuationToken,
+            mailboxIds: args.mailboxId
+                ? new Set([args.mailboxId])
+                : undefined,
+            excludeDeleted: true,
+        }), "Confident"));
+    });
     server.registerTool("get_thread", {
         description: "Fetch the messages of one conversation, oldest first, at envelope level.",
         inputSchema: {

package/dist/trash.d.ts

@@ -0,0 +1,3 @@
+import { type Refusable } from "@remit/mailbox-service";
+import type { McpDeps } from "./deps.js";
+export declare const trashFolderOf: (deps: Pick<McpDeps, "mailboxSpecialUse">, accountId: string) => Promise<Refusable<string>>;

package/dist/trash.js

@@ -0,0 +1,9 @@
+import { trashMailboxAt } from "@remit/data-ports/folder-role";
+import { accept, invalid } from "@remit/mailbox-service";
+export const trashFolderOf = async (deps, accountId) => {
+    const trash = trashMailboxAt(await deps.mailboxSpecialUse.resolveTrashRole(accountId), "resolved");
+    if (!trash.allowed) {
+        return invalid(`Account ${accountId} has no Trash folder Remit can move mail into. Set one under Folder roles in settings.`);
+    }
+    return accept(trash.mailbox.mailboxId);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@remit/mcp-server",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "The remit MCP server: mail tools over streamable HTTP and the OAuth authorization server that guards them.",
 	"type": "module",
 	"exports": {
@@ -25,12 +25,12 @@
 		"@better-auth/oauth-provider": "^1.7.12",
 		"@hono/node-server": "^2.1.3",
 		"@modelcontextprotocol/sdk": "1.32.1",
-		"@remit/auth-service": "0.3.9",
-		"@remit/data-ports": "2.7.0",
-		"@remit/domain-enums": "0.0.51",
-		"@remit/drizzle-service": "3.5.0",
-		"@remit/mailbox-service": "2.19.0",
-		"@remit/storage-service": "0.0.37",
+		"@remit/auth-service": "0.3.11",
+		"@remit/data-ports": "2.8.0",
+		"@remit/domain-enums": "0.0.53",
+		"@remit/drizzle-service": "3.6.0",
+		"@remit/mailbox-service": "2.21.0",
+		"@remit/storage-service": "0.0.39",
 		"@remit/ui": "0.0.234",
 		"better-auth": "^1.7.12",
 		"drizzle-orm": "1.0.0-rc.5",
@@ -38,12 +38,12 @@
 		"react": "^19",
 		"react-dom": "^19",
 		"zod": "^4.6.7",
-		"@remit/backend": "5.5.0",
+		"@remit/backend": "5.7.0",
 		"@types/react": "^19",
 		"@types/react-dom": "^19"
 	},
 	"devDependencies": {
-		"@remit/imap-worker": "3.2.2",
+		"@remit/imap-worker": "3.3.0",
 		"@tailwindcss/vite": "^4",
 		"tailwindcss": "^4",
 		"tsx": "*",