mcp-email-server 0.0.3__py3-none-any.whl

mcp_email_server/app.py

@@ -0,0 +1,54 @@
+from datetime import datetime
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_email_server.config import (
+    AccountAttributes,
+    EmailSettings,
+    ProviderSettings,
+    get_settings,
+)
+from mcp_email_server.emails.dispatcher import dispatch_handler
+from mcp_email_server.emails.models import EmailPageResponse
+
+mcp = FastMCP("email")
+
+
+@mcp.resource("email://{account_name}")
+async def get_account(account_name: str) -> EmailSettings | ProviderSettings | None:
+    settings = get_settings()
+    return settings.get_account(account_name, masked=True)
+
+
+@mcp.tool()
+async def list_available_accounts() -> list[AccountAttributes]:
+    settings = get_settings()
+    return [account.masked() for account in settings.get_accounts()]
+
+
+@mcp.tool()
+async def add_email_account(email: EmailSettings) -> None:
+    settings = get_settings()
+    settings.add_email(email)
+    settings.store()
+
+
+@mcp.tool()
+async def page_email(
+    account_name: str,
+    page: int = 1,
+    page_size: int = 10,
+    before: datetime | None = None,
+    after: datetime | None = None,
+    include: str | None = None,
+) -> EmailPageResponse:
+    handler = dispatch_handler(account_name)
+
+    return await handler.get_emails(page=page, page_size=page_size, before=before, after=after, include=include)
+
+
+@mcp.tool()
+async def send_email(account_name: str, recipient: str, subject: str, body: str) -> None:
+    handler = dispatch_handler(account_name)
+    await handler.send_email(recipient, subject, body)
+    return

mcp_email_server/cli.py

@@ -0,0 +1,38 @@
+import typer
+
+from mcp_email_server.app import mcp
+from mcp_email_server.config import delete_settings
+
+app = typer.Typer()
+
+
+@app.command()
+def stdio():
+    mcp.run(transport="stdio")
+
+
+@app.command()
+def sse(
+    host: str = "localhost",
+    port: int = 9557,
+):
+    mcp.settings.host = host
+    mcp.settings.port = port
+    mcp.run(transport="sse")
+
+
+@app.command()
+def ui():
+    from mcp_email_server.ui import main as ui_main
+
+    ui_main()
+
+
+@app.command()
+def reset():
+    delete_settings()
+    typer.echo("✅ Config reset")
+
+
+if __name__ == "__main__":
+    app(["stdio"])

mcp_email_server/config.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import datetime
+import os
+from pathlib import Path
+
+import tomli_w
+from pydantic import BaseModel, Field, model_validator
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+from mcp_email_server.log import logger
+
+DEFAILT_CONFIG_PATH = "~/.config/zerolib/mcp_email_server/config.toml"
+
+CONFIG_PATH = Path(os.getenv("MCP_EMAIL_SERVER_CONFIG_PATH", DEFAILT_CONFIG_PATH)).expanduser().resolve()
+
+
+class EmailServer(BaseModel):
+    user_name: str
+    password: str
+    host: str
+    port: int
+    use_ssl: bool = True  # Usually port 465
+    start_ssl: bool = False  # Usually port 587
+
+    def masked(self) -> EmailServer:
+        return self.model_copy(update={"password": "********"})
+
+
+class AccountAttributes(BaseModel):
+    account_name: str
+    description: str = ""
+    created_at: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    updated_at: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+    @model_validator(mode="after")
+    @classmethod
+    def update_updated_at(cls, obj: AccountAttributes) -> AccountAttributes:
+        """Update updated_at field."""
+        # must disable validation to avoid infinite loop
+        obj.model_config["validate_assignment"] = False
+
+        # update updated_at field
+        obj.updated_at = datetime.datetime.now()
+
+        # enable validation again
+        obj.model_config["validate_assignment"] = True
+        return obj
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AccountAttributes):
+            return NotImplemented
+        return self.model_dump(exclude={"created_at", "updated_at"}) == other.model_dump(
+            exclude={"created_at", "updated_at"}
+        )
+
+    def masked(self) -> AccountAttributes:
+        return self.model_copy()
+
+
+class EmailSettings(AccountAttributes):
+    full_name: str
+    email_address: str
+    incoming: EmailServer
+    outgoing: EmailServer
+
+    @classmethod
+    def init(
+        cls,
+        *,
+        account_name: str,
+        full_name: str,
+        email_address: str,
+        user_name: str,
+        password: str,
+        imap_host: str,
+        smtp_host: str,
+        imap_user_name: str | None = None,
+        imap_password: str | None = None,
+        imap_port: int = 993,
+        imap_ssl: bool = True,
+        smtp_port: int = 465,
+        smtp_ssl: bool = True,
+        smtp_start_ssl: bool = False,
+        smtp_user_name: str | None = None,
+        smtp_password: str | None = None,
+    ) -> EmailSettings:
+        return cls(
+            account_name=account_name,
+            full_name=full_name,
+            email_address=email_address,
+            incoming=EmailServer(
+                user_name=imap_user_name or user_name,
+                password=imap_password or password,
+                host=imap_host,
+                port=imap_port,
+                use_ssl=imap_ssl,
+            ),
+            outgoing=EmailServer(
+                user_name=smtp_user_name or user_name,
+                password=smtp_password or password,
+                host=smtp_host,
+                port=smtp_port,
+                use_ssl=smtp_ssl,
+                start_ssl=smtp_start_ssl,
+            ),
+        )
+
+    def masked(self) -> EmailSettings:
+        return self.model_copy(
+            update={
+                "incoming": self.incoming.masked(),
+                "outgoing": self.outgoing.masked(),
+            }
+        )
+
+
+class ProviderSettings(AccountAttributes):
+    provider_name: str
+    api_key: str
+
+    def masked(self) -> AccountAttributes:
+        return self.model_copy(update={"api_key": "********"})
+
+
+class Settings(BaseSettings):
+    emails: list[EmailSettings] = []
+    providers: list[ProviderSettings] = []
+    db_location: str = CONFIG_PATH.with_name("db.sqlite3").as_posix()
+
+    model_config = SettingsConfigDict(toml_file=CONFIG_PATH, validate_assignment=True, revalidate_instances="always")
+
+    def add_email(self, email: EmailSettings) -> None:
+        """Use re-assigned for validation to work."""
+        self.emails = [email, *self.emails]
+
+    def add_provider(self, provider: ProviderSettings) -> None:
+        """Use re-assigned for validation to work."""
+        self.providers = [provider, *self.providers]
+
+    def delete_email(self, account_name: str) -> None:
+        """Use re-assigned for validation to work."""
+        self.emails = [email for email in self.emails if email.account_name != account_name]
+
+    def delete_provider(self, account_name: str) -> None:
+        """Use re-assigned for validation to work."""
+        self.providers = [provider for provider in self.providers if provider.account_name != account_name]
+
+    def get_account(self, account_name: str, masked: bool = False) -> EmailSettings | ProviderSettings | None:
+        for email in self.emails:
+            if email.account_name == account_name:
+                return email if not masked else email.masked()
+        for provider in self.providers:
+            if provider.account_name == account_name:
+                return provider if not masked else provider.masked()
+        return None
+
+    def get_accounts(self, masked: bool = False) -> list[EmailSettings | ProviderSettings]:
+        accounts = self.emails + self.providers
+        if masked:
+            return [account.masked() for account in accounts]
+        return accounts
+
+    @model_validator(mode="after")
+    @classmethod
+    def check_unique_account_names(cls, obj: Settings) -> Settings:
+        account_names = set()
+        for email in obj.emails:
+            if email.account_name in account_names:
+                raise ValueError(f"Duplicate account name {email.account_name}")
+            account_names.add(email.account_name)
+        for provider in obj.providers:
+            if provider.account_name in account_names:
+                raise ValueError(f"Duplicate account name {provider.account_name}")
+            account_names.add(provider.account_name)
+
+        return obj
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (TomlConfigSettingsSource(settings_cls),)
+
+    def _to_toml(self) -> str:
+        data = self.model_dump()
+        return tomli_w.dumps(data)
+
+    def store(self) -> None:
+        toml_file = self.model_config["toml_file"]
+        toml_file.parent.mkdir(parents=True, exist_ok=True)
+        toml_file.write_text(self._to_toml())
+        logger.info(f"Settings stored in {toml_file}")
+
+
+_settings = None
+
+
+def get_settings(reload: bool = False) -> Settings:
+    global _settings
+    if not _settings or reload:
+        logger.info(f"Loading settings from {CONFIG_PATH}")
+        _settings = Settings()
+    return _settings
+
+
+def store_settings(settings: Settings | None = None) -> None:
+    if not settings:
+        settings = get_settings()
+    settings.store()
+    return
+
+
+def delete_settings() -> None:
+    if not CONFIG_PATH.exists():
+        logger.info(f"Settings file {CONFIG_PATH} does not exist")
+        return
+    CONFIG_PATH.unlink()
+    logger.info(f"Deleted settings file {CONFIG_PATH}")

mcp_email_server/emails/__init__.py

@@ -0,0 +1,27 @@
+import abc
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp_email_server.emails.models import EmailPageResponse
+
+
+class EmailHandler(abc.ABC):
+    @abc.abstractmethod
+    async def get_emails(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        include: str | None = None,
+    ) -> "EmailPageResponse":
+        """
+        Get emails
+        """
+
+    @abc.abstractmethod
+    async def send_email(self, recipient: str, subject: str, body: str) -> None:
+        """
+        Send email
+        """

mcp_email_server/emails/classic.py

@@ -0,0 +1,253 @@
+import email.utils
+from collections.abc import AsyncGenerator
+from datetime import datetime
+from email.mime.text import MIMEText
+from email.parser import BytesParser
+from email.policy import default
+from typing import Any
+
+import aioimaplib
+import aiosmtplib
+
+from mcp_email_server.config import EmailServer, EmailSettings
+from mcp_email_server.emails import EmailHandler
+from mcp_email_server.emails.models import EmailData, EmailPageResponse
+
+
+class EmailClient:
+    def __init__(self, email_server: EmailServer, sender: str | None = None):
+        self.email_server = email_server
+        self.sender = sender or email_server.user_name
+
+        self.imap_class = aioimaplib.IMAP4_SSL if self.email_server.use_ssl else aioimaplib.IMAP4
+
+        self.smtp_use_tls = self.email_server.use_ssl
+        self.smtp_start_tls = self.email_server.start_ssl
+
+    def _parse_email_data(self, raw_email: bytes) -> dict[str, Any]:  # noqa: C901
+        """Parse raw email data into a structured dictionary."""
+        parser = BytesParser(policy=default)
+        email_message = parser.parsebytes(raw_email)
+
+        # Extract email parts
+        subject = email_message.get("Subject", "")
+        sender = email_message.get("From", "")
+        date_str = email_message.get("Date", "")
+
+        # Parse date
+        try:
+            date_tuple = email.utils.parsedate_tz(date_str)
+            date = datetime.fromtimestamp(email.utils.mktime_tz(date_tuple)) if date_tuple else datetime.now()
+        except Exception:
+            date = datetime.now()
+
+        # Get body content
+        body = ""
+        attachments = []
+
+        if email_message.is_multipart():
+            for part in email_message.walk():
+                content_type = part.get_content_type()
+                content_disposition = str(part.get("Content-Disposition", ""))
+
+                # Handle attachments
+                if "attachment" in content_disposition:
+                    filename = part.get_filename()
+                    if filename:
+                        attachments.append(filename)
+                # Handle text parts
+                elif content_type == "text/plain":
+                    body_part = part.get_payload(decode=True)
+                    if body_part:
+                        charset = part.get_content_charset("utf-8")
+                        try:
+                            body += body_part.decode(charset)
+                        except UnicodeDecodeError:
+                            body += body_part.decode("utf-8", errors="replace")
+        else:
+            # Handle plain text emails
+            payload = email_message.get_payload(decode=True)
+            if payload:
+                charset = email_message.get_content_charset("utf-8")
+                try:
+                    body = payload.decode(charset)
+                except UnicodeDecodeError:
+                    body = payload.decode("utf-8", errors="replace")
+
+        return {
+            "subject": subject,
+            "from": sender,
+            "body": body,
+            "date": date,
+            "attachments": attachments,
+        }
+
+    async def get_emails_stream(  # noqa: C901
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        include: str | None = None,
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        imap = self.imap_class(self.email_server.host, self.email_server.port)
+        try:
+            # Wait for the connection to be established
+            await imap._client_task
+            await imap.wait_hello_from_server()
+
+            # Login and select inbox
+            await imap.login(self.email_server.user_name, self.email_server.password)
+            await imap.select("INBOX")
+
+            # Build search criteria
+            search_criteria = []
+            if before:
+                search_criteria.extend(["BEFORE", before.isoformat()])
+            if after:
+                search_criteria.extend(["AFTER", after.isoformat()])
+            if include:
+                search_criteria.extend(["TEXT", include])
+
+            # If no specific criteria, search for ALL
+            if not search_criteria:
+                search_criteria = ["ALL"]
+
+            # Search for messages
+            _, messages = await imap.search(*search_criteria)
+            message_ids = messages[0].split()
+            start = (page - 1) * page_size
+            end = start + page_size
+
+            # Fetch each message
+            for _, message_id in enumerate(message_ids[start:end]):
+                try:
+                    # Convert message_id from bytes to string
+                    message_id_str = message_id.decode("utf-8")
+
+                    # Use the string version of the message ID
+                    _, data = await imap.fetch(message_id_str, "RFC822")
+
+                    # Find the email data in the response
+                    raw_email = None
+
+                    # The actual email content is in the bytearray at index 1
+                    if len(data) > 1 and isinstance(data[1], bytearray) and len(data[1]) > 0:
+                        raw_email = bytes(data[1])
+                    else:
+                        # Fallback to searching through all items
+                        for _, item in enumerate(data):
+                            if isinstance(item, (bytes, bytearray)) and len(item) > 100:
+                                # Skip header lines that contain FETCH
+                                if isinstance(item, bytes) and b"FETCH" in item:
+                                    continue
+                                # This is likely the email content
+                                raw_email = bytes(item) if isinstance(item, bytearray) else item
+                                break
+
+                    if raw_email:
+                        try:
+                            parsed_email = self._parse_email_data(raw_email)
+                            yield parsed_email
+                        except Exception as e:
+                            # Log error but continue with other emails
+                            print(f"Error parsing email: {e!s}")
+                    else:
+                        print(f"Could not find email data in response for message ID: {message_id_str}")
+                except Exception as e:
+                    print(f"Error fetching message {message_id}: {e!s}")
+        finally:
+            # Ensure we logout properly
+            try:
+                await imap.logout()
+            except Exception as e:
+                print(f"Error during logout: {e}")
+
+    async def get_email_count(
+        self,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        include: str | None = None,
+    ) -> int:
+        imap = self.imap_class(self.email_server.host, self.email_server.port)
+        try:
+            # Wait for the connection to be established
+            await imap._client_task
+            await imap.wait_hello_from_server()
+
+            # Login and select inbox
+            await imap.login(self.email_server.user_name, self.email_server.password)
+            await imap.select("INBOX")
+
+            # Build search criteria
+            search_criteria = []
+            if before:
+                search_criteria.extend(["BEFORE", before.isoformat()])
+            if after:
+                search_criteria.extend(["AFTER", after.isoformat()])
+            if include:
+                search_criteria.extend(["TEXT", include])
+
+            # If no specific criteria, search for ALL
+            if not search_criteria:
+                search_criteria = ["ALL"]
+
+            # Search for messages and count them
+            _, messages = await imap.search(*search_criteria)
+            return len(messages[0].split())
+        finally:
+            # Ensure we logout properly
+            try:
+                await imap.logout()
+            except Exception as e:
+                print(f"Error during logout: {e}")
+
+    async def send_email(self, recipient: str, subject: str, body: str):
+        msg = MIMEText(body)
+        msg["Subject"] = subject
+        msg["From"] = self.sender
+        msg["To"] = recipient
+
+        async with aiosmtplib.SMTP(
+            hostname=self.email_server.host,
+            port=self.email_server.port,
+            start_tls=self.smtp_start_tls,
+            use_tls=self.smtp_use_tls,
+        ) as smtp:
+            await smtp.login(self.email_server.user_name, self.email_server.password)
+            await smtp.send_message(msg)
+
+
+class ClassicEmailHandler(EmailHandler):
+    def __init__(self, email_settings: EmailSettings):
+        self.email_settings = email_settings
+        self.incoming_client = EmailClient(email_settings.incoming)
+        self.outgoing_client = EmailClient(
+            email_settings.outgoing,
+            sender=f"{email_settings.full_name} <{email_settings.email_address}>",
+        )
+
+    async def get_emails(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        include: str | None = None,
+    ) -> EmailPageResponse:
+        emails = []
+        async for email_data in self.incoming_client.get_emails_stream(page, page_size, before, after, include):
+            emails.append(EmailData.from_email(email_data))
+        total = await self.incoming_client.get_email_count(before, after, include)
+        return EmailPageResponse(
+            page=page,
+            page_size=page_size,
+            before=before,
+            after=after,
+            include=include,
+            emails=emails,
+            total=total,
+        )
+
+    async def send_email(self, recipient: str, subject: str, body: str) -> None:
+        await self.outgoing_client.send_email(recipient, subject, body)

mcp_email_server/emails/dispatcher.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp_email_server.config import EmailSettings, ProviderSettings, get_settings
+from mcp_email_server.emails.classic import ClassicEmailHandler
+
+if TYPE_CHECKING:
+    from mcp_email_server.emails import EmailHandler
+
+
+def dispatch_handler(account_name: str) -> EmailHandler:
+    settings = get_settings()
+    account = settings.get_account(account_name)
+    if isinstance(account, ProviderSettings):
+        raise NotImplementedError
+    if isinstance(account, EmailSettings):
+        return ClassicEmailHandler(account)

mcp_email_server/emails/models.py

@@ -0,0 +1,32 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class EmailData(BaseModel):
+    subject: str
+    sender: str
+    body: str
+    date: datetime
+    attachments: list[str]
+
+    @classmethod
+    def from_email(cls, email: dict[str, Any]):
+        return cls(
+            subject=email["subject"],
+            sender=email["from"],
+            body=email["body"],
+            date=email["date"],
+            attachments=email["attachments"],
+        )
+
+
+class EmailPageResponse(BaseModel):
+    page: int
+    page_size: int
+    before: datetime | None
+    after: datetime | None
+    include: str | None
+    emails: list[EmailData]
+    total: int

mcp_email_server/log.py

@@ -0,0 +1,9 @@
+import os
+
+USER_DEFINED_LOG_LEVEL = os.getenv("MCP_EMAIL_SERVER_LOG_LEVEL", "INFO")
+
+os.environ["LOGURU_LEVEL"] = USER_DEFINED_LOG_LEVEL
+
+from loguru import logger  # noqa: E402
+
+__all__ = ["logger"]

mcp_email_server/tools/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+    "mcpServers": {
+        "zerolib-email": {
+            "command": "{{ ENTRYPOINT }}",
+            "args": ["stdio"]
+        }
+    }
+}