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

msgraph_mcp/graph/trimming.py

@@ -0,0 +1,359 @@
+"""Trim raw Graph dicts to small agent-friendly shapes.
+
+All trimmers accept dict-shaped input (raw Graph JSON), not msgraph-sdk
+model objects. Tool implementations are responsible for calling
+.serialize() or otherwise producing a plain dict before trimming.
+
+include_raw=True returns {**trimmed, "raw": raw}.
+"""
+
+from __future__ import annotations
+
+import html as _htmllib
+import json
+import re
+from typing import Any
+
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+_HOSTED_RE = re.compile(r"hostedContents/([^/\"'\s]+)/\$value")
+
+
+def _attach_raw(trimmed: dict, raw: dict, include_raw: bool) -> dict:
+    if include_raw:
+        return {**trimmed, "raw": raw}
+    return trimmed
+
+
+def _email(rec: dict | None) -> dict | None:
+    if not rec:
+        return None
+    addr = rec.get("emailAddress") or {}
+    return {"name": addr.get("name"), "address": addr.get("address")}
+
+
+def _emails(recs: list[dict] | None) -> list[dict]:
+    return [e for e in (_email(r) for r in (recs or [])) if e is not None]
+
+
+def trim_message(raw: dict, *, include_body: bool, include_raw: bool) -> dict:
+    body = raw.get("body") or {}
+    flag = raw.get("flag") or {}
+    trimmed: dict[str, Any] = {
+        "id": raw.get("id"),
+        "subject": raw.get("subject"),
+        "from": _email(raw.get("from")),
+        "to": _emails(raw.get("toRecipients")),
+        "cc": _emails(raw.get("ccRecipients")),
+        "received": raw.get("receivedDateTime"),
+        "sent": raw.get("sentDateTime"),
+        "snippet": raw.get("bodyPreview"),
+        "body_type": body.get("contentType") or "text",
+        "is_read": bool(raw.get("isRead")),
+        "is_draft": bool(raw.get("isDraft")),
+        "has_attachments": bool(raw.get("hasAttachments")),
+        "importance": raw.get("importance") or "normal",
+        "flag": flag.get("flagStatus") or "notFlagged",
+        "categories": list(raw.get("categories") or []),
+        "conversation_id": raw.get("conversationId"),
+        "web_link": raw.get("webLink"),
+        "parent_folder_id": raw.get("parentFolderId"),
+        "inference_classification": raw.get("inferenceClassification"),
+    }
+    if include_body:
+        trimmed["body"] = body.get("content")
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_event(raw: dict, *, include_body: bool, include_raw: bool) -> dict:
+    start = raw.get("start") or {}
+    end = raw.get("end") or {}
+    location = raw.get("location") or {}
+    online = raw.get("onlineMeeting") or {}
+    body = raw.get("body") or {}
+    attendees_raw = raw.get("attendees") or []
+    attendees = []
+    for a in attendees_raw:
+        email = _email(a)
+        status = (a.get("status") or {}).get("response")
+        attendees.append(
+            {
+                "name": (email or {}).get("name"),
+                "address": (email or {}).get("address"),
+                "type": a.get("type"),
+                "response": status,
+            }
+        )
+    trimmed: dict[str, Any] = {
+        "id": raw.get("id"),
+        "subject": raw.get("subject"),
+        "organizer": _email(raw.get("organizer")),
+        "start": {"date_time": start.get("dateTime"), "time_zone": start.get("timeZone")},
+        "end": {"date_time": end.get("dateTime"), "time_zone": end.get("timeZone")},
+        "location": location.get("displayName"),
+        "is_all_day": bool(raw.get("isAllDay")),
+        "is_cancelled": bool(raw.get("isCancelled")),
+        "is_online_meeting": bool(raw.get("isOnlineMeeting")),
+        "attendees": attendees,
+        "body_preview": raw.get("bodyPreview"),
+        "show_as": raw.get("showAs"),
+        "sensitivity": raw.get("sensitivity"),
+        "recurrence": raw.get("recurrence"),
+        "web_link": raw.get("webLink"),
+    }
+    if raw.get("isOnlineMeeting"):
+        trimmed["online_meeting_url"] = online.get("joinUrl")
+    if include_body:
+        trimmed["body"] = body.get("content")
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_folder(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "display_name": raw.get("displayName"),
+        "parent_folder_id": raw.get("parentFolderId"),
+        "total_item_count": raw.get("totalItemCount"),
+        "unread_item_count": raw.get("unreadItemCount"),
+        "child_folder_count": raw.get("childFolderCount"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_attachment_list(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "name": raw.get("name"),
+        "content_type": raw.get("contentType"),
+        "size_bytes": raw.get("size"),
+        "is_inline": bool(raw.get("isInline")),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_attachment_download(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "name": raw.get("name"),
+        "content_type": raw.get("contentType"),
+        "size_bytes": raw.get("size"),
+        "content_base64": raw.get("contentBytes"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_user(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "display_name": raw.get("displayName"),
+        "user_principal_name": raw.get("userPrincipalName"),
+        "mail": raw.get("mail"),
+        "job_title": raw.get("jobTitle"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_calendar(raw: dict, *, include_raw: bool) -> dict:
+    owner = raw.get("owner") or {}
+    trimmed = {
+        "id": raw.get("id"),
+        "name": raw.get("name"),
+        "owner": {"name": owner.get("name"), "address": owner.get("address")} if owner else None,
+        "can_edit": bool(raw.get("canEdit")),
+        "is_default_calendar": bool(raw.get("isDefaultCalendar")),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def _trim_rule_conditions(raw: dict | None) -> dict | None:
+    if not raw:
+        return None
+    return {
+        "sender_contains": raw.get("senderContains"),
+        "subject_contains": raw.get("subjectContains"),
+        "body_contains": raw.get("bodyContains"),
+        "body_or_subject_contains": raw.get("bodyOrSubjectContains"),
+        "from_addresses": _emails(raw.get("fromAddresses")),
+        "has_attachments": raw.get("hasAttachments"),
+        "categories": raw.get("categories"),
+    }
+
+
+def _trim_rule_actions(raw: dict | None) -> dict | None:
+    if not raw:
+        return None
+    return {
+        "move_to_folder": raw.get("moveToFolder"),
+        "copy_to_folder": raw.get("copyToFolder"),
+        "delete": raw.get("delete"),
+        "mark_as_read": raw.get("markAsRead"),
+        "mark_importance": raw.get("markImportance"),
+        "assign_categories": raw.get("assignCategories"),
+        "forward_to": _emails(raw.get("forwardTo")),
+        "stop_processing_rules": raw.get("stopProcessingRules"),
+    }
+
+
+def trim_message_rule(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "display_name": raw.get("displayName"),
+        "sequence": raw.get("sequence"),
+        "is_enabled": bool(raw.get("isEnabled")),
+        "has_error": bool(raw.get("hasError")),
+        "is_read_only": bool(raw.get("isReadOnly")),
+        "conditions": _trim_rule_conditions(raw.get("conditions")),
+        "actions": _trim_rule_actions(raw.get("actions")),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def _html_to_snippet(content: str | None, content_type: str | None, *, limit: int = 280) -> str | None:
+    if not content:
+        return None
+    text = content
+    if (content_type or "").lower() == "html":
+        text = _TAG_RE.sub(" ", text)
+    text = _htmllib.unescape(text)
+    text = _WS_RE.sub(" ", text).strip()
+    if len(text) > limit:
+        text = text[:limit].rstrip() + "..."
+    return text or None
+
+
+def _hosted_content_refs(content: str | None) -> list[dict]:
+    if not content:
+        return []
+    # dict.fromkeys preserves first-seen order and de-dupes repeated ids.
+    return [{"hosted_content_id": hid} for hid in dict.fromkeys(_HOSTED_RE.findall(content))]
+
+
+def _reaction_counts(reactions: list[dict] | None) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for r in reactions or []:
+        rt = r.get("reactionType")
+        if rt:
+            counts[rt] = counts.get(rt, 0) + 1
+    return counts
+
+
+def _card_texts(node: Any) -> list[str]:
+    """Collect every "text" string in an Adaptive Card JSON tree, in order."""
+    texts: list[str] = []
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if key == "text" and isinstance(value, str):
+                texts.append(value)
+            else:
+                texts.extend(_card_texts(value))
+    elif isinstance(node, list):
+        for value in node:
+            texts.extend(_card_texts(value))
+    return texts
+
+
+def _card_snippet(raw_attachments: list[dict], *, limit: int = 280) -> str | None:
+    """Build a snippet from card attachment text (app/bot posts have no body text)."""
+    texts: list[str] = []
+    for a in raw_attachments:
+        content = a.get("content")
+        if not isinstance(content, str) or "card" not in (a.get("contentType") or ""):
+            continue
+        try:
+            card = json.loads(content)
+        except ValueError:
+            continue
+        texts.extend(_card_texts(card))
+    joined = _WS_RE.sub(" ", " ".join(t for t in texts if t.strip())).strip()
+    if len(joined) > limit:
+        joined = joined[:limit].rstrip() + "..."
+    return joined or None
+
+
+def trim_chat_message(raw: dict, *, include_body: bool, include_raw: bool) -> dict:
+    body = raw.get("body") or {}
+    from_user = raw.get("from") or {}
+    content = body.get("content")
+    content_type = body.get("contentType")
+    raw_attachments = list(raw.get("attachments") or [])
+    attachments = []
+    for a in raw_attachments:
+        entry = {
+            "id": a.get("id"),
+            "name": a.get("name"),
+            "content_type": a.get("contentType"),
+            "content_url": a.get("contentUrl"),
+        }
+        if include_body:
+            entry["content"] = a.get("content")
+        attachments.append(entry)
+    mentions = [m.get("mentionText") for m in (raw.get("mentions") or []) if m.get("mentionText")]
+    trimmed: dict[str, Any] = {
+        "id": raw.get("id"),
+        "message_type": raw.get("messageType") or "message",
+        "from": from_user.get("displayName"),
+        "from_id": from_user.get("id"),
+        "created": raw.get("createdDateTime"),
+        "last_modified": raw.get("lastModifiedDateTime"),
+        "deleted": raw.get("deletedDateTime") is not None,
+        "importance": raw.get("importance") or "normal",
+        "subject": raw.get("subject"),
+        # Bot/app posts often have a body that is just an <attachment> tag;
+        # fall back to the card attachments' text so the snippet stays useful.
+        "snippet": _html_to_snippet(content, content_type) or _card_snippet(raw_attachments),
+        "body_type": content_type or "text",
+        "attachments": attachments,
+        "mentions": mentions,
+        "hosted_content_refs": _hosted_content_refs(content),
+        "reactions": _reaction_counts(raw.get("reactions")),
+        "web_url": raw.get("webUrl"),
+    }
+    if include_body:
+        trimmed["body"] = content
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_chat(raw: dict, *, include_raw: bool) -> dict:
+    preview = raw.get("lastMessagePreview") or {}
+    trimmed = {
+        "id": raw.get("id"),
+        "chat_type": raw.get("chatType"),
+        "topic": raw.get("topic"),
+        "members": list(raw.get("members") or []),
+        # True last-activity time (created time of the most recent message).
+        "last_message_time": preview.get("createdDateTime"),
+        # Graph's lastUpdatedDateTime: only bumped on rename/membership
+        # changes, NOT on new messages. Kept for reference, but do not treat
+        # it as last activity -- use last_message_time for that.
+        "metadata_updated": raw.get("lastUpdatedDateTime"),
+        "web_url": raw.get("webUrl"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_team(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "display_name": raw.get("displayName"),
+        "description": raw.get("description"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_channel(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "id": raw.get("id"),
+        "display_name": raw.get("displayName"),
+        "description": raw.get("description"),
+        "membership_type": raw.get("membershipType"),
+        "web_url": raw.get("webUrl"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)
+
+
+def trim_hosted_content_download(raw: dict, *, include_raw: bool) -> dict:
+    trimmed = {
+        "content_type": raw.get("contentType"),
+        "size_bytes": raw.get("size"),
+        "content_base64": raw.get("contentBytes"),
+    }
+    return _attach_raw(trimmed, raw, include_raw)

msgraph_mcp/server.py

@@ -0,0 +1,61 @@
+"""FastMCP server entry point.
+
+Boot order:
+  1. Validate config (fail fast if env is missing).
+  2. Build the GraphClient (lazy token acquisition — no Graph calls yet).
+  3. Build a FastMCP app, register all tools, and run on stdio.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from msgraph_mcp import config
+from msgraph_mcp.graph.client import GraphClient
+from msgraph_mcp.tools import register_all
+
+
+_INSTRUCTIONS = """
+Microsoft Outlook (mail + calendar) and Microsoft Teams (read-only) via Microsoft Graph.
+
+This server acts as the signed-in user (delegated auth). All tools that
+touch a mailbox or calendar accept an optional `mailbox` argument (email
+or user ID) to target shared mailboxes/calendars; omit it to use the
+signed-in user's own mailbox.
+
+Teams tools are read-only and act as the signed-in user: list_chats,
+list_chat_messages, list_joined_teams, list_channels, list_channel_messages,
+list_message_replies, and download_hosted_content. They take no `mailbox`
+argument (delegated auth reads only your own chats; channel messages are
+team-scoped).
+
+Downloads: download_attachment and download_hosted_content return
+PNG/JPEG/GIF/WebP content as a native MCP image block (viewable directly,
+no base64 decoding needed). Pass `save_path` (a file path, or an existing
+directory) to write the bytes to disk and get back {path, content_type,
+size_bytes} instead — use that for non-image content or when you want a
+file on disk. Other content without `save_path` still returns base64.
+
+Pagination: list/search tools accept `limit` (1-100, default 25) and
+`page_token`. Pass the returned `next_page_token` back as `page_token`
+to fetch the next page.
+
+Responses are trimmed by default. Pass `include_raw=true` to any tool
+that returns objects to also get the full Graph payload.
+""".strip()
+
+
+def build_server() -> FastMCP:
+    # Fail fast on missing env (raises ConfigError before we hit the event loop)
+    config.client_id()
+    config.authority()
+
+    mcp = FastMCP(name="msgraph-mcp", instructions=_INSTRUCTIONS)
+    graph = GraphClient()
+    register_all(mcp, graph=graph)
+    return mcp
+
+
+def main() -> None:
+    mcp = build_server()
+    mcp.run()  # stdio transport by default

msgraph_mcp/tools/__init__.py

@@ -0,0 +1,35 @@
+"""Tool registration entry point.
+
+register_all(mcp) wires every tool into the FastMCP app. Each tool module
+exposes a register(mcp, *, graph) function so we can keep modules small.
+"""
+
+from __future__ import annotations
+
+from msgraph_mcp.tools import (
+    calendar,
+    mail_actions,
+    mail_batch,
+    mail_folders,
+    mail_read,
+    mail_rules,
+    mail_write,
+    teams_chats,
+    teams_channels,
+    teams_content,
+    util,
+)
+
+
+def register_all(mcp, *, graph) -> None:
+    util.register(mcp, graph=graph)
+    mail_read.register(mcp, graph=graph)
+    mail_write.register(mcp, graph=graph)
+    mail_folders.register(mcp, graph=graph)
+    mail_actions.register(mcp, graph=graph)
+    mail_batch.register(mcp, graph=graph)
+    mail_rules.register(mcp, graph=graph)
+    calendar.register(mcp, graph=graph)
+    teams_chats.register(mcp, graph=graph)
+    teams_channels.register(mcp, graph=graph)
+    teams_content.register(mcp, graph=graph)

msgraph_mcp/tools/_binary.py

@@ -0,0 +1,48 @@
+"""Shared helpers for tools that return downloaded binary content.
+
+Image bytes are returned to the client as a native MCP image block
+(mcp.server.fastmcp.utilities.types.Image) so agents see the image directly
+instead of a base64 text payload; save_path writes bytes to disk instead and
+returns only metadata. Non-image content without save_path falls back to the
+legacy base64 dict.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from mcp.server.fastmcp.utilities.types import Image
+
+_EXT_BY_CONTENT_TYPE = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+}
+
+
+def is_image(content_type: str | None) -> bool:
+    return bool(content_type) and content_type in _EXT_BY_CONTENT_TYPE
+
+
+def ext_for(content_type: str | None) -> str:
+    return _EXT_BY_CONTENT_TYPE.get(content_type or "", ".bin")
+
+
+def image_result(meta: dict, data: bytes, content_type: str) -> list:
+    """Metadata dict + native MCP image block (FastMCP renders both)."""
+    return [meta, Image(data=data, format=content_type.removeprefix("image/"))]
+
+
+def write_bytes(save_path: str, data: bytes, *, default_name: str) -> str:
+    """Write data to save_path and return the resolved path.
+
+    save_path may be a file path, or an existing directory (default_name is
+    appended). Parent directories are created as needed.
+    """
+    target = pathlib.Path(save_path).expanduser()
+    if target.is_dir():
+        target = target / default_name
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(data)
+    return str(target)