@atomicmail/mcp 0.2.1 → 0.2.2

package/README.md

@@ -1,3 +1,7 @@
+---
+description: Install and configure the @atomicmail/mcp stdio server, tools (register, jmap_request, help), and host-specific notes for chat-based agents.
+---
+
 # @atomicmail/mcp
 
 Atomic Mail MCP server — a local stdio Model Context Protocol server that gives
@@ -23,11 +27,11 @@ Your MCP host spawns this process; see configuration below.
 
 ## Tools exposed
 
-| Tool           | Description                                                                                                                                               |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `register`     | PoW signup; persists credentials. Idempotent when username matches inbox.                                                                                 |
-| `jmap_request` | JMAP batch via `ops` or `ops_file`. Uppercase `$VAR_NAME` tokens are substituted (`$ACCOUNT_ID` / `$INBOX` from session; others via optional `vars` map). |
-| `help`         | Built-in docs (`topic` optional).                                                                                                                         |
+| Tool           | Description                                                                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `register`     | PoW signup; persists credentials. Idempotent when username matches inbox.                                                                                                                   |
+| `jmap_request` | JMAP batch via `ops` or `ops_file`. Uppercase `$VAR_NAME` tokens are substituted (`$ACCOUNT_ID` / `$INBOX` / `$UPLOAD_URL` / `$DOWNLOAD_URL` from session; others via optional `vars` map). |
+| `help`         | Built-in docs (`topic` optional); use `topic: "readme"` for the published package `README.md`.                                                                                              |
 
 ## Typical MCP workflow
 
@@ -62,11 +66,12 @@ Resolution order for `ops_file`:
 Placeholder rules:
 
 - Pattern: `$VAR_NAME`, where `VAR_NAME` matches `^[A-Z][A-Z0-9_]*$`.
-- Built-ins: `$ACCOUNT_ID`, `$INBOX`.
+- Built-ins: `$ACCOUNT_ID`, `$INBOX`, `$UPLOAD_URL`, `$DOWNLOAD_URL`.
 - Lowercase `$tokens` such as JMAP back-references (`$draft`) are not matched.
 - Custom placeholders: passed in `vars` as string values.
 - Resolution order per variable: `vars` first, then built-in auto-resolvers.
-- Built-ins can be overridden by providing `ACCOUNT_ID` or `INBOX` in `vars`.
+- Built-ins can be overridden by providing `ACCOUNT_ID`, `INBOX`, `UPLOAD_URL`,
+  or `DOWNLOAD_URL` in `vars`.
 - If any referenced variable is unresolved, `jmap_request` fails with a missing
   variables error.
 - Substitution is single-pass: inserted values are not scanned again for nested
@@ -89,13 +94,134 @@ Example:
 
 Mode `0600`:
 
-- `credentials.json` — `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }`
-- `session.jwt` — 4h TTL, rotated via PoW
+- `credentials.json` —
+  `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl }`
+- `session.jwt` — 1h TTL, rotated via PoW
 - `capability.jwt` — 2m TTL, rotated before JMAP calls
 
 These files are created and rotated automatically by MCP tool calls. AgentSkill
 CLI uses the same files.
 
+During PoW auth, the challenge JWT is exchanged via `Authorization: Bearer ...`
+for both `POST /api/v1/challenge` (response header) and `POST /api/v1/session`
+(request header), and session JWT is read from the `POST /api/v1/session`
+response header. `POST /api/v1/capability` accepts session JWT via bearer header
+and returns capability JWT in the response bearer header. PoW values (`powHex`,
+`nonce`) remain in the JSON body for session creation.
+
+## Attachments and blobs
+
+Two blob paths are supported:
+
+- **RFC 9404 in-band blobs** via `Blob/upload` and `Blob/get` over
+  `jmap_request`.
+- **RFC 8620 out-of-band blobs** via `uploadUrl` and `downloadUrl` templates
+  from JMAP session.
+
+### Inline blob flow (RFC 9404)
+
+Add `urn:ietf:params:jmap:blob` and upload data in the same JMAP batch:
+
+```json
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission",
+    "urn:ietf:params:jmap:blob"
+  ],
+  "methodCalls": [
+    [
+      "Blob/upload",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "b1": {
+            "data:asText": "Hello attachment",
+            "type": "text/plain"
+          }
+        }
+      },
+      "b0"
+    ],
+    [
+      "Email/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "m1": {
+            "from": [{ "email": "$INBOX" }],
+            "to": [{ "email": "$TO" }],
+            "subject": "With attachment",
+            "bodyValues": {
+              "body1": { "value": "See attachment." }
+            },
+            "textBody": [{ "partId": "body1", "type": "text/plain" }],
+            "attachments": [
+              {
+                "blobId": "#b1",
+                "type": "text/plain",
+                "name": "note.txt"
+              }
+            ]
+          }
+        }
+      },
+      "m0"
+    ],
+    [
+      "EmailSubmission/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": { "s1": { "emailId": "#m1" } }
+      },
+      "s0"
+    ]
+  ]
+}
+```
+
+### Separate upload/download flow (RFC 8620)
+
+Use the templated URLs from session/credentials:
+
+- `$UPLOAD_URL` template contains `{accountId}`.
+- `$DOWNLOAD_URL` template contains `{accountId}`, `{blobId}`, `{name}`, and
+  `{type}`.
+
+Example (MCP flow):
+
+1. Call `jmap_request` to get attachment metadata (for example `Email/get` with
+   `attachments`).
+2. Expand `$DOWNLOAD_URL` template with account/blob metadata and fetch bytes
+   via HTTP bearer auth.
+3. To upload bytes, expand `$UPLOAD_URL` with account id and POST binary content
+   per RFC 8620 upload endpoint.
+
+### Blob retrieval (RFC 9404)
+
+For in-band retrieval, use `Blob/get`:
+
+```json
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:blob"
+  ],
+  "methodCalls": [
+    [
+      "Blob/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "ids": ["$BLOB_ID"],
+        "properties": ["id", "data:asBase64", "size", "type"]
+      },
+      "g0"
+    ]
+  ]
+}
+```
+
 ## Defaults
 
 - auth endpoint: `https://auth.atomicmail.ai`

package/esm/lib/agent/auth/agent-auth-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-auth-http.ts"],"names":[],"mappings":"AAoCA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CAS1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}
+{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-auth-http.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA8BD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/esm/lib/agent/auth/agent-auth-http.js

@@ -1,66 +1,65 @@
 // auth-service HTTP: challenge → session → capability.
 import { decodeJwtPayload } from "./agent-jwt.js";
 import { solvePow } from "./agent-pow.js";
-async function postJson(url, body, headers = {}) {
-    const res = await fetch(url, {
+export async function fetchChallenge(authUrl) {
+    const res = await fetch(`${authUrl}/api/v1/challenge`, {
         method: "POST",
-        headers: {
-            ...(body ? { "Content-Type": "application/json" } : {}),
-            ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
     });
     const text = await res.text();
-    const path = (() => {
-        try {
-            return new URL(url).pathname;
-        }
-        catch {
-            return url;
-        }
-    })();
     if (!res.ok) {
-        throw new Error(`auth-service ${path} returned ${res.status}: ${text}`);
-    }
-    try {
-        return JSON.parse(text);
+        throw new Error(`auth-service /api/v1/challenge returned ${res.status}: ${text}`);
     }
-    catch {
-        throw new Error(`auth-service ${path} returned non-JSON body: ${text}`);
-    }
-}
-export async function fetchChallenge(authUrl) {
-    const data = await postJson(`${authUrl}/api/v1/challenge`, undefined);
-    if (typeof data.challengeJWT !== "string") {
-        throw new Error("Challenge response missing challengeJWT.");
-    }
-    const payload = decodeJwtPayload(data.challengeJWT);
+    const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+    const payload = decodeJwtPayload(challengeJWT);
     if (typeof payload.jti !== "string" ||
         typeof payload.difficulty !== "number") {
         throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
     }
     return {
-        challengeJWT: data.challengeJWT,
+        challengeJWT,
         challenge: payload.jti,
         difficulty: payload.difficulty,
     };
 }
 export async function exchangeSession(authUrl, body) {
-    const data = await postJson(`${authUrl}/api/v1/session`, { ...body });
-    if (typeof data.sessionJWT !== "string") {
-        throw new Error("Session response missing sessionJWT.");
+    const { challengeJWT, ...payload } = body;
+    const res = await fetch(`${authUrl}/api/v1/session`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${challengeJWT}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/session returned ${res.status}: ${text}`);
+    }
+    const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+    let data = {};
+    if (text.trim().length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new Error("auth-service /api/v1/session returned non-JSON body.");
+        }
     }
     return {
-        sessionJWT: data.sessionJWT,
+        sessionJWT,
         apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
     };
 }
 export async function fetchCapability(authUrl, sessionJWT) {
-    const data = await postJson(`${authUrl}/api/v1/capability`, undefined, { Authorization: `Bearer ${sessionJWT}` });
-    if (typeof data.capabilityJWT !== "string") {
-        throw new Error("Capability response missing capabilityJWT.");
+    const res = await fetch(`${authUrl}/api/v1/capability`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${sessionJWT}` },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/capability returned ${res.status}: ${text}`);
     }
-    return data.capabilityJWT;
+    return readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
 }
 export async function performPoWAndSession(input) {
     const { authUrl, scryptSalt } = input;
@@ -74,3 +73,13 @@ export async function performPoWAndSession(input) {
         username: input.username,
     });
 }
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

package/esm/lib/agent/auth/agent-jwt.d.ts

@@ -1,5 +1,3 @@
-export declare const SESSION_TTL_MS: number;
-export declare const CAPABILITY_TTL_MS: number;
 export declare const SESSION_SAFETY_MARGIN_MS = 60000;
 export declare const CAPABILITY_SAFETY_MARGIN_MS = 20000;
 export interface JwtPayload {

package/esm/lib/agent/auth/agent-jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-jwt.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-jwt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QAAqB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAgB,CAAC;AAE/C,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE"}
+{"version":3,"file":"agent-jwt.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-jwt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE"}

package/esm/lib/agent/auth/agent-jwt.js

@@ -1,6 +1,4 @@
 // JWT helpers for capability/session expiry checks.
-export const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
-export const CAPABILITY_TTL_MS = 2 * 60 * 1000;
 export const SESSION_SAFETY_MARGIN_MS = 60_000;
 export const CAPABILITY_SAFETY_MARGIN_MS = 20_000;
 export function decodeJwtPayload(jwt) {

package/esm/lib/agent/jmap/agent-help-content.d.ts

@@ -1,4 +1,5 @@
 export declare const HELP_TOPICS: Record<string, string>;
 export declare const HELP_TOPIC_LIST: string[];
+export declare function normalizeHelpTopic(topic: string): string;
 export declare function getHelp(topic?: string): string;
 //# sourceMappingURL=agent-help-content.d.ts.map

package/esm/lib/agent/jmap/agent-help-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-help-content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+O9C,CAAC;AAEF,eAAO,MAAM,eAAe,UAA2B,CAAC;AAExD,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9C"}
+{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-help-content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA0P9C,CAAC;AAEF,eAAO,MAAM,eAAe,UAA2B,CAAC;AAExD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9C"}

package/esm/lib/agent/jmap/agent-help-content.js

@@ -16,10 +16,12 @@ Three operations only:
 2. **jmap_request** — Send a JMAP method-call batch. Auth and JWT rotation are
    automatic. Pass inline \`ops\` JSON or an \`ops_file\` preset path (same
    substitution applies to both). Uppercase tokens like \`$ACCOUNT_ID\`,
-   \`$INBOX\`, \`$TO\`, \`$SUBJECT\` are replaced before the request is sent.
-   \`$ACCOUNT_ID\` / \`$INBOX\` come from the JMAP session and credentials; pass
-   any other names via MCP \`vars\` or skill \`--vars\`.
-3. **help** — This documentation (optional \`topic\` / \`--topic\`).
+   \`$INBOX\`, \`$UPLOAD_URL\`, \`$DOWNLOAD_URL\`, \`$TO\`, \`$SUBJECT\` are
+   replaced before the request is sent. \`$ACCOUNT_ID\` / \`$INBOX\` /
+   \`$UPLOAD_URL\` / \`$DOWNLOAD_URL\` come from the JMAP session and
+   credentials; pass any other names via MCP \`vars\` or skill \`--vars\`.
+3. **help** — This documentation (optional \`topic\` / \`--topic\`), or the
+   published package README (\`topic\` / \`--topic\` \`readme\`).
 
 ## Typical workflow
 
@@ -29,7 +31,7 @@ Three operations only:
 3. If stuck, read error hints and call \`help\`.
 
 Available topics: overview, installation, auth, jmap_cheatsheet, tools,
-presets, troubleshooting.`,
+presets, troubleshooting. Use \`readme\` for the npm package \`README.md\`.`,
     installation: `\
 # Atomic Mail — Installation
 
@@ -86,18 +88,22 @@ See each package README for details.`,
 Auth is automatic after \`register\` (or when \`credentials.json\` + API key
 exist).
 
-1. **Challenge** — \`POST /api/v1/challenge\`
+1. **Challenge** — \`POST /api/v1/challenge\`, read challenge JWT from
+   \`Authorization: Bearer <challengeJWT>\`
 2. **Proof-of-work** — scrypt until difficulty satisfied
-3. **Session JWT** — \`POST /api/v1/session\` (4h TTL); signup returns a
-   one-time \`apiKey\`
-4. **Capability JWT** — \`POST /api/v1/capability\` (2 min TTL) used as the
-   JMAP bearer
+3. **Session JWT** — \`POST /api/v1/session\` with challenge JWT in
+   \`Authorization: Bearer ...\` and PoW fields (\`powHex\`, \`nonce\`) in JSON
+   body; read session JWT from response \`Authorization: Bearer ...\` (1h TTL);
+   signup returns \`apiKey\` once
+4. **Capability JWT** — \`POST /api/v1/capability\` with session JWT in
+   \`Authorization: Bearer ...\`; read capability JWT from response
+   \`Authorization: Bearer ...\` (2 min TTL) used as the JMAP bearer
 
 JWTs are rotated before expiry and written back to disk.
 
 ## Credential files (mode 0600)
 
-\`credentials.json\` — \`{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }\`  
+\`credentials.json\` — \`{ apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl }\`  
 \`session.jwt\` — session token  
 \`capability.jwt\` — capability token
 
@@ -119,7 +125,8 @@ JWTs are rotated before expiry and written back to disk.
 
 ## Examples
 
-Use \`$ACCOUNT_ID\` and \`$INBOX\` for session fields; use \`$TO\`, \`$SUBJECT\`,
+Use \`$ACCOUNT_ID\`, \`$INBOX\`, \`$UPLOAD_URL\`, and \`$DOWNLOAD_URL\` for
+session fields; use \`$TO\`, \`$SUBJECT\`,
 etc., and supply values via MCP \`vars\` or \`--vars\` (JSON object of strings).
 
 ### Mailboxes
@@ -174,7 +181,8 @@ replaces credentials in the directory and registers a new inbox.
 **Skill:** \`help [--topic TOPIC]\`
 
 Topics: overview, installation, auth, jmap_cheatsheet, tools, presets,
-troubleshooting.`,
+troubleshooting. Topic \`readme\` prints the published package \`README.md\`
+(same layout as npm; requires install from npm).`,
     presets: `\
 # JMAP presets
 
@@ -199,11 +207,14 @@ keywords like \`$draft\` stay untouched).
 - \`$ACCOUNT_ID\` — primary mail account id (from \`GET /.well-known/jmap\` when
   referenced).
 - \`$INBOX\` — inbox email address from credentials.
+- \`$UPLOAD_URL\` — RFC 8620 upload URL template from JMAP session.
+- \`$DOWNLOAD_URL\` — RFC 8620 download URL template from JMAP session.
 - Any other \`$FOO\` — must appear in MCP \`vars\` or skill \`--vars\` as
   \`"FOO": "..."\` (string values only; JSON escaping in the preset body is your
   responsibility).
 
-You may override \`ACCOUNT_ID\` / \`INBOX\` via \`vars\` / \`--vars\` if needed.`,
+You may override \`ACCOUNT_ID\` / \`INBOX\` / \`UPLOAD_URL\` / \`DOWNLOAD_URL\`
+via \`vars\` / \`--vars\` if needed.`,
     troubleshooting: `\
 # Troubleshooting
 
@@ -234,11 +245,19 @@ Pass every custom placeholder in MCP \`vars\` or \`--vars\` as a JSON object of
 strings. Ensure \`register\` completed so \`$ACCOUNT_ID\` / \`$INBOX\` can resolve.`,
 };
 export const HELP_TOPIC_LIST = Object.keys(HELP_TOPICS);
+export function normalizeHelpTopic(topic) {
+    return topic.toLowerCase().replace(/[\s-]/g, "_");
+}
 export function getHelp(topic) {
     if (!topic) {
         return HELP_TOPICS["overview"];
     }
-    const key = topic.toLowerCase().replace(/[\s-]/g, "_");
+    const key = normalizeHelpTopic(topic);
+    if (key === "readme") {
+        return ("Topic \"readme\" prints the package README.md from the npm install. " +
+            "From MCP use {\"topic\":\"readme\"}; from the CLI: " +
+            "`atomicmail help --topic readme`.");
+    }
     return (HELP_TOPICS[key] ??
-        `Unknown topic "${topic}". Available topics: ${HELP_TOPIC_LIST.join(", ")}`);
+        `Unknown topic "${topic}". Available topics: ${HELP_TOPIC_LIST.join(", ")}, readme`);
 }

package/esm/lib/agent/jmap/agent-jmap.d.ts

@@ -8,6 +8,11 @@ export declare function parseJmapEnvelope(raw: string, defaultUsing: string[], s
 export declare function resolveOpsFilePath(credentialDir: string, opsFile: string): string;
 export declare function readOpsFile(credentialDir: string, opsFile: string): Promise<string>;
 export declare function extractPrimaryMailAccountId(session: Record<string, unknown>): string;
+export interface JmapBlobEndpoints {
+    uploadUrl: string;
+    downloadUrl: string;
+}
+export declare function extractBlobEndpoints(session: Record<string, unknown>): JmapBlobEndpoints;
 export declare function fetchJmapWellKnown(apiUrl: string, capabilityJwt: string): Promise<Record<string, unknown>>;
 /** Minimal surface for JMAP execution (implemented by AgentSession). */
 export interface JmapSessionPort {
@@ -18,6 +23,8 @@ export interface JmapSessionPort {
     getPrimaryMailAccountId(): Promise<string>;
     getCapabilityToken(): Promise<string>;
     readonly currentInboxId?: string;
+    readonly currentUploadUrl?: string;
+    readonly currentDownloadUrl?: string;
 }
 export interface RunJmapRequestInput {
     session: JmapSessionPort;

package/esm/lib/agent/jmap/agent-jmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-jmap.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,kBAAkB,qEAGrB,CAAC;AAEX,eAAO,MAAM,aAAa,EAAG,2BAAoC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,YAAY,CAyBd;AAED,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED,wBAAsB,WAAW,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAiBjB;AA8CD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAcR;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAclC;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4C5D;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5D;AAQD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU5D"}
+{"version":3,"file":"agent-jmap.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,kBAAkB,qEAGrB,CAAC;AAEX,eAAO,MAAM,aAAa,EAAG,2BAAoC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,YAAY,CAyBd;AAED,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED,wBAAsB,WAAW,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAiBjB;AA8CD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAcR;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,iBAAiB,CAUnB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAclC;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmD5D;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5D;AAQD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/esm/lib/agent/jmap/agent-jmap.js

@@ -93,6 +93,17 @@ export function extractPrimaryMailAccountId(session) {
     }
     return id;
 }
+export function extractBlobEndpoints(session) {
+    const uploadUrl = session["uploadUrl"];
+    const downloadUrl = session["downloadUrl"];
+    if (typeof uploadUrl !== "string" || uploadUrl.length === 0) {
+        throw new Error("JMAP session missing uploadUrl.");
+    }
+    if (typeof downloadUrl !== "string" || downloadUrl.length === 0) {
+        throw new Error("JMAP session missing downloadUrl.");
+    }
+    return { uploadUrl, downloadUrl };
+}
 export async function fetchJmapWellKnown(apiUrl, capabilityJwt) {
     const base = apiUrl.replace(/\/+$/, "");
     const res = await fetch(`${base}/.well-known/jmap`, {
@@ -120,6 +131,11 @@ export async function runJmapRequest(input) {
             ACCOUNT_ID: () => input.session.getPrimaryMailAccountId(),
             INBOX: async () => input.session.currentInboxId ??
                 (await readCredentials(input.session.files.credentialsFile)).inboxId,
+            UPLOAD_URL: async () => input.session.currentUploadUrl ??
+                (await readCredentials(input.session.files.credentialsFile)).uploadUrl,
+            DOWNLOAD_URL: async () => input.session.currentDownloadUrl ??
+                (await readCredentials(input.session.files.credentialsFile))
+                    .downloadUrl,
         },
     });
     const envelope = parseJmapEnvelope(raw, input.defaultUsing, input.sourceLabel);

package/esm/lib/agent/session/agent-credentials-store.d.ts

@@ -4,6 +4,8 @@ export interface Credentials {
     authUrl: string;
     apiUrl: string;
     scryptSalt: string;
+    uploadUrl: string;
+    downloadUrl: string;
 }
 export interface SkillFiles {
     credentialsFile: string;

package/esm/lib/agent/session/agent-credentials-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-credentials-store.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-credentials-store.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiCxE;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAOlC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"agent-credentials-store.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-credentials-store.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmCxE;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAOlC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/esm/lib/agent/session/agent-credentials-store.js

@@ -39,6 +39,8 @@ export async function readCredentials(path) {
         "authUrl",
         "apiUrl",
         "scryptSalt",
+        "uploadUrl",
+        "downloadUrl",
     ];
     for (const k of required) {
         if (typeof obj[k] !== "string" || obj[k].length === 0) {

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

@@ -28,16 +28,21 @@ export declare class AgentSession {
     private sessionJWT;
     private capabilityJWT;
     private cachedMailAccountId;
+    private cachedUploadUrl;
+    private cachedDownloadUrl;
     constructor(cfg: AgentSessionConfig);
     static create(cfg: AgentSessionConfig): Promise<AgentSession>;
     get hasApiKey(): boolean;
     get currentInboxId(): string | undefined;
+    get currentUploadUrl(): string | undefined;
+    get currentDownloadUrl(): string | undefined;
     private loadFromDisk;
     /**
      * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
      */
     getPrimaryMailAccountId(): Promise<string>;
     invalidateJmapSessionCache(): void;
+    private refreshJmapSessionData;
     /**
      * Register or return existing inbox when username matches (idempotent).
      * Different username replaces on-disk credentials and creates a new inbox.

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

@@ -1 +1 @@
-{"version":3,"file":"agent-session.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/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"}
+{"version":3,"file":"agent-session.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-session.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,UAAU,EAMhB,MAAM,8BAA8B,CAAC;AActC,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;IAChD,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,iBAAiB,CAAqB;gBAElC,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;IAED,IAAI,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAEzC;IAED,IAAI,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAE3C;YAEa,YAAY;IAY1B;;OAEG;IACG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAehD,0BAA0B,IAAI,IAAI;YAMpB,sBAAsB;IASpC;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8EnD,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;YA4B7B,aAAa;IA2B3B,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,CA6B9B"}

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

@@ -1,7 +1,7 @@
 // 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 "../auth/agent-jwt.js";
-import { extractPrimaryMailAccountId, fetchJmapWellKnown, } from "../jmap/agent-jmap.js";
+import { extractBlobEndpoints, extractPrimaryMailAccountId, fetchJmapWellKnown, } from "../jmap/agent-jmap.js";
 import { fetchCapability, performPoWAndSession } from "../auth/agent-auth-http.js";
 function normalizeUsername(u) {
     return u.trim().toLowerCase();
@@ -24,6 +24,8 @@ export class AgentSession {
     sessionJWT;
     capabilityJWT;
     cachedMailAccountId;
+    cachedUploadUrl;
+    cachedDownloadUrl;
     constructor(cfg) {
         this.authUrl = cfg.authUrl.replace(/\/+$/, "");
         this.apiUrl = cfg.apiUrl.replace(/\/+$/, "");
@@ -44,6 +46,12 @@ export class AgentSession {
     get currentInboxId() {
         return this.inboxId;
     }
+    get currentUploadUrl() {
+        return this.cachedUploadUrl;
+    }
+    get currentDownloadUrl() {
+        return this.cachedDownloadUrl;
+    }
     async loadFromDisk() {
         this.sessionJWT = await tryReadJwtFile(this.files.sessionFile);
         this.capabilityJWT = await tryReadJwtFile(this.files.capabilityFile);
@@ -51,22 +59,37 @@ export class AgentSession {
         if (disk) {
             this.apiKey = this.apiKey ?? disk.apiKey;
             this.inboxId = this.inboxId ?? disk.inboxId;
+            this.cachedUploadUrl = disk.uploadUrl;
+            this.cachedDownloadUrl = disk.downloadUrl;
         }
     }
     /**
      * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
      */
     async getPrimaryMailAccountId() {
-        if (this.cachedMailAccountId)
+        if (this.cachedMailAccountId &&
+            this.cachedUploadUrl &&
+            this.cachedDownloadUrl) {
             return this.cachedMailAccountId;
-        const cap = await this.getCapabilityToken();
-        const session = await fetchJmapWellKnown(this.apiUrl, cap);
-        const id = extractPrimaryMailAccountId(session);
-        this.cachedMailAccountId = id;
-        return id;
+        }
+        await this.refreshJmapSessionData();
+        if (!this.cachedMailAccountId) {
+            throw new Error("JMAP session missing primary mail account id.");
+        }
+        return this.cachedMailAccountId;
     }
     invalidateJmapSessionCache() {
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
+    }
+    async refreshJmapSessionData() {
+        const cap = await this.getCapabilityToken();
+        const session = await fetchJmapWellKnown(this.apiUrl, cap);
+        this.cachedMailAccountId = extractPrimaryMailAccountId(session);
+        const blobs = extractBlobEndpoints(session);
+        this.cachedUploadUrl = blobs.uploadUrl;
+        this.cachedDownloadUrl = blobs.downloadUrl;
     }
     /**
      * Register or return existing inbox when username matches (idempotent).
@@ -115,15 +138,22 @@ export class AgentSession {
         }
         this.inboxId = claims.inboxId;
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
+        const accountId = await this.getPrimaryMailAccountId();
+        if (!this.cachedUploadUrl || !this.cachedDownloadUrl) {
+            throw new Error("JMAP session did not provide upload/download URLs.");
+        }
         const creds = {
             apiKey: this.apiKey,
             inboxId: this.inboxId,
             authUrl: this.authUrl,
             apiUrl: this.apiUrl,
             scryptSalt: this.scryptSalt,
+            uploadUrl: this.cachedUploadUrl,
+            downloadUrl: this.cachedDownloadUrl,
         };
         await writeCredentials(this.files.credentialsFile, creds);
-        const accountId = await this.getPrimaryMailAccountId();
         return {
             inbox: this.inboxId,
             accountId,
@@ -171,6 +201,8 @@ export class AgentSession {
         this.sessionJWT = result.sessionJWT;
         this.capabilityJWT = undefined;
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
         await writeJwtFile(this.files.sessionFile, this.sessionJWT);
     }
     destroy() {
@@ -193,12 +225,16 @@ export async function persistLoginWithApiKey(input) {
     if (typeof inboxId !== "string" || inboxId.length === 0) {
         throw new Error("Capability JWT did not contain an inboxId claim.");
     }
+    const jmapSession = await fetchJmapWellKnown(apiUrl, capabilityJWT);
+    const blobs = extractBlobEndpoints(jmapSession);
     await writeCredentials(input.files.credentialsFile, {
         apiKey: input.apiKey,
         inboxId,
         authUrl,
         apiUrl,
         scryptSalt: input.scryptSalt,
+        uploadUrl: blobs.uploadUrl,
+        downloadUrl: blobs.downloadUrl,
     });
     await writeJwtFile(input.files.sessionFile, session.sessionJWT);
     await writeJwtFile(input.files.capabilityFile, capabilityJWT);

package/esm/lib/core/read-npm-package-readme.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads README.md from the npm package root (next to package.json).
+ * Intended for published @atomicmail/mcp and @atomicmail/agent-skill layouts.
+ */
+export declare function readNpmPackageReadme(): Promise<string>;
+//# sourceMappingURL=read-npm-package-readme.d.ts.map

package/esm/lib/core/read-npm-package-readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-npm-package-readme.d.ts","sourceRoot":"","sources":["../../../src/lib/core/read-npm-package-readme.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CA+C5D"}

package/esm/lib/core/read-npm-package-readme.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const MAX_DEPTH = 16;
+const ATOMICMAIL_NPM_NAMES = new Set([
+    "@atomicmail/mcp",
+    "@atomicmail/agent-skill",
+]);
+function isEnoent(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * Reads README.md from the npm package root (next to package.json).
+ * Intended for published @atomicmail/mcp and @atomicmail/agent-skill layouts.
+ */
+export async function readNpmPackageReadme() {
+    const moduleDir = dirname(fileURLToPath(globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url));
+    let currentDir = moduleDir;
+    for (let i = 0; i < MAX_DEPTH; i++) {
+        const pkgPath = resolve(currentDir, "package.json");
+        const readmePath = resolve(currentDir, "README.md");
+        let pkgRaw;
+        try {
+            pkgRaw = await readFile(pkgPath, "utf-8");
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+            const parent = resolve(currentDir, "..");
+            if (parent === currentDir)
+                break;
+            currentDir = parent;
+            continue;
+        }
+        let name;
+        try {
+            name = JSON.parse(pkgRaw).name;
+        }
+        catch {
+            name = undefined;
+        }
+        if (!name || !ATOMICMAIL_NPM_NAMES.has(name)) {
+            const parent = resolve(currentDir, "..");
+            if (parent === currentDir)
+                break;
+            currentDir = parent;
+            continue;
+        }
+        try {
+            return await readFile(readmePath, "utf-8");
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+        const parent = resolve(currentDir, "..");
+        if (parent === currentDir)
+            break;
+        currentDir = parent;
+    }
+    throw new Error("Could not find Atomic Mail package README.md — use a published npm install " +
+        "(@atomicmail/mcp or @atomicmail/agent-skill) for --topic readme.");
+}

package/esm/lib/mod.d.ts

@@ -1,5 +1,6 @@
 export * from "./network/auth-client.js";
 export * from "./core/utils.js";
+export * from "./core/read-npm-package-readme.js";
 export * from "./core/consts.js";
 export * from "./core/types.js";
 export * from "./agent/session/agent-credentials-store.js";

package/esm/lib/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/lib/mod.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/lib/mod.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC"}

package/esm/lib/mod.js

@@ -1,5 +1,6 @@
 export * from "./network/auth-client.js";
 export * from "./core/utils.js";
+export * from "./core/read-npm-package-readme.js";
 export * from "./core/consts.js";
 export * from "./core/types.js";
 export * from "./agent/session/agent-credentials-store.js";

package/esm/lib/network/auth-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/lib/network/auth-client.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;gBAEL,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM9D;AAOD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,EAAE,iBAAiB;IAKtC;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBrD,4DAA4D;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAqBjD;;;OAGG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAgBvC,cAAc;YAkCd,WAAW;YAeX,gBAAgB;IAuB9B;;;;;;;OAOG;YACW,QAAQ;CAgBvB"}
+{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/lib/network/auth-client.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;gBAEL,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM9D;AAOD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,EAAE,iBAAiB;IAKtC;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBrD,4DAA4D;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBjD;;;OAGG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAoBvC,cAAc;YAsCd,WAAW;YAyCX,gBAAgB;IAuB9B;;;;;;;OAOG;YACW,QAAQ;CAgBvB"}

package/esm/lib/network/auth-client.js

@@ -40,32 +40,26 @@ export class AuthClient {
     async signup(username) {
         const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
         const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
-        const data = await this.postSession({
-            challengeJWT,
+        const { sessionJWT, data } = await this.postSession(challengeJWT, {
             powHex,
             nonce: nonce.toString(),
             username,
         });
-        if (typeof data.apiKey !== "string" ||
-            typeof data.sessionJWT !== "string") {
-            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey or sessionJWT.");
+        if (typeof data.apiKey !== "string") {
+            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey.");
         }
-        return { apiKey: data.apiKey, sessionJWT: data.sessionJWT };
+        return { apiKey: data.apiKey, sessionJWT };
     }
     /** Exchange an existing API key for a fresh session JWT. */
     async login(apiKey) {
         const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
         const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
-        const data = await this.postSession({
-            challengeJWT,
+        const { sessionJWT } = await this.postSession(challengeJWT, {
             powHex,
             nonce: nonce.toString(),
             apiKey,
         });
-        if (typeof data.sessionJWT !== "string") {
-            throw new AuthClientError(200, JSON.stringify(data), "Login response missing sessionJWT.");
-        }
-        return { sessionJWT: data.sessionJWT };
+        return { sessionJWT };
     }
     /**
      * Exchange a session JWT for a short-lived capability JWT (audience:
@@ -76,38 +70,57 @@ export class AuthClient {
             method: "POST",
             headers: { Authorization: `Bearer ${sessionJWT}` },
         });
-        const data = await this.parseJsonOrThrow(res, "capability");
-        if (typeof data.capabilityJWT !== "string") {
-            throw new AuthClientError(res.status, JSON.stringify(data), "Capability response missing capabilityJWT.");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service capability returned ${res.status}: ${text}`);
         }
-        return { capabilityJWT: data.capabilityJWT };
+        const capabilityJWT = readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
+        return { capabilityJWT };
     }
     async fetchChallenge() {
         const res = await fetch(`${this.baseUrl}/api/v1/challenge`, {
             method: "POST",
         });
-        const data = await this.parseJsonOrThrow(res, "challenge");
-        if (typeof data.challengeJWT !== "string") {
-            throw new AuthClientError(res.status, JSON.stringify(data), "Challenge response missing challengeJWT.");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service challenge returned ${res.status}: ${text}`);
         }
-        const payload = decodeJwtPayload(data.challengeJWT);
+        const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+        const payload = decodeJwtPayload(challengeJWT);
         if (typeof payload.jti !== "string" ||
             typeof payload.difficulty !== "number") {
-            throw new AuthClientError(res.status, data.challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
+            throw new AuthClientError(res.status, challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
         }
         return {
-            challengeJWT: data.challengeJWT,
+            challengeJWT,
             challenge: payload.jti,
             difficulty: payload.difficulty,
         };
     }
-    async postSession(body) {
+    async postSession(challengeJWT, body) {
         const res = await fetch(`${this.baseUrl}/api/v1/session`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${challengeJWT}`,
+            },
             body: JSON.stringify(body),
         });
-        return await this.parseJsonOrThrow(res, "session");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service session returned ${res.status}: ${text}`);
+        }
+        const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+        let data = {};
+        if (text.trim().length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new AuthClientError(res.status, text, "auth-service session returned non-JSON body.");
+            }
+        }
+        return { sessionJWT, data };
     }
     async parseJsonOrThrow(res, endpoint) {
         const text = await res.text();
@@ -186,3 +199,13 @@ function decodeJwtPayload(jwt) {
         .padEnd(payloadB64Url.length + padLen, "=");
     return JSON.parse(atob(base64));
 }
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

package/esm/mcp/main.js

@@ -20,7 +20,8 @@ WORKFLOW
   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).
+  3. Call help for full documentation (JMAP cheatsheet, presets, troubleshooting);
+     topic readme returns the npm package README.
 
 CREDENTIAL DIRECTORY
   Default ~/.atomicmail/ (override ATOMIC_MAIL_CREDENTIALS_DIR). Same files as

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

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

package/esm/mcp/tools/help.js

@@ -1,22 +1,45 @@
 import { z } from "zod";
-import { getHelp, HELP_TOPIC_LIST } from "../../lib/mod.js";
+import { getHelp, HELP_TOPIC_LIST, normalizeHelpTopic, readNpmPackageReadme, } from "../../lib/mod.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(", ") + ".",
+            "troubleshooting; or the published package README when topic is readme. " +
+            "Optional topic. Topics: " +
+            HELP_TOPIC_LIST.join(", ") +
+            ", readme.",
         inputSchema: z.object({
             topic: z
                 .string()
                 .optional()
-                .describe(`Topic (e.g. ${HELP_TOPIC_LIST.slice(0, 4).join(", ")}, ...). Omit for overview.`),
+                .describe(`Topic (e.g. ${HELP_TOPIC_LIST.slice(0, 4).join(", ")}, ..., readme). Use readme for the npm package README.md. Omit for overview.`),
         }),
         annotations: {
             readOnlyHint: true,
             idempotentHint: true,
         },
-    }, ({ topic }) => ({
-        content: [{ type: "text", text: getHelp(topic) }],
-    }));
+    }, async ({ topic }) => {
+        try {
+            if (topic !== undefined && normalizeHelpTopic(topic) === "readme") {
+                const text = await readNpmPackageReadme();
+                return {
+                    content: [{ type: "text", text }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: getHelp(topic) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: error instanceof Error ? error.message : String(error),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
 }

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

@@ -1 +1 @@
-{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/jmap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAE1B,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,YAAY,GACpB,IAAI,CAmIN"}
+{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/jmap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAE1B,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,YAAY,GACpB,IAAI,CAoIN"}

package/esm/mcp/tools/jmap.js

@@ -7,8 +7,9 @@ export function registerJmapTool(server, session) {
             "Provide exactly one of: `ops` (JSON string — methodCalls array or full " +
             "envelope) or `ops_file` (preset path; relative paths resolve against " +
             "the credential directory). Tokens `$VAR_NAME` (uppercase `$FOO_BAR`) in " +
-            "either input are replaced: `$ACCOUNT_ID` and `$INBOX` come from the JMAP " +
-            "session; pass other names via `vars`.",
+            "either input are replaced: `$ACCOUNT_ID`, `$INBOX`, `$UPLOAD_URL`, and " +
+            "`$DOWNLOAD_URL` come from the JMAP session/credentials; pass other names " +
+            "via `vars`.",
         inputSchema: z.object({
             using: z
                 .array(z.string())
@@ -29,7 +30,7 @@ export function registerJmapTool(server, session) {
                 .optional()
                 .describe("Map of placeholder names (no `$`) to string values, e.g. " +
                 '{ "TO": "a@b.com", "SUBJECT": "Hi" } for `$TO` and `$SUBJECT` in ' +
-                "ops or ops_file. Overrides session values for `ACCOUNT_ID` / `INBOX` if set."),
+                "ops or ops_file. Overrides session values for `ACCOUNT_ID`, `INBOX`, `UPLOAD_URL`, or `DOWNLOAD_URL` if set."),
         }),
     }, async ({ using, ops, ops_file, vars }) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomicmail/mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Atomic Mail MCP server — local stdio proxy with PoW auth and JMAP, for AI agents.",
   "keywords": [
     "atomic-mail",