@remit/mcp-server 0.7.2 → 0.9.0

package/dist/deps.d.ts

@@ -1,5 +1,5 @@
 import type { RemitClient } from "@remit/backend/client";
-import type { IAccountRepository, IFilterRepository, IMailboxRepository, IMessageRepository, IOrganizeJobRequestRepository, IThreadMessageRepository, OrganizeJobEvent, QueueProducer } from "@remit/data-ports";
+import type { IAccountRepository, IAddressRepository, IFilterRepository, IMailboxRepository, IMessageRepository, IOrganizeJobRequestRepository, IThreadMessageRepository, OrganizeJobEvent, QueueProducer } from "@remit/data-ports";
 import type { BodyPartMaterializer, BodySyncCue, MailboxQueueService, MaterializeLogger, OrganizeJobLogger } from "@remit/mailbox-service";
 import type { StorageService } from "@remit/storage-service";
 export declare const FOLDER_SETTLE_TIMEOUT_MS = 20000;
@@ -17,7 +17,8 @@ export interface FilterToolDeps {
 export interface McpDeps {
     account: Pick<IAccountRepository, "get" | "listAllByAccountConfig">;
     mailbox: Pick<IMailboxRepository, "get" | "listAllByAccount" | "findByPath" | "resolveAccountId">;
-    message: Pick<IMessageRepository, "get" | "describe">;
+    address: Pick<IAddressRepository, "countCategoryOverridesSince">;
+    message: Pick<IMessageRepository, "get" | "describe" | "countClassifiedSince">;
     threadMessage: Pick<IThreadMessageRepository, "listByMailbox" | "listByThread" | "searchByDate">;
     filter: Pick<IFilterRepository, "listPageByAccountConfig" | "refreshExpiry" | "create" | "get" | "update">;
     organizeJobRequest: Pick<IOrganizeJobRequestRepository, "create" | "get">;

package/dist/deps.js

@@ -3,6 +3,7 @@ export const FOLDER_POLL_INTERVAL_MS = 500;
 export const mcpDepsOf = (client, { logger, settle }) => ({
     account: client.account,
     mailbox: client.mailbox,
+    address: client.address,
     message: client.message,
     threadMessage: client.threadMessage,
     filter: client.filter,

package/dist/filter-tools.js

@@ -1,4 +1,4 @@
-import { FILTER_NO_ACTION, } from "@remit/data-ports";
+import { FILTER_NO_ACTION, FilterRuleV1Schema, filterClausesFromRule, MAX_FILTER_RULE_DEPTH, MAX_FILTER_RULE_LEAVES, } from "@remit/data-ports";
 import { isNotFoundError } from "@remit/data-ports/errors";
 import { deriveAccountConfigId } from "@remit/data-ports/id";
 import { FilterClauseField, FilterMatchOperator, FilterScope, FilterState, } from "@remit/domain-enums";
@@ -18,8 +18,10 @@ const toFilter = (item) => ({
     expiresAt: item.expiresAt,
     state: item.state,
     disabledReason: item.disabledReason,
-    matchOperator: item.matchOperator,
-    literalClauses: item.literalClauses,
+    ...filterClausesFromRule(item.rule),
+    rule: item.rule,
+    priority: item.priority,
+    stop: item.stop,
     actionLabelId: item.actionLabelId,
     actionMailboxId: item.actionMailboxId,
     ruleChangedAt: item.ruleChangedAt,
@@ -59,7 +61,15 @@ const literalClauses = z
         .describe("Message attribute the clause matches"),
     value: z.string().min(1).max(256).describe("Literal text to match"),
 }))
-    .min(1);
+    .min(1)
+    .describe("Literal clauses combined by matchOperator. Send these or rule.");
+const rule = FilterRuleV1Schema.describe(`A Sieve-like test tree. Send this or literalClauses, never both. At most ${MAX_FILTER_RULE_LEAVES} header, address or hasWords tests and ${MAX_FILTER_RULE_DEPTH} levels, counting the top test. Example: {"version":1,"test":{"test":"allof","tests":[{"test":"address","match":"Is","part":"RegistrableDomain","key":"github.com"},{"test":"not","operand":{"test":"header","match":"Contains","header":"Subject","key":"security"}}]}}`);
+const priority = z
+    .int()
+    .describe("Evaluation order: lower runs first; ties go to the most recently changed filter. The first matching filter with a folder decides the move, and labels add up");
+const stop = z
+    .boolean()
+    .describe("When true, a message this filter matches is not evaluated against any later filter");
 const scope = z
     .enum(FilterScope)
     .describe("Standing runs until changed; Temporary stops at expiresAt");
@@ -85,7 +95,7 @@ export const registerFilterTools = (server, deps, userId) => {
         logger: deps.filters.logger,
     };
     server.registerTool("list_filters", {
-        description: "List the user's mail filters: what each matches, where it moves or labels mail, and whether it is on. A page at a time.",
+        description: "List the user's mail filters: what each matches (rule, plus literalClauses when the rule is a flat list), its priority and stop, where it moves or labels mail, and whether it is on. A page at a time.",
         inputSchema: {
             accountId,
             continuationToken: z
@@ -107,14 +117,17 @@ export const registerFilterTools = (server, deps, userId) => {
         });
     });
     server.registerTool("create_filter", {
-        description: "Create a filter that sorts new mail, and queue a job that applies it to existing mail. Returns the filter and the organizeJobId of that job. A target folder must be confirmed by the mail server first.",
+        description: "Create a filter that sorts new mail, and queue a job that applies it to existing mail. Match with literalClauses for a flat list, or with rule for not, nesting and exact matches. Returns the filter and the organizeJobId of that job. A target folder must be confirmed by the mail server first.",
         inputSchema: {
             accountId,
             name: z.string().min(1).max(256).describe("Name for the filter"),
             scope: scope.default(FilterScope.Standing),
             expiresAt: expiresAt.optional(),
             matchOperator: matchOperator.default(FilterMatchOperator.And),
-            literalClauses,
+            literalClauses: literalClauses.optional(),
+            rule: rule.optional(),
+            priority: priority.default(0),
+            stop: stop.default(false),
             actionMailboxId: actionMailboxId.default(FILTER_NO_ACTION),
             actionLabelId: actionLabelId.default(FILTER_NO_ACTION),
         },
@@ -129,7 +142,7 @@ export const registerFilterTools = (server, deps, userId) => {
         });
     });
     server.registerTool("update_filter", {
-        description: "Change a filter: its name, clauses, target folder or label, scope, expiry, or turn it on or off. Only the fields given change. Set applyToExisting to also queue a job that applies the filter to existing mail; its organizeJobId is returned.",
+        description: "Change a filter: its name, clauses or rule, priority, stop, target folder or label, scope, expiry, or turn it on or off. Only the fields given change. A filter whose rule has no clause form (literalClauses is empty in list_filters) changes only through rule. Set applyToExisting to also queue a job that applies the filter to existing mail; its organizeJobId is returned.",
         inputSchema: {
             accountId,
             filterId: z.string().min(1).describe("Filter from list_filters"),
@@ -138,6 +151,9 @@ export const registerFilterTools = (server, deps, userId) => {
             expiresAt: expiresAt.optional(),
             matchOperator: matchOperator.optional(),
             literalClauses: literalClauses.optional(),
+            rule: rule.optional(),
+            priority: priority.optional(),
+            stop: stop.optional(),
             actionMailboxId: actionMailboxId.optional(),
             actionLabelId: actionLabelId.optional(),
             state: z

package/dist/read-tools.js

@@ -1,7 +1,8 @@
 import { NotFoundError } from "@remit/data-ports/errors";
 import { AddressRole, ContentDisposition, MediaType, } from "@remit/domain-enums";
-import { materializeBodyParts, ownedMessages } from "@remit/mailbox-service";
+import { materializeBodyParts, ownedMessages, readClassifierStats, } from "@remit/mailbox-service";
 import { z } from "zod";
+import { toolError } from "./tool-result.js";
 export const MAX_BODY_BYTES = 20 * 1024;
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 50;
@@ -21,7 +22,17 @@ 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 toThreadRow = (row) => ({
+const classificationOf = (message, detail) => ({
+    classificationState: message.classificationState,
+    category: message.category,
+    scores: detail === "All"
+        ? message.classifierScores
+        : message.classifierScores.filter((score) => score.confident),
+});
+const authOf = (message) => message.authResult === undefined
+    ? { state: "NotParsed" }
+    : { state: "Parsed", ...message.authResult };
+const toThreadRow = (row, message, detail) => ({
     threadId: row.threadId,
     messageId: row.messageId,
     mailboxId: row.mailboxId,
@@ -33,11 +44,26 @@ const toThreadRow = (row) => ({
     isRead: row.isRead,
     hasAttachment: row.hasAttachment,
     hasStars: row.hasStars,
+    classification: classificationOf(message, detail),
+    auth: authOf(message),
 });
-const toPage = (result) => ({
-    items: result.items.map(toThreadRow),
-    continuationToken: result.continuationToken,
-});
+const toPage = async (deps, result, detail) => {
+    const messages = new Map((await deps.message.get(result.items.map((row) => row.messageId))).map((message) => [message.messageId, message]));
+    const items = result.items.flatMap((row) => {
+        const message = messages.get(row.messageId);
+        return message === undefined ? [] : [toThreadRow(row, message, detail)];
+    });
+    if (items.length !== result.items.length) {
+        const missing = result.items
+            .map((row) => row.messageId)
+            .filter((messageId) => !messages.has(messageId));
+        throw new NotFoundError(`Message not found: ${missing.join(", ")}`);
+    }
+    return {
+        items,
+        continuationToken: result.continuationToken,
+    };
+};
 const addressesByRole = (addresses, role) => addresses
     .filter((address) => address.addressRole === role)
     .sort((left, right) => left.addressOrder - right.addressOrder)
@@ -98,12 +124,12 @@ export const registerReadTools = (server, deps, accountConfigId) => {
             order,
         },
         annotations: READ_ONLY,
-    }, async (args) => asJson(toPage(await deps.threadMessage.listByMailbox(accountConfigId, args.mailboxId, {
+    }, 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")));
     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.",
         inputSchema: {
@@ -122,7 +148,7 @@ export const registerReadTools = (server, deps, accountConfigId) => {
             order,
         },
         annotations: READ_ONLY,
-    }, async (args) => asJson(toPage(await deps.threadMessage.searchByDate(accountConfigId, {
+    }, async (args) => asJson(await toPage(deps, await deps.threadMessage.searchByDate(accountConfigId, {
         query: args.query,
         from: args.from,
         subject: args.subject,
@@ -137,7 +163,7 @@ export const registerReadTools = (server, deps, accountConfigId) => {
             ? 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: {
@@ -146,12 +172,27 @@ export const registerReadTools = (server, deps, accountConfigId) => {
             continuationToken,
         },
         annotations: READ_ONLY,
-    }, async (args) => asJson(toPage(await deps.threadMessage.listByThread(args.threadId, accountConfigId, {
+    }, async (args) => asJson(await toPage(deps, await deps.threadMessage.listByThread(args.threadId, accountConfigId, {
         order: "asc",
         limit: args.limit ?? DEFAULT_PAGE_SIZE,
         continuationToken: args.continuationToken,
         excludeDeleted: true,
-    }))));
+    }), "All")));
+    server.registerTool("classifier_stats", {
+        description: "Count what the classifier decided for mail that arrived on or after a date: messages examined, messages per category, confident scores per label, and how often the user corrected it.",
+        inputSchema: {
+            since: z
+                .string()
+                .min(1)
+                .describe("Start of the window, an ISO 8601 date-time with zone offset, such as 2026-11-01T00:00:00+01:00"),
+        },
+        annotations: READ_ONLY,
+    }, async (args) => {
+        const stats = await readClassifierStats(deps, accountConfigId, args.since);
+        if (!stats.ok)
+            return toolError(`${stats.message}.`);
+        return asJson(stats.value);
+    });
     server.registerTool("get_message", {
         description: `Read one message: envelope, flags, attachment metadata and its plain-text body, up to ${MAX_BODY_BYTES / 1024} KB.`,
         inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@remit/mcp-server",
-	"version": "0.7.2",
+	"version": "0.9.0",
 	"description": "The remit MCP server: mail tools over streamable HTTP and the OAuth authorization server that guards them.",
 	"type": "module",
 	"exports": {