read-no-evil-mcp 0.2.0__py3-none-any.whl

read_no_evil_mcp/email/connectors/base.py

@@ -0,0 +1,148 @@
+"""Abstract base class for email connectors."""
+
+from abc import ABC, abstractmethod
+from datetime import date, timedelta
+from types import TracebackType
+
+from read_no_evil_mcp.models import Email, EmailSummary, Folder
+
+
+class BaseConnector(ABC):
+    """Abstract base class defining the interface for email connectors."""
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish connection to the email server."""
+        ...
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close connection to the email server."""
+        ...
+
+    @abstractmethod
+    def list_folders(self) -> list[Folder]:
+        """List all available folders/mailboxes.
+
+        Returns:
+            List of Folder objects representing available mailboxes.
+        """
+        ...
+
+    @abstractmethod
+    def fetch_emails(
+        self,
+        folder: str = "INBOX",
+        *,
+        lookback: timedelta,
+        from_date: date | None = None,
+        limit: int | None = None,
+    ) -> list[EmailSummary]:
+        """Fetch email summaries from a folder within a time range.
+
+        Args:
+            folder: Folder/mailbox to fetch from (default: INBOX)
+            lookback: How far back to look from from_date
+            from_date: Starting point for lookback (default: today)
+            limit: Maximum number of emails to return
+
+        Returns:
+            List of EmailSummary objects, newest first.
+        """
+        ...
+
+    @abstractmethod
+    def get_email(self, folder: str, uid: int) -> Email | None:
+        """Fetch full email content by UID.
+
+        Args:
+            folder: Folder/mailbox containing the email
+            uid: Unique identifier of the email
+
+        Returns:
+            Full Email object or None if not found.
+        """
+        ...
+
+    @abstractmethod
+    def move_email(self, folder: str, uid: int, target_folder: str) -> bool:
+        """Move an email to a target folder.
+
+        Args:
+            folder: Folder/mailbox containing the email
+            uid: Unique identifier of the email
+            target_folder: Destination folder to move the email to
+
+        Returns:
+            True if successful, False if email not found.
+        """
+        ...
+
+    @abstractmethod
+    def delete_email(self, folder: str, uid: int) -> bool:
+        """Delete an email by UID.
+
+        Args:
+            folder: Folder/mailbox containing the email
+            uid: Unique identifier of the email
+
+        Returns:
+            True if email was deleted successfully, False otherwise.
+        """
+        ...
+
+    def can_send(self) -> bool:
+        """Check if this connector supports sending emails.
+
+        Override this method to return True in connectors that support sending.
+
+        Returns:
+            True if send() is supported, False otherwise.
+        """
+        return False
+
+    def send(
+        self,
+        from_address: str,
+        to: list[str],
+        subject: str,
+        body: str,
+        from_name: str | None = None,
+        cc: list[str] | None = None,
+        reply_to: str | None = None,
+    ) -> bool:
+        """Send an email (optional capability).
+
+        This is an optional method. Connectors that support sending emails
+        should override this method and can_send() to return True.
+
+        Args:
+            from_address: Sender email address (e.g., "user@example.com").
+            to: List of recipient email addresses.
+            subject: Email subject line.
+            body: Email body text (plain text).
+            from_name: Optional display name for sender (e.g., "Atlas").
+            cc: Optional list of CC recipients.
+            reply_to: Optional Reply-To email address.
+
+        Returns:
+            True if email was sent successfully.
+
+        Raises:
+            NotImplementedError: If the connector doesn't support sending.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support sending emails")
+
+    def __enter__(self) -> "BaseConnector":
+        """Context manager entry - connect to server."""
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Context manager exit - disconnect from server."""
+        self.disconnect()

read_no_evil_mcp/email/connectors/imap.py

@@ -0,0 +1,288 @@
+"""IMAP connector for reading emails using imap-tools."""
+
+from datetime import date, timedelta
+
+from imap_tools import AND, MailBox, MailBoxUnencrypted
+from imap_tools import EmailAddress as IMAPEmailAddress
+
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.email.connectors.smtp import SMTPConnector
+from read_no_evil_mcp.models import (
+    Attachment,
+    Email,
+    EmailAddress,
+    EmailSummary,
+    Folder,
+    IMAPConfig,
+    SMTPConfig,
+)
+
+# Default sender for emails without from address
+_DEFAULT_SENDER = EmailAddress(address="unknown@unknown")
+
+
+def _convert_address(addr: IMAPEmailAddress | None) -> EmailAddress:
+    """Convert imap-tools EmailAddress to our EmailAddress model."""
+    if addr is None or not addr.email:
+        return _DEFAULT_SENDER
+    return EmailAddress(name=addr.name or None, address=addr.email)
+
+
+def _convert_addresses(addrs: tuple[IMAPEmailAddress, ...]) -> list[EmailAddress]:
+    """Convert tuple of imap-tools EmailAddress to list of our EmailAddress model."""
+    return [
+        EmailAddress(name=addr.name or None, address=addr.email) for addr in addrs if addr.email
+    ]
+
+
+class IMAPConnector(BaseConnector):
+    """Connector for reading emails via IMAP using imap-tools.
+
+    Optionally supports sending emails via SMTP when smtp_config is provided.
+    """
+
+    def __init__(
+        self,
+        config: IMAPConfig,
+        smtp_config: SMTPConfig | None = None,
+    ) -> None:
+        """Initialize IMAP connector.
+
+        Args:
+            config: IMAP server configuration.
+            smtp_config: Optional SMTP configuration for sending emails.
+        """
+        self.config = config
+        self._mailbox: MailBox | MailBoxUnencrypted | None = None
+        self._smtp_config = smtp_config
+        self._smtp_connector: SMTPConnector | None = None
+
+    def connect(self) -> None:
+        """Establish connection to IMAP server (and SMTP if configured)."""
+        if self.config.ssl:
+            mailbox: MailBox | MailBoxUnencrypted = MailBox(self.config.host, self.config.port)
+        else:
+            mailbox = MailBoxUnencrypted(self.config.host, self.config.port)
+
+        mailbox.login(
+            self.config.username,
+            self.config.password.get_secret_value(),
+        )
+        self._mailbox = mailbox
+
+        # Connect to SMTP if configured
+        if self._smtp_config:
+            self._smtp_connector = SMTPConnector(self._smtp_config)
+            self._smtp_connector.connect()
+
+    def disconnect(self) -> None:
+        """Close connection to IMAP server (and SMTP if connected)."""
+        if self._mailbox:
+            self._mailbox.logout()
+            self._mailbox = None
+
+        if self._smtp_connector:
+            self._smtp_connector.disconnect()
+            self._smtp_connector = None
+
+    def list_folders(self) -> list[Folder]:
+        """List all folders/mailboxes."""
+        if not self._mailbox:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        folders = []
+        for folder_info in self._mailbox.folder.list():
+            folders.append(
+                Folder(
+                    name=folder_info.name,
+                    delimiter=folder_info.delim,
+                    flags=list(folder_info.flags),
+                )
+            )
+        return folders
+
+    def fetch_emails(
+        self,
+        folder: str = "INBOX",
+        *,
+        lookback: timedelta,
+        from_date: date | None = None,
+        limit: int | None = None,
+    ) -> list[EmailSummary]:
+        """Fetch email summaries from a folder within a time range.
+
+        Args:
+            folder: IMAP folder to fetch from (default: INBOX)
+            lookback: Required. How far back to look (e.g., timedelta(days=7))
+            from_date: Starting point for lookback (default: today)
+            limit: Optional max number of emails to return
+
+        Returns:
+            List of EmailSummary, newest first
+        """
+        if not self._mailbox:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        self._mailbox.folder.set(folder)
+
+        # Calculate date range
+        end_date = from_date or date.today()
+        start_date = end_date - lookback
+
+        # Build IMAP criteria - filter happens server-side
+        criteria = AND(date_gte=start_date, date_lt=end_date + timedelta(days=1))
+
+        summaries = []
+        for msg in self._mailbox.fetch(criteria, reverse=True, bulk=True):
+            sender = _convert_address(msg.from_values)
+
+            summaries.append(
+                EmailSummary(
+                    uid=int(msg.uid) if msg.uid else 0,
+                    folder=folder,
+                    subject=msg.subject or "(no subject)",
+                    sender=sender,
+                    date=msg.date,
+                    has_attachments=len(msg.attachments) > 0,
+                )
+            )
+
+            if limit and len(summaries) >= limit:
+                break
+
+        return summaries
+
+    def get_email(self, folder: str, uid: int) -> Email | None:
+        """Fetch full email content by UID."""
+        if not self._mailbox:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        self._mailbox.folder.set(folder)
+
+        for msg in self._mailbox.fetch(AND(uid=str(uid))):
+            sender = _convert_address(msg.from_values)
+
+            attachments = [
+                Attachment(
+                    filename=att.filename or "unnamed",
+                    content_type=att.content_type or "application/octet-stream",
+                    size=att.size,
+                )
+                for att in msg.attachments
+            ]
+
+            return Email(
+                uid=int(msg.uid) if msg.uid else 0,
+                folder=folder,
+                subject=msg.subject or "(no subject)",
+                sender=sender,
+                date=msg.date,
+                has_attachments=len(attachments) > 0,
+                to=_convert_addresses(msg.to_values),
+                cc=_convert_addresses(msg.cc_values),
+                body_plain=msg.text or None,
+                body_html=msg.html or None,
+                attachments=attachments,
+                message_id=msg.headers.get("message-id", [None])[0],
+            )
+
+        return None
+
+    def move_email(self, folder: str, uid: int, target_folder: str) -> bool:
+        """Move an email to a target folder.
+
+        Args:
+            folder: Folder/mailbox containing the email
+            uid: Unique identifier of the email
+            target_folder: Destination folder to move the email to
+
+        Returns:
+            True if successful, False if email not found.
+        """
+        if not self._mailbox:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        self._mailbox.folder.set(folder)
+
+        # Check if email exists
+        emails = list(self._mailbox.fetch(AND(uid=str(uid))))
+        if not emails:
+            return False
+
+        # Move email to target folder
+        self._mailbox.move(str(uid), target_folder)
+        return True
+
+    def delete_email(self, folder: str, uid: int) -> bool:
+        """Delete an email by UID.
+
+        Args:
+            folder: IMAP folder containing the email
+            uid: Unique identifier of the email
+
+        Returns:
+            True if email was deleted successfully, False otherwise.
+        """
+        if not self._mailbox:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        self._mailbox.folder.set(folder)
+
+        # Use imap-tools delete method to mark email as deleted
+        self._mailbox.delete(str(uid))
+
+        return True
+
+    def can_send(self) -> bool:
+        """Check if this connector supports sending emails.
+
+        Returns:
+            True if SMTP is configured, False otherwise.
+        """
+        return self._smtp_config is not None
+
+    def send(
+        self,
+        from_address: str,
+        to: list[str],
+        subject: str,
+        body: str,
+        from_name: str | None = None,
+        cc: list[str] | None = None,
+        reply_to: str | None = None,
+    ) -> bool:
+        """Send an email via SMTP.
+
+        Args:
+            from_address: Sender email address (e.g., "user@example.com").
+            to: List of recipient email addresses.
+            subject: Email subject line.
+            body: Email body text (plain text).
+            from_name: Optional display name for sender (e.g., "Atlas").
+            cc: Optional list of CC recipients.
+            reply_to: Optional Reply-To email address.
+
+        Returns:
+            True if email was sent successfully.
+
+        Raises:
+            NotImplementedError: If SMTP is not configured.
+            RuntimeError: If not connected.
+        """
+        if not self._smtp_config:
+            raise NotImplementedError(
+                "IMAPConnector does not support sending emails without SMTP configuration"
+            )
+
+        if not self._smtp_connector:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        return self._smtp_connector.send_email(
+            from_address=from_address,
+            to=to,
+            subject=subject,
+            body=body,
+            from_name=from_name,
+            cc=cc,
+            reply_to=reply_to,
+        )

read_no_evil_mcp/email/connectors/smtp.py

@@ -0,0 +1,110 @@
+"""SMTP connector for sending emails using smtplib."""
+
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+from read_no_evil_mcp.models import SMTPConfig
+
+
+class SMTPConnector:
+    """Connector for sending emails via SMTP using smtplib."""
+
+    def __init__(self, config: SMTPConfig) -> None:
+        """Initialize SMTP connector.
+
+        Args:
+            config: SMTP server configuration.
+        """
+        self.config = config
+        self._connection: smtplib.SMTP | smtplib.SMTP_SSL | None = None
+
+    def connect(self) -> None:
+        """Establish connection to SMTP server."""
+        if self.config.ssl:
+            self._connection = smtplib.SMTP_SSL(self.config.host, self.config.port)
+        else:
+            self._connection = smtplib.SMTP(self.config.host, self.config.port)
+            self._connection.starttls()
+
+        self._connection.login(
+            self.config.username,
+            self.config.password.get_secret_value(),
+        )
+
+    def disconnect(self) -> None:
+        """Close connection to SMTP server."""
+        if self._connection:
+            self._connection.quit()
+            self._connection = None
+
+    def __enter__(self) -> "SMTPConnector":
+        """Enter context manager, connecting to the server."""
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit context manager, disconnecting from the server."""
+        self.disconnect()
+
+    def send_email(
+        self,
+        from_address: str,
+        to: list[str],
+        subject: str,
+        body: str,
+        from_name: str | None = None,
+        cc: list[str] | None = None,
+        reply_to: str | None = None,
+    ) -> bool:
+        """Send an email.
+
+        Args:
+            from_address: Sender email address (e.g., "user@example.com").
+            to: List of recipient email addresses.
+            subject: Email subject line.
+            body: Email body text (plain text).
+            from_name: Optional display name for sender (e.g., "Atlas").
+            cc: Optional list of CC recipients.
+            reply_to: Optional Reply-To email address.
+
+        Returns:
+            True if email was sent successfully.
+
+        Raises:
+            RuntimeError: If not connected to SMTP server.
+            smtplib.SMTPException: If sending fails.
+        """
+        if not self._connection:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        msg = MIMEMultipart()
+        # Build From header with optional display name
+        if from_name:
+            msg["From"] = f"{from_name} <{from_address}>"
+        else:
+            msg["From"] = from_address
+        msg["To"] = ", ".join(to)
+        msg["Subject"] = subject
+
+        if cc:
+            msg["Cc"] = ", ".join(cc)
+
+        if reply_to:
+            msg["Reply-To"] = reply_to
+
+        msg.attach(MIMEText(body, "plain"))
+
+        # Build recipient list (to + cc)
+        recipients = list(to)
+        if cc:
+            recipients.extend(cc)
+
+        # Use from_address directly for SMTP envelope (no parsing needed)
+        self._connection.sendmail(from_address, recipients, msg.as_string())
+        return True

read_no_evil_mcp/exceptions.py

@@ -0,0 +1,44 @@
+"""Custom exceptions for read-no-evil-mcp."""
+
+
+class ReadNoEvilError(Exception):
+    """Base exception for read-no-evil-mcp."""
+
+
+class ConfigError(ReadNoEvilError):
+    """Raised when there is a configuration error."""
+
+
+class AccountNotFoundError(ReadNoEvilError):
+    """Raised when a requested account is not found."""
+
+    def __init__(self, account_id: str) -> None:
+        self.account_id = account_id
+        super().__init__(f"Account not found: {account_id}")
+
+
+class CredentialNotFoundError(ConfigError):
+    """Raised when credentials for an account are not found."""
+
+    def __init__(self, account_id: str, env_key: str) -> None:
+        self.account_id = account_id
+        self.env_key = env_key
+        super().__init__(
+            f"Missing credential for account '{account_id}': "
+            f"environment variable {env_key} is not set"
+        )
+
+
+class UnsupportedConnectorError(ConfigError):
+    """Raised when an unsupported connector type is requested."""
+
+    def __init__(self, connector_type: str) -> None:
+        self.connector_type = connector_type
+        super().__init__(f"Unsupported connector type: {connector_type}")
+
+
+class PermissionDeniedError(ReadNoEvilError):
+    """Raised when an operation is not permitted for an account."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)