apple-mail-mcp 1.0.0

package/build/types.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Type Definitions for Apple Mail MCP Server
+ *
+ * This module contains all TypeScript interfaces and types used throughout
+ * the Apple Mail MCP server. These types model:
+ *
+ * - Apple Mail data structures (messages, mailboxes, accounts)
+ * - AppleScript execution results
+ * - MCP tool parameters
+ *
+ * @module types
+ */
+/**
+ * Represents an email message in Apple Mail.
+ */
+export interface Message {
+    /** Unique identifier for the message */
+    id: string;
+    /** Subject line of the email */
+    subject: string;
+    /** Sender email address */
+    sender: string;
+    /** Sender display name (if available) */
+    senderName?: string;
+    /** Recipients (To field) */
+    recipients: string[];
+    /** CC recipients */
+    ccRecipients?: string[];
+    /** BCC recipients (only available for sent mail) */
+    bccRecipients?: string[];
+    /** Date the message was received */
+    dateReceived: Date;
+    /** Date the message was sent */
+    dateSent?: Date;
+    /** Whether the message has been read */
+    isRead: boolean;
+    /** Whether the message is flagged */
+    isFlagged: boolean;
+    /** Whether the message is marked as junk */
+    isJunk: boolean;
+    /** Whether the message has been deleted */
+    isDeleted: boolean;
+    /** Name of the mailbox containing the message */
+    mailbox: string;
+    /** Name of the account containing the message */
+    account: string;
+    /** Whether the message has attachments */
+    hasAttachments: boolean;
+}
+/**
+ * Represents the content of an email message.
+ */
+export interface MessageContent {
+    /** Message identifier */
+    id: string;
+    /** Subject line */
+    subject: string;
+    /** Plain text content */
+    plainText: string;
+    /** HTML content (if available) */
+    htmlContent?: string;
+}
+/**
+ * Represents a mailbox (folder) in Apple Mail.
+ */
+export interface Mailbox {
+    /** Display name of the mailbox */
+    name: string;
+    /** Account containing the mailbox */
+    account: string;
+    /** Number of unread messages */
+    unreadCount: number;
+    /** Total number of messages */
+    messageCount: number;
+}
+/**
+ * Represents an email account in Apple Mail.
+ */
+export interface Account {
+    /** Display name of the account */
+    name: string;
+    /** Primary email address for the account */
+    email: string;
+    /** Account type (e.g., "iCloud", "Gmail", "Exchange") */
+    accountType?: string;
+    /** Whether the account is enabled */
+    enabled: boolean;
+}
+/**
+ * Represents an email attachment.
+ */
+export interface Attachment {
+    /** Attachment identifier */
+    id: string;
+    /** Filename of the attachment */
+    name: string;
+    /** MIME type of the attachment */
+    mimeType: string;
+    /** Size in bytes */
+    size: number;
+}
+/**
+ * Options for AppleScript execution.
+ */
+export interface AppleScriptOptions {
+    /** Maximum execution time in milliseconds */
+    timeoutMs?: number;
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds */
+    retryDelayMs?: number;
+}
+/**
+ * Result from executing an AppleScript command.
+ */
+export interface AppleScriptResult {
+    /** Whether the script executed successfully */
+    success: boolean;
+    /** Output from the script (stdout) */
+    output: string;
+    /** Error message if execution failed */
+    error?: string;
+}
+/**
+ * Parameters for searching messages.
+ */
+export interface SearchMessagesParams {
+    /** Text to search for (searches subject, sender, content) */
+    query?: string;
+    /** Filter by sender email address */
+    from?: string;
+    /** Filter by recipient email address */
+    to?: string;
+    /** Filter by subject line */
+    subject?: string;
+    /** Mailbox to search in */
+    mailbox?: string;
+    /** Account to search in */
+    account?: string;
+    /** Filter by read status */
+    isRead?: boolean;
+    /** Filter by flagged status */
+    isFlagged?: boolean;
+    /** Start date for search range */
+    dateFrom?: Date;
+    /** End date for search range */
+    dateTo?: Date;
+    /** Maximum number of results to return */
+    limit?: number;
+}
+/**
+ * Parameters for sending an email.
+ */
+export interface SendEmailParams {
+    /** Recipient email addresses (To field) */
+    to: string[];
+    /** CC recipients */
+    cc?: string[];
+    /** BCC recipients */
+    bcc?: string[];
+    /** Email subject line */
+    subject: string;
+    /** Email body content */
+    body: string;
+    /** Whether the body is HTML formatted */
+    isHtml?: boolean;
+    /** Account to send from */
+    account?: string;
+}
+/**
+ * Parameters for getting a message by ID.
+ */
+export interface GetMessageParams {
+    /** Message identifier */
+    id: string;
+}
+/**
+ * Parameters for listing messages.
+ */
+export interface ListMessagesParams {
+    /** Mailbox to list messages from */
+    mailbox?: string;
+    /** Account to list messages from */
+    account?: string;
+    /** Maximum number of messages to return */
+    limit?: number;
+    /** Filter to unread messages only */
+    unreadOnly?: boolean;
+}
+/**
+ * Parameters for mailbox operations.
+ */
+export interface MailboxParams {
+    /** Mailbox name */
+    name: string;
+    /** Account containing the mailbox */
+    account?: string;
+}
+/**
+ * Parameters for moving a message.
+ */
+export interface MoveMessageParams {
+    /** Message identifier */
+    id: string;
+    /** Destination mailbox name */
+    mailbox: string;
+    /** Account containing the destination mailbox */
+    account?: string;
+}
+/**
+ * Individual check result in a health check.
+ */
+export interface HealthCheckItem {
+    /** Name of the check */
+    name: string;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Details about the check result */
+    message: string;
+}
+/**
+ * Result of a health check operation.
+ */
+export interface HealthCheckResult {
+    /** Whether all checks passed */
+    healthy: boolean;
+    /** Individual check results */
+    checks: HealthCheckItem[];
+}
+/**
+ * Statistics for a mailbox.
+ */
+export interface MailboxStats {
+    /** Mailbox name */
+    name: string;
+    /** Total message count */
+    messageCount: number;
+    /** Unread message count */
+    unreadCount: number;
+}
+/**
+ * Statistics for an account.
+ */
+export interface AccountStats {
+    /** Account name */
+    name: string;
+    /** Total messages in account */
+    totalMessages: number;
+    /** Total unread messages */
+    unreadMessages: number;
+    /** Number of mailboxes */
+    mailboxCount: number;
+    /** Per-mailbox statistics */
+    mailboxes: MailboxStats[];
+}
+/**
+ * Recently received message counts.
+ */
+export interface RecentlyReceivedStats {
+    /** Messages received in last 24 hours */
+    last24h: number;
+    /** Messages received in last 7 days */
+    last7d: number;
+    /** Messages received in last 30 days */
+    last30d: number;
+}
+/**
+ * Overall mail statistics.
+ */
+export interface MailStats {
+    /** Total messages across all accounts */
+    totalMessages: number;
+    /** Total unread messages */
+    totalUnread: number;
+    /** Per-account statistics */
+    accounts: AccountStats[];
+    /** Recently received message counts */
+    recentlyReceived?: RecentlyReceivedStats;
+}
+/**
+ * Result of a batch operation on a single item.
+ */
+export interface BatchOperationResult {
+    /** Item identifier */
+    id: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+}
+/**
+ * Status of Mail.app sync activity.
+ */
+export interface SyncStatus {
+    /** Whether sync activity was detected */
+    syncDetected: boolean;
+    /** Number of items pending upload */
+    pendingUpload: number;
+    /** Whether there was recent database activity */
+    recentActivity: boolean;
+    /** Seconds since last database change */
+    secondsSinceLastChange: number;
+    /** Error message if status check failed */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.js

@@ -0,0 +1,13 @@
+/**
+ * Type Definitions for Apple Mail MCP Server
+ *
+ * This module contains all TypeScript interfaces and types used throughout
+ * the Apple Mail MCP server. These types model:
+ *
+ * - Apple Mail data structures (messages, mailboxes, accounts)
+ * - AppleScript execution results
+ * - MCP tool parameters
+ *
+ * @module types
+ */
+export {};

package/build/utils/applescript.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AppleScript Execution Utilities
+ *
+ * This module provides a safe interface for executing AppleScript commands
+ * on macOS. It handles script execution, error capture, and result parsing.
+ *
+ * @module utils/applescript
+ */
+import type { AppleScriptResult, AppleScriptOptions } from "../types.js";
+/**
+ * Executes an AppleScript command and returns a structured result.
+ *
+ * This function serves as the bridge between TypeScript and macOS AppleScript.
+ * It handles the complexity of shell escaping, execution, and error handling
+ * so that calling code can work with clean TypeScript interfaces.
+ *
+ * The script is executed synchronously via the `osascript` command-line tool.
+ * Multi-line scripts are supported and preserved (important for AppleScript
+ * tell blocks and repeat loops).
+ *
+ * @param script - The AppleScript code to execute
+ * @param options - Optional execution settings (timeout, etc.)
+ * @returns A result object with success status and output or error message
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default timeout (30 seconds)
+ * const result = executeAppleScript(`
+ *   tell application "Notes"
+ *     get name of every note
+ *   end tell
+ * `);
+ *
+ * // With custom timeout for complex operations
+ * const result = executeAppleScript(complexScript, { timeoutMs: 60000 });
+ *
+ * if (result.success) {
+ *   console.log("Notes:", result.output);
+ * } else {
+ *   console.error("Failed:", result.error);
+ * }
+ * ```
+ */
+export declare function executeAppleScript(script: string, options?: AppleScriptOptions): AppleScriptResult;
+//# sourceMappingURL=applescript.d.ts.map

package/build/utils/applescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applescript.d.ts","sourceRoot":"","sources":["../../src/utils/applescript.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAuOxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CA6HnB"}