npm - hypermail-mcp - Versions diffs - 0.7.6 → 0.7.7 - Mend

hypermail-mcp 0.7.6 → 0.7.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/cli.js CHANGED Viewed

@@ -6881,9 +6881,6 @@ var require_dist = __commonJS({
   }
 });
-// src/cli.ts
-import { randomBytes as randomBytes2 } from "crypto";
 // node_modules/.pnpm/@modelcontextprotocol+sdk@1.29.0_zod@4.4.3/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
 import * as z3rt from "zod/v3";
 import * as z4mini from "zod/v4-mini";
@@ -13854,7 +13851,7 @@ var StreamableHTTPServerTransport = class {
 // src/server.ts
 import { randomUUID as randomUUID6 } from "crypto";
-import { createServer as createHttpServer } from "http";
+import { createServer as createHttpServer2 } from "http";
 // src/store/account-store.ts
 import { promises as fs2 } from "fs";
@@ -13897,8 +13894,11 @@ function decrypt(buf, key) {
   return JSON.parse(pt.toString("utf8"));
 }
 function resolveDataDir(explicit) {
-  if (explicit && explicit.length > 0) return path.resolve(explicit);
-  return path.join(homedir(), ".hypermail-mcp");
+  if (explicit && explicit.length > 0) return explicit;
+  const envDataDir = process.env.HYPERMAIL_DATA_DIR;
+  if (envDataDir && envDataDir.length > 0) return envDataDir;
+  const dataHome = process.env.XDG_DATA_HOME && process.env.XDG_DATA_HOME.length > 0 ? process.env.XDG_DATA_HOME : path.join(homedir(), ".local", "share");
+  return path.join(dataHome, "hypermail-mcp");
 }
 function parseEnvKey(raw) {
   const s = raw.trim();
@@ -13911,7 +13911,7 @@ function parseEnvKey(raw) {
   return createHash("sha256").update(s, "utf8").digest();
 }
 async function resolveKey(dataDir) {
-  const env = process.env.HYPERMAIL_MCP_KEY;
+  const env = process.env.HYPERMAIL_KEY;
   if (env && env.length > 0) {
     const k = parseEnvKey(env);
     if (k) return k;
@@ -14082,7 +14082,7 @@ function beginDeviceCode(scopes = DEFAULT_SCOPES, clientIdOverride, tenantOverri
         if (!info.userCode || !info.verificationUri) {
           reject(
             new Error(
-              "Microsoft device-code endpoint returned no code. Check HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID is a valid Azure Entra public-client application."
+              "Microsoft device-code endpoint returned no code. Check HYPERMAIL_OUTLOOK_CLIENT_ID is a valid Azure Entra public-client application."
             )
           );
           return;
@@ -15545,12 +15545,16 @@ var ImapProvider = class {
 import { randomUUID as randomUUID5 } from "crypto";
 // src/providers/gmail/auth.ts
+import { createHash as createHash2, randomBytes as randomBytes2 } from "crypto";
+import { createServer as createHttpServer } from "http";
 import { OAuth2Client } from "google-auth-library";
-var GOOGLE_DEVICE_CODE_URL = "https://oauth2.googleapis.com/device/code";
+var GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
 var GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
 var DEFAULT_SCOPES2 = [
   "https://www.googleapis.com/auth/gmail.modify"
 ];
+var DEFAULT_GMAIL_OAUTH_CALLBACK_PATH = "/oauth/gmail/callback";
+var DEFAULT_FLOW_TTL_MS = 20 * 6e4;
 function isSerializedGmailTokens(obj) {
   if (typeof obj !== "object" || obj === null) return false;
   const o = obj;
@@ -15571,6 +15575,82 @@ function buildOAuth2Client(tokens) {
   }
   return client;
 }
+function base64Url(buf) {
+  return buf.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function randomBase64Url(bytes = 32) {
+  return base64Url(randomBytes2(bytes));
+}
+function codeChallenge(verifier) {
+  return base64Url(createHash2("sha256").update(verifier).digest());
+}
+function htmlResponse(title, body) {
+  return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>${title}</title></head>
+<body><h1>${title}</h1><p>${body}</p></body>
+</html>`;
+}
+function sendHtml(res, status, title, body) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "text/html; charset=utf-8");
+  res.end(htmlResponse(title, body));
+}
+async function startLocalCallbackServer() {
+  let redirectUri = "";
+  let captured;
+  let closed = false;
+  const server = createHttpServer((req, res) => {
+    if (!req.url) {
+      sendHtml(res, 400, "Gmail authorization failed", "The callback URL was empty.");
+      return;
+    }
+    const callbackUrl = new URL(req.url, redirectUri);
+    if (callbackUrl.pathname !== "/oauth2callback") {
+      sendHtml(res, 404, "Not found", "This local callback server only handles Gmail OAuth redirects.");
+      return;
+    }
+    captured = callbackUrl.toString();
+    const error = callbackUrl.searchParams.get("error");
+    if (error) {
+      sendHtml(res, 400, "Gmail authorization failed", "You can close this tab and return to your MCP client.");
+    } else {
+      sendHtml(res, 200, "Gmail authorization complete", "You can close this tab and return to your MCP client.");
+    }
+    setImmediate(closeServer);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address) {
+    closeServer();
+    throw new Error("Failed to start local Gmail OAuth callback server");
+  }
+  redirectUri = `http://127.0.0.1:${address.port}/oauth2callback`;
+  function closeServer() {
+    if (closed) return;
+    closed = true;
+    try {
+      server.close();
+    } catch {
+    }
+  }
+  return {
+    redirectUri,
+    cancel: closeServer,
+    consumeAuthorizationResponse() {
+      if (!captured) return void 0;
+      const authorizationResponse = captured;
+      captured = void 0;
+      return { authorizationResponse };
+    }
+  };
+}
 async function getEmailFromToken(accessToken) {
   const res = await fetch(
     "https://gmail.googleapis.com/gmail/v1/users/me/profile",
@@ -15589,134 +15669,115 @@ async function getEmailFromToken(accessToken) {
   const data = await res.json();
   return data.emailAddress;
 }
-function beginDeviceCode2(scopes = DEFAULT_SCOPES2, clientIdOverride, clientSecretOverride) {
-  const clientId = clientIdOverride;
+async function beginAuthorizationCode(options = {}) {
+  const scopes = options.scopes ?? DEFAULT_SCOPES2;
+  const clientId = options.clientId;
   if (!clientId) {
     throw new Error(
-      "HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID is required for Gmail OAuth \u2014 set it via HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID or provider config"
+      "HYPERMAIL_GMAIL_CLIENT_ID is required for Gmail OAuth \u2014 set HYPERMAIL_GMAIL_CLIENT_ID before adding a Gmail account"
     );
   }
-  const clientSecret = clientSecretOverride || void 0;
-  let resolve;
-  let reject;
-  const result = new Promise(
-    (res, rej) => {
-      resolve = res;
-      reject = rej;
-    }
-  );
-  let userCode = "";
-  let verificationUri = "";
-  let message = "";
-  let expiresAt = new Date(Date.now() + 15 * 6e4).toISOString();
-  let aborted = false;
-  const ready = (async () => {
-    try {
-      const dcParams = new URLSearchParams();
-      dcParams.set("client_id", clientId);
-      if (clientSecret) dcParams.set("client_secret", clientSecret);
-      dcParams.set("scope", scopes.join(" "));
-      const dcRes = await fetch(GOOGLE_DEVICE_CODE_URL, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: dcParams.toString()
-      });
-      if (!dcRes.ok) {
-        const errBody = await dcRes.json().catch(() => ({}));
-        throw new Error(
-          `Google device-code request failed: ${errBody.error_description ?? errBody.error ?? dcRes.statusText}`
-        );
-      }
-      const dcData = await dcRes.json();
-      userCode = dcData.user_code;
-      verificationUri = dcData.verification_url;
-      const deviceCode = dcData.device_code;
-      let interval = dcData.interval ?? 5;
-      if (dcData.expires_in) {
-        expiresAt = new Date(
-          Date.now() + dcData.expires_in * 1e3
-        ).toISOString();
-      }
-      message = `Go to ${verificationUri} and enter code: ${userCode}`;
-      const tokenParams = new URLSearchParams();
-      tokenParams.set("client_id", clientId);
-      if (clientSecret) tokenParams.set("client_secret", clientSecret);
-      tokenParams.set("device_code", deviceCode);
-      tokenParams.set(
-        "grant_type",
-        "urn:ietf:params:oauth:grant-type:device_code"
-      );
-      const deadline = Date.now() + dcData.expires_in * 1e3;
-      while (Date.now() < deadline && !aborted) {
-        await new Promise((r) => setTimeout(r, interval * 1e3));
-        if (aborted) return;
-        const tokenRes = await fetch(GOOGLE_TOKEN_URL, {
-          method: "POST",
-          headers: { "Content-Type": "application/x-www-form-urlencoded" },
-          body: tokenParams.toString()
-        });
-        const tokenData = await tokenRes.json();
-        if (tokenData.access_token) {
-          const email = await getEmailFromToken(tokenData.access_token);
-          const tokens = {
-            clientId,
-            clientSecret,
-            accessToken: tokenData.access_token,
-            refreshToken: tokenData.refresh_token ?? "",
-            expiryDate: tokenData.expires_in ? Date.now() + tokenData.expires_in * 1e3 : Date.now() + 36e5,
-            scopes: tokenData.scope ? tokenData.scope.split(" ") : scopes,
-            email
-          };
-          resolve({ tokens, email });
-          return;
-        }
-        switch (tokenData.error) {
-          case "authorization_pending":
-            break;
-          // keep polling
-          case "slow_down":
-            interval += 1;
-            break;
-          case "expired_token":
-            throw new Error("Device code expired \u2014 please try again");
-          case "access_denied":
-            throw new Error("User denied access");
-          default:
-            throw new Error(
-              `Token request failed: ${tokenData.error ?? "unknown error"}`
-            );
-        }
-      }
-      if (!aborted) {
-        throw new Error("Device code expired \u2014 please try again");
-      }
-    } catch (err) {
-      if (!aborted) reject(err);
-    }
-  })();
+  const localCallback = options.redirectUri ? void 0 : await startLocalCallbackServer();
+  const redirectUri = options.redirectUri ?? localCallback?.redirectUri;
+  if (!redirectUri) {
+    throw new Error("Failed to resolve Gmail OAuth redirect URI");
+  }
+  const state = randomBase64Url(24);
+  const codeVerifier = randomBase64Url(64);
+  const expiresAt = new Date(Date.now() + DEFAULT_FLOW_TTL_MS).toISOString();
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: scopes.join(" "),
+    access_type: "offline",
+    prompt: "consent",
+    state,
+    code_challenge: codeChallenge(codeVerifier),
+    code_challenge_method: "S256"
+  });
+  const verificationUri = `${GOOGLE_AUTH_URL}?${params.toString()}`;
   return {
-    get userCode() {
-      return userCode;
-    },
-    get verificationUri() {
-      return verificationUri;
-    },
-    get message() {
-      return message;
-    },
-    get expiresAt() {
-      return expiresAt;
-    },
-    result,
+    userCode: "",
+    verificationUri,
+    message: "Open this URL in a browser to authorize Gmail access. After approval, the account setup should complete automatically when the agent polls. If the browser cannot reach the callback, paste the final redirected URL back to the agent.",
+    expiresAt,
+    state,
+    codeVerifier,
+    redirectUri,
+    scopes,
+    clientId,
+    clientSecret: options.clientSecret || void 0,
     cancel() {
-      aborted = true;
+      localCallback?.cancel();
     },
-    ...{ _ready: ready }
+    consumeAuthorizationResponse() {
+      return localCallback?.consumeAuthorizationResponse();
+    }
   };
 }
-async function awaitDeviceCodeReady2(b) {
-  const r = b._ready;
-  await r;
+function parseAuthorizationCompletion(flow, input) {
+  if (input.authorizationResponse) {
+    let url;
+    try {
+      url = new URL(input.authorizationResponse);
+    } catch {
+      throw new Error("authorizationResponse must be a full redirected URL");
+    }
+    const error = url.searchParams.get("error");
+    if (error) {
+      const description = url.searchParams.get("error_description");
+      throw new Error(
+        `Google OAuth failed: ${description || error}`
+      );
+    }
+    const code = url.searchParams.get("code");
+    if (!code) {
+      throw new Error("authorizationResponse is missing the OAuth code");
+    }
+    return { code, state: url.searchParams.get("state") ?? void 0 };
+  }
+  if (input.code) {
+    return { code: input.code, state: input.state };
+  }
+  throw new Error(
+    "Paste the final redirected URL from Google as authorizationResponse, or provide code and state"
+  );
+}
+async function completeAuthorizationCode(flow, input) {
+  const { code, state } = parseAuthorizationCompletion(flow, input);
+  if (state !== void 0 && state !== flow.state) {
+    throw new Error("OAuth state mismatch \u2014 restart Gmail account setup");
+  }
+  const tokenParams = new URLSearchParams();
+  tokenParams.set("client_id", flow.clientId);
+  if (flow.clientSecret) tokenParams.set("client_secret", flow.clientSecret);
+  tokenParams.set("code", code);
+  tokenParams.set("redirect_uri", flow.redirectUri);
+  tokenParams.set("grant_type", "authorization_code");
+  tokenParams.set("code_verifier", flow.codeVerifier);
+  const tokenRes = await fetch(GOOGLE_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: tokenParams
+  });
+  const tokenData = await tokenRes.json().catch(() => ({}));
+  if (!tokenRes.ok || !tokenData.access_token) {
+    throw new Error(
+      "Token request failed: " + (tokenData.error_description ?? tokenData.error ?? tokenRes.statusText)
+    );
+  }
+  const email = await getEmailFromToken(tokenData.access_token);
+  const tokens = {
+    clientId: flow.clientId,
+    clientSecret: flow.clientSecret,
+    accessToken: tokenData.access_token,
+    refreshToken: tokenData.refresh_token ?? "",
+    expiryDate: tokenData.expires_in ? Date.now() + tokenData.expires_in * 1e3 : Date.now() + 36e5,
+    scopes: tokenData.scope ? tokenData.scope.split(" ") : flow.scopes,
+    email
+  };
+  return { tokens, email };
 }
 // src/providers/gmail/client.ts
@@ -16400,6 +16461,7 @@ var GmailProvider = class {
     this.opts = opts;
     this.clientId = opts.clientId;
     this.clientSecret = opts.clientSecret;
+    this.redirectUri = opts.redirectUri;
     this.clients = new GmailClientFactory(
       opts.store,
       opts.clientId,
@@ -16412,14 +16474,14 @@ var GmailProvider = class {
   pending = /* @__PURE__ */ new Map();
   clientId;
   clientSecret;
+  redirectUri;
   // ── account lifecycle ──
   async addAccount(input) {
-    const begin = beginDeviceCode2(
-      void 0,
-      this.clientId,
-      this.clientSecret
-    );
-    await awaitDeviceCodeReady2(begin);
+    const begin = await beginAuthorizationCode({
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      redirectUri: this.redirectUri
+    });
     const handle = randomUUID5();
     const flow = {
       begin,
@@ -16428,31 +16490,11 @@ var GmailProvider = class {
       settled: "pending"
     };
     this.pending.set(handle, flow);
-    begin.result.then(async ({ tokens, email }) => {
-      const resolvedEmail = (email || input.email || "").toLowerCase();
-      if (!resolvedEmail) {
-        flow.settled = "error";
-        flow.error = "no email returned from Google account";
-        return;
-      }
-      const rec = {
-        email: resolvedEmail,
-        provider: "gmail",
-        displayName: resolvedEmail,
-        tokens,
-        addedAt: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      const saved = await this.opts.store.upsertAccount(rec);
-      flow.account = saved;
-      flow.settled = "ready";
-    }).catch((err) => {
-      flow.settled = "error";
-      flow.error = err instanceof Error ? err.message : String(err);
-    });
     return {
       status: "pending",
       handle,
       verification: {
+        type: "oauth_url",
         userCode: begin.userCode,
         verificationUri: begin.verificationUri,
         expiresAt: begin.expiresAt,
@@ -16460,7 +16502,7 @@ var GmailProvider = class {
       }
     };
   }
-  async completeAddAccount(handle) {
+  async completeAddAccount(handle, input = {}) {
     const flow = this.pending.get(handle);
     if (!flow) return { status: "error", error: "unknown handle" };
     if (Date.now() - flow.startedAt > 20 * 6e4 && flow.settled === "pending") {
@@ -16469,17 +16511,67 @@ var GmailProvider = class {
     }
     if (flow.settled === "ready" && flow.account) {
       this.pending.delete(handle);
+      flow.begin.cancel();
       return { status: "ready", account: flow.account };
     }
     if (flow.settled === "error") {
       this.pending.delete(handle);
+      flow.begin.cancel();
       return { status: "error", error: flow.error ?? "unknown error" };
     }
     if (flow.settled === "expired") {
       this.pending.delete(handle);
+      flow.begin.cancel();
       return { status: "expired" };
     }
-    return { status: "pending" };
+    let completionInput = input;
+    if (!completionInput.authorizationResponse && !completionInput.code) {
+      const captured = flow.begin.consumeAuthorizationResponse();
+      if (!captured) return { status: "pending" };
+      completionInput = captured;
+    }
+    try {
+      const { tokens, email } = await completeAuthorizationCode(flow.begin, completionInput);
+      const resolvedEmail = (email || flow.emailHint || "").toLowerCase();
+      if (!resolvedEmail) {
+        throw new Error("no email returned from Google account");
+      }
+      const rec = {
+        email: resolvedEmail,
+        provider: "gmail",
+        displayName: resolvedEmail,
+        tokens,
+        addedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const saved = await this.opts.store.upsertAccount(rec);
+      this.pending.delete(handle);
+      flow.begin.cancel();
+      return { status: "ready", account: saved };
+    } catch (err) {
+      this.pending.delete(handle);
+      flow.begin.cancel();
+      return {
+        status: "error",
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  async completeAddAccountFromRedirect(authorizationResponse) {
+    let state;
+    try {
+      state = new URL(authorizationResponse).searchParams.get("state");
+    } catch {
+      return { status: "error", error: "authorizationResponse must be a full redirected URL" };
+    }
+    if (!state) {
+      return { status: "error", error: "authorizationResponse is missing OAuth state" };
+    }
+    for (const [handle, flow] of this.pending) {
+      if (flow.begin.state === state) {
+        return this.completeAddAccount(handle, { authorizationResponse });
+      }
+    }
+    return { status: "error", error: "unknown OAuth state \u2014 restart Gmail account setup" };
   }
   // ── browse ──
   async listEmails(account, opts) {
@@ -16556,7 +16648,8 @@ function buildRegistry(opts) {
   providers.set("gmail", new GmailProvider({
     store: opts.store,
     clientId: gmailCfg?.clientId,
-    clientSecret: gmailCfg?.clientSecret
+    clientSecret: gmailCfg?.clientSecret,
+    redirectUri: gmailCfg?.redirectUri
   }));
   function get(id) {
     const p = providers.get(id);
@@ -16605,8 +16698,11 @@ function fail(message) {
   };
 }
 function errMsg(err) {
-  if (err instanceof Error) return err.message;
-  return String(err);
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.includes("HYPERMAIL_GMAIL_CLIENT_ID")) {
+    return "Missing Gmail OAuth configuration: set HYPERMAIL_GMAIL_CLIENT_ID before adding a Gmail account.";
+  }
+  return message;
 }
 var providerIdEnum = z2.enum(["outlook", "imap", "gmail"]);
 var emailAddrSchema = z2.object({
@@ -16754,6 +16850,7 @@ function registerAccountTools(server, ctx) {
     status: z3.enum(["pending", "ready"]),
     handle: z3.string().optional(),
     verification: z3.object({
+      type: z3.enum(["device_code", "oauth_url"]).optional(),
       userCode: z3.string(),
       verificationUri: z3.string(),
       expiresAt: z3.string(),
@@ -16803,7 +16900,16 @@ function registerAccountTools(server, ctx) {
         description: "Poll/finalize a pending add_account flow. Returns `pending` until the user completes the device-code step, then `ready` with the persisted account.",
         inputSchema: z3.object({
           provider: providerIdEnum,
-          handle: z3.string().min(1)
+          handle: z3.string().min(1),
+          authorizationResponse: z3.string().optional().describe(
+            "For OAuth providers such as Gmail: paste the full final redirected URL from the browser after consent."
+          ),
+          code: z3.string().optional().describe(
+            "For OAuth providers such as Gmail: raw authorization code if the client extracted it from the redirect URL."
+          ),
+          state: z3.string().optional().describe(
+            "For OAuth providers such as Gmail: OAuth state returned with a raw authorization code."
+          )
         }),
         outputSchema: completeAddAccountOutputSchema
       },
@@ -16815,7 +16921,11 @@ function registerAccountTools(server, ctx) {
           );
         }
         try {
-          const res = await provider.completeAddAccount(args.handle);
+          const res = await provider.completeAddAccount(args.handle, {
+            authorizationResponse: args.authorizationResponse,
+            code: args.code,
+            state: args.state
+          });
           return ok(res, res);
         } catch (err) {
           return fail(errMsg(err));
@@ -17731,7 +17841,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.6",
+  version: "0.7.7",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -17746,7 +17856,7 @@ var package_default = {
   scripts: {
     build: "tsup",
     dev: "tsup --watch",
-    "dev:http": "tsup && node dist/cli.js --http --config hypermail-config.http.json",
+    "dev:http": "tsup && node dist/cli.js --http",
     start: "node dist/cli.js",
     typecheck: "tsc --noEmit",
     check: "pnpm test && pnpm typecheck && pnpm build",
@@ -17842,11 +17952,11 @@ function sleep(ms) {
 // src/watcher/script.ts
 import { spawn } from "child_process";
-async function runScript(email, config) {
-  if (!config.script) return false;
-  const { path: scriptPath, timeoutMs, retry } = config.script;
-  const maxAttempts = retry?.maxAttempts ?? 5;
-  const baseDelayMs = retry?.baseDelayMs ?? 1e3;
+async function runNotifyCommand(email, config) {
+  if (!config.notifyCommand) return false;
+  const { command, timeoutMs, retry } = config.notifyCommand;
+  const maxAttempts = retry.maxAttempts;
+  const baseDelayMs = retry.baseDelayMs;
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     if (attempt > 0) {
       const delay = baseDelayMs * 2 ** (attempt - 1);
@@ -17854,28 +17964,29 @@ async function runScript(email, config) {
     }
     try {
       const ok2 = await spawnWithTimeout(
-        scriptPath,
+        command,
         JSON.stringify(email),
         timeoutMs
       );
       if (ok2) return true;
       console.error(
-        `[hypermail-watch] script ${email.id} attempt ${attempt + 1}/${maxAttempts}: non-zero exit code`
+        `[hypermail-watch] notify command ${email.id} attempt ${attempt + 1}/${maxAttempts}: non-zero exit code`
       );
     } catch (err) {
       console.error(
-        `[hypermail-watch] script ${email.id} attempt ${attempt + 1}/${maxAttempts}: ${String(err)}`
+        `[hypermail-watch] notify command ${email.id} attempt ${attempt + 1}/${maxAttempts}: ${String(err)}`
       );
     }
   }
   console.error(
-    `[hypermail-watch] script delivery failed after ${maxAttempts} retries for ${email.id}`
+    `[hypermail-watch] notify command delivery failed after ${maxAttempts} retries for ${email.id}`
   );
   return false;
 }
-function spawnWithTimeout(scriptPath, stdinData, timeoutMs) {
+function spawnWithTimeout(command, stdinData, timeoutMs) {
   return new Promise((resolve) => {
-    const child = spawn("node", [scriptPath], {
+    const child = spawn(command, {
+      shell: true,
       stdio: ["pipe", "pipe", "pipe"]
     });
     let stderr = "";
@@ -17885,7 +17996,7 @@ function spawnWithTimeout(scriptPath, stdinData, timeoutMs) {
     const timer = setTimeout(() => {
       child.kill("SIGTERM");
       if (stderr) {
-        console.error(`[hypermail-watch] script timed out after ${timeoutMs}ms. stderr:
+        console.error(`[hypermail-watch] notify command timed out after ${timeoutMs}ms. stderr:
 ${stderr}`);
       }
       resolve(false);
@@ -17893,14 +18004,14 @@ ${stderr}`);
     child.on("close", (code) => {
       clearTimeout(timer);
       if (stderr && code !== 0) {
-        console.error(`[hypermail-watch] script stderr:
+        console.error(`[hypermail-watch] notify command stderr:
 ${stderr}`);
       }
       resolve(code === 0);
     });
     child.on("error", (err) => {
       clearTimeout(timer);
-      console.error(`[hypermail-watch] script spawn error: ${err.message}`);
+      console.error(`[hypermail-watch] notify command spawn error: ${err.message}`);
       resolve(false);
     });
     child.stdin?.end(stdinData);
@@ -17980,69 +18091,86 @@ var WatcherManager = class {
   }
   async emit(full) {
     await postWebhook(full, this.config);
-    runScript(full, this.config).catch((err) => {
+    runNotifyCommand(full, this.config).catch((err) => {
       console.error(
-        `[hypermail-watch] script unhandled error for ${full.id}:`,
+        `[hypermail-watch] notify command unhandled error for ${full.id}:`,
         err
       );
     });
   }
 };
-// src/config.ts
-import { z as z8 } from "zod";
 // src/config/load.ts
-import { readFileSync as readFileSync2 } from "fs";
-var ENV_HTTP_ENABLED = "HYPERMAIL_HTTP_ENABLED";
+var ENV_DATA_DIR = "HYPERMAIL_DATA_DIR";
+var ENV_KEY = "HYPERMAIL_KEY";
+var ENV_TRANSPORT = "HYPERMAIL_TRANSPORT";
 var ENV_HTTP_PORT = "HYPERMAIL_HTTP_PORT";
 var ENV_HTTP_HOST = "HYPERMAIL_HTTP_HOST";
 var ENV_TOOLS_DISABLED = "HYPERMAIL_TOOLS_DISABLED";
 var ENV_TOOLS_ENABLED = "HYPERMAIL_TOOLS_ENABLED";
-var ENV_OUTLOOK_CLIENT_ID = "HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID";
-var ENV_OUTLOOK_TENANT_ID = "HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID";
-var ENV_GMAIL_CLIENT_ID = "HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID";
-var ENV_GMAIL_CLIENT_SECRET = "HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET";
+var ENV_OUTLOOK_CLIENT_ID = "HYPERMAIL_OUTLOOK_CLIENT_ID";
+var ENV_OUTLOOK_TENANT_ID = "HYPERMAIL_OUTLOOK_TENANT_ID";
+var ENV_GMAIL_CLIENT_ID = "HYPERMAIL_GMAIL_CLIENT_ID";
+var ENV_GMAIL_CLIENT_SECRET = "HYPERMAIL_GMAIL_CLIENT_SECRET";
+var ENV_GMAIL_REDIRECT_URI = "HYPERMAIL_GMAIL_REDIRECT_URI";
 var ENV_WATCH_ENABLED = "HYPERMAIL_WATCH_ENABLED";
-var ENV_WATCH_POLL_INTERVAL = "HYPERMAIL_WATCH_POLL_INTERVAL";
+var ENV_WATCH_POLL_SECONDS = "HYPERMAIL_WATCH_POLL_SECONDS";
 var ENV_WATCH_WEBHOOK_URL = "HYPERMAIL_WATCH_WEBHOOK_URL";
-var ENV_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS = "HYPERMAIL_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS";
-var ENV_WATCH_WEBHOOK_RETRY_BASE_DELAY = "HYPERMAIL_WATCH_WEBHOOK_RETRY_BASE_DELAY_MS";
-var ENV_WATCH_SCRIPT_PATH = "HYPERMAIL_WATCH_SCRIPT_PATH";
-var ENV_WATCH_SCRIPT_TIMEOUT_MS = "HYPERMAIL_WATCH_SCRIPT_TIMEOUT_MS";
-var ENV_WATCH_SCRIPT_RETRY_MAX_ATTEMPTS = "HYPERMAIL_WATCH_SCRIPT_RETRY_MAX_ATTEMPTS";
-var ENV_WATCH_SCRIPT_RETRY_BASE_DELAY = "HYPERMAIL_WATCH_SCRIPT_RETRY_BASE_DELAY_MS";
-var ENV_VAR_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
-function resolveEnvVars(value) {
-  return value.replace(ENV_VAR_RE, (_match, name) => {
-    return process.env[name] ?? "";
-  });
+var ENV_WATCH_WEBHOOK_RETRY_ATTEMPTS = "HYPERMAIL_WATCH_WEBHOOK_RETRY_ATTEMPTS";
+var ENV_WATCH_WEBHOOK_RETRY_DELAY_MS = "HYPERMAIL_WATCH_WEBHOOK_RETRY_DELAY_MS";
+var ENV_WATCH_NOTIFY_COMMAND = "HYPERMAIL_WATCH_NOTIFY_COMMAND";
+var ENV_WATCH_NOTIFY_TIMEOUT_MS = "HYPERMAIL_WATCH_NOTIFY_TIMEOUT_MS";
+var ENV_WATCH_NOTIFY_RETRY_ATTEMPTS = "HYPERMAIL_WATCH_NOTIFY_RETRY_ATTEMPTS";
+var ENV_WATCH_NOTIFY_RETRY_DELAY_MS = "HYPERMAIL_WATCH_NOTIFY_RETRY_DELAY_MS";
+var DEFAULT_TRANSPORT = "stdio";
+var DEFAULT_HTTP_PORT = 3e3;
+var DEFAULT_HTTP_HOST = "127.0.0.1";
+var DEFAULT_WATCH_POLL_SECONDS = 10;
+var DEFAULT_RETRY_ATTEMPTS = 5;
+var DEFAULT_RETRY_DELAY_MS = 1e3;
+var DEFAULT_NOTIFY_TIMEOUT_MS = 3e4;
+function envRaw(name) {
+  return process.env[name];
 }
-function deepResolve(obj) {
-  if (typeof obj === "string") return resolveEnvVars(obj);
-  if (Array.isArray(obj)) return obj.map(deepResolve);
-  if (obj && typeof obj === "object") {
-    const out = {};
-    for (const [key, val] of Object.entries(obj)) {
-      out[key] = deepResolve(val);
-    }
-    return out;
-  }
-  return obj;
+function optionalEnvString(name) {
+  const value = envRaw(name);
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
-function parseBool(value) {
+function parseBoolEnv(name) {
+  const value = envRaw(name);
   if (value === void 0) return void 0;
   const lower = value.trim().toLowerCase();
-  if (lower === "true" || lower === "1" || lower === "yes") return true;
-  if (lower === "false" || lower === "0" || lower === "no" || lower === "") return false;
-  return void 0;
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  throw new Error(`${name} must be either "true" or "false"`);
 }
-function parseIntSafe(value) {
+function parseTransportEnv() {
+  const value = envRaw(ENV_TRANSPORT);
   if (value === void 0) return void 0;
+  const lower = value.trim().toLowerCase();
+  if (lower === "stdio" || lower === "http") return lower;
+  throw new Error(`${ENV_TRANSPORT} must be either "stdio" or "http"`);
+}
+function parsePositiveInteger(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "number") {
+    return Number.isInteger(value) && value > 0 ? value : void 0;
+  }
   const trimmed = value.trim();
-  if (trimmed === "") return void 0;
-  const n = Number.parseInt(trimmed, 10);
-  return Number.isNaN(n) ? void 0 : n;
+  if (!/^[0-9]+$/.test(trimmed)) return void 0;
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+function parsePositiveIntegerEnv(name, defaultValue) {
+  const value = envRaw(name);
+  if (value === void 0) return defaultValue;
+  const parsed = parsePositiveInteger(value);
+  if (parsed === void 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return parsed;
 }
 function parseStringArray(value) {
   if (value === void 0) return void 0;
@@ -18050,159 +18178,173 @@ function parseStringArray(value) {
   if (trimmed === "") return [];
   return trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 }
-function validateToolNames(toolNames, listName) {
+function validateToolNames(toolNames, envName) {
   if (!toolNames || toolNames.length === 0) return;
   const known = new Set(KNOWN_TOOLS);
   for (const name of toolNames) {
     if (!known.has(name)) {
       throw new Error(
-        `Unknown tool "${name}" in ${listName}. Known tools: ${KNOWN_TOOLS.join(", ")}`
+        `Unknown tool "${name}" in ${envName}. Known tools: ${KNOWN_TOOLS.join(", ")}`
       );
     }
   }
 }
-function loadConfig(configPath, cliOverrides = {}) {
-  let raw = {};
-  if (configPath) {
-    try {
-      raw = JSON.parse(readFileSync2(configPath, "utf-8"));
-    } catch (err) {
-      const detail = err instanceof SyntaxError ? "Invalid JSON" : err instanceof Error ? err.message : String(err);
-      throw new Error(`Failed to read config file "${configPath}": ${detail}`);
+function validateWebhookUrl(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error("unsupported protocol");
     }
+    return raw;
+  } catch {
+    throw new Error(`${ENV_WATCH_WEBHOOK_URL} must be a valid http(s) URL`);
   }
-  raw = deepResolve(raw);
-  const parsed = rawConfigSchema.parse(raw);
-  const http = {
-    enabled: cliOverrides.http ?? parsed.http?.enabled ?? parseBool(process.env[ENV_HTTP_ENABLED]) ?? false,
-    port: cliOverrides.port ?? parsed.http?.port ?? parseIntSafe(process.env[ENV_HTTP_PORT]) ?? 3e3,
-    host: cliOverrides.host ?? parsed.http?.host ?? process.env[ENV_HTTP_HOST] ?? "127.0.0.1"
-  };
-  const toolsDisabled = parsed.tools?.disabled ?? parseStringArray(process.env[ENV_TOOLS_DISABLED]);
-  const toolsEnabled = parsed.tools?.enabled ?? parseStringArray(process.env[ENV_TOOLS_ENABLED]);
-  if (toolsDisabled && toolsEnabled) {
-    throw new Error(
-      "tools.disabled and tools.enabled are mutually exclusive \u2014 use one or the other"
+}
+function resolveHttpConfig(transport, cliOverrides, warnings) {
+  const portSource = cliOverrides.port !== void 0 ? "--port" : ENV_HTTP_PORT;
+  const rawPort = cliOverrides.port ?? envRaw(ENV_HTTP_PORT);
+  const parsedPort = parsePositiveInteger(rawPort);
+  let port = DEFAULT_HTTP_PORT;
+  if (parsedPort !== void 0 && parsedPort <= 65535) {
+    port = parsedPort;
+  } else if (rawPort !== void 0 && transport === "http") {
+    warnings.push(
+      `Invalid ${portSource}; using default HTTP port ${DEFAULT_HTTP_PORT}.`
     );
   }
-  if (toolsEnabled !== void 0 && toolsEnabled.length === 0) {
+  const hostSource = cliOverrides.host !== void 0 ? "--host" : ENV_HTTP_HOST;
+  const rawHost = cliOverrides.host ?? envRaw(ENV_HTTP_HOST);
+  let host = DEFAULT_HTTP_HOST;
+  if (rawHost !== void 0 && rawHost.trim().length > 0) {
+    host = rawHost.trim();
+  } else if (rawHost !== void 0 && transport === "http") {
+    warnings.push(
+      `Invalid ${hostSource}; using default HTTP host ${DEFAULT_HTTP_HOST}.`
+    );
+  }
+  return { port, host };
+}
+function resolveToolsConfig() {
+  const disabled = parseStringArray(envRaw(ENV_TOOLS_DISABLED));
+  const enabled = parseStringArray(envRaw(ENV_TOOLS_ENABLED));
+  const disabledIsNonEmpty = disabled !== void 0 && disabled.length > 0;
+  const enabledIsNonEmpty = enabled !== void 0 && enabled.length > 0;
+  if (disabledIsNonEmpty && enabledIsNonEmpty) {
     throw new Error(
-      "tools.enabled is empty \u2014 at least one tool must be listed. To enable all tools, omit the tools section entirely."
+      `${ENV_TOOLS_DISABLED} and ${ENV_TOOLS_ENABLED} are mutually exclusive \u2014 use one or the other`
     );
   }
-  validateToolNames(toolsDisabled, "tools.disabled");
-  validateToolNames(toolsEnabled, "tools.enabled");
-  const tools = toolsDisabled || toolsEnabled ? { disabled: toolsDisabled, enabled: toolsEnabled } : void 0;
-  const outlookClientId = parsed.providers?.outlook?.clientId ?? process.env[ENV_OUTLOOK_CLIENT_ID];
-  const outlookTenantId = parsed.providers?.outlook?.tenantId ?? process.env[ENV_OUTLOOK_TENANT_ID];
-  const gmailClientId = parsed.providers?.gmail?.clientId ?? process.env[ENV_GMAIL_CLIENT_ID];
-  const gmailClientSecret = parsed.providers?.gmail?.clientSecret ?? process.env[ENV_GMAIL_CLIENT_SECRET];
+  validateToolNames(disabled, ENV_TOOLS_DISABLED);
+  validateToolNames(enabled, ENV_TOOLS_ENABLED);
+  if (enabledIsNonEmpty) return { enabled };
+  if (disabledIsNonEmpty) return { disabled };
+  return void 0;
+}
+function resolveProvidersConfig() {
+  const outlookClientId = optionalEnvString(ENV_OUTLOOK_CLIENT_ID);
+  const outlookTenantId = optionalEnvString(ENV_OUTLOOK_TENANT_ID);
+  const gmailClientId = optionalEnvString(ENV_GMAIL_CLIENT_ID);
+  const gmailClientSecret = optionalEnvString(ENV_GMAIL_CLIENT_SECRET);
+  const gmailRedirectUri = optionalEnvString(ENV_GMAIL_REDIRECT_URI);
   let providers;
-  if (outlookClientId || outlookTenantId || gmailClientId || gmailClientSecret) {
+  if (outlookClientId || outlookTenantId || gmailClientId || gmailClientSecret || gmailRedirectUri) {
     providers = {};
     if (outlookClientId || outlookTenantId) {
       providers.outlook = {};
       if (outlookClientId) providers.outlook.clientId = outlookClientId;
       if (outlookTenantId) providers.outlook.tenantId = outlookTenantId;
     }
-    if (gmailClientId || gmailClientSecret) {
+    if (gmailClientId || gmailClientSecret || gmailRedirectUri) {
       providers.gmail = {};
       if (gmailClientId) providers.gmail.clientId = gmailClientId;
       if (gmailClientSecret) providers.gmail.clientSecret = gmailClientSecret;
+      if (gmailRedirectUri) providers.gmail.redirectUri = gmailRedirectUri;
     }
   }
-  const watchEnabledEnv = parseBool(process.env[ENV_WATCH_ENABLED]);
-  let watch;
-  if (parsed.watch || watchEnabledEnv !== void 0) {
-    const webhookUrl = parsed.watch?.webhook?.url ?? process.env[ENV_WATCH_WEBHOOK_URL];
-    let webhook;
-    if (webhookUrl) {
-      const retryMaxAttempts = parsed.watch?.webhook?.retry?.maxAttempts ?? parseIntSafe(process.env[ENV_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS]) ?? 5;
-      const retryBaseDelayMs = parsed.watch?.webhook?.retry?.baseDelayMs ?? parseIntSafe(process.env[ENV_WATCH_WEBHOOK_RETRY_BASE_DELAY]) ?? 1e3;
-      webhook = {
-        url: webhookUrl,
-        retry: { maxAttempts: retryMaxAttempts, baseDelayMs: retryBaseDelayMs }
-      };
-    }
-    const scriptPath = parsed.watch?.script?.path ?? process.env[ENV_WATCH_SCRIPT_PATH];
-    let script;
-    if (scriptPath) {
-      const scriptTimeoutMs = parsed.watch?.script?.timeoutMs ?? parseIntSafe(process.env[ENV_WATCH_SCRIPT_TIMEOUT_MS]) ?? 3e4;
-      const scriptRetryMaxAttempts = parsed.watch?.script?.retry?.maxAttempts ?? parseIntSafe(process.env[ENV_WATCH_SCRIPT_RETRY_MAX_ATTEMPTS]) ?? 5;
-      const scriptRetryBaseDelayMs = parsed.watch?.script?.retry?.baseDelayMs ?? parseIntSafe(process.env[ENV_WATCH_SCRIPT_RETRY_BASE_DELAY]) ?? 1e3;
-      script = {
-        path: scriptPath,
-        timeoutMs: scriptTimeoutMs,
-        retry: {
-          maxAttempts: scriptRetryMaxAttempts,
-          baseDelayMs: scriptRetryBaseDelayMs
-        }
-      };
-    }
-    watch = {
-      enabled: watchEnabledEnv ?? parsed.watch?.enabled ?? false,
-      pollIntervalSeconds: parsed.watch?.pollIntervalSeconds ?? parseIntSafe(process.env[ENV_WATCH_POLL_INTERVAL]) ?? 10,
-      webhook,
-      script
+  return providers;
+}
+function resolveRetryConfig(attemptsEnv, delayEnv) {
+  return {
+    maxAttempts: parsePositiveIntegerEnv(attemptsEnv, DEFAULT_RETRY_ATTEMPTS),
+    baseDelayMs: parsePositiveIntegerEnv(delayEnv, DEFAULT_RETRY_DELAY_MS)
+  };
+}
+function resolveWatchConfig() {
+  const enabled = parseBoolEnv(ENV_WATCH_ENABLED) ?? false;
+  if (!enabled) return void 0;
+  const pollIntervalSeconds = parsePositiveIntegerEnv(
+    ENV_WATCH_POLL_SECONDS,
+    DEFAULT_WATCH_POLL_SECONDS
+  );
+  const webhookUrl = optionalEnvString(ENV_WATCH_WEBHOOK_URL);
+  let webhook;
+  if (webhookUrl) {
+    webhook = {
+      url: validateWebhookUrl(webhookUrl),
+      retry: resolveRetryConfig(
+        ENV_WATCH_WEBHOOK_RETRY_ATTEMPTS,
+        ENV_WATCH_WEBHOOK_RETRY_DELAY_MS
+      )
     };
   }
+  const rawNotifyCommand = envRaw(ENV_WATCH_NOTIFY_COMMAND);
+  let notifyCommand;
+  if (rawNotifyCommand !== void 0) {
+    const command = rawNotifyCommand.trim();
+    if (!command) {
+      throw new Error(`${ENV_WATCH_NOTIFY_COMMAND} must not be empty when watch is enabled`);
+    }
+    notifyCommand = {
+      command,
+      timeoutMs: parsePositiveIntegerEnv(
+        ENV_WATCH_NOTIFY_TIMEOUT_MS,
+        DEFAULT_NOTIFY_TIMEOUT_MS
+      ),
+      retry: resolveRetryConfig(
+        ENV_WATCH_NOTIFY_RETRY_ATTEMPTS,
+        ENV_WATCH_NOTIFY_RETRY_DELAY_MS
+      )
+    };
+  }
+  if (!webhook && !notifyCommand) {
+    throw new Error(
+      `${ENV_WATCH_ENABLED}=true requires ${ENV_WATCH_WEBHOOK_URL} or ${ENV_WATCH_NOTIFY_COMMAND}`
+    );
+  }
+  return {
+    enabled: true,
+    pollIntervalSeconds,
+    webhook,
+    notifyCommand
+  };
+}
+function loadConfig(cliOverrides = {}) {
+  const warnings = [];
+  const transport = cliOverrides.transport ?? parseTransportEnv() ?? DEFAULT_TRANSPORT;
+  const http = resolveHttpConfig(transport, cliOverrides, warnings);
+  const tools = resolveToolsConfig();
+  const providers = resolveProvidersConfig();
+  const watch = resolveWatchConfig();
+  const dataDir = cliOverrides.dataDir ?? optionalEnvString(ENV_DATA_DIR);
+  if (!optionalEnvString(ENV_KEY)) {
+    warnings.push(
+      `${ENV_KEY} is not set; a local generated key will be used. Set ${ENV_KEY} explicitly for portable hosted deployments.`
+    );
+  }
   return {
-    dataDir: cliOverrides.dataDir ?? parsed.dataDir ?? process.env.HYPERMAIL_MCP_DATA_DIR,
-    http,
-    tools,
-    providers,
-    watch
+    config: {
+      dataDir,
+      transport,
+      http,
+      tools,
+      providers,
+      watch
+    },
+    warnings
   };
 }
 // src/config.ts
-var httpConfigSchema = z8.object({
-  enabled: z8.boolean().default(false),
-  port: z8.number().int().min(1).max(65535).default(3e3),
-  host: z8.string().default("127.0.0.1")
-});
-var toolsConfigSchema = z8.object({
-  disabled: z8.array(z8.string()).optional(),
-  enabled: z8.array(z8.string()).optional()
-});
-var outlookProviderSchema = z8.object({
-  clientId: z8.string().optional(),
-  tenantId: z8.string().optional()
-});
-var gmailProviderSchema = z8.object({
-  clientId: z8.string().optional(),
-  clientSecret: z8.string().optional()
-});
-var providersConfigSchema = z8.object({
-  outlook: outlookProviderSchema.optional(),
-  gmail: gmailProviderSchema.optional()
-});
-var watchRetrySchema = z8.object({
-  maxAttempts: z8.number().int().min(1).max(10).default(5),
-  baseDelayMs: z8.number().int().min(100).default(1e3)
-});
-var watchWebhookSchema = z8.object({
-  url: z8.string(),
-  retry: watchRetrySchema.optional()
-});
-var watchScriptSchema = z8.object({
-  path: z8.string(),
-  timeoutMs: z8.number().int().min(1e3).default(3e4),
-  retry: watchRetrySchema.optional()
-});
-var watchConfigSchema = z8.object({
-  enabled: z8.boolean().default(false),
-  pollIntervalSeconds: z8.number().int().min(10).max(3600).default(10),
-  webhook: watchWebhookSchema.optional(),
-  script: watchScriptSchema.optional()
-});
-var rawConfigSchema = z8.object({
-  dataDir: z8.string().optional(),
-  http: httpConfigSchema.optional(),
-  tools: toolsConfigSchema.optional(),
-  providers: providersConfigSchema.optional(),
-  watch: watchConfigSchema.optional()
-});
 var KNOWN_TOOLS = [
   "list_accounts",
   "add_account",
@@ -18226,8 +18368,7 @@ var KNOWN_TOOLS = [
   "send_email",
   "draft_email",
   "edit_draft",
-  "send_draft",
-  "check_notifications"
+  "send_draft"
 ];
 function resolveTools(config) {
   if (!config.tools) {
@@ -18261,19 +18402,68 @@ async function startServer(opts) {
     registerTools(s, { store, registry, tools });
     return s;
   };
-  if (config.http.enabled) {
-    await startHttp(createServer, config.http.host, config.http.port);
+  if (config.transport === "http") {
+    await startHttp(createServer, registry, config.http.host, config.http.port);
   } else {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
   }
 }
-async function startHttp(createServer, host, port) {
+function firstHeader(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function requestBaseUrl(req) {
+  const proto = firstHeader(req.headers["x-forwarded-proto"]) ?? "http";
+  const host = firstHeader(req.headers["x-forwarded-host"]) ?? firstHeader(req.headers.host) ?? "127.0.0.1";
+  return `${proto}://${host}`;
+}
+function escapeHtml2(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function sendOAuthHtml(res, status, title, body) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "text/html; charset=utf-8");
+  res.end(`<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>${escapeHtml2(title)}</title></head>
+<body><h1>${escapeHtml2(title)}</h1><p>${escapeHtml2(body)}</p></body>
+</html>`);
+}
+async function handleGmailOAuthCallback(req, res, registry) {
+  const provider = registry.get("gmail");
+  if (!provider.completeAddAccountFromRedirect) {
+    sendOAuthHtml(res, 500, "Gmail authorization failed", "This server cannot complete Gmail OAuth callbacks.");
+    return;
+  }
+  const authorizationResponse = new URL(req.url ?? "", requestBaseUrl(req)).toString();
+  const result = await provider.completeAddAccountFromRedirect(authorizationResponse);
+  if (result.status === "ready") {
+    sendOAuthHtml(res, 200, "Gmail authorization complete", "You can close this tab and return to your MCP client.");
+    return;
+  }
+  sendOAuthHtml(
+    res,
+    400,
+    "Gmail authorization failed",
+    result.status === "error" ? result.error ?? "Unknown Gmail OAuth error." : "The Gmail OAuth flow was not ready. Restart account setup and try again."
+  );
+}
+async function startHttp(createServer, registry, host, port) {
   const sessions = /* @__PURE__ */ new Map();
-  const http = createHttpServer(async (req, res) => {
+  const http = createHttpServer2(async (req, res) => {
     try {
-      if (!req.url || !req.url.startsWith("/mcp")) {
+      if (!req.url) {
+        res.statusCode = 404;
+        res.end("not found");
+        return;
+      }
+      const pathname = new URL(req.url, requestBaseUrl(req)).pathname;
+      if (req.method === "GET" && pathname === DEFAULT_GMAIL_OAUTH_CALLBACK_PATH) {
+        await handleGmailOAuthCallback(req, res, registry);
+        return;
+      }
+      if (!req.url.startsWith("/mcp")) {
         res.statusCode = 404;
         res.end("not found");
         return;
@@ -18314,128 +18504,136 @@ async function startHttp(createServer, host, port) {
   console.error(`[hypermail-mcp] listening on http://${host}:${port}/mcp`);
 }
-// src/cli.ts
+// src/cli-args.ts
+import { randomBytes as randomBytes3 } from "crypto";
+function readValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (value === void 0 || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
 function parseArgs(argv) {
+  if (argv[0] === "generate-key") {
+    if (argv.length > 1) {
+      throw new Error(`Unknown argument for generate-key: ${argv[1]}`);
+    }
+    return { command: "generate-key", help: false, overrides: {} };
+  }
   const out = {
-    http: false,
-    port: 3e3,
-    host: "127.0.0.1",
-    help: false
+    help: false,
+    overrides: {}
   };
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    switch (a) {
+    const arg = argv[i] ?? "";
+    switch (arg) {
       case "--http":
-        out.http = true;
+        out.overrides.transport = "http";
         break;
-      case "--port":
-        out.port = Number(argv[++i] ?? "3000");
-        break;
-      case "--host":
-        out.host = String(argv[++i] ?? "127.0.0.1");
+      case "--port": {
+        const value = readValue(argv, i, "--port");
+        out.overrides.port = Number(value);
+        i++;
         break;
-      case "--data-dir":
-        out.dataDir = String(argv[++i] ?? "");
+      }
+      case "--host": {
+        const value = readValue(argv, i, "--host");
+        out.overrides.host = value;
+        i++;
         break;
-      case "--config":
-        out.config = String(argv[++i] ?? "");
+      }
+      case "--data-dir": {
+        const value = readValue(argv, i, "--data-dir");
+        out.overrides.dataDir = value;
+        i++;
         break;
+      }
       case "-h":
       case "--help":
         out.help = true;
         break;
       default:
-        if (a && a.startsWith("--")) {
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
         }
+        throw new Error(`Unknown argument: ${arg}`);
     }
   }
   return out;
 }
-function printHelp() {
-  const msg = `hypermail-mcp \u2014 unified email MCP server
+function generateKey() {
+  return randomBytes3(32).toString("base64");
+}
+function helpText() {
+  return `hypermail-mcp \u2014 unified email MCP server
 Usage:
   hypermail-mcp [options]
+  hypermail-mcp generate-key
 Options:
   --http              Run as Streamable HTTP server (default: stdio)
   --port <n>          HTTP port (default: 3000)
   --host <addr>       HTTP bind address (default: 127.0.0.1)
   --data-dir <path>   Where to store the encrypted accounts file
-                      (default: $HYPERMAIL_MCP_DATA_DIR or ~/.hypermail-mcp)
-  --config <path>     Path to hypermail-config.json
   -h, --help          Show this help
 Configuration:
-  All settings can be provided via environment variables \u2014 no config file
-  required. Use hypermail-config.json for advanced scenarios.
+  Configure the server with flat HYPERMAIL_* environment variables.
+  CLI flags override environment values for this invocation only.
-  Environment variables:
+Core environment variables:
+  HYPERMAIL_DATA_DIR
+  HYPERMAIL_KEY
+  HYPERMAIL_TRANSPORT=stdio|http
+  HYPERMAIL_HTTP_PORT
+  HYPERMAIL_HTTP_HOST
+  HYPERMAIL_TOOLS_ENABLED
+  HYPERMAIL_TOOLS_DISABLED
-  HYPERMAIL_MCP_DATA_DIR              Data directory (string)
-  HYPERMAIL_HTTP_ENABLED              Enable HTTP mode (bool: true/false/1/0)
-  HYPERMAIL_HTTP_PORT                 HTTP port (number)
-  HYPERMAIL_HTTP_HOST                 HTTP bind address (string)
-  HYPERMAIL_TOOLS_DISABLED            Comma-separated tool names to disable
-  HYPERMAIL_TOOLS_ENABLED             Comma-separated tool names to enable
-  HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID   Outlook OAuth client ID (string)
-  HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID   Outlook tenant ID (string)
-  HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID     Gmail OAuth client ID (string)
-  HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET Gmail OAuth client secret (string)
-  HYPERMAIL_WATCH_ENABLED             Enable inbox polling (bool)
-  HYPERMAIL_WATCH_POLL_INTERVAL       Poll interval in seconds (number)
-  HYPERMAIL_WATCH_WEBHOOK_URL         Webhook URL for new-email events (string)
-  HYPERMAIL_WATCH_WEBHOOK_RETRY_MAX_ATTEMPTS  Retry max attempts (number)
-  HYPERMAIL_WATCH_WEBHOOK_RETRY_BASE_DELAY_MS Retry base delay ms (number)
-  HYPERMAIL_MCP_KEY                   Encryption master key (hex or base64)
+Provider environment variables:
+  HYPERMAIL_OUTLOOK_CLIENT_ID
+  HYPERMAIL_OUTLOOK_TENANT_ID
+  HYPERMAIL_GMAIL_CLIENT_ID
+  HYPERMAIL_GMAIL_CLIENT_SECRET
+  HYPERMAIL_GMAIL_REDIRECT_URI
-  Priority: CLI flags > config file > env vars > defaults.
+Watcher environment variables:
+  HYPERMAIL_WATCH_ENABLED=true|false
+  HYPERMAIL_WATCH_POLL_SECONDS
+  HYPERMAIL_WATCH_WEBHOOK_URL
+  HYPERMAIL_WATCH_WEBHOOK_RETRY_ATTEMPTS
+  HYPERMAIL_WATCH_WEBHOOK_RETRY_DELAY_MS
+  HYPERMAIL_WATCH_NOTIFY_COMMAND
+  HYPERMAIL_WATCH_NOTIFY_TIMEOUT_MS
+  HYPERMAIL_WATCH_NOTIFY_RETRY_ATTEMPTS
+  HYPERMAIL_WATCH_NOTIFY_RETRY_DELAY_MS
-  Example (env-only, no config file):
-    HYPERMAIL_HTTP_ENABLED=true \\
-    HYPERMAIL_HTTP_PORT=8080 \\
-    HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID=abc123 \\
-    HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID=common \\
-    HYPERMAIL_MCP_DATA_DIR=/data/hypermail \\
-    hypermail-mcp --http
-  Example hypermail-config.json:
-    {
-      "dataDir": "/path/to/data",
-      "http": { "enabled": false },
-      "tools": { "disabled": ["send_email"] },
-      "providers": {
-        "outlook": {
-          "clientId": "\${HYPERMAIL_PROVIDERS_OUTLOOK_CLIENT_ID}",
-          "tenantId": "\${HYPERMAIL_PROVIDERS_OUTLOOK_TENANT_ID}"
-        },
-        "gmail": {
-          "clientId": "\${HYPERMAIL_PROVIDERS_GMAIL_CLIENT_ID}",
-          "clientSecret": "\${HYPERMAIL_PROVIDERS_GMAIL_CLIENT_SECRET}"
-        }
-      }
-    }
+Example:
+  HYPERMAIL_TRANSPORT=http \\
+  HYPERMAIL_HTTP_PORT=8080 \\
+  HYPERMAIL_OUTLOOK_CLIENT_ID=... \\
+  HYPERMAIL_DATA_DIR=/data/hypermail \\
+  hypermail-mcp
 `;
-  process.stdout.write(msg);
 }
+// src/cli.ts
 async function main() {
-  const rawArgs = process.argv.slice(2);
-  if (rawArgs[0] === "generate-key") {
-    const key = `hm_sk_${randomBytes2(32).toString("hex")}`;
-    process.stdout.write(key + "\n");
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.command === "generate-key") {
+    process.stdout.write(generateKey() + "\n");
     return;
   }
-  const opts = parseArgs(rawArgs);
   if (opts.help) {
-    printHelp();
+    process.stdout.write(helpText());
     return;
   }
-  const config = loadConfig(opts.config, {
-    http: opts.http,
-    port: opts.port,
-    host: opts.host,
-    dataDir: opts.dataDir
-  });
+  const { config, warnings } = loadConfig(opts.overrides);
+  for (const warning of warnings) {
+    process.stderr.write(`[hypermail-mcp] warning: ${warning}
+`);
+  }
   await startServer({ config });
 }
 main().catch((err) => {