feat: Support order inbox email and set desc default (#26)

* feat: Support order inbox email and set desc default

* test

* Add more on desc

Author: Wh1isper

mcp_email_server/app.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Annotated
+from typing import Annotated, Literal
 
 from mcp.server.fastmcp import FastMCP
 from pydantic import Field
@@ -38,19 +38,31 @@ async def add_email_account(email: EmailSettings) -> None:
 @mcp.tool(description="Paginate emails, page start at 1, before and since as UTC datetime.")
 async def page_email(
     account_name: Annotated[str, Field(description="The name of the email account.")],
-    page: Annotated[int, Field(default=1, description="The page number to retrieve (starting from 1).")] = 1,
+    page: Annotated[
+        int,
+        Field(default=1, description="The page number to retrieve (starting from 1)."),
+    ] = 1,
     page_size: Annotated[int, Field(default=10, description="The number of emails to retrieve per page.")] = 10,
     before: Annotated[
-        datetime | None, Field(default=None, description="Retrieve emails before this datetime (UTC).")
+        datetime | None,
+        Field(default=None, description="Retrieve emails before this datetime (UTC)."),
     ] = None,
     since: Annotated[
-        datetime | None, Field(default=None, description="Retrieve emails since this datetime (UTC).")
+        datetime | None,
+        Field(default=None, description="Retrieve emails since this datetime (UTC)."),
     ] = None,
     subject: Annotated[str | None, Field(default=None, description="Filter emails by subject.")] = None,
     body: Annotated[str | None, Field(default=None, description="Filter emails by body.")] = None,
     text: Annotated[str | None, Field(default=None, description="Filter emails by text.")] = None,
     from_address: Annotated[str | None, Field(default=None, description="Filter emails by sender address.")] = None,
-    to_address: Annotated[str | None, Field(default=None, description="Filter emails by recipient address.")] = None,
+    to_address: Annotated[
+        str | None,
+        Field(default=None, description="Filter emails by recipient address."),
+    ] = None,
+    order: Annotated[
+        Literal["asc", "desc"],
+        Field(default=None, description="Order emails by field. `asc` or `desc`."),
+    ] = "desc",
 ) -> EmailPageResponse:
     handler = dispatch_handler(account_name)
 
@@ -64,6 +76,7 @@ async def page_email(
         text=text,
         from_address=from_address,
         to_address=to_address,
+        order=order,
     )
 
 

mcp_email_server/emails/__init__.py

@@ -19,6 +19,7 @@ async def get_emails(
         text: str | None = None,
         from_address: str | None = None,
         to_address: str | None = None,
+        order: str = "desc",
     ) -> "EmailPageResponse":
         """
         Get emails

mcp_email_server/emails/classic.py

@@ -94,6 +94,7 @@ async def get_emails_stream(  # noqa: C901
         text: str | None = None,
         from_address: str | None = None,
         to_address: str | None = None,
+        order: str = "desc",
     ) -> AsyncGenerator[dict[str, Any], None]:
         imap = self.imap_class(self.email_server.host, self.email_server.port)
         try:
@@ -119,6 +120,9 @@ async def get_emails_stream(  # noqa: C901
             start = (page - 1) * page_size
             end = start + page_size
 
+            if order == "desc":
+                message_ids.reverse()
+
             # Fetch each message
             for _, message_id in enumerate(message_ids[start:end]):
                 try:
@@ -279,10 +283,11 @@ async def get_emails(
         text: str | None = None,
         from_address: str | None = None,
         to_address: str | None = None,
+        order: str = "desc",
     ) -> EmailPageResponse:
         emails = []
         async for email_data in self.incoming_client.get_emails_stream(
-            page, page_size, before, since, subject, body, text, from_address, to_address
+            page, page_size, before, since, subject, body, text, from_address, to_address, order
         ):
             emails.append(EmailData.from_email(email_data))
         total = await self.incoming_client.get_email_count(before, since, subject, body, text, from_address, to_address)

tests/test_classic_handler.py

@@ -106,7 +106,7 @@ async def test_get_emails(self, classic_handler):
 
                 # Verify the client methods were called correctly
                 classic_handler.incoming_client.get_emails_stream.assert_called_once_with(
-                    1, 10, now, None, "Test", None, None, "sender@example.com", None
+                    1, 10, now, None, "Test", None, None, "sender@example.com", None, "desc"
                 )
                 mock_count.assert_called_once_with(now, None, "Test", None, None, "sender@example.com", None)
 

tests/test_mcp_tools.py

@@ -159,6 +159,7 @@ async def test_page_email(self):
                 text=None,
                 from_address="sender@example.com",
                 to_address=None,
+                order="desc",
             )
 
     @pytest.mark.asyncio