@rndmjoker/proton-mcp 0.4.4

package/dist/tools/messages.js

@@ -0,0 +1,221 @@
+/**
+ * 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 * as z from 'zod';
+import { describeFailure, withSignIn } from './failures.js';
+import { track } from '../in-flight.js';
+import { listMessages, getMessage, MAX_LIST_LIMIT } from '../mail/messages.js';
+import { getAttachment } from '../mail/attachments.js';
+import { searchMessages } from '../mail/search.js';
+import { ALL_MAIL } from '../mail/ids.js';
+import { formatList, formatMessage, formatSearch, formatSize, wrapUntrusted } from './format.js';
+const asError = describeFailure;
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+export function registerMessageTools(server, connection) {
+    server.registerTool('list_messages', {
+        title: 'List messages',
+        description: 'Lists the messages of a mailbox, newest first by the date the sender wrote, which also holds ' +
+            'across pages. Returns headers only: sender, subject, date, size and the message id. It never ' +
+            'returns message bodies, because a single message averages around 16000 tokens raw. Use ' +
+            'get_message with an id to read one. Ordering reads one date per message in the mailbox, so a ' +
+            'very large mailbox takes a moment; the answer says so when it does.',
+        inputSchema: z.object({
+            mailbox: z
+                .string()
+                .default('INBOX')
+                .describe('The mailbox path, for example "INBOX", "Archive" or "Folders/Work". Use list_folders to see them.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_LIST_LIMIT)
+                .default(25)
+                .describe(`How many messages to return, at most ${MAX_LIST_LIMIT}.`),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe('How many of the newest messages to skip. Used for paging.'),
+            unreadOnly: z.boolean().default(false).describe('When true, only unread messages are listed.'),
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ mailbox, limit, offset, unreadOnly }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const result = await listMessages(connection, mailbox, { limit, offset, unreadOnly });
+            return ok(formatList(result));
+        }
+        catch (error) {
+            return asError(error, `listing "${mailbox}"`);
+        }
+    }), 'list_messages'));
+    server.registerTool('search_messages', {
+        title: 'Search messages',
+        description: 'Searches a mailbox by text, subject, sender, recipient, date range, read state, star or size. ' +
+            'At least one criterion is required. Returns headers only, newest first across pages, with paging. ' +
+            'A full-text search walks the local database of the Bridge and takes a few seconds on a large ' +
+            'mailbox, while criteria such as unread or date are fast. Searching "All Mail" covers every ' +
+            'mailbox including trash.',
+        inputSchema: z.object({
+            mailbox: z
+                .string()
+                .default(ALL_MAIL)
+                .describe(`Which mailbox to search. Defaults to "${ALL_MAIL}", which holds every message.`),
+            text: z
+                .string()
+                .optional()
+                .describe('Free text, matched against body and headers. This is the slow criterion.'),
+            subject: z.string().optional().describe('Substring of the subject.'),
+            from: z.string().optional().describe('Substring of the sender address or display name.'),
+            to: z.string().optional().describe('Substring of a recipient address.'),
+            since: z
+                .string()
+                .optional()
+                .describe('Only messages on or after this date, as YYYY-MM-DD.'),
+            before: z.string().optional().describe('Only messages before this date, as YYYY-MM-DD.'),
+            unreadOnly: z.boolean().optional().describe('When true, only unread messages.'),
+            starredOnly: z.boolean().optional().describe('When true, only starred messages.'),
+            largerThan: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Minimum size in bytes. Useful for finding messages with large attachments.'),
+            limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(25).describe('How many results to return.'),
+            offset: z.number().int().min(0).default(0).describe('How many results to skip, for paging.'),
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const criteria = { limit: args.limit, offset: args.offset };
+            if (args.text)
+                criteria.text = args.text;
+            if (args.subject)
+                criteria.subject = args.subject;
+            if (args.from)
+                criteria.from = args.from;
+            if (args.to)
+                criteria.to = args.to;
+            if (args.unreadOnly !== undefined)
+                criteria.seen = !args.unreadOnly;
+            if (args.starredOnly !== undefined)
+                criteria.flagged = args.starredOnly;
+            if (args.largerThan !== undefined)
+                criteria.largerThan = args.largerThan;
+            for (const [name, value] of [
+                ['since', args.since],
+                ['before', args.before],
+            ]) {
+                if (!value)
+                    continue;
+                const parsed = new Date(value);
+                if (Number.isNaN(parsed.getTime())) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `"${value}" is not a usable date for ${name}. Expected YYYY-MM-DD.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                criteria[name] = parsed;
+            }
+            const result = await searchMessages(connection, args.mailbox, criteria);
+            return ok(formatSearch(result));
+        }
+        catch (error) {
+            return asError(error, `searching "${args.mailbox}"`);
+        }
+    }), 'search_messages'));
+    server.registerTool('get_message', {
+        title: 'Read a message',
+        description: 'Reads one message by its id and returns it as readable text. HTML is converted to text, ' +
+            'images and styling are dropped and no external content is fetched. Long bodies are shortened ' +
+            'with a visible note. The body is marked as untrusted third-party content.',
+        inputSchema: z.object({
+            messageId: z
+                .string()
+                .describe('The message id from list_messages or search, passed on unchanged.'),
+            mailbox: z
+                .string()
+                .optional()
+                .describe('Optional: the mailbox to look in first. Saves a lookup. Without it the search goes through "All Mail".'),
+            maxChars: z
+                .number()
+                .int()
+                .min(500)
+                .max(200_000)
+                .optional()
+                .describe('Optional character budget for the body. Higher values cost context.'),
+            textOffset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Where to continue reading a long message. The answer names the next offset when ' +
+                'something was left out, so a long message can be read in parts instead of raising ' +
+                'the budget until it fits.'),
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ messageId, mailbox, maxChars, textOffset }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const options = {};
+            if (mailbox)
+                options.hint = mailbox;
+            if (maxChars)
+                options.maxTextChars = maxChars;
+            if (textOffset)
+                options.textOffset = textOffset;
+            const message = await getMessage(connection, messageId, options);
+            return ok(formatMessage(message));
+        }
+        catch (error) {
+            return asError(error, 'reading the message');
+        }
+    }), 'get_message'));
+    server.registerTool('get_attachment', {
+        title: 'Read an attachment',
+        description: 'Reads one attachment of a message by index. The index comes from the attachment list in ' +
+            'get_message. Textual attachments are returned as text, binary ones are refused with a reason ' +
+            'rather than dumped into the context.',
+        inputSchema: z.object({
+            messageId: z.string().describe('The message id the attachment belongs to.'),
+            index: z
+                .number()
+                .int()
+                .min(0)
+                .describe('Index of the attachment, as shown by get_message. Starts at 0.'),
+            mailbox: z.string().optional().describe('Optional: the mailbox to look in first.'),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Where to continue reading a long attachment. The answer names the next offset.'),
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ messageId, index, mailbox, offset }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            const options = {};
+            if (mailbox)
+                options.hint = mailbox;
+            if (offset)
+                options.offset = offset;
+            const a = await getAttachment(connection, messageId, index, options);
+            const head = `Attachment "${a.filename}" (${a.contentType}, ${formatSize(a.size)})`;
+            if (a.unsupportedReason) {
+                return ok(`${head}\n\n${a.unsupportedReason}`);
+            }
+            return ok(wrapUntrusted(a.text ?? '', head));
+        }
+        catch (error) {
+            return asError(error, 'reading the attachment');
+        }
+    }), 'get_attachment'));
+}
+//# sourceMappingURL=messages.js.map

package/dist/tools/messages.js.map

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

package/dist/tools/send.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tools: send_message, send_reply, send_forward, send_draft.
+ *
+ * All four go through one function, `confirmed`, and that is the point. Four
+ * copies of a confirmation is four chances for one of them to drift, and the
+ * one that drifts is the one that sends without asking.
+ *
+ * Why replying and forwarding are sending tools of their own, rather than
+ * "make a draft, then send the draft": measured, Proton rewrites the thread
+ * headers of anything it stores. A reply written to a draft and sent later
+ * carries Proton's internal thread id and not the In-Reply-To and References
+ * that were built. Building the reply and handing it to SMTP without storing it
+ * in between is the only way the headers we wrote are the headers that go out.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { RequestStateCodec } from '@modelcontextprotocol/server';
+import type { Connection } from '../bridge/connection.js';
+import type { Config, BridgeCredentials } from '../config.js';
+import { type PendingSend } from './confirm.js';
+export interface SendDependencies {
+    config: Config;
+    connection: Connection;
+    getCredentials: () => Promise<BridgeCredentials | undefined>;
+    readOnly: () => boolean;
+    from: () => string | undefined;
+    /** Seals and opens the state that carries a confirmation across the round trip. */
+    codec: RequestStateCodec<PendingSend>;
+}
+export declare function registerSendTools(server: McpServer, deps: SendDependencies): void;

package/dist/tools/send.js

@@ -0,0 +1,236 @@
+/**
+ * Tools: send_message, send_reply, send_forward, send_draft.
+ *
+ * All four go through one function, `confirmed`, and that is the point. Four
+ * copies of a confirmation is four chances for one of them to drift, and the
+ * one that drifts is the one that sends without asking.
+ *
+ * Why replying and forwarding are sending tools of their own, rather than
+ * "make a draft, then send the draft": measured, Proton rewrites the thread
+ * headers of anything it stores. A reply written to a draft and sent later
+ * carries Proton's internal thread id and not the In-Reply-To and References
+ * that were built. Building the reply and handing it to SMTP without storing it
+ * in between is the only way the headers we wrote are the headers that go out.
+ */
+import * as z from 'zod';
+import { BridgeError } from '../bridge/errors.js';
+import { htmlToText } from '../mime/parse.js';
+import { sendMessage } from '../mail/send.js';
+import { buildReplyDraft, buildForwardDraft, readDraftForSending, DRAFTS, } from '../mail/drafts.js';
+import { describeRecipients, mintMessageId, parseRecipient, parseRecipients, MARKUP_NOTE, PLAIN_TEXT_NOTE, UTF8_NOTE, } from '../mail/compose.js';
+import { clientCanConfirm, confirmationAnswer, confirmationRequest, digestOf, pendingSend, refuse, } from './confirm.js';
+import { describeFailure, withSignIn } from './failures.js';
+import { track } from '../in-flight.js';
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+/**
+ * Measured: SMTP accepted a message about six seconds before IMAP showed it,
+ * and an appended message took about twenty seconds to reach "All Mail". A tool
+ * that checked its own send would describe a state that is not the outcome.
+ */
+const AFTER_NOTE = 'The Bridge has taken the message; Proton delivers it from there. It takes a moment to appear ' +
+    'in Sent, so do not look for it straight away. An immediate listing would be misleading rather ' +
+    'than informative.';
+/**
+ * What went out.
+ *
+ * Built from the draft rather than cut out of the confirmation text by line
+ * number. The first version did the latter and lost the body: it printed "The
+ * message begins:" followed by nothing, because a slice by index breaks the
+ * moment the text it slices gains a line.
+ */
+function describeOutcome(draft, outcome) {
+    const lines = [
+        `Sent. The Bridge accepted the message for ${outcome.accepted.length} recipient(s).`,
+        '',
+        describeRecipients(draft),
+        `Subject: ${draft.subject || '(no subject)'}`,
+        ...(draft.attachedMessage ? [`Attached: ${draft.attachedMessage.filename}`] : []),
+        `Id: ${outcome.messageId}`,
+    ];
+    if (outcome.rejected.length) {
+        lines.push('', `Refused for: ${outcome.rejected.join(', ')}. The message went to the others, so it was ` +
+            'delivered in part rather than not at all.');
+    }
+    lines.push('', AFTER_NOTE);
+    return lines.join('\n');
+}
+function requireFrom(deps) {
+    const address = deps.from();
+    if (!address) {
+        throw new BridgeError('Nobody is signed in, so there is no address to send from. Sign in through the ' +
+            'configuration page first.');
+    }
+    return address;
+}
+/**
+ * The whole confirmation flow, once.
+ *
+ * `build` produces the message from the call's arguments. It runs on both
+ * rounds, and it has to: the second round recomputes the digest from what the
+ * client is asking for now and compares it with what the user actually agreed
+ * to. Building once and trusting the client to hand it back would be trusting
+ * exactly the thing that needs checking.
+ */
+async function confirmed(deps, ctx, tool, what, build) {
+    // Asked before anything else. A confirmation for a send that read-only would
+    // refuse anyway is a question with no honest answer.
+    if (deps.readOnly()) {
+        return describeFailure(new BridgeError('The server is running read-only, so sending is refused. This is set by ' +
+            'PROTON_MCP_READ_ONLY and the web interface reports it as the current mode.'), 'sending');
+    }
+    const draft = await build();
+    const digest = digestOf(draft);
+    const pending = pendingSend(ctx);
+    if (!pending) {
+        // First round. Nothing is sent here under any circumstances.
+        if (!clientCanConfirm(ctx))
+            return refuse.noElicitation();
+        const state = await deps.codec.mint({ tool, digest }, ctx);
+        return confirmationRequest(draft, what, state);
+    }
+    // Second round. The seal has already been verified by the SDK, so what is
+    // left is whether it says the same thing this call is asking for.
+    if (pending.tool !== tool)
+        return refuse.wrongTool();
+    if (pending.digest !== digest)
+        return refuse.changed();
+    if (confirmationAnswer(ctx) !== 'yes')
+        return refuse.declined();
+    const outcome = await sendMessage(deps.config, deps.getCredentials, deps.readOnly(), draft);
+    return ok(describeOutcome(draft, outcome));
+}
+const addressList = (what) => z
+    .array(z.string())
+    .optional()
+    .describe(`${what} Each entry is an address, optionally as "Display Name <name@example.com>".`);
+const CONFIRMATION_NOTE = 'Every send asks the user to confirm first, through the client, showing the final recipients, ' +
+    'the subject and the first lines. There is no way to switch that off, and a client that cannot ' +
+    'show the question cannot send at all.';
+export function registerSendTools(server, deps) {
+    server.registerTool('send_message', {
+        title: 'Send a message',
+        description: `Composes a message and sends it. ${CONFIRMATION_NOTE} ${PLAIN_TEXT_NOTE} ${MARKUP_NOTE} ${UTF8_NOTE}`,
+        inputSchema: z.object({
+            to: addressList('The main recipients.'),
+            cc: addressList('Recipients in copy, visible to everyone.'),
+            bcc: addressList('Recipients in blind copy. They receive it; the others do not see them.'),
+            subject: z.string().default('').describe('The subject line.'),
+            text: z.string().default('').describe('The body, as plain text.'),
+            html: z
+                .string()
+                .optional()
+                .describe('The body as markup instead of plain text. Give this or text, not both. Permitted ' +
+                'are headings, paragraphs, line breaks, rules, quotes, emphasis, lists, tables, ' +
+                'links and images, with colour, font, alignment, spacing and borders. Images may ' +
+                'point at a full address; anything outside the permitted set is refused with a ' +
+                'reason rather than removed.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (input, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            return await confirmed(deps, ctx, 'send_message', 'This message', async () => {
+                const from = parseRecipient(requireFrom(deps));
+                if (input.html !== undefined && input.text) {
+                    throw new BridgeError('Both a text and a markup body were given. A message carries one or the ' +
+                        'other: Proton drops the text half of a message that has both, so the half ' +
+                        'that was confirmed would never arrive. Give whichever one this message is.');
+                }
+                return {
+                    from,
+                    to: parseRecipients(input.to),
+                    cc: parseRecipients(input.cc),
+                    bcc: parseRecipients(input.bcc),
+                    subject: input.subject,
+                    // The readable rendering, so that everything downstream can
+                    // read `text` and get something true.
+                    text: input.html !== undefined ? htmlToText(input.html) : input.text,
+                    messageId: mintMessageId(from.address),
+                    ...(input.html !== undefined ? { html: input.html } : {}),
+                };
+            });
+        }
+        catch (error) {
+            return describeFailure(error, 'sending the message');
+        }
+    }), 'send_message'));
+    server.registerTool('send_reply', {
+        title: 'Reply to a message',
+        description: 'Replies to a message and sends the reply, with the reference headers that put it in the ' +
+            'same conversation. Unlike a reply written as a draft, this one keeps those headers: ' +
+            'Proton rewrites them for anything it stores, and this is never stored before it goes. ' +
+            `${CONFIRMATION_NOTE} ${PLAIN_TEXT_NOTE} ${MARKUP_NOTE} ${UTF8_NOTE}`,
+        inputSchema: z.object({
+            messageId: z.string().describe('The message being replied to.'),
+            text: z.string().describe('The reply. The original is quoted below it.'),
+            replyAll: z
+                .boolean()
+                .default(false)
+                .describe('When true, the other recipients of the original are put in copy.'),
+            html: z
+                .string()
+                .optional()
+                .describe('Your part of the message as markup instead of plain text. The original is quoted ' +
+                'below it either way. The quote is always built from the original\'s text, never ' +
+                'from its own markup, so a message full of markup this server would not send can ' +
+                'still be replied to or forwarded.'),
+            mailbox: z.string().optional().describe('The mailbox the original is in, if known.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ messageId, text, replyAll, mailbox, html }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            return await confirmed(deps, ctx, 'send_reply', 'This reply', () => buildReplyDraft(deps.connection, requireFrom(deps), messageId, text, {
+                all: replyAll,
+                ...(mailbox ? { mailbox } : {}),
+                ...(html !== undefined ? { html } : {}),
+            }));
+        }
+        catch (error) {
+            return describeFailure(error, 'sending the reply');
+        }
+    }), 'send_reply'));
+    server.registerTool('send_forward', {
+        title: 'Forward a message',
+        description: 'Forwards a message and sends it. The original is quoted, and when it carries attachments ' +
+            `the whole original travels along so nothing of it is lost. ${CONFIRMATION_NOTE} ${PLAIN_TEXT_NOTE} ${MARKUP_NOTE} ${UTF8_NOTE}`,
+        inputSchema: z.object({
+            messageId: z.string().describe('The message being forwarded.'),
+            to: z.array(z.string()).min(1).describe('Who to forward it to.'),
+            text: z.string().default('').describe('Anything to say above the forwarded message.'),
+            html: z
+                .string()
+                .optional()
+                .describe('Your part of the message as markup instead of plain text. The original is quoted ' +
+                'below it either way. The quote is always built from the original\'s text, never ' +
+                'from its own markup, so a message full of markup this server would not send can ' +
+                'still be replied to or forwarded.'),
+            mailbox: z.string().optional().describe('The mailbox the original is in, if known.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ messageId, to, text, mailbox, html }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            return await confirmed(deps, ctx, 'send_forward', 'This forward', () => buildForwardDraft(deps.connection, requireFrom(deps), messageId, to, text, { ...(mailbox ? { mailbox } : {}), ...(html !== undefined ? { html } : {}) }));
+        }
+        catch (error) {
+            return describeFailure(error, 'sending the forward');
+        }
+    }), 'send_forward'));
+    server.registerTool('send_draft', {
+        title: 'Send a draft',
+        description: `Sends a draft that is already in "${DRAFTS}". The draft is not removed afterwards: this ` +
+            'server does not follow a send it deliberately does not verify with a second write. ' +
+            'Use trash_messages on the draft once the message shows up in Sent. ' +
+            `${CONFIRMATION_NOTE}`,
+        inputSchema: z.object({
+            messageId: z.string().describe('The id of the draft, from list_drafts or create_draft.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ messageId }, ctx) => track(() => withSignIn(ctx, async () => {
+        try {
+            return await confirmed(deps, ctx, 'send_draft', 'This draft', () => readDraftForSending(deps.connection, requireFrom(deps), messageId));
+        }
+        catch (error) {
+            return describeFailure(error, 'sending the draft');
+        }
+    }), 'send_draft'));
+}
+//# sourceMappingURL=send.js.map

package/dist/tools/send.js.map

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

package/dist/tools/sign-in-required.d.ts

@@ -0,0 +1,94 @@
+/**
+ * What a tool does when nobody has signed in.
+ *
+ * The point is narrow and worth stating plainly: a model told only that
+ * credentials are missing will ask the user to type their Bridge password into
+ * the chat, where it lands in a transcript. So the answer always names the local
+ * page instead, and says not to ask.
+ *
+ * Two ways of getting the user there:
+ *
+ * 1. **URL elicitation**, which the specification provides for exactly this
+ *    case. The client shows the address, the user signs in, and the tool call
+ *    is retried.
+ * 2. **A plain failure naming the address**, for clients that cannot elicit.
+ *
+ * ## Why this is a returned value and not a call
+ *
+ * The obvious-looking route, `ctx.mcpReq.elicitInput({mode:'url'})`, cannot work
+ * here. Protocol revision 2026-07-28 has no server-to-client request channel at
+ * all, and `serveStdio` marks its server instance as that era at construction.
+ * The push API therefore throws on every call this server will ever serve. That
+ * is why the earlier attempt at this never elicited anything and always fell
+ * back to the text.
+ *
+ * The replacement is a value the handler RETURNS: `inputRequired(...)` with an
+ * embedded URL elicitation. The client fulfils it and calls the tool again, so
+ * the retry is an ordinary second invocation rather than a loop inside the
+ * handler.
+ *
+ * The SDK's shim fulfils such a return on a 2025-era connection as well, and it
+ * does so under `serveStdio` too. An earlier note here said otherwise, on the
+ * strength of a measurement that must have been taken against a different
+ * serving mode; re-measured on 31.07.2026 against SDK 2.0.0, `serveStdio` pins
+ * one instance for the life of the connection, the returned request reaches the
+ * client as an `elicitation/create`, and the answer comes back. The text answer
+ * below is therefore the fallback for a client that declares nothing, not for
+ * every client. See clientCanShowUrl.
+ *
+ * ## No requestState
+ *
+ * `inputRequired` also accepts an opaque `requestState` that travels through the
+ * client and comes back. We do not use it. Whether someone is signed in is
+ * answered by asking the session, which is the truth; a claim carried back
+ * through the client would be attacker-controlled input that we would then have
+ * to integrity-protect for no gain. The embedded request alone satisfies the
+ * protocol's at-least-one rule.
+ */
+import type { CallToolResult, InputRequiredResult } from '@modelcontextprotocol/server';
+/**
+ * The key our embedded elicitation is filed under.
+ *
+ * Also how a retry is recognised: a response under this key means the client has
+ * already taken the user to the page once.
+ */
+export declare const SIGN_IN_KEY = "protonMcpSignIn";
+/** Which of the two situations a caller is in. */
+export type MissingCredentials = 'not-signed-in' | 'locked';
+/**
+ * Whether the client said it can show a URL.
+ *
+ * Asked in advance rather than attempted and caught, because there is nothing to
+ * catch: an embedded request the client never declared support for is refused by
+ * the SDK *after* the handler returns. The caller would get that refusal instead
+ * of an address, so an undeclared capability means the text answer.
+ *
+ * The paragraph that used to stand here claimed, as a measurement, that only the
+ * request's own envelope could be consulted and that a handshake declaration was
+ * unavailable under `serveStdio`. That was wrong, and it was wrong in the
+ * expensive direction: on this SDK the envelope does not exist at all, so the
+ * check answered no for every client and the elicitation never once fired. Where
+ * the declaration now comes from is in capabilities.ts.
+ */
+export declare function clientCanShowUrl(ctx: unknown): boolean;
+/** The failure used when elicitation is unavailable, declined or fruitless. */
+export declare function signInFailure(url: string | undefined, note?: string, state?: MissingCredentials): CallToolResult;
+/**
+ * Asks the client to take the user to the sign-in page.
+ *
+ * Returned from the handler, not sent. See the note at the top of this file for
+ * why that is the only thing that can work here.
+ */
+export declare function signInElicitation(url: string, state?: MissingCredentials): InputRequiredResult;
+/** What came back from a previous round, if this call is a retry. */
+export type PriorAttempt = 'none' | 'accepted' | 'refused';
+/**
+ * Whether the client has already been through the sign-in page for this call.
+ *
+ * "accepted" means the user was shown the page and said they were done, so a
+ * still-missing sign-in is a real failure rather than a reason to ask again.
+ * Asking twice in a row would be a loop the user cannot escape.
+ */
+export declare function priorAttempt(ctx: unknown): PriorAttempt;
+/** The note explaining a retry that still found no credentials. */
+export declare function retryNote(attempt: PriorAttempt, state?: MissingCredentials): string | undefined;