@atomicmail/mcp 0.1.0 → 0.2.0

package/esm/lib/src/agent-session.d.ts

@@ -0,0 +1,62 @@
+import { type SkillFiles } from "./agent-credentials-store.js";
+export interface AgentSessionConfig {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    inboxId?: string;
+    credentialDir: string;
+    files: SkillFiles;
+}
+export interface RegisterResult {
+    inbox: string;
+    accountId: string;
+    /** Present only on first-time signup (not idempotent replay). */
+    apiKey?: string;
+    idempotent?: boolean;
+}
+/** Local-part of an inbox email, or the whole string if no @. */
+export declare function inboxLocalPart(inboxId: string): string;
+export declare class AgentSession {
+    private readonly authUrl;
+    readonly apiUrl: string;
+    private readonly scryptSalt;
+    private apiKey;
+    private inboxId;
+    readonly credentialDir: string;
+    readonly files: SkillFiles;
+    private sessionJWT;
+    private capabilityJWT;
+    private cachedMailAccountId;
+    constructor(cfg: AgentSessionConfig);
+    static create(cfg: AgentSessionConfig): Promise<AgentSession>;
+    get hasApiKey(): boolean;
+    get currentInboxId(): string | undefined;
+    private loadFromDisk;
+    /**
+     * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
+     */
+    getPrimaryMailAccountId(): Promise<string>;
+    invalidateJmapSessionCache(): void;
+    /**
+     * Register or return existing inbox when username matches (idempotent).
+     * Different username replaces on-disk credentials and creates a new inbox.
+     */
+    register(username: string): Promise<RegisterResult>;
+    getCapabilityToken(): Promise<string>;
+    private ensureSession;
+    destroy(): void;
+}
+export interface PersistLoginWithApiKeyInput {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey: string;
+    files: SkillFiles;
+    onPowProgress?: (nonce: bigint) => void;
+}
+/** PoW login with an existing API key; writes credentials + JWT files. */
+export declare function persistLoginWithApiKey(input: PersistLoginWithApiKeyInput): Promise<{
+    inboxId: string;
+}>;
+//# sourceMappingURL=agent-session.d.ts.map

package/esm/lib/src/agent-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session.d.ts","sourceRoot":"","sources":["../../../src/lib/src/agent-session.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,UAAU,EAMhB,MAAM,8BAA8B,CAAC;AAatC,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAMD,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,mBAAmB,CAAqB;gBAEpC,GAAG,EAAE,kBAAkB;WAUtB,MAAM,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMnE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAEvC;YAEa,YAAY;IAU1B;;OAEG;IACG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAShD,0BAA0B,IAAI,IAAI;IAIlC;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuEnD,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;YA4B7B,aAAa;IAyB3B,OAAO,IAAI,IAAI;CAGhB;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,0EAA0E;AAC1E,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB9B"}

package/esm/lib/src/agent-session.js

@@ -0,0 +1,206 @@
+// Stateful PoW + capability JWT + optional cached JMAP session (accountId).
+import { tryReadCredentials, tryReadJwtFile, unlinkCredentialArtifacts, writeCredentials, writeJwtFile, } from "./agent-credentials-store.js";
+import { CAPABILITY_SAFETY_MARGIN_MS, decodeJwtPayload, isJwtExpired, SESSION_SAFETY_MARGIN_MS, } from "./agent-jwt.js";
+import { extractPrimaryMailAccountId, fetchJmapWellKnown, } from "./agent-jmap.js";
+import { fetchCapability, performPoWAndSession } from "./agent-auth-http.js";
+function normalizeUsername(u) {
+    return u.trim().toLowerCase();
+}
+/** Local-part of an inbox email, or the whole string if no @. */
+export function inboxLocalPart(inboxId) {
+    const i = inboxId.indexOf("@");
+    return i === -1
+        ? normalizeUsername(inboxId)
+        : normalizeUsername(inboxId.slice(0, i));
+}
+export class AgentSession {
+    authUrl;
+    apiUrl;
+    scryptSalt;
+    apiKey;
+    inboxId;
+    credentialDir;
+    files;
+    sessionJWT;
+    capabilityJWT;
+    cachedMailAccountId;
+    constructor(cfg) {
+        this.authUrl = cfg.authUrl.replace(/\/+$/, "");
+        this.apiUrl = cfg.apiUrl.replace(/\/+$/, "");
+        this.scryptSalt = cfg.scryptSalt;
+        this.apiKey = cfg.apiKey;
+        this.inboxId = cfg.inboxId;
+        this.credentialDir = cfg.credentialDir;
+        this.files = cfg.files;
+    }
+    static async create(cfg) {
+        const session = new AgentSession(cfg);
+        await session.loadFromDisk();
+        return session;
+    }
+    get hasApiKey() {
+        return this.apiKey !== undefined && this.apiKey.length > 0;
+    }
+    get currentInboxId() {
+        return this.inboxId;
+    }
+    async loadFromDisk() {
+        this.sessionJWT = await tryReadJwtFile(this.files.sessionFile);
+        this.capabilityJWT = await tryReadJwtFile(this.files.capabilityFile);
+        const disk = await tryReadCredentials(this.files.credentialsFile);
+        if (disk) {
+            this.apiKey = this.apiKey ?? disk.apiKey;
+            this.inboxId = this.inboxId ?? disk.inboxId;
+        }
+    }
+    /**
+     * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
+     */
+    async getPrimaryMailAccountId() {
+        if (this.cachedMailAccountId)
+            return this.cachedMailAccountId;
+        const cap = await this.getCapabilityToken();
+        const session = await fetchJmapWellKnown(this.apiUrl, cap);
+        const id = extractPrimaryMailAccountId(session);
+        this.cachedMailAccountId = id;
+        return id;
+    }
+    invalidateJmapSessionCache() {
+        this.cachedMailAccountId = undefined;
+    }
+    /**
+     * Register or return existing inbox when username matches (idempotent).
+     * Different username replaces on-disk credentials and creates a new inbox.
+     */
+    async register(username) {
+        const want = normalizeUsername(username);
+        if (this.hasApiKey && !this.inboxId) {
+            throw new Error("Cannot register: an API key is configured but inboxId is unknown. " +
+                "Fix credentials.json or unset ATOMIC_MAIL_API_KEY before registering.");
+        }
+        if (this.hasApiKey && this.inboxId) {
+            const have = inboxLocalPart(this.inboxId);
+            if (have === want) {
+                const accountId = await this.getPrimaryMailAccountId();
+                return {
+                    inbox: this.inboxId,
+                    accountId,
+                    idempotent: true,
+                };
+            }
+            await unlinkCredentialArtifacts(this.files);
+            this.apiKey = undefined;
+            this.inboxId = undefined;
+            this.sessionJWT = undefined;
+            this.capabilityJWT = undefined;
+            this.cachedMailAccountId = undefined;
+        }
+        const result = await performPoWAndSession({
+            authUrl: this.authUrl,
+            scryptSalt: this.scryptSalt,
+            username,
+        });
+        if (!result.apiKey) {
+            throw new Error("Signup did not return an apiKey — this indicates a server bug.");
+        }
+        this.apiKey = result.apiKey;
+        this.sessionJWT = result.sessionJWT;
+        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
+        const capability = await fetchCapability(this.authUrl, this.sessionJWT);
+        this.capabilityJWT = capability;
+        await writeJwtFile(this.files.capabilityFile, capability);
+        const claims = decodeJwtPayload(capability);
+        if (typeof claims.inboxId !== "string" || claims.inboxId.length === 0) {
+            throw new Error("Capability JWT missing inboxId claim after signup.");
+        }
+        this.inboxId = claims.inboxId;
+        this.cachedMailAccountId = undefined;
+        const creds = {
+            apiKey: this.apiKey,
+            inboxId: this.inboxId,
+            authUrl: this.authUrl,
+            apiUrl: this.apiUrl,
+            scryptSalt: this.scryptSalt,
+        };
+        await writeCredentials(this.files.credentialsFile, creds);
+        const accountId = await this.getPrimaryMailAccountId();
+        return {
+            inbox: this.inboxId,
+            accountId,
+            apiKey: this.apiKey,
+        };
+    }
+    async getCapabilityToken() {
+        if (this.capabilityJWT &&
+            !isJwtExpired(this.capabilityJWT, CAPABILITY_SAFETY_MARGIN_MS)) {
+            return this.capabilityJWT;
+        }
+        await this.ensureSession();
+        if (!this.sessionJWT) {
+            throw new Error("Internal: ensureSession() left sessionJWT unset.");
+        }
+        const cap = await fetchCapability(this.authUrl, this.sessionJWT);
+        this.capabilityJWT = cap;
+        await writeJwtFile(this.files.capabilityFile, cap);
+        try {
+            const claims = decodeJwtPayload(cap);
+            if (typeof claims.inboxId === "string" && claims.inboxId.length > 0) {
+                this.inboxId = claims.inboxId;
+            }
+        }
+        catch {
+            // non-fatal
+        }
+        return cap;
+    }
+    async ensureSession() {
+        if (this.sessionJWT &&
+            !isJwtExpired(this.sessionJWT, SESSION_SAFETY_MARGIN_MS)) {
+            return;
+        }
+        if (!this.apiKey) {
+            throw new Error("No API key configured and no valid session on disk. Run register " +
+                "first, set ATOMIC_MAIL_API_KEY, or place credentials.json in the " +
+                "credential directory.");
+        }
+        const result = await performPoWAndSession({
+            authUrl: this.authUrl,
+            scryptSalt: this.scryptSalt,
+            apiKey: this.apiKey,
+        });
+        this.sessionJWT = result.sessionJWT;
+        this.capabilityJWT = undefined;
+        this.cachedMailAccountId = undefined;
+        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
+    }
+    destroy() {
+        // reserved
+    }
+}
+/** PoW login with an existing API key; writes credentials + JWT files. */
+export async function persistLoginWithApiKey(input) {
+    const authUrl = input.authUrl.replace(/\/+$/, "");
+    const apiUrl = input.apiUrl.replace(/\/+$/, "");
+    const session = await performPoWAndSession({
+        authUrl,
+        scryptSalt: input.scryptSalt,
+        apiKey: input.apiKey,
+        onPowProgress: input.onPowProgress,
+    });
+    const capabilityJWT = await fetchCapability(authUrl, session.sessionJWT);
+    const claims = decodeJwtPayload(capabilityJWT);
+    const inboxId = claims.inboxId;
+    if (typeof inboxId !== "string" || inboxId.length === 0) {
+        throw new Error("Capability JWT did not contain an inboxId claim.");
+    }
+    await writeCredentials(input.files.credentialsFile, {
+        apiKey: input.apiKey,
+        inboxId,
+        authUrl,
+        apiUrl,
+        scryptSalt: input.scryptSalt,
+    });
+    await writeJwtFile(input.files.sessionFile, session.sessionJWT);
+    await writeJwtFile(input.files.capabilityFile, capabilityJWT);
+    return { inboxId };
+}

package/esm/lib/src/agent-vars.d.ts

@@ -0,0 +1,23 @@
+/** Matches `$FOO_BAR`; excludes JMAP keywords like `$draft` (lowercase). */
+export declare const VAR_PATTERN: RegExp;
+/** Names substituted from JMAP session / credentials when not overridden in `vars`. */
+export declare const SESSION_VAR_NAMES: Set<string>;
+export interface SubstituteVarsInput {
+    raw: string;
+    /** Caller-supplied values; keys are names without `$` (e.g. `TO`, `SUBJECT`). */
+    vars?: Record<string, string>;
+    /** Invoked only when the name appears in `raw`, is absent from `vars`, and a resolver exists. */
+    autoResolvers?: Record<string, () => Promise<string> | string>;
+}
+export interface SubstituteVarsResult {
+    text: string;
+}
+/** Unique variable names in order of first occurrence (without leading `$`). */
+export declare function findVarReferences(raw: string): string[];
+/**
+ * Replaces every `$VAR_NAME` in `raw` with the corresponding string.
+ * Single pass — values are not scanned for further `$` tokens.
+ * Throws if any referenced variable has no value (after vars + autoResolvers).
+ */
+export declare function substituteVars(input: SubstituteVarsInput): Promise<SubstituteVarsResult>;
+//# sourceMappingURL=agent-vars.d.ts.map

package/esm/lib/src/agent-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-vars.d.ts","sourceRoot":"","sources":["../../../src/lib/src/agent-vars.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,eAAO,MAAM,WAAW,QAAyB,CAAC;AAMlD,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,aAA2C,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvD;AAeD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CA+B/B"}

package/esm/lib/src/agent-vars.js

@@ -0,0 +1,65 @@
+// Variable substitution for JMAP presets / inline ops ($VAR_NAME tokens).
+/** Matches `$FOO_BAR`; excludes JMAP keywords like `$draft` (lowercase). */
+export const VAR_PATTERN = /\$([A-Z][A-Z0-9_]*)/g;
+function varPattern() {
+    return new RegExp(VAR_PATTERN.source, VAR_PATTERN.flags);
+}
+/** Names substituted from JMAP session / credentials when not overridden in `vars`. */
+export const SESSION_VAR_NAMES = new Set(["ACCOUNT_ID", "INBOX"]);
+/** Unique variable names in order of first occurrence (without leading `$`). */
+export function findVarReferences(raw) {
+    const seen = new Set();
+    const order = [];
+    for (const m of raw.matchAll(varPattern())) {
+        const name = m[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            order.push(name);
+        }
+    }
+    return order;
+}
+function formatMissingError(missing) {
+    const tokens = missing.map((n) => `$${n}`);
+    const hasSession = missing.some((n) => SESSION_VAR_NAMES.has(n));
+    let msg = `Missing values for variables: ${tokens.join(", ")}. ` +
+        "Pass custom placeholders in vars (MCP) or --vars (skill).";
+    if (hasSession) {
+        msg +=
+            " For $ACCOUNT_ID and $INBOX, ensure register completed and credentials are valid, " +
+                "or pass overrides in vars.";
+    }
+    return new Error(msg);
+}
+/**
+ * Replaces every `$VAR_NAME` in `raw` with the corresponding string.
+ * Single pass — values are not scanned for further `$` tokens.
+ * Throws if any referenced variable has no value (after vars + autoResolvers).
+ */
+export async function substituteVars(input) {
+    const names = findVarReferences(input.raw);
+    if (names.length === 0) {
+        return { text: input.raw };
+    }
+    const userVars = input.vars ?? {};
+    const resolved = new Map();
+    for (const name of names) {
+        if (Object.prototype.hasOwnProperty.call(userVars, name)) {
+            resolved.set(name, userVars[name]);
+            continue;
+        }
+        const resolver = input.autoResolvers?.[name];
+        if (resolver) {
+            resolved.set(name, await resolver());
+            continue;
+        }
+    }
+    const missing = names.filter((n) => !resolved.has(n));
+    if (missing.length > 0) {
+        throw formatMissingError(missing);
+    }
+    const text = input.raw.replace(varPattern(), (_full, name) => {
+        return resolved.get(name);
+    });
+    return { text };
+}

package/esm/mcp/src/main.js

@@ -1,88 +1,58 @@
 #!/usr/bin/env node
-// AtomicMail MCP server — local stdio proxy with PoW auth and JMAP.
+// AtomicMail MCP server — stdio, PoW auth, JMAP (register / jmap_request / help).
 //
-// Designed to be launched by an MCP-capable agent host (Cursor, Claude
-// Desktop, Continue, Cline, ...) as a child process and communicated with
-// over stdio.
-//
-// CONFIGURATION (priority order):
-//   1. credentials.json + session.jwt + capability.jwt in the credential
-//      directory (default: ~/.atomicmail/, override with the env var
-//      ATOMIC_MAIL_CREDENTIALS_DIR). This is the SAME on-disk layout
-//      produced by the atomic-mail-signup CLI from @atomic-mail/agent-skill.
-//   2. ATOMIC_MAIL_AUTH_URL / ATOMIC_MAIL_API_URL / ATOMIC_MAIL_API_KEY —
-//      overlay individual fields on top of (1). Optional: ATOMIC_MAIL_SCRYPT_SALT
-//      overrides the built-in PoW salt (normally unnecessary).
-//
-// If auth and API URLs cannot be resolved, the server fails fast on startup.
-//
-// See README.md for installation and MCP host configuration examples.
+// CONFIGURATION: credentials.json + session.jwt + capability.jwt in the
+// credential directory (default ~/.atomicmail/, override ATOMIC_MAIL_CREDENTIALS_DIR),
+// merged with ATOMIC_MAIL_AUTH_URL / ATOMIC_MAIL_API_URL / ATOMIC_MAIL_API_KEY.
 import process from "node:process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { AuthSession, resolveConfig } from "./auth-session.js";
-import { registerDocsTool } from "./tools/docs.js";
+import { AgentSession } from "../../lib/src/agent-session.js";
+import { resolveAgentConfigFromEnv } from "../../lib/src/agent-resolve-config.js";
+import { registerHelpTool } from "./tools/help.js";
 import { registerJmapTool } from "./tools/jmap.js";
 import { registerRegisterTool } from "./tools/register.js";
 const VERSION = "0.1.0";
 const INSTRUCTIONS = `\
-AtomicMail MCP server — a programmable email inbox for AI agents.
+Atomic Mail MCP — programmable inbox for AI agents.
 
 WORKFLOW
-  1. If you do not yet have an account, call the 'register' tool with a
-     desired username. It performs a Proof-of-Work signup and persists
-     credentials.json + session.jwt + capability.jwt into the credential
-     directory so future invocations skip this step.
-  2. Call 'jmap_session' to fetch your accountId, capabilities, and the
-     mailbox URL. Cache the accountId — every subsequent JMAP call needs it.
-  3. Call 'jmap_request' with one or more JMAP method calls. Auth (session
-     + capability JWT rotation) is fully automatic. You can either pass
-     'methodCalls' inline or 'opsFile' (a path to a saved JSON preset).
-  4. Call 'get_docs' for in-depth topic guides. Topics include:
-     overview, auth, jmap_cheatsheet, tools, installation, presets,
-     troubleshooting.
+  1. Call register with a desired username (PoW signup; credentials on disk).
+  2. Call jmap_request with JMAP method calls (inline ops JSON or ops_file preset).
+     $VAR_NAME tokens: $ACCOUNT_ID / $INBOX from session; pass others in vars.
+  3. Call help for full documentation (JMAP cheatsheet, presets, troubleshooting).
 
-CREDENTIAL FILES
-  Credentials live in ~/.atomicmail/ by default (override with
-  ATOMIC_MAIL_CREDENTIALS_DIR). The same files are produced by the
-  atomic-mail-signup CLI from @atomic-mail/agent-skill so you can mix and
-  match the two — e.g. bootstrap an account with the CLI, then point the
-  MCP at the same directory.
+CREDENTIAL DIRECTORY
+  Default ~/.atomicmail/ (override ATOMIC_MAIL_CREDENTIALS_DIR). Same files as
+  the @atomicmail/agent-skill CLI: credentials.json, session.jwt, capability.jwt.
 
-    credentials.json   { apiKey, inboxId, authUrl, apiUrl, scryptSalt }
-    session.jwt        4-hour TTL, rotated automatically via PoW.
-    capability.jwt     2-minute TTL, rotated automatically via /capability.
-
-ENVIRONMENT VARIABLES
-  ATOMIC_MAIL_CREDENTIALS_DIR   override default credential directory
-  ATOMIC_MAIL_AUTH_URL          auth-service base URL
-  ATOMIC_MAIL_API_URL           api-service / JMAP base URL
-  ATOMIC_MAIL_SCRYPT_SALT       optional PoW salt override (defaults match auth-service)
-  ATOMIC_MAIL_API_KEY           existing API key (skip signup)
+ENVIRONMENT
+  ATOMIC_MAIL_CREDENTIALS_DIR  credential directory
+  ATOMIC_MAIL_AUTH_URL         auth-service base URL
+  ATOMIC_MAIL_API_URL          JMAP / API base URL
+  ATOMIC_MAIL_SCRYPT_SALT      optional PoW salt override
+  ATOMIC_MAIL_API_KEY          optional existing API key
 
 SECURITY
-  credentials.json contains your apiKey — treat it like a password. Files
-  are written with mode 0600.
-
-For full reference call get_docs with the relevant topic.`;
+  credentials.json contains your apiKey — treat it as a secret (mode 0600).`;
 async function main() {
     let config;
     try {
-        config = await resolveConfig();
+        config = await resolveAgentConfigFromEnv();
     }
     catch (err) {
-        console.error("AtomicMail MCP: configuration error:", err instanceof Error ? err.message : err);
+        console.error("Atomic Mail MCP: configuration error:", err instanceof Error ? err.message : err);
         process.exit(1);
     }
-    console.error(`AtomicMail MCP v${VERSION}: credential dir '${config.credentialDir}' ` +
+    console.error(`Atomic Mail MCP v${VERSION}: credential dir '${config.credentialDir}' ` +
         `(config source: ${config.source}).`);
     if (config.apiKey) {
-        console.error(`AtomicMail MCP: API key found${config.inboxId ? ` (inbox ${config.inboxId})` : ""}.`);
+        console.error(`Atomic Mail MCP: API key configured${config.inboxId ? ` (inbox ${config.inboxId})` : ""}.`);
     }
     else {
-        console.error("AtomicMail MCP: no API key configured — call the 'register' tool to create an account.");
+        console.error("Atomic Mail MCP: no API key — call register to create an account.");
     }
-    const session = await AuthSession.create({
+    const session = await AgentSession.create({
         authUrl: config.authUrl,
         apiUrl: config.apiUrl,
         scryptSalt: config.scryptSalt,
@@ -94,7 +64,7 @@ async function main() {
     const server = new McpServer({ name: "atomicmail", version: VERSION }, { instructions: INSTRUCTIONS });
     registerRegisterTool(server, session);
     registerJmapTool(server, session);
-    registerDocsTool(server);
+    registerHelpTool(server);
     const cleanup = () => {
         session.destroy();
     };
@@ -108,9 +78,9 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("AtomicMail MCP: server running on stdio");
+    console.error("Atomic Mail MCP: server running on stdio");
 }
 main().catch((err) => {
-    console.error("AtomicMail MCP: fatal error:", err);
+    console.error("Atomic Mail MCP: fatal error:", err);
     process.exit(1);
 });

package/esm/mcp/src/tools/help.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+export declare function registerHelpTool(server: McpServer): void;
+//# sourceMappingURL=help.d.ts.map

package/esm/mcp/src/tools/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../../src/mcp/src/tools/help.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAOtE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4BxD"}

package/esm/mcp/src/tools/help.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { getHelp, HELP_TOPIC_LIST, } from "../../../lib/src/agent-help-content.js";
+export function registerHelpTool(server) {
+    server.registerTool("help", {
+        title: "Atomic Mail documentation",
+        description: "Return in-depth documentation: JMAP cheatsheet, presets, auth flow, " +
+            "troubleshooting. Optional topic. Topics: " +
+            HELP_TOPIC_LIST.join(", ") + ".",
+        inputSchema: z.object({
+            topic: z
+                .string()
+                .optional()
+                .describe(`Topic (e.g. ${HELP_TOPIC_LIST.slice(0, 4).join(", ")}, ...). Omit for overview.`),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, ({ topic }) => ({
+        content: [{ type: "text", text: getHelp(topic) }],
+    }));
+}

package/esm/mcp/src/tools/jmap.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
-import type { AuthSession } from "../auth-session.js";
-export declare function registerJmapTool(server: McpServer, session: AuthSession): void;
+import type { AgentSession } from "../../../lib/src/agent-session.js";
+export declare function registerJmapTool(server: McpServer, session: AgentSession): void;
 //# sourceMappingURL=jmap.d.ts.map

package/esm/mcp/src/tools/jmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../../src/mcp/src/tools/jmap.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2CtD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,GACnB,IAAI,CAyMN"}
+{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../../src/mcp/src/tools/jmap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAOtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEtE,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,YAAY,GACpB,IAAI,CAmIN"}