@rndmjoker/proton-mcp 0.4.4

package/dist/tools/sign-in-required.js

@@ -0,0 +1,168 @@
+/**
+ * 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 { inputRequired, inputResponse } from '@modelcontextprotocol/server';
+import { canElicitUrl } from './capabilities.js';
+/**
+ * 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 const SIGN_IN_KEY = 'protonMcpSignIn';
+const MESSAGE = 'proton-mcp is not signed in to Proton Mail Bridge yet. Open the configuration page and enter ' +
+    'the Proton address together with the Bridge password, which is the one the Bridge generates ' +
+    'and not the Proton account password.';
+/**
+ * The other reason a tool finds no credentials: they are on disk, encrypted.
+ *
+ * A separate message because the remedy is a different one, and the message
+ * above sends the user to the wrong place entirely. Nothing has to be looked up
+ * in the Bridge and no address has to be typed: the Bridge password is already
+ * stored, and the one thing missing is the master password that decrypts it,
+ * which is asked for once per start and never kept.
+ *
+ * Telling somebody to fetch their Bridge password when all they need is the
+ * password they chose themselves is the kind of wrong advice that ends with the
+ * encrypted file being thrown away.
+ */
+const LOCKED_MESSAGE = 'proton-mcp has credentials stored, in an encrypted file that is not open yet. It needs the ' +
+    'master password that was chosen when they were saved. Nothing else is missing: the Bridge ' +
+    'password is already on disk, and no address has to be entered again.';
+function messageFor(state) {
+    return state === 'locked' ? LOCKED_MESSAGE : MESSAGE;
+}
+/**
+ * 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 function clientCanShowUrl(ctx) {
+    return canElicitUrl(ctx);
+}
+/** The failure used when elicitation is unavailable, declined or fruitless. */
+export function signInFailure(url, note, state = 'not-signed-in') {
+    const message = messageFor(state);
+    const head = note ? `${note}\n\n${message}` : message;
+    if (!url) {
+        // No page to send anyone to. For a locked file that is a dead end worth
+        // naming as one: the master password can only be entered there.
+        const text = state === 'locked'
+            ? `${head}\n\nThe configuration page is not running, so the file cannot be unlocked right ` +
+                'now. It failed to start, most likely because its port was in use; setting ' +
+                'PROTON_MCP_WEB_PORT to a free port and restarting is the way out. Do not ask for the ' +
+                'master password in this conversation.'
+            : `${head}\n\nThe configuration page is not running. Set BRIDGE_USER and BRIDGE_PASS in ` +
+                'the environment instead. Do not ask for the password in this conversation.';
+        return { content: [{ type: 'text', text }], isError: true };
+    }
+    const instruction = state === 'locked'
+        ? 'Tell the user to open it and enter their master password there. Do not ask for the ' +
+            'master password in this conversation: it is the one thing that can decrypt the stored ' +
+            'credentials, and it has no business in a transcript.'
+        : 'Tell the user to open it and sign in there. Do not ask for the password in this ' +
+            'conversation.';
+    return {
+        content: [{ type: 'text', text: `${head}\n\nOpen ${url}\n\n${instruction}` }],
+        isError: true,
+    };
+}
+/**
+ * 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 function signInElicitation(url, state = 'not-signed-in') {
+    return inputRequired({
+        inputRequests: {
+            [SIGN_IN_KEY]: inputRequired.elicitUrl({ message: messageFor(state), url }),
+        },
+    });
+}
+/**
+ * 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 function priorAttempt(ctx) {
+    const responses = ctx?.mcpReq?.inputResponses;
+    if (!responses)
+        return 'none';
+    const view = inputResponse(responses, SIGN_IN_KEY);
+    if (view.kind === 'missing')
+        return 'none';
+    if (view.kind === 'elicit' && view.action === 'accept')
+        return 'accepted';
+    return 'refused';
+}
+/** The note explaining a retry that still found no credentials. */
+export function retryNote(attempt, state = 'not-signed-in') {
+    if (attempt === 'accepted') {
+        if (state === 'locked') {
+            return 'The page was opened but the credentials are still locked, so the master password was not entered.';
+        }
+        return 'The sign-in page was opened but no credentials arrived, so the sign-in was not completed.';
+    }
+    if (attempt === 'refused') {
+        return 'The request to open the sign-in page was declined or cancelled.';
+    }
+    return undefined;
+}
+//# sourceMappingURL=sign-in-required.js.map

package/dist/tools/sign-in-required.js.map

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

package/dist/web/layout.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The frame every page of the local interface sits in.
+ *
+ * Split out of pages.ts when the single status page became a set of sections:
+ * the styles, the navigation and the outer document are the same everywhere, and
+ * they were the larger half of that file.
+ *
+ * **There is no JavaScript here, and none anywhere in this interface.** The
+ * Content-Security-Policy forbids it, and that is not a limitation worked
+ * around: a page that cannot run script cannot be made to do anything by markup
+ * that finds its way in. So navigation is links, switches are form controls, and
+ * anything that looks interactive is CSS. See security.ts for the rest of the
+ * policy.
+ *
+ * The look follows Proton's own interfaces closely enough to feel related and
+ * uses none of their assets. No logo, no wordmark, no icon of theirs: those are
+ * trademarks, and every page says in as many words that this is not their
+ * project.
+ */
+/** Escapes text for use in HTML. Applied to everything, without exception. */
+export declare function escapeHtml(value: string): string;
+/**
+ * The sections, in the order they appear.
+ *
+ * The top level is the service, which is why there is a group holding a single
+ * entry today: Proton Drive is meant to sit beside Proton Mail later, and a
+ * structure introduced at that point would move everything the user had learned.
+ */
+export type Section = 'overview' | 'mailboxes' | 'bridge' | 'credentials' | 'activity'
+/** Pages outside the navigation: sign-in, unlock, rejection. */
+ | 'none';
+/**
+ * Whether the notice appears, and whether it can be sent away.
+ *
+ * It is read once and then it is furniture, so it can be dismissed and stays
+ * dismissed. What does not go away is the `unofficial` mark beside the name in
+ * the rail: the point of the notice is that nobody mistakes this for Proton's
+ * own software, and a mark that is always in view carries that better than a
+ * paragraph nobody reads twice.
+ *
+ * Dismissing is a form post rather than a click handler, because there is no
+ * JavaScript here, and it is remembered by the server rather than by the
+ * browser, because a setting the server holds survives a different browser.
+ */
+export type DisclaimerState = 
+/** Shown, with the button. The token is bound to the dismissal path. */
+{
+    csrf: string;
+    from: Section;
+}
+/** Shown without a button: no valid session to remember a dismissal against. */
+ | 'plain'
+/** Dismissed earlier, so not shown at all. */
+ | 'dismissed';
+export interface LayoutOptions {
+    title: string;
+    body: string;
+    /**
+     * Which entry is marked as current. `none` renders no navigation at all,
+     * which is what the sign-in and unlock pages want: there is nothing to reach
+     * yet, and a rail full of dead links would suggest otherwise.
+     */
+    section: Section;
+    /** Needed to build the links. Absent before anybody has signed in. */
+    token?: string;
+    /** Defaults to showing it without a button, the safe direction. */
+    disclaimer?: DisclaimerState;
+}
+export declare function layout(options: LayoutOptions): string;
+/** Renders a duration the way a person would say it. */
+export declare function formatDuration(ms: number): string;
+/** An error banner, or nothing. */
+export declare function errorBanner(message: string | undefined): string;
+/** A success banner, or nothing. */
+export declare function noticeBanner(message: string | undefined): string;