@rndmjoker/proton-mcp 0.4.4

package/dist/tools/guidance.js

@@ -0,0 +1,226 @@
+/**
+ * What this server tells a model about itself.
+ *
+ * Two channels, and the difference between them is the whole design here:
+ *
+ * - **`instructions`** travels with every connection whether anyone wants it or
+ *   not, so it costs context on every single session. It says only what a model
+ *   would otherwise get wrong before it had a reason to look anything up.
+ * - **Resources** are read on demand. They can afford to be thorough, because
+ *   nobody pays for the ones that are not read.
+ *
+ * The split is not tidiness. A tool description that grows until nobody reads
+ * it protects nobody, and the same is true of instructions. So the short text
+ * names the traps and points here; the long text explains why they are traps.
+ *
+ * What goes in them is not invented. Everything below was measured against a
+ * running Bridge and a real mailbox, and the numbers are kept in because a model
+ * deciding whether to wait three seconds or twenty is better served by the
+ * measurement than by the word "briefly".
+ */
+/**
+ * Sent to every client at connection time.
+ *
+ * Deliberately short. Each line is here because a model got it wrong in
+ * practice or would have: writing HTML into a plain text field, transliterating
+ * umlauts away, checking a write immediately and reporting the intermediate
+ * state as the outcome.
+ */
+export const INSTRUCTIONS = [
+    'This server reads and writes a Proton Mail account through a local Proton Mail Bridge.',
+    '',
+    'Four things are worth knowing before the first call, because they are the ones that go',
+    'wrong quietly:',
+    '',
+    '1. Nothing is sent without a person agreeing to it. Every sending tool asks first, through',
+    '   the client, showing the final recipients. The first call never sends, and there is no',
+    '   setting that turns the question off.',
+    '2. A message body is either plain text or markup, never both. Markup written into the text',
+    '   field arrives as visible tags. All text is UTF-8: write words the way the language',
+    '   spells them rather than transliterating characters away.',
+    '3. Writes need time to settle, and how much depends on what was written. Flags are',
+    '   immediate; a move takes about fifteen seconds; a new message needs about twenty before',
+    '   it appears in "All Mail". Checking straight after a write reports an intermediate state',
+    '   as though it were the result.',
+    '4. Nothing here deletes for good. "Delete" means moving to the trash.',
+    '',
+    'Two guides can be read when they are needed:',
+    '  proton-mcp://guide/writing   composing messages, formatting, quoting, what the',
+    '                               confirmation shows',
+    '  proton-mcp://guide/bridge    how the Bridge behaves, with the measurements behind the',
+    '                               numbers above',
+].join('\n');
+const WRITING_GUIDE = `# Writing messages with this server
+
+## Text or markup, never both
+
+Every tool that composes a message takes either \`text\` or \`html\`. Giving both is
+refused rather than resolved by a preference, because Proton keeps the markup and
+drops the plain text half of a message that carries both. Whichever one this
+server chose to prefer, the other would silently never arrive.
+
+Markup placed in the \`text\` field is not interpreted. It arrives as visible
+characters and the recipient reads the tags.
+
+## What markup you may write
+
+Headings, paragraphs, line breaks, rules, quotes, emphasis, lists, tables, links
+and images. Styling by colour, background, font, size, weight, alignment,
+spacing and borders. Images may point at a full address or at a file carried
+inside the message.
+
+Anything else is **refused, not quietly removed**, and the answer names what and
+why. A message that was silently altered is no longer the message anyone agreed
+to, so there is nothing to guess at: if a send is refused, the reason says which
+element or property and what to use instead.
+
+Two refusals are worth understanding rather than working around:
+
+- **Properties that hide content** (\`display\`, \`visibility\`, \`opacity\`,
+  \`position\`, a size of zero) are refused. They let a message be delivered
+  looking different from how it was written.
+- **Addresses** are limited to \`http\`, \`https\`, \`mailto\` and \`cid\`. A \`data:\`
+  address would carry a whole file inside the markup, where nothing lists it as
+  an attachment.
+
+## What the person confirming is shown
+
+Not only the body. Understanding this explains most of the rules above.
+
+- The beginning of what you wrote, as it will read.
+- **Every address in it, in full**, links and images alike, each with the text it
+  is shown as. A link's visible text and its target are the same string in plain
+  text and two different strings in markup, and that difference is the shape of
+  every phishing message ever written.
+- **Every piece of text a recipient can read that the body preview does not
+  show.** An image's alt text is the clearest case: it never appears in the
+  converted body, and mail clients block remote images by default, so it is
+  frequently what the recipient actually reads.
+- Every file carried with the message, with its size.
+
+The agreement is bound to that exact message by a fingerprint covering the
+sender, every recipient, the subject, the markup and the contents of each
+carried file. Changing anything between the question and the answer means
+nothing is sent. So compose the message you mean, then ask; do not ask and then
+adjust.
+
+## Replying and forwarding
+
+The original is quoted below your part, with its formatting intact. You write
+your own part and nothing else; the quote is assembled by this server from the
+message being answered.
+
+- Your part goes through the rules above.
+- **The quote does not**, and could not: real mail is full of elements this
+  server would never write itself, and holding a quote to that list would make
+  replying to most messages impossible. It is kept as it was written, minus the
+  elements that would reach out of the quote and restyle your text above it.
+- The confirmation counts the quote rather than listing it. A quoted newsletter
+  carries dozens of addresses that arrived in the recipient's mailbox already,
+  and listing those would bury the ones you are answering for.
+
+Replying as a **draft** and replying as a **send** differ in more than whether
+anything leaves. Proton rewrites the thread headers of anything it stores, so a
+reply written to a draft and sent later carries Proton's idea of the
+conversation. A reply handed straight to SMTP keeps its \`In-Reply-To\` and stays
+in the thread. If threading matters, use \`send_reply\` rather than
+\`reply_draft\` followed by \`send_draft\`.
+
+## Attachments
+
+A message cannot be given a file from this machine. That is a decision that has
+not been made rather than a feature that is missing: which paths a model may
+reach is its own question. Forwarding loses nothing regardless, because the
+original travels along whole when it carries attachments.
+`;
+const BRIDGE_GUIDE = `# How the Bridge behaves
+
+Everything here was measured against a running Bridge rather than read in a
+specification, and several of these contradict what the specification would
+suggest.
+
+## Waiting times differ by an order of magnitude
+
+| Operation | Before it is visible |
+| :--- | :--- |
+| Setting a flag, read state or star | immediately, and unchanged twenty seconds later |
+| A message appended to a mailbox | immediately in that mailbox |
+| The same message in "All Mail" | about twenty seconds |
+| A move between folders, settled | about fifteen seconds |
+| SMTP accepting a message | about six and a half seconds |
+| A sent message visible over IMAP | about three seconds after that |
+
+During the settling time a move shows the message in **both** mailboxes. A check
+run straight after a write therefore reports something that is not the outcome.
+Wait, or simply report what was asked for.
+
+## Folders and labels are different things
+
+A message lives in exactly one folder and carries any number of labels.
+
+- Applying a label leaves the message where it is. Removing one leaves the
+  folder and the other labels untouched, and does not move anything to trash.
+- **Moving a message into a label is not a move.** The label is applied and the
+  message stays in its folder. \`move_messages\` refuses a label for that reason
+  and points at \`add_label\`.
+- Labels survive a move between folders.
+- "All Mail" holds every message exactly once, including the ones in the trash.
+  A listing of it does not say which folder a message is really in.
+
+## Two commands that report success without doing anything
+
+- **A copy into a mailbox that does not exist reports success and changes
+  nothing.** No error, and the destination is not created either. Whether a
+  label exists has to be established before the call, not after it.
+- **A move out of "All Mail" does nothing**, and reports a refusal as a falsy
+  return value rather than as an error. Moving needs the folder a message really
+  sits in.
+
+## Other measured behaviour
+
+- **Proton fills the inbox through delivery, not through IMAP.** A message moved
+  to "INBOX" was measured to end up elsewhere shortly afterwards.
+- **A message with both a text and an HTML part arrives with only the HTML.**
+- **Proton attaches its own public key to every message sent through the
+  Bridge.** It is filtered out of every attachment list here, so a client showing
+  three attachments where this server reports two is showing that key.
+- **Proton rewrites the thread headers of anything it stores.** A draft appended
+  with \`In-Reply-To\` and \`References\` comes back without the first and with the
+  second replaced. A message handed to SMTP keeps them.
+- **Searching is fast and local.** It runs against the Bridge's own database.
+  Ordering a listing by date is the expensive part, because there is no
+  server-side sort: it reads one date per message in the mailbox before a page
+  can be cut, and the answer says so when it took a while.
+
+## The trap behind all of these
+
+Every one of the surprises above looked settled after a single measurement and
+turned out differently on the second. A move looked like a copy because the
+message was briefly in both places. A missing label looked like a successful
+copy because the command said so. If something here is ever re-measured, it is
+worth doing twice with a pause in between.
+`;
+/**
+ * Makes the guides readable.
+ *
+ * Registered as resources rather than folded into tool descriptions, because a
+ * description is paid for on every listing whether it is needed or not, and
+ * these are long by design.
+ */
+export function registerGuidance(server) {
+    server.registerResource('writing-guide', 'proton-mcp://guide/writing', {
+        title: 'Writing messages with this server',
+        description: 'Composing messages: text against markup, what markup is permitted and what is refused, ' +
+            'what the person confirming a send is shown, how replies and forwards quote the original, ' +
+            'and why replying as a draft and replying as a send are not the same thing.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({ contents: [{ uri: uri.href, text: WRITING_GUIDE, mimeType: 'text/markdown' }] }));
+    server.registerResource('bridge-guide', 'proton-mcp://guide/bridge', {
+        title: 'How the Proton Mail Bridge behaves',
+        description: 'Measured behaviour of the Bridge: how long each kind of write takes to settle, how ' +
+            'folders and labels differ, and the two commands that report success without having done ' +
+            'anything.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({ contents: [{ uri: uri.href, text: BRIDGE_GUIDE, mimeType: 'text/markdown' }] }));
+}
+//# sourceMappingURL=guidance.js.map

package/dist/tools/guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.js","sourceRoot":"","sources":["../../src/tools/guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,wFAAwF;IACxF,EAAE;IACF,wFAAwF;IACxF,gBAAgB;IAChB,EAAE;IACF,4FAA4F;IAC5F,0FAA0F;IAC1F,yCAAyC;IACzC,4FAA4F;IAC5F,uFAAuF;IACvF,6DAA6D;IAC7D,oFAAoF;IACpF,2FAA2F;IAC3F,4FAA4F;IAC5F,kCAAkC;IAClC,uEAAuE;IACvE,EAAE;IACF,8CAA8C;IAC9C,kFAAkF;IAClF,mDAAmD;IACnD,yFAAyF;IACzF,8CAA8C;CAC/C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFrB,CAAA;AAED,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkEpB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,4BAA4B,EAC5B;QACE,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EACT,yFAAyF;YACzF,2FAA2F;YAC3F,4EAA4E;QAC9E,QAAQ,EAAE,eAAe;KAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CACnG,CAAA;IAED,MAAM,CAAC,gBAAgB,CACrB,cAAc,EACd,2BAA2B,EAC3B;QACE,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EACT,qFAAqF;YACrF,0FAA0F;YAC1F,WAAW;QACb,QAAQ,EAAE,eAAe;KAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CAClG,CAAA;AACH,CAAC"}

package/dist/tools/interface.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tool: open_configuration
+ *
+ * Hands out the address of the local web interface, including the access token.
+ *
+ * Why a tool rather than only a line on stderr: most clients hide a server's
+ * stderr, so a user who wants to reach the interface would have to go digging
+ * through logs. Asking the assistant is the obvious move, and this makes it
+ * work.
+ *
+ * The token does end up in the conversation. That is a deliberate trade: it
+ * grants access to a page on loopback that shows configuration and state, never
+ * message content, and it is worthless from any other machine. It changes with
+ * every restart. The alternative, making the user hunt for a log line, would
+ * mostly result in nobody using the interface at all.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { StoreKind } from '../credentials/store.js';
+export interface InterfaceInfo {
+    url: () => string;
+    running: () => boolean;
+    signedIn: () => boolean;
+    address: () => string | undefined;
+    storeKind: () => StoreKind | undefined;
+    /** Whether credentials are stored but still need a master password. */
+    locked?: () => Promise<boolean>;
+}
+export declare function registerInterfaceTool(server: McpServer, info: InterfaceInfo): void;

package/dist/tools/interface.js

@@ -0,0 +1,63 @@
+/**
+ * Tool: open_configuration
+ *
+ * Hands out the address of the local web interface, including the access token.
+ *
+ * Why a tool rather than only a line on stderr: most clients hide a server's
+ * stderr, so a user who wants to reach the interface would have to go digging
+ * through logs. Asking the assistant is the obvious move, and this makes it
+ * work.
+ *
+ * The token does end up in the conversation. That is a deliberate trade: it
+ * grants access to a page on loopback that shows configuration and state, never
+ * message content, and it is worthless from any other machine. It changes with
+ * every restart. The alternative, making the user hunt for a log line, would
+ * mostly result in nobody using the interface at all.
+ */
+import * as z from 'zod';
+import { STORE_DESCRIPTIONS } from '../credentials/store.js';
+import { track } from '../in-flight.js';
+export function registerInterfaceTool(server, info) {
+    server.registerTool('open_configuration', {
+        title: 'Open the configuration interface',
+        description: 'Returns the address of the local configuration interface, which runs for as long as this ' +
+            'server does. Use it when the user asks how to sign in, where to change settings, or when ' +
+            'another tool reports that no credentials are available. The address contains an access ' +
+            'token and changes every time the server restarts.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => track(async () => {
+        if (!info.running()) {
+            const failure = {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'The configuration interface is not running. It failed to start, most likely ' +
+                            'because its port was in use. Set PROTON_MCP_WEB_PORT to a free port and restart ' +
+                            'the server. Credentials can still be provided through the BRIDGE_USER and ' +
+                            'BRIDGE_PASS environment variables.',
+                    },
+                ],
+                isError: true,
+            };
+            return failure;
+        }
+        const lines = [`Configuration interface: ${info.url()}`, ''];
+        if (info.signedIn()) {
+            const kind = info.storeKind();
+            lines.push(`Signed in as ${info.address()}.`, kind
+                ? `Credentials are kept in: ${STORE_DESCRIPTIONS[kind].title}.`
+                : 'Credentials are held for this session only.', '', 'The page shows the connection state and lets the user sign out.');
+        }
+        else if ((await info.locked?.()) === true) {
+            lines.push('Credentials are stored in an encrypted file and only need to be unlocked. Opening the', 'address above leads to a page asking for the master password, and nothing else: the', 'Bridge password is already on disk.', '', 'Tell the user to open it themselves. Do not ask them for the master password here.');
+        }
+        else {
+            lines.push('Not signed in yet. Opening the address above leads to a form asking for the Proton', 'address and the Bridge password, which is the password the Bridge generates and not', 'the Proton account password.', '', 'Tell the user to open it themselves. Do not ask them for the password here: it has no', 'business in a conversation, and the page exists so that it never has to be.');
+        }
+        lines.push('', 'The address is only reachable from this machine and the token changes on every restart.');
+        const answer = { content: [{ type: 'text', text: lines.join('\n') }] };
+        return answer;
+    }, 'open_configuration'));
+}
+//# sourceMappingURL=interface.js.map

package/dist/tools/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/tools/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAGxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAYvC,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,IAAmB;IAC1E,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,KAAK,EAAE,kCAAkC;QACzC,WAAW,EACT,2FAA2F;YAC3F,2FAA2F;YAC3F,yFAAyF;YACzF,mDAAmD;QACrD,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;KAC1D,EACD,KAAK,IAAI,EAAE,CACT,KAAK,CAAC,KAAK,IAAI,EAAE;QACf,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACpB,MAAM,OAAO,GAAmB;gBAC9B,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EACF,8EAA8E;4BAC9E,kFAAkF;4BAClF,4EAA4E;4BAC5E,oCAAoC;qBACvC;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAA;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;QAED,MAAM,KAAK,GAAa,CAAC,4BAA4B,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;QAEtE,IAAI,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;YAC7B,KAAK,CAAC,IAAI,CACR,gBAAgB,IAAI,CAAC,OAAO,EAAE,GAAG,EACjC,IAAI;gBACF,CAAC,CAAC,4BAA4B,kBAAkB,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG;gBAC/D,CAAC,CAAC,6CAA6C,EACjD,EAAE,EACF,iEAAiE,CAClE,CAAA;QACH,CAAC;aAAM,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CACR,uFAAuF,EACvF,qFAAqF,EACrF,qCAAqC,EACrC,EAAE,EACF,oFAAoF,CACrF,CAAA;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,oFAAoF,EACpF,qFAAqF,EACrF,8BAA8B,EAC9B,EAAE,EACF,uFAAuF,EACvF,6EAA6E,CAC9E,CAAA;QACH,CAAC;QAED,KAAK,CAAC,IAAI,CACR,EAAE,EACF,yFAAyF,CAC1F,CAAA;QAED,MAAM,MAAM,GAAmB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAA;QACtF,OAAO,MAAM,CAAA;IACf,CAAC,EAAE,oBAAoB,CAAC,CAC3B,CAAA;AACH,CAAC"}

package/dist/tools/labels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tools: add_label, remove_label
+ *
+ * The first tools that change anything. Two properties matter more than the
+ * feature itself:
+ *
+ * - They honour the read-only mode. Until now `PROTON_MCP_READ_ONLY` was a
+ *   setting the web interface displayed and nothing enforced, because there was
+ *   nothing to prevent. From here on the display has to be true.
+ * - They never report success they have not established. A copy into a label
+ *   that does not exist is accepted by the Bridge and changes nothing, so the
+ *   label is checked beforehand, and the answer says what was asked for rather
+ *   than claiming a verified outcome.
+ *
+ * Labelling is not put behind a confirmation. It changes no content, sends
+ * nothing outside, and is undone by the opposite call. The confirmation
+ * requirement belongs to sending, where a wrong decision cannot be taken back.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { Connection } from '../bridge/connection.js';
+export declare function registerLabelTools(server: McpServer, connection: Connection, readOnly: () => boolean): void;

package/dist/tools/labels.js

@@ -0,0 +1,92 @@
+/**
+ * Tools: add_label, remove_label
+ *
+ * The first tools that change anything. Two properties matter more than the
+ * feature itself:
+ *
+ * - They honour the read-only mode. Until now `PROTON_MCP_READ_ONLY` was a
+ *   setting the web interface displayed and nothing enforced, because there was
+ *   nothing to prevent. From here on the display has to be true.
+ * - They never report success they have not established. A copy into a label
+ *   that does not exist is accepted by the Bridge and changes nothing, so the
+ *   label is checked beforehand, and the answer says what was asked for rather
+ *   than claiming a verified outcome.
+ *
+ * Labelling is not put behind a confirmation. It changes no content, sends
+ * nothing outside, and is undone by the opposite call. The confirmation
+ * requirement belongs to sending, where a wrong decision cannot be taken back.
+ */
+import * as z from 'zod';
+import { addLabel, removeLabel, LABEL_PREFIX } from '../mail/labels.js';
+import { describeFailure, withSignIn } from './failures.js';
+import { track } from '../in-flight.js';
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+/**
+ * Written into both answers.
+ *
+ * Measured: right after a write the Bridge reports an intermediate state. A
+ * model that checks its own result immediately will describe something that is
+ * not the outcome, so it is told not to.
+ */
+const DELAY_NOTE = 'The Bridge needs a moment to reconcile with Proton. Listing the label straight away ' +
+    'may not show the change yet, and an immediate check would be misleading rather than informative.';
+const labelArgument = z
+    .string()
+    .describe(`The label name, for example "Work". The "${LABEL_PREFIX}" prefix may be included and is optional. ` +
+    'Use list_folders to see which labels exist. Labels are created in Proton itself, not here.');
+const messageArgument = z
+    .string()
+    .describe('The message id from a listing or a search, with or without angle brackets.');
+const mailboxHint = z
+    .string()
+    .optional()
+    .describe('The mailbox the message is in, if known. Only a shortcut for the lookup.');
+export function registerLabelTools(server, connection, readOnly) {
+    server.registerTool('add_label', {
+        title: 'Apply a label',
+        description: 'Applies an existing label to a message. In Proton a message lives in exactly one folder ' +
+            'but can carry any number of labels, so this adds to the message rather than moving it: ' +
+            'it stays where it is and keeps the labels it already has. ' +
+            'The label has to exist already; this server does not create labels.',
+        inputSchema: z.object({
+            messageId: messageArgument,
+            label: labelArgument,
+            mailbox: mailboxHint,
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ messageId, label, mailbox }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const result = await addLabel(connection, readOnly(), messageId, label, mailbox);
+            return ok(`Applied "${result.label}" to ${result.messageId}, which is in "${result.path}". ` +
+                `It has not been moved. ${DELAY_NOTE}`);
+        }
+        catch (error) {
+            return describeFailure(error, `applying the label "${label}"`);
+        }
+    }), 'add_label'));
+    server.registerTool('remove_label', {
+        title: 'Remove a label',
+        description: 'Removes a label from a message. The message keeps its folder and its other labels, and ' +
+            'does not go to trash. Only labels can be removed this way, never folders: a message ' +
+            'always lives in some folder, and moving it is a different operation.',
+        inputSchema: z.object({
+            messageId: messageArgument,
+            label: labelArgument,
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ messageId, label }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const result = await removeLabel(connection, readOnly(), messageId, label);
+            if (!result.wasApplied) {
+                return ok(`${result.messageId} does not carry "${result.label}", so there was nothing to remove. ` +
+                    'Nothing was changed.');
+            }
+            return ok(`Removed "${result.label}" from ${result.messageId}. The message keeps its folder and ` +
+                `its other labels. ${DELAY_NOTE}`);
+        }
+        catch (error) {
+            return describeFailure(error, `removing the label "${label}"`);
+        }
+    }), 'remove_label'));
+}
+//# sourceMappingURL=labels.js.map

package/dist/tools/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../src/tools/labels.ts"],"names":[],"mappings":"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"}

package/dist/tools/list-folders.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tool: list_folders
+ *
+ * Lists the mailboxes. Deliberately its own tool and never a side dish of
+ * another answer: mailbox names are personal data on their own. Folders and
+ * labels belong to the Proton account rather than to a single address, so this
+ * exposes the whole account structure. A name like Folders/Banking/Revolut
+ * gives away a bank even when not a single message inside it is visible.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { Connection, Mailbox } from '../bridge/connection.js';
+/** Builds the text output. Kept compact, because mailbox lists get long. */
+export declare function format(mailboxes: Mailbox[]): string;
+export declare function registerListFolders(server: McpServer, connection: Connection): void;

package/dist/tools/list-folders.js

@@ -0,0 +1,70 @@
+/**
+ * Tool: list_folders
+ *
+ * Lists the mailboxes. Deliberately its own tool and never a side dish of
+ * another answer: mailbox names are personal data on their own. Folders and
+ * labels belong to the Proton account rather than to a single address, so this
+ * exposes the whole account structure. A name like Folders/Banking/Revolut
+ * gives away a bank even when not a single message inside it is visible.
+ */
+import * as z from 'zod';
+import { describeFailure, withSignIn } from './failures.js';
+import { track } from '../in-flight.js';
+const inputSchema = z.object({
+    kind: z
+        .enum(['all', 'system', 'folder', 'label'])
+        .default('all')
+        .describe('Which mailboxes to list. "system" covers Inbox, Sent, Trash and so on, ' +
+        '"folder" the user-created folders, "label" the labels.'),
+    onlySelectable: z
+        .boolean()
+        .default(false)
+        .describe('When true, only mailboxes that can hold messages are listed.'),
+});
+/** Builds the text output. Kept compact, because mailbox lists get long. */
+export function format(mailboxes) {
+    if (mailboxes.length === 0)
+        return 'No mailboxes found.';
+    const groups = [
+        ['system', 'System mailboxes'],
+        ['folder', 'Folders'],
+        ['label', 'Labels'],
+    ];
+    const lines = [];
+    for (const [kind, heading] of groups) {
+        const part = mailboxes.filter((m) => m.kind === kind && m.selectable);
+        if (part.length === 0)
+            continue;
+        lines.push(`## ${heading} (${part.length})`);
+        for (const m of part) {
+            const role = m.specialUse ? `  [${m.specialUse}]` : '';
+            lines.push(`- ${m.path}${role}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+export function registerListFolders(server, connection) {
+    server.registerTool('list_folders', {
+        title: 'List mailboxes',
+        description: 'Lists the folders and labels of the Proton account. ' +
+            'Proton distinguishes folders (a message lives in exactly one) from labels ' +
+            '(a message can carry any number). Over IMAP both appear as directories.',
+        inputSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ kind, onlySelectable }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            let mailboxes = await connection.listMailboxes();
+            if (kind !== 'all')
+                mailboxes = mailboxes.filter((m) => m.kind === kind);
+            if (onlySelectable)
+                mailboxes = mailboxes.filter((m) => m.selectable);
+            const answer = { content: [{ type: 'text', text: format(mailboxes) }] };
+            return answer;
+        }
+        catch (error) {
+            return describeFailure(error, 'listing mailboxes');
+        }
+    }), 'list_folders'));
+}
+//# sourceMappingURL=list-folders.js.map

package/dist/tools/list-folders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-folders.js","sourceRoot":"","sources":["../../src/tools/list-folders.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAGxB,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAEvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;SAC1C,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,yEAAyE;QACvE,wDAAwD,CAC3D;IACH,cAAc,EAAE,CAAC;SACd,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,8DAA8D,CAAC;CAC5E,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,UAAU,MAAM,CAAC,SAAoB;IACzC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,qBAAqB,CAAA;IAExD,MAAM,MAAM,GAAqC;QAC/C,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QAC9B,CAAC,QAAQ,EAAE,SAAS,CAAC;QACrB,CAAC,OAAO,EAAE,QAAQ,CAAC;KACpB,CAAA;IAED,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,CAAA;QACrE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QAC/B,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;QAC5C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;YACtD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC,CAAA;QAClC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;AACnC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,UAAsB;IAC3E,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,sDAAsD;YACtD,4EAA4E;YAC5E,yEAAyE;QAC3E,WAAW;QACX,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;KAC1D,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,EAAE,CACtC,KAAK,CAAC,GAAG,EAAE,CACT,UAAU,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;QACzB,IAAI,CAAC;YACH,IAAI,SAAS,GAAG,MAAM,UAAU,CAAC,aAAa,EAAE,CAAA;YAChD,IAAI,IAAI,KAAK,KAAK;gBAAE,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;YACxE,IAAI,cAAc;gBAAE,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;YAErE,MAAM,MAAM,GAAmB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAA;YACvF,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,eAAe,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAA;QACpD,CAAC;IACH,CAAC,CAAC,EACF,cAAc,CACf,CACJ,CAAA;AACH,CAAC"}

package/dist/tools/messages.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The reading tools: list_messages, get_message, get_attachment.
+ *
+ * All three are read-only. Every one of them goes through track() so that a
+ * shutdown waits for the answer instead of cutting it off.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { Connection } from '../bridge/connection.js';
+export declare function registerMessageTools(server: McpServer, connection: Connection): void;