@diskd-ai/email-client-mcp 0.1.0

package/dist/tools/listEmails.js

@@ -0,0 +1,101 @@
+/**
+ * MCP tool: list_emails -- paginated metadata listing of a mailbox.
+ *
+ * Live-IMAP. Combines IMAP UID SEARCH (with optional filters) and
+ * envelope-only FETCH for matched UIDs. Pagination is offset-based:
+ * the first call returns the highest-UID page, subsequent calls pass
+ * the previous page's `nextCursor` (a UID).
+ */
+import { z } from "zod";
+import { imapError, notFound } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { fetchEnvelopesUidRange, withMailboxLock } from "../imap/fetch.js";
+export const listEmailsInput = z
+    .object({
+    account: z.string().min(1),
+    mailbox: z.string().min(1),
+    pageSize: z.number().int().min(1).max(200).default(50),
+    cursor: z.number().int().nonnegative().nullable().optional(),
+    unread: z.boolean().optional(),
+    flagged: z.boolean().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+    subject: z.string().optional(),
+    since: z.string().datetime().optional(),
+})
+    .strict();
+export const listEmails = async (pool, input) => {
+    if (!pool.accountIds.includes(input.account))
+        return Err(notFound(`account '${input.account}'`));
+    const clientR = await pool.forAccount(input.account);
+    if (clientR.tag === "Err")
+        return clientR;
+    const client = clientR.value;
+    try {
+        return await withMailboxLock(client, input.mailbox, async () => {
+            const query = {
+                ...(input.unread === true ? { unseen: true } : {}),
+                ...(input.unread === false ? { seen: true } : {}),
+                ...(input.flagged === true ? { flagged: true } : {}),
+                ...(input.from ? { from: input.from } : {}),
+                ...(input.to ? { to: input.to } : {}),
+                ...(input.subject ? { subject: input.subject } : {}),
+                ...(input.since ? { since: new Date(input.since) } : {}),
+            };
+            const allUidsResult = await client.search(query, {
+                uid: true,
+            });
+            const allUids = Array.isArray(allUidsResult)
+                ? allUidsResult.slice().sort((a, b) => b - a)
+                : [];
+            const cursor = input.cursor ?? null;
+            const startIdx = cursor === null ? 0 : allUids.findIndex((u) => u < cursor);
+            const safeStart = startIdx === -1 ? allUids.length : startIdx;
+            const pageUids = allUids.slice(safeStart, safeStart + input.pageSize);
+            const nextCursor = safeStart + input.pageSize < allUids.length
+                ? (pageUids[pageUids.length - 1] ?? null)
+                : null;
+            if (pageUids.length === 0) {
+                return Ok({ account: input.account, mailbox: input.mailbox, items: [], nextCursor });
+            }
+            const minUid = Math.min(...pageUids);
+            const maxUid = Math.max(...pageUids);
+            const wanted = new Set(pageUids);
+            const items = [];
+            for await (const env of fetchEnvelopesUidRange(client, minUid, maxUid)) {
+                if (!wanted.has(env.uid))
+                    continue;
+                const e = env.envelope ?? {};
+                items.push({
+                    uid: env.uid,
+                    messageId: e.messageId ?? null,
+                    subject: e.subject ?? "",
+                    from: e.from && e.from.length > 0 && e.from[0]
+                        ? {
+                            name: e.from[0].name && e.from[0].name.length > 0 ? e.from[0].name : null,
+                            address: e.from[0].address ?? "",
+                        }
+                        : null,
+                    to: (e.to ?? []).map((a) => ({
+                        name: a.name && a.name.length > 0 ? a.name : null,
+                        address: a.address ?? "",
+                    })),
+                    date: e.date instanceof Date
+                        ? e.date.toISOString()
+                        : typeof e.date === "string"
+                            ? new Date(e.date).toISOString()
+                            : "",
+                    flags: env.flags instanceof Set ? Array.from(env.flags) : [...(env.flags ?? [])],
+                    hasAttachments: false,
+                });
+            }
+            // Sort by UID descending to match the cursor walk.
+            items.sort((a, b) => b.uid - a.uid);
+            return Ok({ account: input.account, mailbox: input.mailbox, items, nextCursor });
+        });
+    }
+    catch (cause) {
+        return Err(imapError(input.account, "list_emails failed", cause));
+    }
+};
+//# sourceMappingURL=listEmails.js.map

package/dist/tools/listEmails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listEmails.js","sourceRoot":"","sources":["../../src/tools/listEmails.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAiB,SAAS,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG3E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5D,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC;KACD,MAAM,EAAE,CAAC;AAqBZ,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,IAAc,EACd,KAAsB,EACuB,EAAE;IAC/C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACjG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YAE7D,MAAM,KAAK,GAAiB;gBAC1B,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClD,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD,CAAC;YAEF,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAA2C,EAAE;gBACrF,GAAG,EAAE,IAAI;aACV,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;gBAC1C,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC7C,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC;YACpC,MAAM,QAAQ,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;YAC5E,MAAM,SAAS,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;YACtE,MAAM,UAAU,GACd,SAAS,GAAG,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC,MAAM;gBACzC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;gBACzC,CAAC,CAAC,IAAI,CAAC;YAEX,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;YACvF,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;YACjC,MAAM,KAAK,GAAkB,EAAE,CAAC;YAChC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;gBACvE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACnC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC;oBACT,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI;oBAC9B,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE;oBACxB,IAAI,EACF,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;wBACtC,CAAC,CAAC;4BACE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;4BACzE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE;yBACjC;wBACH,CAAC,CAAC,IAAI;oBACV,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC3B,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;wBACjD,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE;qBACzB,CAAC,CAAC;oBACH,IAAI,EACF,CAAC,CAAC,IAAI,YAAY,IAAI;wBACpB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE;wBACtB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;4BAC1B,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;4BAChC,CAAC,CAAC,EAAE;oBACV,KAAK,EAAE,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;oBAChF,cAAc,EAAE,KAAK;iBACtB,CAAC,CAAC;YACL,CAAC;YACD,mDAAmD;YACnD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACpC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACnF,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;AACH,CAAC,CAAC"}

package/dist/tools/listMailboxFolder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP tool: list_mailbox_folder -- IMAP folder list per account with
+ * unread counts and special-use flags. Live-IMAP read.
+ */
+import { z } from "zod";
+import { type AppError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import type { ImapPool } from "../imap/pool.js";
+export declare const listMailboxFolderInput: z.ZodObject<{
+    account: z.ZodString;
+    includeUnreadCount: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    account: string;
+    includeUnreadCount: boolean;
+}, {
+    account: string;
+    includeUnreadCount?: boolean | undefined;
+}>;
+export type ListMailboxFolderInput = z.infer<typeof listMailboxFolderInput>;
+export type ListedFolder = {
+    readonly path: string;
+    readonly name: string;
+    readonly delimiter: string;
+    readonly specialUse: string | null;
+    readonly subscribed: boolean;
+    readonly virtual: boolean;
+    readonly unreadCount: number | null;
+};
+export type ListMailboxFolderResult = {
+    readonly account: string;
+    readonly folders: readonly ListedFolder[];
+};
+export declare const listMailboxFolder: (pool: ImapPool, input: ListMailboxFolderInput) => Promise<Result<AppError, ListMailboxFolderResult>>;

package/dist/tools/listMailboxFolder.js

@@ -0,0 +1,60 @@
+/**
+ * MCP tool: list_mailbox_folder -- IMAP folder list per account with
+ * unread counts and special-use flags. Live-IMAP read.
+ */
+import { z } from "zod";
+import { errorMessage, imapError, notFound } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { withMailboxLock } from "../imap/fetch.js";
+import { isVirtualFolderPath, isVirtualSpecialUse } from "../imap/virtualFolders.js";
+export const listMailboxFolderInput = z
+    .object({
+    account: z.string().min(1),
+    includeUnreadCount: z.boolean().default(false),
+})
+    .strict();
+export const listMailboxFolder = async (pool, input) => {
+    if (!pool.accountIds.includes(input.account)) {
+        return Err(notFound(`account '${input.account}'`));
+    }
+    const clientR = await pool.forAccount(input.account);
+    if (clientR.tag === "Err")
+        return clientR;
+    const client = clientR.value;
+    try {
+        const folders = await client.list();
+        const out = [];
+        for (const f of folders) {
+            const specialUse = (f.specialUse ?? null);
+            const virtual = isVirtualFolderPath(f.path) || isVirtualSpecialUse(specialUse);
+            let unreadCount = null;
+            if (input.includeUnreadCount && !virtual) {
+                try {
+                    const status = await client.status(f.path, { unseen: true });
+                    unreadCount = Number(status.unseen ?? 0);
+                }
+                catch {
+                    unreadCount = null;
+                }
+            }
+            out.push({
+                path: f.path,
+                name: f.name,
+                delimiter: f.delimiter ?? "/",
+                specialUse,
+                subscribed: f.subscribed ?? false,
+                virtual,
+                unreadCount,
+            });
+        }
+        return Ok({ account: input.account, folders: out });
+    }
+    catch (cause) {
+        return Err(imapError(input.account, errorMessage({ kind: "ImapError", accountId: input.account, message: "list" }), cause));
+    }
+    finally {
+        // Note: client.list() does not require a per-mailbox lock.
+        void withMailboxLock; // silence unused import marker if list doesn't need lock
+    }
+};
+//# sourceMappingURL=listMailboxFolder.js.map

package/dist/tools/listMailboxFolder.js.map

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

package/dist/tools/moveEmail.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP tool: move_email -- IMAP MOVE one message between folders.
+ *
+ * Refuses virtual mailboxes as the source (Gmail "[Gmail]/All Mail",
+ * Starred, etc.) -- callers should use `find_mailbox_folder` first to
+ * resolve the real folder.
+ */
+import { z } from "zod";
+import { type AppError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import type { ImapPool } from "../imap/pool.js";
+export declare const moveEmailInput: z.ZodObject<{
+    account: z.ZodString;
+    sourceMailbox: z.ZodString;
+    targetMailbox: z.ZodString;
+    uid: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    uid: number;
+    account: string;
+    sourceMailbox: string;
+    targetMailbox: string;
+}, {
+    uid: number;
+    account: string;
+    sourceMailbox: string;
+    targetMailbox: string;
+}>;
+export type MoveEmailInput = z.infer<typeof moveEmailInput>;
+export type MoveEmailResult = {
+    readonly account: string;
+    readonly sourceMailbox: string;
+    readonly targetMailbox: string;
+    readonly uid: number;
+    readonly newUid: number | null;
+};
+export declare const moveEmail: (pool: ImapPool, input: MoveEmailInput) => Promise<Result<AppError, MoveEmailResult>>;

package/dist/tools/moveEmail.js

@@ -0,0 +1,52 @@
+/**
+ * MCP tool: move_email -- IMAP MOVE one message between folders.
+ *
+ * Refuses virtual mailboxes as the source (Gmail "[Gmail]/All Mail",
+ * Starred, etc.) -- callers should use `find_mailbox_folder` first to
+ * resolve the real folder.
+ */
+import { z } from "zod";
+import { imapError, notFound, virtualFolderRefused } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { withMailboxLock } from "../imap/fetch.js";
+import { isVirtualFolderPath } from "../imap/virtualFolders.js";
+export const moveEmailInput = z
+    .object({
+    account: z.string().min(1),
+    sourceMailbox: z.string().min(1),
+    targetMailbox: z.string().min(1),
+    uid: z.number().int().positive(),
+})
+    .strict();
+export const moveEmail = async (pool, input) => {
+    if (!pool.accountIds.includes(input.account))
+        return Err(notFound(`account '${input.account}'`));
+    if (isVirtualFolderPath(input.sourceMailbox)) {
+        return Err(virtualFolderRefused(input.sourceMailbox));
+    }
+    const clientR = await pool.forAccount(input.account);
+    if (clientR.tag === "Err")
+        return clientR;
+    const client = clientR.value;
+    try {
+        return await withMailboxLock(client, input.sourceMailbox, async () => {
+            const result = await client.messageMove([input.uid], input.targetMailbox, { uid: true });
+            if (result === false) {
+                return Err(imapError(input.account, "IMAP MOVE returned false (server refused)"));
+            }
+            const uidMap = result.uidMap;
+            const newUid = uidMap?.get(input.uid) ?? null;
+            return Ok({
+                account: input.account,
+                sourceMailbox: input.sourceMailbox,
+                targetMailbox: input.targetMailbox,
+                uid: input.uid,
+                newUid,
+            });
+        });
+    }
+    catch (cause) {
+        return Err(imapError(input.account, "move_email failed", cause));
+    }
+};
+//# sourceMappingURL=moveEmail.js.map

package/dist/tools/moveEmail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveEmail.js","sourceRoot":"","sources":["../../src/tools/moveEmail.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAiB,SAAS,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,MAAM,EAAE,CAAC;AAWZ,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,IAAc,EACd,KAAqB,EACuB,EAAE;IAC9C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACjG,IAAI,mBAAmB,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAC7C,OAAO,GAAG,CAAC,oBAAoB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;YACnE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YACzF,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACrB,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,2CAA2C,CAAC,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAyC,CAAC;YAChE,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;YAC9C,OAAO,EAAE,CAAC;gBACR,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;AACH,CAAC,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bind tool implementations to the MCP server using the modern
+ * `registerTool(name, config, cb)` API. Each handler returns
+ * `{content:[{type:'text', text}]}` (success) or `{isError:true, ...}`
+ * (typed AppError). Stringified JSON keeps the transport simple for
+ * any client; agents parse it.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Account } from "../config/schema.js";
+import type { ImapPool } from "../imap/pool.js";
+import type { Watcher } from "../sync/watcher.js";
+export type ToolDeps = {
+    readonly accounts: readonly Account[];
+    readonly imapPool: ImapPool;
+    readonly watcher: Watcher;
+};
+export declare const registerTools: (server: McpServer, deps: ToolDeps) => void;

package/dist/tools/registry.js

@@ -0,0 +1,64 @@
+/**
+ * Bind tool implementations to the MCP server using the modern
+ * `registerTool(name, config, cb)` API. Each handler returns
+ * `{content:[{type:'text', text}]}` (success) or `{isError:true, ...}`
+ * (typed AppError). Stringified JSON keeps the transport simple for
+ * any client; agents parse it.
+ */
+import { errorMessage } from "../domain/errors.js";
+import { bulkAction, bulkActionInput } from "./bulkAction.js";
+import { findMailboxFolder, findMailboxFolderInput } from "./findMailboxFolder.js";
+import { getEmail, getEmailInput } from "./getEmail.js";
+import { getEmails, getEmailsInput } from "./getEmails.js";
+import { getWatcherStatus, getWatcherStatusInput } from "./getWatcherStatus.js";
+import { listAccounts, listAccountsInput } from "./listAccounts.js";
+import { listEmails, listEmailsInput } from "./listEmails.js";
+import { listMailboxFolder, listMailboxFolderInput } from "./listMailboxFolder.js";
+import { moveEmail, moveEmailInput } from "./moveEmail.js";
+const ok = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+});
+const err = (e) => ({
+    content: [{ type: "text", text: errorMessage(e) }],
+    isError: true,
+});
+const fromResult = (r) => r.tag === "Ok" ? ok(r.value) : err(r.error);
+export const registerTools = (server, deps) => {
+    server.registerTool("list_accounts", {
+        description: "List all configured email accounts. Call this first to discover available account names for use with other tools.",
+        inputSchema: listAccountsInput.shape,
+    }, async () => ok(listAccounts(deps.accounts)));
+    server.registerTool("list_mailbox_folder", {
+        description: "List all mailbox folders for an account with unread counts and special-use flags. Use list_accounts first to get the account name.",
+        inputSchema: listMailboxFolderInput.shape,
+    }, async (args) => fromResult(await listMailboxFolder(deps.imapPool, args)));
+    server.registerTool("find_mailbox_folder", {
+        description: "Find which real mailbox folder(s) an email belongs to. Required before move_email or delete_email when the email was found in a virtual folder (e.g., 'All Mail', 'Starred').",
+        inputSchema: findMailboxFolderInput.shape,
+    }, async (args) => fromResult(await findMailboxFolder(deps.imapPool, args)));
+    server.registerTool("list_emails", {
+        description: "List emails in a mailbox with optional filters. Returns paginated metadata (read/unread, flagged, attachments, labels). Use get_email for full body content.",
+        inputSchema: listEmailsInput.shape,
+    }, async (args) => fromResult(await listEmails(deps.imapPool, args)));
+    server.registerTool("get_email", {
+        description: "Get the full content of a specific email by UID. Does NOT mark it seen (BODY.PEEK). format=text strips HTML, format=stripped also drops quoted replies and signatures. Set markRead=true to flip \\Seen.",
+        inputSchema: getEmailInput.shape,
+    }, async (args) => fromResult(await getEmail(deps.imapPool, args)));
+    server.registerTool("get_emails", {
+        description: "Fetch multiple emails in one call (max 20). More efficient than repeated get_email when triaging. Defaults to format=text. Does NOT mark seen.",
+        inputSchema: getEmailsInput.shape,
+    }, async (args) => fromResult(await getEmails(deps.imapPool, args)));
+    server.registerTool("move_email", {
+        description: "Move an email to a different mailbox folder. sourceMailbox must be a real folder (not 'All Mail'). Use find_mailbox_folder if the email was discovered in a virtual folder.",
+        inputSchema: moveEmailInput.shape,
+    }, async (args) => fromResult(await moveEmail(deps.imapPool, args)));
+    server.registerTool("bulk_action", {
+        description: "Batch operation on multiple emails by UID list. Supports mark_read, mark_unread, flag, unflag, move, delete. Max 100 UIDs.",
+        inputSchema: bulkActionInput.shape,
+    }, async (args) => fromResult(await bulkAction(deps.imapPool, args)));
+    server.registerTool("get_watcher_status", {
+        description: "Status of the IMAP-to-Drive sync watcher: per-account/per-folder progress, last tick error, current sync state.",
+        inputSchema: getWatcherStatusInput.shape,
+    }, async () => ok(getWatcherStatus(deps.watcher)));
+};
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@diskd-ai/email-client-mcp",
+  "version": "0.1.0",
+  "description": "Drive-backed multi-account email MCP with reliable IMAP-to-mailboxes sync.",
+  "license": "LGPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "email-client-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/server.js stdio",
+    "dev": "tsx src/server.ts stdio",
+    "prepublishOnly": "bun run build && bun run test"
+  },
+  "dependencies": {
+    "@diskd/sdk": "5.1.2",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "imapflow": "^1.2.9",
+    "smol-toml": "^1.6.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.7",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5"
+  }
+}