msgraph-mcp-server 0.3.0__py3-none-any.whl

msgraph_mcp/tools/mail_read.py

@@ -0,0 +1,333 @@
+"""Mail read tools: list, search, get, list/download attachments."""
+
+from __future__ import annotations
+
+import base64
+
+from kiota_abstractions.base_request_configuration import RequestConfiguration
+from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import (
+    MessagesRequestBuilder as FolderMessagesRequestBuilder,
+)
+from msgraph.generated.users.item.messages.messages_request_builder import (
+    MessagesRequestBuilder,
+)
+
+from msgraph_mcp.auth.token import NotAuthenticatedError
+from msgraph_mcp.graph.errors import map_kiota_error
+from msgraph_mcp.graph.pagination import (
+    decode_page_token,
+    encode_next_link,
+    validate_limit,
+)
+from msgraph_mcp.graph.serialize import (
+    attachment_to_dict,
+    message_to_dict,
+)
+from msgraph_mcp.graph.trimming import (
+    trim_attachment_download,
+    trim_attachment_list,
+    trim_message,
+)
+from msgraph_mcp.tools import _binary
+
+
+def _list_messages_query(*, limit: int, filter_expr: str | None = None):
+    qp = FolderMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
+        top=limit,
+        orderby=["receivedDateTime DESC"],
+        filter=filter_expr,
+    )
+    return RequestConfiguration[
+        FolderMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters
+    ](query_parameters=qp)
+
+
+def _build_list_filter(*, unread_only: bool, filter: str | None) -> str | None:
+    parts: list[str] = []
+    if unread_only:
+        parts.append("isRead eq false")
+    if filter:
+        parts.append(f"({filter})")
+    return " and ".join(parts) if parts else None
+
+
+def _search_query(*, limit: int, query: str):
+    qp = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
+        top=limit,
+        search=query,
+    )
+    return RequestConfiguration[
+        MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters
+    ](query_parameters=qp)
+
+
+async def list_messages(
+    *,
+    graph,
+    folder_id: str = "inbox",
+    mailbox: str | None = None,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_raw: bool = False,
+    unread_only: bool = False,
+    filter: str | None = None,
+) -> dict:
+    """List messages from a mail folder, newest first.
+
+    Args:
+        folder_id: Folder id, or a well-known name (inbox, sentitems, drafts,
+            deleteditems, archive, junkemail). Default: inbox.
+        mailbox: Optional mailbox (email or user ID). Default: signed-in user.
+        limit: 1-100. Default 25.
+        page_token: Pass next_page_token from a previous result to continue.
+        include_raw: Include the raw Graph payload under "raw" on each item.
+        unread_only: When True, only return messages where isRead is false.
+            Adds `isRead eq false` to the server-side $filter.
+        filter: Raw OData $filter expression applied server-side. Combined
+            with `unread_only` using `and`. Examples:
+            `from/emailAddress/address eq 'a@x.com'`,
+            `hasAttachments eq true`,
+            `contains(subject,'report')`,
+            `receivedDateTime ge 2026-05-01T00:00:00Z`.
+            Cannot be combined with $search — use `search_messages` for that.
+
+    Returns:
+        {"items": [trimmed_message, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit)
+    filter_expr = _build_list_filter(unread_only=unread_only, filter=filter)
+    builder = graph.mailbox(mailbox).mail_folders.by_mail_folder_id(folder_id).messages
+    try:
+        if page_token is not None:
+            url = decode_page_token(page_token)
+            collection = await builder.with_url(url).get()
+        else:
+            collection = await builder.get(
+                request_configuration=_list_messages_query(limit=limit, filter_expr=filter_expr)
+            )
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+
+    items = [
+        trim_message(message_to_dict(m), include_body=False, include_raw=include_raw)
+        for m in (collection.value or [])
+    ]
+    return {"items": items, "next_page_token": encode_next_link(getattr(collection, "odata_next_link", None))}
+
+
+async def search_messages(
+    *,
+    graph,
+    query: str,
+    mailbox: str | None = None,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_raw: bool = False,
+) -> dict:
+    """Search messages across all folders using Graph $search.
+
+    The query is passed to Graph as-is — supply quoting yourself if you need
+    a literal phrase (e.g. '"weekly report"') or KQL fielded predicates
+    (e.g. 'from:alice subject:"report"').
+
+    Graph does not allow combining $search with $filter or $orderby, and KQL
+    has no `isread`/`unread`/`flag`/`in` predicates. To filter by isRead /
+    sender / date / attachments while keyword-matching, use `list_messages`
+    with `filter="contains(subject,'…')"` (or `contains(body/content,'…')`)
+    instead — that path supports the full $filter grammar.
+
+    Args:
+        query: Graph $search expression. Plain tokens match across common
+            mail fields; quoted phrases match literally; KQL `field:value`
+            forms target specific fields.
+        mailbox: Optional mailbox.
+        limit: 1-100.
+        page_token: Continuation token.
+        include_raw: Include raw payloads.
+    """
+    limit = validate_limit(limit)
+    builder = graph.mailbox(mailbox).messages
+    try:
+        if page_token is not None:
+            url = decode_page_token(page_token)
+            collection = await builder.with_url(url).get()
+        else:
+            collection = await builder.get(request_configuration=_search_query(limit=limit, query=query))
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+
+    items = [
+        trim_message(message_to_dict(m), include_body=False, include_raw=include_raw)
+        for m in (collection.value or [])
+    ]
+    return {"items": items, "next_page_token": encode_next_link(getattr(collection, "odata_next_link", None))}
+
+
+async def get_message(
+    *,
+    graph,
+    message_id: str,
+    mailbox: str | None = None,
+    include_body: bool = False,
+    include_raw: bool = False,
+) -> dict:
+    """Fetch a single message by id.
+
+    Args:
+        message_id: Graph message id.
+        mailbox: Optional mailbox.
+        include_body: When True, the full body is returned. Default False
+            (snippet only).
+        include_raw: Include the raw Graph payload under "raw".
+
+    Returns:
+        Trimmed message object.
+    """
+    try:
+        msg = await graph.mailbox(mailbox).messages.by_message_id(message_id).get()
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return trim_message(message_to_dict(msg), include_body=include_body, include_raw=include_raw)
+
+
+async def list_attachments(
+    *,
+    graph,
+    message_id: str,
+    mailbox: str | None = None,
+    include_raw: bool = False,
+) -> dict:
+    """List attachments on a message (metadata only — no content)."""
+    try:
+        collection = await graph.mailbox(mailbox).messages.by_message_id(message_id).attachments.get()
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    items = [
+        trim_attachment_list(attachment_to_dict(a, include_content=False), include_raw=include_raw)
+        for a in (collection.value or [])
+    ]
+    return {"items": items, "next_page_token": None}
+
+
+async def download_attachment(
+    *,
+    graph,
+    message_id: str,
+    attachment_id: str,
+    mailbox: str | None = None,
+    save_path: str | None = None,
+    include_raw: bool = False,
+) -> dict | list:
+    """Download a single attachment.
+
+    Args:
+        save_path: Write the bytes to this file path (or into this existing
+            directory, using the attachment's name) instead of returning
+            content. Returns {"path", "name", "content_type", "size_bytes"}.
+
+    Returns:
+        - Image attachments (PNG/JPEG/GIF/WebP, no save_path): metadata plus
+          the image itself as a native MCP image block, viewable directly.
+        - With save_path: {"path", "name", "content_type", "size_bytes"}.
+        - Otherwise: {name, content_type, size_bytes, content_base64}.
+    """
+    try:
+        att = await (
+            graph.mailbox(mailbox)
+            .messages.by_message_id(message_id)
+            .attachments.by_attachment_id(attachment_id)
+            .get()
+        )
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+
+    content = getattr(att, "content_bytes", None)
+    if isinstance(content, str):
+        content = base64.b64decode(content)
+    if isinstance(content, (bytes, bytearray)):
+        content = bytes(content)
+        name = getattr(att, "name", None)
+        content_type = getattr(att, "content_type", None)
+
+        if save_path is not None:
+            path = _binary.write_bytes(
+                save_path, content,
+                default_name=name or f"attachment-{attachment_id}{_binary.ext_for(content_type)}",
+            )
+            return {
+                "path": path, "name": name,
+                "content_type": content_type, "size_bytes": len(content),
+            }
+
+        if _binary.is_image(content_type):
+            meta = {"name": name, "content_type": content_type, "size_bytes": len(content)}
+            return _binary.image_result(meta, content, content_type)
+
+    return trim_attachment_download(attachment_to_dict(att, include_content=True), include_raw=include_raw)
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="list_messages", description=list_messages.__doc__ or "")
+    async def _list_messages(
+        folder_id: str = "inbox",
+        mailbox: str | None = None,
+        limit: int = 25,
+        page_token: str | None = None,
+        include_raw: bool = False,
+        unread_only: bool = False,
+        filter: str | None = None,
+    ):
+        return await list_messages(
+            graph=graph, folder_id=folder_id, mailbox=mailbox,
+            limit=limit, page_token=page_token, include_raw=include_raw,
+            unread_only=unread_only, filter=filter,
+        )
+
+    @mcp.tool(name="search_messages", description=search_messages.__doc__ or "")
+    async def _search_messages(
+        query: str,
+        mailbox: str | None = None,
+        limit: int = 25,
+        page_token: str | None = None,
+        include_raw: bool = False,
+    ):
+        return await search_messages(
+            graph=graph, query=query, mailbox=mailbox,
+            limit=limit, page_token=page_token, include_raw=include_raw,
+        )
+
+    @mcp.tool(name="get_message", description=get_message.__doc__ or "")
+    async def _get_message(
+        message_id: str,
+        mailbox: str | None = None,
+        include_body: bool = False,
+        include_raw: bool = False,
+    ):
+        return await get_message(
+            graph=graph, message_id=message_id, mailbox=mailbox,
+            include_body=include_body, include_raw=include_raw,
+        )
+
+    @mcp.tool(name="list_attachments", description=list_attachments.__doc__ or "")
+    async def _list_attachments(message_id: str, mailbox: str | None = None, include_raw: bool = False):
+        return await list_attachments(graph=graph, message_id=message_id, mailbox=mailbox, include_raw=include_raw)
+
+    @mcp.tool(name="download_attachment", description=download_attachment.__doc__ or "")
+    async def _download_attachment(
+        message_id: str, attachment_id: str, mailbox: str | None = None,
+        save_path: str | None = None, include_raw: bool = False,
+    ):
+        return await download_attachment(
+            graph=graph, message_id=message_id, attachment_id=attachment_id,
+            mailbox=mailbox, save_path=save_path, include_raw=include_raw,
+        )