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

msgraph_mcp/tools/mail_write.py

@@ -0,0 +1,403 @@
+"""Mail write tools: send, draft, reply, reply_all, forward, update, delete."""
+
+from __future__ import annotations
+
+import base64
+from typing import Literal
+
+from msgraph.generated.models.attachment import Attachment
+from msgraph.generated.models.body_type import BodyType
+from msgraph.generated.models.email_address import EmailAddress
+from msgraph.generated.models.file_attachment import FileAttachment
+from msgraph.generated.models.followup_flag import FollowupFlag
+from msgraph.generated.models.followup_flag_status import FollowupFlagStatus
+from msgraph.generated.models.importance import Importance
+from msgraph.generated.models.item_body import ItemBody
+from msgraph.generated.models.message import Message
+from msgraph.generated.models.recipient import Recipient
+from msgraph.generated.users.item.messages.item.forward.forward_post_request_body import (
+    ForwardPostRequestBody,
+)
+from msgraph.generated.users.item.messages.item.reply.reply_post_request_body import (
+    ReplyPostRequestBody,
+)
+from msgraph.generated.users.item.messages.item.reply_all.reply_all_post_request_body import (
+    ReplyAllPostRequestBody,
+)
+from msgraph.generated.users.item.send_mail.send_mail_post_request_body import (
+    SendMailPostRequestBody,
+)
+
+from msgraph_mcp.auth.token import NotAuthenticatedError
+from msgraph_mcp.graph.errors import GraphValidationError, map_kiota_error
+from msgraph_mcp.graph.serialize import message_to_dict
+from msgraph_mcp.graph.trimming import trim_message
+
+
+_MAX_INLINE_ATTACHMENT_BYTES = 3 * 1024 * 1024
+
+
+def _recipient(addr: str) -> Recipient:
+    r = Recipient()
+    e = EmailAddress()
+    e.address = addr
+    r.email_address = e
+    return r
+
+
+def _recipients(addrs: list[str] | None) -> list[Recipient]:
+    return [_recipient(a) for a in (addrs or [])]
+
+
+def _body(text: str, body_type: Literal["text", "html"]) -> ItemBody:
+    b = ItemBody()
+    b.content_type = BodyType.Text if body_type == "text" else BodyType.Html
+    b.content = text
+    return b
+
+
+def _validate_and_build_attachments(atts: list[dict] | None) -> list[Attachment]:
+    if not atts:
+        return []
+    total = 0
+    built: list[Attachment] = []
+    for spec in atts:
+        try:
+            raw = base64.b64decode(spec["content_b64"], validate=True)
+        except (KeyError, ValueError) as exc:
+            raise GraphValidationError(f"Invalid attachment content_b64: {exc}") from exc
+        total += len(raw)
+        if total > _MAX_INLINE_ATTACHMENT_BYTES:
+            raise GraphValidationError(
+                f"Attachment payload exceeds 3 MB raw limit (got {total} bytes). "
+                "Use a chunked upload (not supported in v1) for larger files."
+            )
+        fa = FileAttachment()
+        fa.name = spec.get("name") or "attachment"
+        fa.content_type = spec.get("content_type") or "application/octet-stream"
+        fa.content_bytes = raw
+        fa.odata_type = "#microsoft.graph.fileAttachment"
+        built.append(fa)
+    return built
+
+
+def _build_message(
+    *,
+    to: list[str],
+    subject: str,
+    body: str,
+    body_type: Literal["text", "html"],
+    cc: list[str] | None = None,
+    bcc: list[str] | None = None,
+    attachments: list[dict] | None = None,
+) -> Message:
+    m = Message()
+    m.subject = subject
+    m.body = _body(body, body_type)
+    m.to_recipients = _recipients(to)
+    m.cc_recipients = _recipients(cc)
+    m.bcc_recipients = _recipients(bcc)
+    atts = _validate_and_build_attachments(attachments)
+    if atts:
+        m.attachments = atts
+    return m
+
+
+async def send_message(
+    *,
+    graph,
+    to: list[str],
+    subject: str,
+    body: str,
+    body_type: Literal["text", "html"] = "text",
+    cc: list[str] | None = None,
+    bcc: list[str] | None = None,
+    attachments: list[dict] | None = None,
+    save_to_sent_items: bool = True,
+    mailbox: str | None = None,
+) -> dict:
+    """Send a new message immediately.
+
+    Args:
+        to: List of recipient email addresses (required, non-empty).
+        subject: Subject line.
+        body: Message body.
+        body_type: "text" or "html". Default "text".
+        cc: Optional CC list.
+        bcc: Optional BCC list.
+        attachments: Optional list of {name, content_b64, content_type}.
+            Total raw size must be <= 3 MB.
+        save_to_sent_items: Default True.
+        mailbox: Optional mailbox (defaults to signed-in user).
+
+    Returns:
+        {"status": "sent"}
+    """
+    if not to:
+        raise GraphValidationError("`to` must be a non-empty list of email addresses")
+    msg = _build_message(
+        to=to, subject=subject, body=body, body_type=body_type,
+        cc=cc, bcc=bcc, attachments=attachments,
+    )
+    req = SendMailPostRequestBody()
+    req.message = msg
+    req.save_to_sent_items = save_to_sent_items
+    try:
+        await graph.mailbox(mailbox).send_mail.post(req)
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return {"status": "sent"}
+
+
+async def create_draft(
+    *,
+    graph,
+    to: list[str],
+    subject: str,
+    body: str,
+    body_type: Literal["text", "html"] = "text",
+    cc: list[str] | None = None,
+    bcc: list[str] | None = None,
+    attachments: list[dict] | None = None,
+    mailbox: str | None = None,
+    include_raw: bool = False,
+) -> dict:
+    """Create a draft message (not sent). Returns the trimmed draft."""
+    msg = _build_message(
+        to=to, subject=subject, body=body, body_type=body_type,
+        cc=cc, bcc=bcc, attachments=attachments,
+    )
+    try:
+        created = await graph.mailbox(mailbox).messages.post(msg)
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return trim_message(message_to_dict(created), include_body=False, include_raw=include_raw)
+
+
+def _reply_body(comment: str | None, to: list[str] | None) -> ReplyPostRequestBody:
+    body = ReplyPostRequestBody()
+    if comment is not None:
+        body.comment = comment
+    if to:
+        m = Message()
+        m.to_recipients = _recipients(to)
+        body.message = m
+    return body
+
+
+def _reply_all_body(comment: str | None) -> ReplyAllPostRequestBody:
+    body = ReplyAllPostRequestBody()
+    if comment is not None:
+        body.comment = comment
+    return body
+
+
+def _forward_body(comment: str | None, to: list[str]) -> ForwardPostRequestBody:
+    body = ForwardPostRequestBody()
+    if comment is not None:
+        body.comment = comment
+    body.to_recipients = _recipients(to)
+    return body
+
+
+async def reply_message(
+    *,
+    graph,
+    message_id: str,
+    comment: str | None = None,
+    extra_to: list[str] | None = None,
+    mailbox: str | None = None,
+) -> dict:
+    """Reply to the sender of a message."""
+    try:
+        await (
+            graph.mailbox(mailbox)
+            .messages.by_message_id(message_id)
+            .reply.post(_reply_body(comment, extra_to))
+        )
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return {"status": "sent"}
+
+
+async def reply_all_message(
+    *,
+    graph,
+    message_id: str,
+    comment: str | None = None,
+    mailbox: str | None = None,
+) -> dict:
+    """Reply-all to a message (sender + everyone on the to/cc lines)."""
+    try:
+        await (
+            graph.mailbox(mailbox)
+            .messages.by_message_id(message_id)
+            .reply_all.post(_reply_all_body(comment))
+        )
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return {"status": "sent"}
+
+
+async def forward_message(
+    *,
+    graph,
+    message_id: str,
+    to: list[str],
+    comment: str | None = None,
+    mailbox: str | None = None,
+) -> dict:
+    """Forward a message to new recipients."""
+    if not to:
+        raise GraphValidationError("`to` must be a non-empty list of email addresses")
+    try:
+        await (
+            graph.mailbox(mailbox)
+            .messages.by_message_id(message_id)
+            .forward.post(_forward_body(comment, to))
+        )
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return {"status": "sent"}
+
+
+_IMPORTANCE_MAP = {"low": Importance.Low, "normal": Importance.Normal, "high": Importance.High}
+_FLAG_MAP = {
+    "notFlagged": FollowupFlagStatus.NotFlagged,
+    "flagged": FollowupFlagStatus.Flagged,
+    "complete": FollowupFlagStatus.Complete,
+}
+
+
+async def update_message(
+    *,
+    graph,
+    message_id: str,
+    is_read: bool | None = None,
+    flag: Literal["notFlagged", "flagged", "complete"] | None = None,
+    importance: Literal["low", "normal", "high"] | None = None,
+    categories: list[str] | None = None,
+    parent_folder_id: str | None = None,
+    mailbox: str | None = None,
+    include_raw: bool = False,
+) -> dict:
+    """Patch a message's read state / flag / importance / categories.
+
+    For moving a message between folders, prefer `move_message` (clearer
+    intent). This tool patches in-place; setting parent_folder_id here
+    works but is not the primary path.
+
+    Returns the trimmed updated message.
+    """
+    patch = Message()
+    if is_read is not None:
+        patch.is_read = is_read
+    if flag is not None:
+        if flag not in _FLAG_MAP:
+            raise GraphValidationError(f"flag must be one of {list(_FLAG_MAP)}")
+        ff = FollowupFlag()
+        ff.flag_status = _FLAG_MAP[flag]
+        patch.flag = ff
+    if importance is not None:
+        if importance not in _IMPORTANCE_MAP:
+            raise GraphValidationError(f"importance must be one of {list(_IMPORTANCE_MAP)}")
+        patch.importance = _IMPORTANCE_MAP[importance]
+    if categories is not None:
+        patch.categories = list(categories)
+    if parent_folder_id is not None:
+        patch.parent_folder_id = parent_folder_id
+
+    try:
+        updated = await graph.mailbox(mailbox).messages.by_message_id(message_id).patch(patch)
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return trim_message(message_to_dict(updated), include_body=False, include_raw=include_raw)
+
+
+async def delete_message(
+    *, graph, message_id: str, mailbox: str | None = None
+) -> dict:
+    """Soft-delete a message (moves it to Deleted Items)."""
+    try:
+        await graph.mailbox(mailbox).messages.by_message_id(message_id).delete()
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return {"status": "deleted"}
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="send_message", description=send_message.__doc__ or "")
+    async def _send(
+        to: list[str], subject: str, body: str,
+        body_type: Literal["text", "html"] = "text",
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None, attachments: list[dict] | None = None,
+        save_to_sent_items: bool = True, mailbox: str | None = None,
+    ):
+        return await send_message(
+            graph=graph, to=to, subject=subject, body=body,
+            body_type=body_type, cc=cc, bcc=bcc, attachments=attachments,
+            save_to_sent_items=save_to_sent_items, mailbox=mailbox,
+        )
+
+    @mcp.tool(name="create_draft", description=create_draft.__doc__ or "")
+    async def _draft(
+        to: list[str], subject: str, body: str,
+        body_type: Literal["text", "html"] = "text",
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None, attachments: list[dict] | None = None,
+        mailbox: str | None = None, include_raw: bool = False,
+    ):
+        return await create_draft(
+            graph=graph, to=to, subject=subject, body=body,
+            body_type=body_type, cc=cc, bcc=bcc, attachments=attachments,
+            mailbox=mailbox, include_raw=include_raw,
+        )
+
+    @mcp.tool(name="reply_message", description=reply_message.__doc__ or "")
+    async def _reply(message_id: str, comment: str | None = None, extra_to: list[str] | None = None, mailbox: str | None = None):
+        return await reply_message(graph=graph, message_id=message_id, comment=comment, extra_to=extra_to, mailbox=mailbox)
+
+    @mcp.tool(name="reply_all_message", description=reply_all_message.__doc__ or "")
+    async def _reply_all(message_id: str, comment: str | None = None, mailbox: str | None = None):
+        return await reply_all_message(graph=graph, message_id=message_id, comment=comment, mailbox=mailbox)
+
+    @mcp.tool(name="forward_message", description=forward_message.__doc__ or "")
+    async def _forward(message_id: str, to: list[str], comment: str | None = None, mailbox: str | None = None):
+        return await forward_message(graph=graph, message_id=message_id, to=to, comment=comment, mailbox=mailbox)
+
+    @mcp.tool(name="update_message", description=update_message.__doc__ or "")
+    async def _update(
+        message_id: str,
+        is_read: bool | None = None,
+        flag: Literal["notFlagged", "flagged", "complete"] | None = None,
+        importance: Literal["low", "normal", "high"] | None = None,
+        categories: list[str] | None = None,
+        parent_folder_id: str | None = None,
+        mailbox: str | None = None,
+        include_raw: bool = False,
+    ):
+        return await update_message(
+            graph=graph, message_id=message_id,
+            is_read=is_read, flag=flag, importance=importance,
+            categories=categories, parent_folder_id=parent_folder_id,
+            mailbox=mailbox, include_raw=include_raw,
+        )
+
+    @mcp.tool(name="delete_message", description=delete_message.__doc__ or "")
+    async def _delete(message_id: str, mailbox: str | None = None):
+        return await delete_message(graph=graph, message_id=message_id, mailbox=mailbox)

msgraph_mcp/tools/teams_channels.py

@@ -0,0 +1,223 @@
+"""Teams channel read tools: joined teams, channels, channel messages, replies."""
+
+from __future__ import annotations
+
+from kiota_abstractions.base_request_configuration import RequestConfiguration
+from msgraph.generated.teams.item.channels.item.messages.messages_request_builder import (
+    MessagesRequestBuilder as ChannelMessagesRequestBuilder,
+)
+from msgraph.generated.teams.item.channels.item.messages.item.replies.replies_request_builder import (
+    RepliesRequestBuilder,
+)
+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 channel_to_dict, chat_message_to_dict, team_to_dict
+from msgraph_mcp.graph.trimming import trim_channel, trim_chat_message, trim_team
+
+_CHANNEL_MSG_MAX = 50
+
+
+def _channel_messages_query(*, limit: int):
+    qp = ChannelMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(top=limit)
+    return RequestConfiguration[
+        ChannelMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters
+    ](query_parameters=qp)
+
+
+def _replies_query(*, limit: int):
+    qp = RepliesRequestBuilder.RepliesRequestBuilderGetQueryParameters(top=limit)
+    return RequestConfiguration[
+        RepliesRequestBuilder.RepliesRequestBuilderGetQueryParameters
+    ](query_parameters=qp)
+
+
+async def _paged(builder, *, page_token, request_configuration):
+    if page_token is not None:
+        url = decode_page_token(page_token)
+        return await builder.with_url(url).get()
+    return await builder.get(request_configuration=request_configuration)
+
+
+async def list_joined_teams(
+    *, graph, limit: int = 25, page_token: str | None = None, include_raw: bool = False
+) -> dict:
+    """List the teams the signed-in user is a member of.
+
+    Args:
+        limit: 1-100. Default 25. Applied client-side (see below); teams
+            beyond the limit are dropped.
+        page_token: Continuation token from a previous result.
+        include_raw: Include the raw Graph payload under "raw" on each item.
+
+    Returns:
+        {"items": [trimmed_team, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit)
+    builder = graph.raw.me.joined_teams
+    try:
+        # /me/joinedTeams rejects $top ("Query option 'Top' is not allowed"),
+        # so fetch unpaged and cap client-side.
+        collection = await _paged(builder, page_token=page_token, request_configuration=None)
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    items = [trim_team(team_to_dict(t), include_raw=include_raw) for t in (collection.value or [])[:limit]]
+    return {"items": items, "next_page_token": encode_next_link(getattr(collection, "odata_next_link", None))}
+
+
+async def list_channels(
+    *, graph, team_id: str, limit: int = 25, page_token: str | None = None, include_raw: bool = False
+) -> dict:
+    """List channels in a team.
+
+    Args:
+        team_id: Graph team id (from list_joined_teams).
+        limit: 1-100. Default 25. Applied client-side (see below); channels
+            beyond the limit are dropped.
+        page_token: Continuation token from a previous result.
+        include_raw: Include the raw Graph payload under "raw" on each item.
+
+    Returns:
+        {"items": [trimmed_channel, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit)
+    builder = graph.raw.teams.by_team_id(team_id).channels
+    try:
+        # /teams/{id}/channels rejects $top ("Query option 'Top' is not
+        # allowed"), so fetch unpaged and cap client-side.
+        collection = await _paged(builder, page_token=page_token, request_configuration=None)
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    items = [trim_channel(channel_to_dict(c), include_raw=include_raw) for c in (collection.value or [])[:limit]]
+    return {"items": items, "next_page_token": encode_next_link(getattr(collection, "odata_next_link", None))}
+
+
+async def list_channel_messages(
+    *,
+    graph,
+    team_id: str,
+    channel_id: str,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_body: bool = False,
+    include_raw: bool = False,
+) -> dict:
+    """List root messages in a channel, newest first.
+
+    Replies are not included here; fetch them with list_message_replies.
+
+    Args:
+        team_id: Graph team id.
+        channel_id: Graph channel id (from list_channels).
+        limit: 1-50 (Graph caps channel message pages at 50). Default 25.
+        page_token: Continuation token from a previous result.
+        include_body: When True, include each message's full body and any
+            attachment card payloads (e.g. Adaptive Card JSON for bot posts).
+            Default False (snippet only; card text still feeds the snippet).
+        include_raw: Include the raw Graph payload under "raw" on each item.
+
+    Returns:
+        {"items": [trimmed_chat_message, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit, maximum=_CHANNEL_MSG_MAX)
+    builder = graph.raw.teams.by_team_id(team_id).channels.by_channel_id(channel_id).messages
+    try:
+        collection = await _paged(builder, page_token=page_token, request_configuration=_channel_messages_query(limit=limit))
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    items = [
+        trim_chat_message(chat_message_to_dict(m), include_body=include_body, 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 list_message_replies(
+    *,
+    graph,
+    team_id: str,
+    channel_id: str,
+    message_id: str,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_body: bool = False,
+    include_raw: bool = False,
+) -> dict:
+    """List replies to a channel message (the thread under a root post), newest first.
+
+    Args:
+        team_id: Graph team id.
+        channel_id: Graph channel id.
+        message_id: Graph id of the root channel message (from list_channel_messages).
+        limit: 1-50 (Graph caps reply pages at 50). Default 25.
+        page_token: Continuation token from a previous result.
+        include_body: When True, include each reply's full body and any
+            attachment card payloads. Default False (snippet only).
+        include_raw: Include the raw Graph payload under "raw" on each item.
+
+    Returns:
+        {"items": [trimmed_chat_message, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit, maximum=_CHANNEL_MSG_MAX)
+    builder = (
+        graph.raw.teams.by_team_id(team_id)
+        .channels.by_channel_id(channel_id)
+        .messages.by_chat_message_id(message_id)
+        .replies
+    )
+    try:
+        collection = await _paged(builder, page_token=page_token, request_configuration=_replies_query(limit=limit))
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    items = [
+        trim_chat_message(chat_message_to_dict(m), include_body=include_body, 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))}
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="list_joined_teams", description=list_joined_teams.__doc__ or "")
+    async def _list_joined_teams(limit: int = 25, page_token: str | None = None, include_raw: bool = False):
+        return await list_joined_teams(graph=graph, limit=limit, page_token=page_token, include_raw=include_raw)
+
+    @mcp.tool(name="list_channels", description=list_channels.__doc__ or "")
+    async def _list_channels(team_id: str, limit: int = 25, page_token: str | None = None, include_raw: bool = False):
+        return await list_channels(graph=graph, team_id=team_id, limit=limit, page_token=page_token, include_raw=include_raw)
+
+    @mcp.tool(name="list_channel_messages", description=list_channel_messages.__doc__ or "")
+    async def _list_channel_messages(
+        team_id: str,
+        channel_id: str,
+        limit: int = 25,
+        page_token: str | None = None,
+        include_body: bool = False,
+        include_raw: bool = False,
+    ):
+        return await list_channel_messages(
+            graph=graph, team_id=team_id, channel_id=channel_id, limit=limit,
+            page_token=page_token, include_body=include_body, include_raw=include_raw,
+        )
+
+    @mcp.tool(name="list_message_replies", description=list_message_replies.__doc__ or "")
+    async def _list_message_replies(
+        team_id: str,
+        channel_id: str,
+        message_id: str,
+        limit: int = 25,
+        page_token: str | None = None,
+        include_body: bool = False,
+        include_raw: bool = False,
+    ):
+        return await list_message_replies(
+            graph=graph, team_id=team_id, channel_id=channel_id, message_id=message_id,
+            limit=limit, page_token=page_token, include_body=include_body, include_raw=include_raw,
+        )