@rndmjoker/proton-mcp 0.4.4

package/dist/session.js

@@ -0,0 +1,220 @@
+/**
+ * The signed-in state of the server.
+ *
+ * Credentials used to be part of the configuration, read once at startup. That
+ * no longer works: with the web interface they can arrive at any time, and they
+ * can be revoked while the server keeps running. This is the one place that
+ * knows whether we are signed in.
+ *
+ * It also decides where credentials come from on startup, in this order:
+ *
+ * 1. Environment variables, when set. An explicit setting is never overruled.
+ * 2. The plain file, which is the interim path and the one existing setups use.
+ * 3. The system keyring, if something was stored there.
+ *
+ * The encrypted file is deliberately not in that list, because it cannot be:
+ * decrypting it needs a master password, and there is nowhere to ask for one
+ * while a stdio server starts up. It is instead reported as **locked**, which
+ * the web interface turns into a page asking for that one password. This is
+ * the whole reason `locked()` and `unlock()` exist rather than a fourth entry
+ * in the loop above.
+ */
+import { KeyringStore } from './credentials/keyring.js';
+import { SessionStore } from './credentials/session.js';
+import { PlainFileStore } from './credentials/plain-file.js';
+import { EncryptedFileStore } from './credentials/encrypted-file.js';
+import { BridgeError } from './bridge/errors.js';
+/** What the encrypted store is told when nobody has supplied a master password. */
+const NO_MASTER_PASSWORD = 'The encrypted credentials file needs a master password. Open the configuration page and ' +
+    'unlock it there.';
+export class Session {
+    #credentials;
+    #storeKind;
+    /**
+     * The master password for the encrypted file, for as long as the process runs.
+     *
+     * Held in memory only, and only when that store is in use. Writing it
+     * anywhere would defeat the point of the option: the file is protected by
+     * something that exists nowhere else.
+     */
+    #masterPassword;
+    #stores;
+    #notify;
+    /** Set once startup has looked for stored credentials. */
+    #restored = false;
+    constructor(options = {}) {
+        this.#notify = options.notify ?? ((m) => process.stderr.write(`proton-mcp: ${m}\n`));
+        // Taken up right away rather than on first use. Reading the environment
+        // costs nothing and cannot block, and leaving it for later made the status
+        // claim "not signed in" while the very next tool call worked.
+        if (options.fromEnvironment) {
+            this.#credentials = options.fromEnvironment;
+            this.#storeKind = 'plain-file';
+            this.#restored = true;
+        }
+        this.#stores = {
+            keyring: options.stores?.keyring ?? new KeyringStore(),
+            session: options.stores?.session ?? new SessionStore(),
+            'plain-file': options.stores?.['plain-file'] ?? new PlainFileStore(),
+            'encrypted-file': options.stores?.['encrypted-file'] ??
+                new EncryptedFileStore(async () => {
+                    if (this.#masterPassword === undefined)
+                        throw new BridgeError(NO_MASTER_PASSWORD);
+                    return this.#masterPassword;
+                }),
+        };
+    }
+    get storeKind() {
+        return this.#storeKind;
+    }
+    get signedIn() {
+        return this.#credentials !== undefined;
+    }
+    /** The address we are signed in as, for display. Never the password. */
+    get address() {
+        return this.#credentials?.user;
+    }
+    /**
+     * Returns the credentials, restoring them from a store on first use.
+     *
+     * Restoring happens here rather than at startup so that a locked keyring
+     * cannot block the server from starting. It costs one attempt on the first
+     * tool call instead.
+     */
+    async credentials() {
+        if (this.#credentials)
+            return this.#credentials;
+        if (this.#restored)
+            return undefined;
+        this.#restored = true;
+        // Order matters: the cheap and non-blocking source first.
+        for (const kind of ['plain-file', 'keyring']) {
+            try {
+                const found = await this.#stores[kind].load();
+                if (found) {
+                    this.#credentials = found;
+                    this.#storeKind = kind;
+                    return found;
+                }
+            }
+            catch (error) {
+                // A store that cannot be read is not a reason to fail: another one may
+                // work, and the web interface can always be used.
+                this.#notify(`could not read credentials from the ${kind}: ${error.message}`);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Whether credentials are stored that only a master password can open.
+     *
+     * Distinct from "not signed in": the user does not need to fetch their Bridge
+     * password from the Bridge again, they need to type one thing. A page that
+     * asked for everything would make the encrypted option feel broken.
+     */
+    async locked() {
+        if (this.#credentials)
+            return false;
+        const exists = this.#stores['encrypted-file'].exists;
+        if (!exists)
+            return false;
+        try {
+            return await exists.call(this.#stores['encrypted-file']);
+        }
+        catch {
+            // Not being able to look is not the same as it being there.
+            return false;
+        }
+    }
+    /**
+     * Opens the encrypted file with the given master password.
+     *
+     * Returns the credentials so the caller can verify them against the Bridge.
+     * On failure the password is dropped again: keeping a wrong one would make
+     * every later attempt fail with a message about the file instead of about
+     * the password.
+     */
+    async unlock(masterPassword) {
+        if (!masterPassword)
+            throw new BridgeError('The master password is required.');
+        this.#masterPassword = masterPassword;
+        try {
+            const found = await this.#stores['encrypted-file'].load();
+            if (!found) {
+                throw new BridgeError('There is no encrypted credentials file to unlock.');
+            }
+            this.#credentials = found;
+            this.#storeKind = 'encrypted-file';
+            this.#restored = true;
+            return found;
+        }
+        catch (error) {
+            this.#masterPassword = undefined;
+            throw error;
+        }
+    }
+    /**
+     * Throws away the encrypted file without opening it.
+     *
+     * The way out for someone who forgot their master password. Without it they
+     * would be stuck on the unlock page for good, because nothing anywhere can
+     * decrypt that file. What is destroyed is a Bridge password that can be
+     * looked up in the Bridge again, so this is recoverable in the only sense
+     * that matters.
+     */
+    async discardEncrypted() {
+        await this.#stores['encrypted-file'].clear();
+        this.#masterPassword = undefined;
+    }
+    /**
+     * Stores credentials and marks the session as signed in.
+     *
+     * The caller has already verified them against the Bridge: storing something
+     * that does not work would be worse than not storing it.
+     */
+    async signIn(credentials, storeKind, 
+    /** Required for the encrypted file, meaningless for every other store. */
+    masterPassword) {
+        if (storeKind === 'encrypted-file') {
+            if (!masterPassword) {
+                throw new BridgeError('Keeping the credentials in an encrypted file needs a master password to encrypt them with.');
+            }
+            this.#masterPassword = masterPassword;
+        }
+        try {
+            await this.#stores[storeKind].save(credentials);
+        }
+        catch (error) {
+            // A master password that did not lead to a stored file must not stay
+            // behind, or the next attempt would silently use it.
+            if (storeKind === 'encrypted-file')
+                this.#masterPassword = undefined;
+            throw error;
+        }
+        this.#credentials = credentials;
+        this.#storeKind = storeKind;
+        this.#restored = true;
+    }
+    /** Forgets the credentials everywhere they might be. */
+    async signOut() {
+        // Every store, not only the one in use: a user signing out means "remove it",
+        // and a leftover in another store would silently sign them back in.
+        for (const kind of Object.keys(this.#stores)) {
+            try {
+                await this.#stores[kind].clear();
+            }
+            catch {
+                // Nothing there is the outcome we wanted anyway.
+            }
+        }
+        this.#credentials = undefined;
+        this.#storeKind = undefined;
+        this.#masterPassword = undefined;
+        this.#restored = true;
+    }
+    /** Replaces a store. Used by tests and by the startup wiring. */
+    setStore(kind, store) {
+        this.#stores[kind] = store;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/settings.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Settings the user can change while the server runs.
+ *
+ * Only the Bridge ports, and that is the whole point of the file: the Bridge
+ * lets you change them, they are the setting most likely to be wrong, and
+ * getting them wrong looks exactly like a Bridge that is not running. Editing an
+ * environment variable in a client's configuration and restarting is a poor way
+ * to find that out.
+ *
+ * **The host is deliberately not settable here.** It stays with the environment,
+ * where changing it is a conscious act. A host field in a web form is a field
+ * that sends the Bridge password to another machine, and no convenience is worth
+ * that.
+ *
+ * The environment still wins. Someone who set BRIDGE_IMAP_PORT explicitly meant
+ * it, and having a stored value silently override it would make their setting a
+ * lie.
+ */
+export interface StoredSettings {
+    imapPort?: number;
+    smtpPort?: number;
+    /**
+     * Whether the "not affiliated with Proton" notice was sent away.
+     *
+     * Kept here rather than in the browser because there is no JavaScript in the
+     * interface to write a cookie, and because a setting the server holds is the
+     * same setting in every browser. It only ever hides the paragraph: the
+     * `unofficial` mark beside the name stays whatever this says.
+     */
+    noticeDismissed?: boolean;
+}
+/** Where the settings live. Next to the credentials, under the user's own data. */
+export declare function settingsPath(env?: NodeJS.ProcessEnv): string;
+/** True for something that can be an IMAP or SMTP port. */
+export declare function isPort(value: unknown): value is number;
+/**
+ * Reads the stored settings.
+ *
+ * A missing, unreadable or broken file yields no settings rather than an error:
+ * these are conveniences, and none of them is worth refusing to start over.
+ * Values that are not ports are dropped individually, so one bad entry does not
+ * discard a good one.
+ */
+export declare function loadSettings(path?: string): Promise<StoredSettings>;
+/**
+ * Writes the settings.
+ *
+ * Mode 600 like everything else this server puts on disk. Port numbers are not
+ * secret, but a directory of mixed permissions is how the file that does matter
+ * ends up readable one day.
+ */
+export declare function saveSettings(settings: StoredSettings, path?: string): Promise<void>;

package/dist/settings.js

@@ -0,0 +1,80 @@
+/**
+ * Settings the user can change while the server runs.
+ *
+ * Only the Bridge ports, and that is the whole point of the file: the Bridge
+ * lets you change them, they are the setting most likely to be wrong, and
+ * getting them wrong looks exactly like a Bridge that is not running. Editing an
+ * environment variable in a client's configuration and restarting is a poor way
+ * to find that out.
+ *
+ * **The host is deliberately not settable here.** It stays with the environment,
+ * where changing it is a conscious act. A host field in a web form is a field
+ * that sends the Bridge password to another machine, and no convenience is worth
+ * that.
+ *
+ * The environment still wins. Someone who set BRIDGE_IMAP_PORT explicitly meant
+ * it, and having a stored value silently override it would make their setting a
+ * lie.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+/** Where the settings live. Next to the credentials, under the user's own data. */
+export function settingsPath(env = process.env) {
+    if (env.PROTON_MCP_SETTINGS_FILE)
+        return env.PROTON_MCP_SETTINGS_FILE;
+    return join(homedir(), '.config', 'proton-mcp', 'settings.json');
+}
+/** True for something that can be an IMAP or SMTP port. */
+export function isPort(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+/**
+ * Reads the stored settings.
+ *
+ * A missing, unreadable or broken file yields no settings rather than an error:
+ * these are conveniences, and none of them is worth refusing to start over.
+ * Values that are not ports are dropped individually, so one bad entry does not
+ * discard a good one.
+ */
+export async function loadSettings(path = settingsPath()) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return {};
+    const candidate = parsed;
+    const settings = {};
+    if (isPort(candidate.imapPort))
+        settings.imapPort = candidate.imapPort;
+    if (isPort(candidate.smtpPort))
+        settings.smtpPort = candidate.smtpPort;
+    // Only a literal true hides it. Anything else, including a string "true" from
+    // a hand-edited file, leaves the notice where it is.
+    if (candidate.noticeDismissed === true)
+        settings.noticeDismissed = true;
+    return settings;
+}
+/**
+ * Writes the settings.
+ *
+ * Mode 600 like everything else this server puts on disk. Port numbers are not
+ * secret, but a directory of mixed permissions is how the file that does matter
+ * ends up readable one day.
+ */
+export async function saveSettings(settings, path = settingsPath()) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAgBjC,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC/D,IAAI,GAAG,CAAC,wBAAwB;QAAE,OAAO,GAAG,CAAC,wBAAwB,CAAA;IACrE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,CAAC,CAAA;AAClE,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,CAAA;AAC7F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAI,GAAG,YAAY,EAAE;IACtD,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;IAED,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAA;IAE5D,MAAM,SAAS,GAAG,MAAiC,CAAA;IACnD,MAAM,QAAQ,GAAmB,EAAE,CAAA;IACnC,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAA;IACtE,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAA;IACtE,8EAA8E;IAC9E,qDAAqD;IACrD,IAAI,SAAS,CAAC,eAAe,KAAK,IAAI;QAAE,QAAQ,CAAC,eAAe,GAAG,IAAI,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAwB,EACxB,IAAI,GAAG,YAAY,EAAE;IAErB,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5D,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;AAClF,CAAC"}

package/dist/tools/actions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tools: move_messages, set_flags, trash_messages.
+ *
+ * The everyday tidying actions. They change where a message sits and how it is
+ * marked, never what it says and never who has seen it, so none of them is put
+ * behind a confirmation. The confirmation requirement belongs to sending, where
+ * a wrong decision cannot be taken back.
+ *
+ * Two properties are worth stating here rather than leaving to the reader:
+ *
+ * - **Nothing in this file deletes.** "Delete" means moving to the trash, which
+ *   Proton keeps and which "All Mail" still lists. A tool that emptied the trash
+ *   would turn a model's mistake into a permanent one.
+ * - **Nothing reports a result it has not established.** A move takes about
+ *   fifteen seconds to settle and shows the message in both places meanwhile, so
+ *   the answers say what was asked for and warn against checking immediately.
+ *   Flags are the exception and get no such warning: measured, they hold at once.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { Connection } from '../bridge/connection.js';
+export declare function registerActionTools(server: McpServer, connection: Connection, readOnly: () => boolean): void;

package/dist/tools/actions.js

@@ -0,0 +1,133 @@
+/**
+ * Tools: move_messages, set_flags, trash_messages.
+ *
+ * The everyday tidying actions. They change where a message sits and how it is
+ * marked, never what it says and never who has seen it, so none of them is put
+ * behind a confirmation. The confirmation requirement belongs to sending, where
+ * a wrong decision cannot be taken back.
+ *
+ * Two properties are worth stating here rather than leaving to the reader:
+ *
+ * - **Nothing in this file deletes.** "Delete" means moving to the trash, which
+ *   Proton keeps and which "All Mail" still lists. A tool that emptied the trash
+ *   would turn a model's mistake into a permanent one.
+ * - **Nothing reports a result it has not established.** A move takes about
+ *   fifteen seconds to settle and shows the message in both places meanwhile, so
+ *   the answers say what was asked for and warn against checking immediately.
+ *   Flags are the exception and get no such warning: measured, they hold at once.
+ */
+import * as z from 'zod';
+import { moveMessages, setFlags, trashMessages, MAX_BATCH, TRASH } from '../mail/actions.js';
+import { formatBatch } from './format.js';
+import { describeFailure, withSignIn } from './failures.js';
+import { track } from '../in-flight.js';
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+/**
+ * Appended to every answer that moved something.
+ *
+ * Measured: a move needs roughly fifteen seconds to settle, and during that
+ * window the Bridge lists the message in the old place as well as the new one. A
+ * model that checks its own work straight away reads that intermediate state and
+ * reports it as the outcome.
+ */
+const SETTLE_NOTE = 'The Bridge needs about fifteen seconds to reconcile a move with Proton, and until then it lists ' +
+    'the message in both the old and the new mailbox. Do not check the result immediately; an ' +
+    'immediate listing would be misleading rather than informative.';
+const messageIds = z
+    .array(z.string())
+    .min(1)
+    .max(MAX_BATCH)
+    .describe(`The message ids, as they came from a listing or a search. At most ${MAX_BATCH} per call.`);
+const mailboxHint = z
+    .string()
+    .optional()
+    .describe('The mailbox the messages are in, if they share one. Only a shortcut: without it every ' +
+    'message is looked for across the mailboxes it could be in, which costs a request each.');
+export function registerActionTools(server, connection, readOnly) {
+    server.registerTool('move_messages', {
+        title: 'Move messages to a folder',
+        description: 'Moves messages into a folder. In Proton a message lives in exactly one folder, so this ' +
+            'takes it out of the one it is in. Labels are not affected and survive the move. ' +
+            'Only folders are valid destinations: moving into a label would apply the label and leave ' +
+            'the message where it is, so a label is refused here and add_label does that job. ' +
+            'The destination has to exist; this server does not create folders.',
+        inputSchema: z.object({
+            messageIds,
+            target: z
+                .string()
+                .describe('The destination folder, for example "Archive" or "Folders/Work". Use list_folders to ' +
+                'see the paths. Note that Proton fills the inbox through delivery: a message moved ' +
+                'to "INBOX" over IMAP was measured to end up elsewhere shortly afterwards.'),
+            mailbox: mailboxHint,
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ messageIds: ids, target, mailbox }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const result = await moveMessages(connection, readOnly(), ids, target, mailbox);
+            return ok(`${formatBatch(result, `Moved into "${result.target}":`)}\n\n${SETTLE_NOTE}`);
+        }
+        catch (error) {
+            return describeFailure(error, `moving messages to "${target}"`);
+        }
+    }), 'move_messages'));
+    server.registerTool('set_flags', {
+        title: 'Set read state and star',
+        description: 'Marks messages as read or unread and sets or clears the star. At least one of the two has ' +
+            'to be given. This changes nothing about where a message sits and nothing about its ' +
+            'content. Proton shows the star as the "Starred" mailbox.',
+        inputSchema: z.object({
+            messageIds,
+            read: z
+                .boolean()
+                .optional()
+                .describe('True marks the messages as read, false as unread. Omit to leave it alone.'),
+            starred: z
+                .boolean()
+                .optional()
+                .describe('True stars the messages, false removes the star. Omit to leave it alone.'),
+            mailbox: mailboxHint,
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ messageIds: ids, read, starred, mailbox }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const changes = {};
+            if (read !== undefined)
+                changes.read = read;
+            if (starred !== undefined)
+                changes.starred = starred;
+            const result = await setFlags(connection, readOnly(), ids, changes, mailbox);
+            const what = [
+                read === undefined ? undefined : read ? 'read' : 'unread',
+                starred === undefined ? undefined : starred ? 'starred' : 'not starred',
+            ]
+                .filter(Boolean)
+                .join(' and ');
+            // No settling note here: measured, flags are correct immediately
+            // and unchanged twenty seconds later.
+            return ok(formatBatch(result, `Set to ${what} for`));
+        }
+        catch (error) {
+            return describeFailure(error, 'changing the read state or the star');
+        }
+    }), 'set_flags'));
+    server.registerTool('trash_messages', {
+        title: 'Move messages to the trash',
+        description: 'Moves messages to the trash. This is what deletion means here: the messages stay in ' +
+            `"${TRASH}" and in "All Mail" and can be moved back out with move_messages. ` +
+            'There is no tool in this server that deletes a message for good or empties the trash, ' +
+            'so that a wrong decision stays reversible.',
+        inputSchema: z.object({ messageIds, mailbox: mailboxHint }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ messageIds: ids, mailbox }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const result = await trashMessages(connection, readOnly(), ids, mailbox);
+            return ok(`${formatBatch(result, `Moved to "${TRASH}":`)}\n\n` +
+                'Nothing was deleted for good. The messages can be moved back out of the trash. ' +
+                SETTLE_NOTE);
+        }
+        catch (error) {
+            return describeFailure(error, 'moving messages to the trash');
+        }
+    }), 'trash_messages'));
+}
+//# sourceMappingURL=actions.js.map

package/dist/tools/actions.js.map

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

package/dist/tools/capabilities.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the client said it can do.
+ *
+ * One module, because two places ask the same question and one of them decides
+ * whether a message may be sent. When they read different sources they give
+ * different answers, and the answer that matters is the one that refuses.
+ *
+ * ## Why this exists at all
+ *
+ * The first version of both checks read the capabilities out of the request's
+ * `_meta` envelope, under `io.modelcontextprotocol/clientCapabilities`. That key
+ * belongs to protocol revision 2026-07-28. The SDK in use here does not speak
+ * that revision at all: its newest is 2025-11-25, and on such a connection the
+ * envelope is not merely empty but absent.
+ *
+ * So the check answered "this client cannot show a form" for every client that
+ * ever connected, and every send was refused. Fail-closed, so nothing went out
+ * without a confirmation. It also meant nothing went out at all.
+ *
+ * Measured on 31.07.2026 against `serveStdio` with SDK 2.0.0:
+ *
+ * | Source | On a 2025-11-25 connection |
+ * | :--- | :--- |
+ * | `ctx.mcpReq.envelope` | absent |
+ * | `server.server.getClientCapabilities()` | the declaration, complete |
+ *
+ * And the round trip itself works: a returned `inputRequired` reaches the client
+ * as an `elicitation/create`, the answer comes back, and the handler runs a
+ * second time with it. Only the question of whether to try was broken.
+ *
+ * ## Both sources, not one
+ *
+ * The envelope is asked first and the handshake second, rather than replacing
+ * one with the other. The envelope is per request and is what a 2026-era
+ * connection carries; the handshake is per connection and is what this era has.
+ * A server that has to guess which one exists is a server that breaks on the
+ * next SDK release, in whichever direction it moves.
+ */
+export declare function setHandshakeCapabilities(source: () => unknown): void;
+/** For tests, which must not inherit a source from another test. */
+export declare function _clearHandshakeCapabilities(): void;
+/**
+ * What this client declared, from whichever source has it.
+ *
+ * Typed as unknown on purpose. The client sent this, so its shape is a claim
+ * rather than a guarantee, and every reader narrows it by hand.
+ */
+export declare function declaredCapabilities(ctx: unknown): unknown;
+/** Whether the client can show a form and give an answer back. */
+export declare function canElicitForm(ctx: unknown): boolean;
+/** Whether the client can put a URL in front of the user. */
+export declare function canElicitUrl(ctx: unknown): boolean;