read-email-mcp 1.0.0

package/dist/tools.d.ts

@@ -0,0 +1,246 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { EmailSyncService } from "./imap.js";
+import type { EmailStore } from "./store.js";
+export interface ToolResult extends CallToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+export interface EmailToolContext {
+    accountEmail: string;
+    storagePath: string;
+    store: EmailStore;
+    sync: Pick<EmailSyncService, "sync">;
+}
+export declare const toolSchemas: {
+    sync_email: z.ZodObject<{
+        mailbox: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        since: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mailbox?: string | undefined;
+        limit?: number | undefined;
+        since?: string | undefined;
+    }, {
+        mailbox?: string | undefined;
+        limit?: number | undefined;
+        since?: string | undefined;
+    }>;
+    get_sync_status: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    list_mailboxes: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    get_recent_emails: z.ZodObject<{
+        mailbox: z.ZodOptional<z.ZodString>;
+        unreadOnly: z.ZodOptional<z.ZodBoolean>;
+        flaggedOnly: z.ZodOptional<z.ZodBoolean>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mailbox?: string | undefined;
+        limit?: number | undefined;
+        unreadOnly?: boolean | undefined;
+        flaggedOnly?: boolean | undefined;
+    }, {
+        mailbox?: string | undefined;
+        limit?: number | undefined;
+        unreadOnly?: boolean | undefined;
+        flaggedOnly?: boolean | undefined;
+    }>;
+    browse_email_dates: z.ZodObject<{
+        granularity: z.ZodDefault<z.ZodEnum<["day", "week", "month"]>>;
+        mailbox: z.ZodOptional<z.ZodString>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        granularity: "day" | "week" | "month";
+        mailbox?: string | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+    }, {
+        mailbox?: string | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        granularity?: "day" | "week" | "month" | undefined;
+    }>;
+    search_emails: z.ZodObject<{
+        mailbox: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        cc: z.ZodOptional<z.ZodString>;
+        subject: z.ZodOptional<z.ZodString>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+        hasAttachments: z.ZodOptional<z.ZodBoolean>;
+        isUnread: z.ZodOptional<z.ZodBoolean>;
+        isFlagged: z.ZodOptional<z.ZodBoolean>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+        sort: z.ZodOptional<z.ZodEnum<["date_asc", "date_desc"]>>;
+    } & {
+        query: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mailbox?: string | undefined;
+        subject?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        cc?: string | undefined;
+        hasAttachments?: boolean | undefined;
+        sort?: "date_asc" | "date_desc" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        isUnread?: boolean | undefined;
+        isFlagged?: boolean | undefined;
+        limit?: number | undefined;
+        query?: string | undefined;
+        cursor?: string | undefined;
+    }, {
+        mailbox?: string | undefined;
+        subject?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        cc?: string | undefined;
+        hasAttachments?: boolean | undefined;
+        sort?: "date_asc" | "date_desc" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        isUnread?: boolean | undefined;
+        isFlagged?: boolean | undefined;
+        limit?: number | undefined;
+        query?: string | undefined;
+        cursor?: string | undefined;
+    }>;
+    list_emails: z.ZodObject<{
+        mailbox: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+        cc: z.ZodOptional<z.ZodString>;
+        subject: z.ZodOptional<z.ZodString>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+        hasAttachments: z.ZodOptional<z.ZodBoolean>;
+        isUnread: z.ZodOptional<z.ZodBoolean>;
+        isFlagged: z.ZodOptional<z.ZodBoolean>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+        sort: z.ZodOptional<z.ZodEnum<["date_asc", "date_desc"]>>;
+    }, "strip", z.ZodTypeAny, {
+        mailbox?: string | undefined;
+        subject?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        cc?: string | undefined;
+        hasAttachments?: boolean | undefined;
+        sort?: "date_asc" | "date_desc" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        isUnread?: boolean | undefined;
+        isFlagged?: boolean | undefined;
+        limit?: number | undefined;
+        cursor?: string | undefined;
+    }, {
+        mailbox?: string | undefined;
+        subject?: string | undefined;
+        from?: string | undefined;
+        to?: string | undefined;
+        cc?: string | undefined;
+        hasAttachments?: boolean | undefined;
+        sort?: "date_asc" | "date_desc" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        isUnread?: boolean | undefined;
+        isFlagged?: boolean | undefined;
+        limit?: number | undefined;
+        cursor?: string | undefined;
+    }>;
+    get_email: z.ZodEffects<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        mailbox: z.ZodOptional<z.ZodString>;
+        uid: z.ZodOptional<z.ZodNumber>;
+        messageId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }>, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }>;
+    get_thread: z.ZodEffects<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        messageId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }>, {
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }>;
+    get_raw_email: z.ZodEffects<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        mailbox: z.ZodOptional<z.ZodString>;
+        uid: z.ZodOptional<z.ZodNumber>;
+        messageId: z.ZodOptional<z.ZodString>;
+    } & {
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxBytes: number;
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+        maxBytes?: number | undefined;
+    }>, {
+        maxBytes: number;
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+    }, {
+        mailbox?: string | undefined;
+        uid?: number | undefined;
+        messageId?: string | undefined;
+        id?: number | undefined;
+        maxBytes?: number | undefined;
+    }>;
+    get_storage_stats: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    optimize_email_store: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+};
+export declare const toolDescriptions: Record<keyof typeof toolSchemas, string>;
+export declare function createToolHandlers(context: EmailToolContext): {
+    sync_email: (input: unknown) => Promise<ToolResult>;
+    get_sync_status: (input: unknown) => Promise<ToolResult>;
+    list_mailboxes: (input: unknown) => Promise<ToolResult>;
+    get_recent_emails: (input: unknown) => Promise<ToolResult>;
+    browse_email_dates: (input: unknown) => Promise<ToolResult>;
+    search_emails: (input: unknown) => Promise<ToolResult>;
+    list_emails: (input: unknown) => Promise<ToolResult>;
+    get_email: (input: unknown) => Promise<ToolResult>;
+    get_thread: (input: unknown) => Promise<ToolResult>;
+    get_raw_email: (input: unknown) => Promise<ToolResult>;
+    get_storage_stats: (input: unknown) => Promise<ToolResult>;
+    optimize_email_store: (input: unknown) => Promise<ToolResult>;
+};

package/dist/tools.js

@@ -0,0 +1,204 @@
+import { z } from "zod";
+import fs from "node:fs/promises";
+export const toolSchemas = {
+    sync_email: z.object({
+        mailbox: z.string().min(1).optional(),
+        limit: z.number().int().positive().max(1000).optional(),
+        since: z.string().datetime().optional()
+    }),
+    get_sync_status: z.object({}),
+    list_mailboxes: z.object({}),
+    get_recent_emails: z.object({
+        mailbox: z.string().min(1).optional(),
+        unreadOnly: z.boolean().optional(),
+        flaggedOnly: z.boolean().optional(),
+        limit: z.number().int().positive().max(100).optional()
+    }),
+    browse_email_dates: z.object({
+        granularity: z.enum(["day", "week", "month"]).default("day"),
+        mailbox: z.string().min(1).optional(),
+        startDate: z.string().datetime().optional(),
+        endDate: z.string().datetime().optional()
+    }),
+    search_emails: messageFilterSchema().extend({
+        query: z.string().min(1).optional()
+    }),
+    list_emails: messageFilterSchema(),
+    get_email: z
+        .object({
+        id: z.number().int().positive().optional(),
+        mailbox: z.string().min(1).optional(),
+        uid: z.number().int().positive().optional(),
+        messageId: z.string().min(1).optional()
+    })
+        .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
+        message: "Provide id, messageId, or mailbox plus uid"
+    }),
+    get_thread: z
+        .object({
+        id: z.number().int().positive().optional(),
+        messageId: z.string().min(1).optional()
+    })
+        .refine((value) => value.id || value.messageId, {
+        message: "Provide id or messageId"
+    }),
+    get_raw_email: emailLocatorBaseSchema()
+        .extend({
+        maxBytes: z.number().int().positive().max(1_000_000).default(65_536)
+    })
+        .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
+        message: "Provide id, messageId, or mailbox plus uid"
+    }),
+    get_storage_stats: z.object({}),
+    optimize_email_store: z.object({})
+};
+export const toolDescriptions = {
+    sync_email: "Pull new messages from the IMAP server into the local mirror. Call this first (or after a gap) before browsing/searching, since every other tool reads the local copy. Tip: start with a small limit on one mailbox (e.g. { mailbox: 'INBOX', limit: 10 }) to verify credentials, then sync more. Without a mailbox, syncs all selectable mailboxes. Uses read-only IMAP access and never mutates the server mailbox.",
+    get_sync_status: "Check how fresh the local mirror is: total messages, latest message date, per-mailbox counts, and the last sync result. Good first call to see whether a sync is needed and whether the previous sync succeeded.",
+    list_mailboxes: "List the mailboxes known locally (e.g. INBOX, Sent, Drafts) with message counts and last-sync time. Use this to discover mailbox names to pass to sync_email, get_recent_emails, or list_emails.",
+    get_recent_emails: "Show the latest emails, newest first. This is the everyday 'what's new in my inbox' tool. Set unreadOnly: true to see only unread messages, or flaggedOnly: true for starred messages. Returns summaries (subject, from, date, preview, attachments, read/flagged state); pass the returned id to get_email for the full body, or get_thread to see the whole conversation.",
+    browse_email_dates: "Summarize message volume over time as counts per day, week, or month. Useful for 'how much email did I get this month' or finding a busy period before drilling in with list_emails/search_emails over that date range.",
+    search_emails: "Full-text search across subject, sender/recipient addresses, preview, and body text, with the same filters as list_emails (mailbox, from, to, cc, subject, date range, attachments, unread, flagged). Use this when looking for specific content or a topic. Returns paginated summaries; use get_email on a hit for the full message.",
+    list_emails: "List email summaries in chronological order with filters (mailbox, from, to, cc, subject, date range, attachments, unread, flagged) and keyset pagination, but without full-text search. Prefer this over search_emails when browsing by sender, date, or mailbox rather than searching body text. Defaults to newest first with a page size of 25.",
+    get_email: "Return the full metadata and body (text and HTML) for a single message. Resolve it by the id returned from get_recent_emails/list_emails/search_emails, by Message-ID, or by mailbox plus UID. Use this after finding a summary you want to read in full.",
+    get_thread: "Return all locally known messages in one conversation, matched via Message-ID, In-Reply-To, and References headers. Give the id or messageId of any message in the thread. Use this to follow a discussion after get_email or when a search hit looks like part of a longer thread.",
+    get_raw_email: "Return the raw RFC822/MIME source for one message, byte-limited (default 64 KiB). Use this only when you need original headers or MIME structure not exposed by get_email, for example to inspect a specific header or attachment encoding.",
+    get_storage_stats: "Report SQLite database, WAL, and shared-memory file sizes plus page counts for the local mirror. Use this to understand disk usage after large syncs.",
+    optimize_email_store: "Run lightweight SQLite and FTS maintenance (ANALYZE/optimize) to keep queries fast. Safe to call occasionally after large syncs or before packaging a local archive."
+};
+export function createToolHandlers(context) {
+    return {
+        sync_email: async (input) => {
+            const args = toolSchemas.sync_email.parse(input);
+            const result = await context.sync.sync(args);
+            return json(result);
+        },
+        get_sync_status: async (input) => {
+            toolSchemas.get_sync_status.parse(input);
+            return json({
+                account: context.accountEmail,
+                storagePath: context.storagePath,
+                ...context.store.getSyncStatus()
+            });
+        },
+        list_mailboxes: async (input) => {
+            toolSchemas.list_mailboxes.parse(input);
+            return json({ mailboxes: context.store.listMailboxes() });
+        },
+        get_recent_emails: async (input) => {
+            const args = toolSchemas.get_recent_emails.parse(input);
+            return json(context.store.listMessages({
+                mailbox: args.mailbox,
+                isUnread: args.unreadOnly,
+                isFlagged: args.flaggedOnly,
+                limit: args.limit,
+                sort: "date_desc"
+            }));
+        },
+        browse_email_dates: async (input) => {
+            const args = toolSchemas.browse_email_dates.parse(input);
+            return json({ buckets: context.store.getDateBuckets(args) });
+        },
+        search_emails: async (input) => {
+            const args = toolSchemas.search_emails.parse(input);
+            return json(context.store.searchMessages(args));
+        },
+        list_emails: async (input) => {
+            const args = toolSchemas.list_emails.parse(input);
+            return json(context.store.listMessages(args));
+        },
+        get_email: async (input) => {
+            const args = toolSchemas.get_email.parse(input);
+            const message = findMessage(context.store, args);
+            if (!message) {
+                throw new Error("Email message not found");
+            }
+            return json({ message });
+        },
+        get_thread: async (input) => {
+            const args = toolSchemas.get_thread.parse(input);
+            return json({ items: context.store.getThread(args.id ?? args.messageId) });
+        },
+        get_raw_email: async (input) => {
+            const args = toolSchemas.get_raw_email.parse(input);
+            const message = findMessage(context.store, args);
+            if (!message) {
+                throw new Error("Email message not found");
+            }
+            const stats = await fs.stat(message.rawPath);
+            const handle = await fs.open(message.rawPath, "r");
+            try {
+                const bytesToRead = Math.min(args.maxBytes, stats.size);
+                const buffer = Buffer.alloc(bytesToRead);
+                const { bytesRead } = await handle.read(buffer, 0, bytesToRead, 0);
+                return json({
+                    id: message.id,
+                    rawPath: message.rawPath,
+                    sizeBytes: stats.size,
+                    returnedBytes: bytesRead,
+                    truncated: bytesRead < stats.size,
+                    content: buffer.subarray(0, bytesRead).toString("utf8")
+                });
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        get_storage_stats: async (input) => {
+            toolSchemas.get_storage_stats.parse(input);
+            return json(context.store.getStorageStats());
+        },
+        optimize_email_store: async (input) => {
+            toolSchemas.optimize_email_store.parse(input);
+            return json(context.store.optimize());
+        }
+    };
+}
+function emailLocatorSchema() {
+    return emailLocatorBaseSchema().refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
+        message: "Provide id, messageId, or mailbox plus uid"
+    });
+}
+function emailLocatorBaseSchema() {
+    return z.object({
+        id: z.number().int().positive().optional(),
+        mailbox: z.string().min(1).optional(),
+        uid: z.number().int().positive().optional(),
+        messageId: z.string().min(1).optional()
+    });
+}
+function messageFilterSchema() {
+    return z.object({
+        mailbox: z.string().min(1).optional(),
+        from: z.string().min(1).optional(),
+        to: z.string().min(1).optional(),
+        cc: z.string().min(1).optional(),
+        subject: z.string().min(1).optional(),
+        startDate: z.string().datetime().optional(),
+        endDate: z.string().datetime().optional(),
+        hasAttachments: z.boolean().optional(),
+        isUnread: z.boolean().optional(),
+        isFlagged: z.boolean().optional(),
+        limit: z.number().int().positive().max(100).optional(),
+        cursor: z.string().min(1).optional(),
+        sort: z.enum(["date_asc", "date_desc"]).optional()
+    });
+}
+function findMessage(store, locator) {
+    return locator.id
+        ? store.getMessageById(locator.id)
+        : locator.messageId
+            ? store.getMessageByMessageId(locator.messageId)
+            : store.getMessageByMailboxUid(locator.mailbox, locator.uid);
+}
+function json(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2)
+            }
+        ]
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+export interface EmailAddress {
+    name?: string;
+    address: string;
+}
+export interface AttachmentSummary {
+    filename?: string;
+    contentType?: string;
+    size?: number;
+    contentId?: string;
+    disposition?: string;
+}
+export interface MailboxRecord {
+    path: string;
+    delimiter: string;
+    uidValidity: string | null;
+    highestUid: number;
+    selectable: boolean;
+    lastSyncedAt?: string | null;
+    messageCount?: number;
+}
+export interface MessageInput {
+    mailbox: string;
+    uid: number;
+    uidValidity: string;
+    messageId: string | null;
+    inReplyTo: string | null;
+    references: string[];
+    subject: string | null;
+    date: string;
+    internalDate: string | null;
+    from: EmailAddress[];
+    to: EmailAddress[];
+    cc: EmailAddress[];
+    bcc: EmailAddress[];
+    flags: string[];
+    size: number | null;
+    hasAttachments: boolean;
+    attachmentCount: number;
+    preview: string | null;
+    text: string | null;
+    html: string | null;
+    headers: Record<string, string | string[]>;
+    attachments: AttachmentSummary[];
+    rawPath: string;
+    parseError: string | null;
+}
+export interface StoredMessage extends MessageInput {
+    id: number;
+}
+export interface MessageSummary {
+    id: number;
+    mailbox: string;
+    uid: number;
+    messageId: string | null;
+    date: string;
+    from: EmailAddress[];
+    to: EmailAddress[];
+    cc: EmailAddress[];
+    subject: string | null;
+    preview: string | null;
+    flags: string[];
+    hasAttachments: boolean;
+    attachmentCount: number;
+}
+export interface MessageFilters {
+    query?: string;
+    mailbox?: string;
+    from?: string;
+    to?: string;
+    cc?: string;
+    subject?: string;
+    startDate?: string;
+    endDate?: string;
+    hasAttachments?: boolean;
+    isUnread?: boolean;
+    isFlagged?: boolean;
+    limit?: number;
+    cursor?: string;
+    sort?: "date_asc" | "date_desc";
+}
+export interface PaginatedMessages {
+    items: MessageSummary[];
+    nextCursor?: string;
+}
+export interface DateBucketOptions {
+    granularity: "day" | "week" | "month";
+    mailbox?: string;
+    startDate?: string;
+    endDate?: string;
+}
+export interface DateBucket {
+    bucket: string;
+    count: number;
+}
+export interface SyncResultRecord {
+    ok: boolean;
+    mailbox: string | null;
+    startedAt: string;
+    finishedAt: string;
+    message: string;
+    syncedMessages: number;
+}
+export interface SyncStatus {
+    totalMessages: number;
+    latestMessageDate: string | null;
+    mailboxes: MailboxRecord[];
+    lastSync: SyncResultRecord | null;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/production-readiness.md

@@ -0,0 +1,70 @@
+# Production Readiness
+
+Use this page as the handoff checklist for running the Read Email MCP server with a real mailbox.
+
+## Current Status
+
+- The server uses the official MCP TypeScript SDK over stdio.
+- IMAP settings are provider-configurable via `IMAP_HOST` (required), `IMAP_PORT` (default 993), `IMAP_SECURE` (default true), and `IMAP_USER` (defaults to the email address), or the matching `--imap-*` CLI args.
+- Setup requires `EMAIL`, `PASSWORD`, and `IMAP_HOST`.
+- Browse and search tools read from a local SQLite mirror, not directly from IMAP.
+- Sync is read-only and uses read-only mailbox locks.
+- SQLite runs with WAL mode, a busy timeout, keyset pagination, and lightweight optimization.
+- Raw RFC822 messages are stored locally for reparse and inspection.
+
+## Local Verification
+
+Run:
+
+```powershell
+npm run verify
+```
+
+That command runs:
+
+- `npm test`
+- `npm run typecheck`
+- `npm run build`
+- `npm run smoke:mcp`
+
+The smoke check starts the built MCP server over stdio with dummy credentials and verifies the registered tools. It proves the server starts and speaks MCP, but it does not prove live authentication.
+
+## Live Mailbox Check
+
+After adding real credentials to the MCP host, run a small sync first:
+
+```json
+{
+  "mailbox": "INBOX",
+  "limit": 10
+}
+```
+
+Then inspect:
+
+- `get_sync_status`
+- `list_mailboxes`
+- `get_recent_emails`
+- `browse_email_dates`
+- `search_emails`
+- `get_email`
+
+Once those look correct, run a larger sync or sync all mailboxes.
+
+## Operational Notes
+
+- The local mirror is stored under `~/.read-email-mcp/<account-hash>/`.
+- Passwords are read from the process environment and are not stored by this server.
+- Raw `.eml` files contain full email content. Keep the storage directory private and backed up according to your own retention rules.
+- The server does not schedule background syncs. Sync runs when the MCP client calls `sync_email`.
+- Use `get_storage_stats` to inspect database size and WAL state.
+- Use `optimize_email_store` after large syncs or before packaging a local archive.
+
+## Not Included
+
+- Sending email
+- Deleting, moving, archiving, flagging, or marking messages read
+- OAuth
+- Background daemon scheduling
+- Attachment byte extraction
+- Web UI