@rndmjoker/proton-mcp 0.4.13 → 0.5.1

package/dist/tools/filter-tools.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Tools: list_filters, get_filters, propose_filter, apply_filter,
+ * reorder_filters, delete_filter and set_filter_status (#59)
+ *
+ * Proton Mail filters live behind an interface Proton has not opened to other
+ * programs, and the Bridge does not carry them. So these tools go through the
+ * user's own browser: the extension Proton MCP Helper does the work in the
+ * Proton page the user is signed in to, and a connector Chrome starts carries
+ * the requests from here to there. This server never holds a Proton session
+ * or password.
+ *
+ * Reading comes in two steps, decided by Tobi on 06.11.2026 after a real
+ * account held 96 filters, some 82,000 characters at once: list_filters gives
+ * the names, get_filters one or several filters in full.
+ *
+ * Proposing is held to the same rules in two places, here and again in the
+ * extension (src/filters/sieve.ts): Proton's spam guard first, then filing and
+ * the read and star flags, and beyond that only what the user allowed, one
+ * action at a time, on the Permissions page and again in the popup of the
+ * extension (Tobi, 06.11.2026: the user decides, and the settings are where).
+ * Nothing that could make the confirmation read differently from what runs
+ * is taken, whatever is allowed. Deleting a filter and switching one on or off
+ * are tools of their own, off until the user switches them on.
+ *
+ * By default the user confirms every change in a window of the extension,
+ * which shows the whole script and, for a change, the difference to the
+ * current one. That window belongs to the extension, not to the Proton page;
+ * measured on 06.11.2026, a browser tool an assistant drives does not reach
+ * it. Each call returns before the user decides, as Tobi chose on 05.11.2026:
+ * a client waiting on a person can run into its own time limit, and
+ * list_filters shows the outcome either way. The user can let each tool act on
+ * its own on the Permissions page, like the sending tools; the rules above
+ * hold regardless.
+ *
+ * Applying runs a saved filter over the mail that is already there, as
+ * Proton's settings do with "Apply filter to existing emails". Only a filter
+ * that passes the rules can be applied by an assistant, since one with discard
+ * would delete the existing mail it matches.
+ *
+ * Moving changes the order Proton runs filters in. Every filter runs on each
+ * incoming message; when several file it into folders, the last one wins. So
+ * a move can change where mail ends up, and the answer names the filters a
+ * moved one passes, warning where one of them does something an assistant may
+ * not set up.
+ *
+ * Applying takes time: on a large mailbox a run can take hours, and while it
+ * runs Proton applies no other filter. So the extension keeps an application
+ * in its queue until Proton takes it, for as long as Chrome stays open, rather
+ * than failing (Tobi, 06.11.2026); saving and moving go through meanwhile.
+ * list_filters shows what waits.
+ *
+ * Every tool first makes sure the Proton page belongs to the account this
+ * server is signed in to, so a filter cannot land in a second account that
+ * happens to be open in the same browser.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { BridgeCredentials } from '../config.js';
+import type { Permissions } from '../permissions.js';
+import type { BrowserRequest, BrowserResponse, ProtonFilter, QueuedAction, RecentChange } from '../browser/messages.js';
+import { type Unlockable } from '../filters/sieve.js';
+export interface FilterToolDependencies {
+    getCredentials: () => Promise<BridgeCredentials | undefined>;
+    permissions?: Permissions;
+    /** Replaced in tests. */
+    ask?: (request: BrowserRequest) => Promise<BrowserResponse>;
+}
+/** The most filters get_filters returns in one call. */
+export declare const MAX_GET = 20;
+/** The most characters of scripts get_filters returns in one call; the rest is named, not dropped. */
+export declare const GET_BUDGET = 60000;
+export declare const LIST_DESCRIPTION: string;
+export declare const GET_DESCRIPTION: string;
+export declare const PROPOSE_DESCRIPTION: string;
+export declare const APPLY_DESCRIPTION: string;
+export declare const DELETE_DESCRIPTION: string;
+export declare const STATUS_DESCRIPTION: string;
+export declare const REORDER_DESCRIPTION: string;
+export declare function formatNames(filters: ProtonFilter[], queue?: QueuedAction[], recent?: RecentChange[], unlocked?: ReadonlySet<Unlockable>): string;
+export declare function formatFull(filters: ProtonFilter[], ids: string[], allowed?: ReadonlySet<Unlockable>): string;
+export declare function registerBrowserFilterTools(server: McpServer, deps: FilterToolDependencies): void;
+/** Which filter moves where, which ones it passes, and where that touches something an assistant may not set up. */
+export declare function describeMoves(before: string[], after: string[], byId: Map<string, ProtonFilter>, ids: string[]): string;