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

msgraph_mcp/tools/teams_chats.py

@@ -0,0 +1,140 @@
+"""Teams chat read tools: list the user's chats and their message history."""
+
+from __future__ import annotations
+
+from kiota_abstractions.base_request_configuration import RequestConfiguration
+from msgraph.generated.chats.chats_request_builder import ChatsRequestBuilder
+from msgraph.generated.chats.item.messages.messages_request_builder import (
+    MessagesRequestBuilder as ChatMessagesRequestBuilder,
+)
+
+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 chat_message_to_dict, chat_to_dict
+from msgraph_mcp.graph.trimming import trim_chat, trim_chat_message
+
+
+def _list_chats_query(*, limit: int):
+    qp = ChatsRequestBuilder.ChatsRequestBuilderGetQueryParameters(
+        top=limit,
+        expand=["members", "lastMessagePreview"],
+    )
+    return RequestConfiguration[ChatsRequestBuilder.ChatsRequestBuilderGetQueryParameters](
+        query_parameters=qp
+    )
+
+
+def _list_chat_messages_query(*, limit: int):
+    qp = ChatMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(top=limit)
+    return RequestConfiguration[
+        ChatMessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters
+    ](query_parameters=qp)
+
+
+async def list_chats(
+    *,
+    graph,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_raw: bool = False,
+) -> dict:
+    """List the signed-in user's Teams chats (1:1, group, meeting).
+
+    Members are expanded so 1:1 chats (which have no topic) are identifiable
+    by participant name. Results come back in Graph's default order (most
+    recent message activity first).
+
+    Each item carries two timestamps; use the right one:
+    - last_message_time: created time of the most recent message (from the
+      expanded lastMessagePreview). This is the true "last activity" time.
+    - metadata_updated: Graph's lastUpdatedDateTime, which only changes on
+      rename/membership events (e.g. someone joining a meeting call), NOT on
+      new messages. Do not use it to judge recency -- a busy 1:1 can show a
+      months-old metadata_updated.
+
+    Args:
+        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.
+
+    Returns:
+        {"items": [trimmed_chat, ...], "next_page_token": str | None}
+    """
+    limit = validate_limit(limit)
+    builder = graph.raw.me.chats
+    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_chats_query(limit=limit))
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+
+    items = [trim_chat(chat_to_dict(c), include_raw=include_raw) for c in (collection.value or [])]
+    return {"items": items, "next_page_token": encode_next_link(getattr(collection, "odata_next_link", None))}
+
+
+async def list_chat_messages(
+    *,
+    graph,
+    chat_id: str,
+    limit: int = 25,
+    page_token: str | None = None,
+    include_body: bool = False,
+    include_raw: bool = False,
+) -> dict:
+    """List messages in a chat, newest first.
+
+    Args:
+        chat_id: Graph chat id (from list_chats).
+        limit: 1-100. 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)
+    builder = graph.raw.chats.by_chat_id(chat_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_chat_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))}
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="list_chats", description=list_chats.__doc__ or "")
+    async def _list_chats(limit: int = 25, page_token: str | None = None, include_raw: bool = False):
+        return await list_chats(graph=graph, limit=limit, page_token=page_token, include_raw=include_raw)
+
+    @mcp.tool(name="list_chat_messages", description=list_chat_messages.__doc__ or "")
+    async def _list_chat_messages(
+        chat_id: str,
+        limit: int = 25,
+        page_token: str | None = None,
+        include_body: bool = False,
+        include_raw: bool = False,
+    ):
+        return await list_chat_messages(
+            graph=graph, chat_id=chat_id, limit=limit,
+            page_token=page_token, include_body=include_body, include_raw=include_raw,
+        )

msgraph_mcp/tools/teams_content.py

@@ -0,0 +1,150 @@
+"""Teams inline hosted-content download.
+
+Inline images and other hosted content live behind an authenticated Graph
+endpoint (.../hostedContents/{id}/$value) that requires the server's
+delegated token, so an agent cannot fetch them directly. This tool proxies
+that authenticated fetch and returns base64, parallel to download_attachment
+for mail. SharePoint/OneDrive-backed file attachments are a different Graph
+surface and are out of scope (see README).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from msgraph_mcp.auth.token import NotAuthenticatedError
+from msgraph_mcp.graph.errors import GraphValidationError, map_kiota_error
+from msgraph_mcp.graph.trimming import trim_hosted_content_download
+from msgraph_mcp.tools import _binary
+
+
+def _sniff_content_type(data: bytes) -> str | None:
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def _hosted_content_builder(graph, *, chat_id, team_id, channel_id, message_id, hosted_content_id):
+    if chat_id is not None:
+        message = graph.raw.chats.by_chat_id(chat_id).messages.by_chat_message_id(message_id)
+    else:
+        message = (
+            graph.raw.teams.by_team_id(team_id)
+            .channels.by_channel_id(channel_id)
+            .messages.by_chat_message_id(message_id)
+        )
+    return message.hosted_contents.by_chat_message_hosted_content_id(hosted_content_id).content
+
+
+async def download_hosted_content(
+    *,
+    graph,
+    message_id: str,
+    hosted_content_id: str,
+    chat_id: str | None = None,
+    team_id: str | None = None,
+    channel_id: str | None = None,
+    save_path: str | None = None,
+    include_raw: bool = False,
+) -> dict | list:
+    """Download one inline hosted-content item (usually an image).
+
+    Specify the message location with exactly one of:
+      - chat_id (for a chat message), or
+      - team_id AND channel_id (for a channel message).
+
+    Get message_id and hosted_content_id from a message's hosted_content_refs
+    (returned by list_chat_messages / list_channel_messages / list_message_replies).
+
+    Args:
+        message_id: Graph id of the message the content is attached to.
+        hosted_content_id: Graph hosted-content id (from hosted_content_refs).
+        chat_id: Chat id, if the message is in a chat.
+        team_id: Team id, if the message is in a channel.
+        channel_id: Channel id, if the message is in a channel.
+        save_path: Write the bytes to this file path (or into this existing
+            directory) instead of returning content. Returns
+            {"path", "content_type", "size_bytes"} with no content payload.
+        include_raw: Include the raw payload under "raw" (ignored when the
+            result is an image block or a saved file).
+
+    Returns:
+        - Image content (PNG/JPEG/GIF/WebP, no save_path): metadata plus the
+          image itself as a native MCP image block, viewable directly.
+        - With save_path: {"path": str, "content_type": str | None, "size_bytes": int}.
+        - Otherwise: {"content_type": str | None, "size_bytes": int,
+          "content_base64": str | None}. content_type is sniffed from the
+          bytes (Graph does not return it on the $value endpoint); it may be
+          None for unrecognized formats.
+    """
+    has_chat = chat_id is not None
+    has_team = team_id is not None
+    has_channel = channel_id is not None
+    if has_chat and (has_team or has_channel):
+        raise GraphValidationError("Provide either chat_id or (team_id and channel_id), not both.")
+    if not has_chat and not (has_team and has_channel):
+        raise GraphValidationError(
+            "Provide a message location: chat_id, or both team_id and channel_id."
+        )
+
+    builder = _hosted_content_builder(
+        graph, chat_id=chat_id, team_id=team_id, channel_id=channel_id,
+        message_id=message_id, hosted_content_id=hosted_content_id,
+    )
+    try:
+        data = await builder.get()
+    except NotAuthenticatedError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+
+    if not isinstance(data, (bytes, bytearray)):
+        raw = {"contentType": None, "size": 0, "contentBytes": None}
+        return trim_hosted_content_download(raw, include_raw=include_raw)
+
+    data = bytes(data)
+    content_type = _sniff_content_type(data)
+
+    if save_path is not None:
+        # hosted_content_id is opaque base64 (unsafe as a filename); hash it.
+        digest = hashlib.sha256(hosted_content_id.encode()).hexdigest()[:8]
+        ext = _binary.ext_for(content_type)
+        default_name = f"hosted-content-{message_id}-{digest}{ext}"
+        path = _binary.write_bytes(save_path, data, default_name=default_name)
+        return {"path": path, "content_type": content_type, "size_bytes": len(data)}
+
+    if _binary.is_image(content_type):
+        meta = {"content_type": content_type, "size_bytes": len(data)}
+        return _binary.image_result(meta, data, content_type)
+
+    raw = {
+        "contentType": content_type,
+        "size": len(data),
+        "contentBytes": base64.b64encode(data).decode("ascii"),
+    }
+    return trim_hosted_content_download(raw, include_raw=include_raw)
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="download_hosted_content", description=download_hosted_content.__doc__ or "")
+    async def _download_hosted_content(
+        message_id: str,
+        hosted_content_id: str,
+        chat_id: str | None = None,
+        team_id: str | None = None,
+        channel_id: str | None = None,
+        save_path: str | None = None,
+        include_raw: bool = False,
+    ):
+        return await download_hosted_content(
+            graph=graph, message_id=message_id, hosted_content_id=hosted_content_id,
+            chat_id=chat_id, team_id=team_id, channel_id=channel_id,
+            save_path=save_path, include_raw=include_raw,
+        )

msgraph_mcp/tools/util.py

@@ -0,0 +1,35 @@
+"""Utility tools (whoami)."""
+
+from __future__ import annotations
+
+from msgraph_mcp.auth.token import NotAuthenticatedError
+from msgraph_mcp.graph.errors import map_kiota_error
+from msgraph_mcp.graph.serialize import user_to_dict
+from msgraph_mcp.graph.trimming import trim_user
+
+
+async def whoami(*, graph, include_raw: bool = False) -> dict:
+    """Return the signed-in user's profile.
+
+    Also a smoke test that authentication is working.
+
+    Args:
+        include_raw: when True, include the raw Graph payload under "raw".
+
+    Returns:
+        Trimmed user object: {id, display_name, user_principal_name, mail, job_title}
+    """
+    try:
+        user = await graph.mailbox(None).get()
+    except NotAuthenticatedError:
+        # Surface the login-required hint directly; don't wrap as a Graph error.
+        raise
+    except Exception as exc:  # noqa: BLE001
+        raise map_kiota_error(exc) from exc
+    return trim_user(user_to_dict(user), include_raw=include_raw)
+
+
+def register(mcp, *, graph) -> None:
+    @mcp.tool(name="whoami", description=whoami.__doc__ or "")
+    async def _whoami(include_raw: bool = False) -> dict:
+        return await whoami(graph=graph, include_raw=include_raw)

msgraph_mcp_server-0.3.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: msgraph-mcp-server
+Version: 0.3.0
+Summary: MCP server for Microsoft Graph: Outlook mail and calendar, plus read-only Microsoft Teams
+Project-URL: Homepage, https://github.com/timfurlong/msgraph-mcp
+Project-URL: Repository, https://github.com/timfurlong/msgraph-mcp
+Project-URL: Issues, https://github.com/timfurlong/msgraph-mcp/issues
+Author: Tim Furlong
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,email,mcp,microsoft-graph,model-context-protocol,outlook,teams
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: msal>=1.31
+Requires-Dist: msgraph-sdk>=1.0
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# MSGraph MCP
+
+<!-- mcp-name: io.github.timfurlong/msgraph-mcp -->
+
+A Model Context Protocol (MCP) server for **Microsoft Graph**. It exposes Microsoft Outlook **mail** and **calendar**, plus read-only Microsoft **Teams** message history, to AI agents via the Microsoft Graph SDK. Acts as the signed-in user (delegated permissions, MSAL device code flow).
+
+> Formerly published as `outlook-mcp`. Renamed because the scope grew beyond Outlook (Teams today, potentially other Graph surfaces later). Outlook mail and calendar remain first-class capabilities. See [Migrating from outlook-mcp](#migrating-from-outlook-mcp).
+
+## What it does
+
+Workflow-oriented tools covering common mail, calendar, and read-only Teams operations:
+
+| Group          | Tools                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Util           | `whoami`                                                                                                                                               |
+| Mail — read    | `list_messages`, `search_messages`, `get_message`, `list_attachments`, `download_attachment`                                                           |
+| Mail — write   | `send_message`, `create_draft`, `reply_message`, `reply_all_message`, `forward_message`, `update_message`, `delete_message`                            |
+| Mail — folders | `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `move_message`                                                                      |
+| Mail — actions | `archive_message`, `mark_read`, `mark_unread`, `flag_message`, `unflag_message`                                                                        |
+| Mail — rules   | `list_rules`, `get_rule`, `create_rule`, `update_rule`, `delete_rule`                                                                                  |
+| Calendar       | `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event`, `cancel_event`, `respond_to_event`, `find_meeting_times` |
+| Teams (read)   | `list_chats`, `list_chat_messages`, `list_joined_teams`, `list_channels`, `list_channel_messages`, `list_message_replies`, `download_hosted_content`      |
+
+Every tool that touches a mailbox or calendar accepts an optional `mailbox` argument (email or user ID) to target shared mailboxes/calendars. Omit it to use the signed-in user's own mailbox.
+
+Every tool that returns objects accepts `include_raw=true` to also include the full Graph payload.
+
+List/search tools support pagination via `limit` (1-100, default 25) and `page_token`.
+
+## Prerequisites
+
+- Python ≥ 3.11
+- `uv`: https://docs.astral.sh/uv/
+- An Entra (Azure AD) app registration with the right permissions (see "Entra setup" below)
+
+## Install
+
+From PyPI (package `msgraph-mcp-server`; the commands it installs are `msgraph-mcp` and `msgraph-mcp-login`):
+
+```bash
+uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server
+```
+
+Then use `msgraph-mcp-login` / `msgraph-mcp` directly wherever the quickstart below says `uv run ...`, and wire the host with `claude mcp add msgraph -- msgraph-mcp`.
+
+## Quickstart (from source)
+
+```bash
+# 1. Install dependencies
+uv sync
+
+# 2. Configure environment
+cp .env.example .env
+# Fill in MSGRAPH_MCP_CLIENT_ID and MSGRAPH_MCP_TENANT_ID
+
+# 3. One-time sign-in (device code flow)
+uv run msgraph-mcp-login
+# Follow the prompt: visit the URL, enter the code, complete sign-in.
+# A token cache is written to ~/.msgraph-mcp/token_cache.bin (mode 0600).
+
+# 4. Wire the MCP into your host
+# - Claude Code:
+claude mcp add msgraph -- uv --directory "$(pwd)" run msgraph-mcp
+
+# - Anything else: configure the host to launch `uv run msgraph-mcp` (stdio).
+```
+
+## Entra setup
+
+The app registration (e.g. "MSGraph MCP") requires:
+
+- **Account type:** single tenant
+- **Redirect URI (public client):** `https://login.microsoftonline.com/common/oauth2/nativeclient`
+- **Delegated permissions** (Microsoft Graph):
+  - `Mail.ReadWrite`
+  - `Mail.ReadWrite.Shared`
+  - `Mail.Send`
+  - `MailboxSettings.ReadWrite`
+  - `Calendars.ReadWrite`
+  - `Calendars.ReadWrite.Shared`
+  - `User.Read`
+  - `Chat.Read` (Teams)
+  - `Team.ReadBasic.All` (Teams)
+  - `Channel.ReadBasic.All` (Teams)
+  - `ChannelMessage.Read.All` (Teams)
+- Admin consent: required for `ChannelMessage.Read.All` (always), plus the `*.Shared` permissions if your tenant requires it.
+
+> If you signed in before any of these scopes were added to the app (for example `MailboxSettings.ReadWrite`, or the Teams scopes), re-run `uv run msgraph-mcp-login` so the cached token picks up the new scopes. Without them, calls needing the missing scope fail with a consent error.
+
+The CLI uses public-client device code flow — **no client secret** is needed or stored.
+
+## Environment variables
+
+| Var                            | Required | Default                          | Purpose                             |
+| ------------------------------ | -------- | -------------------------------- | ----------------------------------- |
+| `MSGRAPH_MCP_CLIENT_ID`        | yes      | —                                | Entra (Azure AD) app client ID      |
+| `MSGRAPH_MCP_TENANT_ID`        | yes      | —                                | Tenant ID (single-tenant authority) |
+| `MSGRAPH_MCP_TOKEN_CACHE_PATH` | no       | `~/.msgraph-mcp/token_cache.bin` | Override token cache file location  |
+
+Process env wins; `.env` at the repo root is loaded as a dev fallback.
+
+Legacy `OUTLOOK_MCP_*` names are honored as a fallback for each variable (the `MSGRAPH_MCP_*` name wins when both are set).
+
+## Migrating from outlook-mcp
+
+This project was named `outlook-mcp` through v0.2.0. What changed in the rename:
+
+| Old                                | New                                |
+| ---------------------------------- | ---------------------------------- |
+| package `outlook-mcp`              | package `msgraph-mcp`              |
+| module `outlook_mcp`               | module `msgraph_mcp`               |
+| `uv run outlook-mcp`               | `uv run msgraph-mcp`               |
+| `uv run outlook-mcp-login`         | `uv run msgraph-mcp-login`         |
+| `OUTLOOK_MCP_*` env vars           | `MSGRAPH_MCP_*` env vars           |
+| `~/.outlook-mcp/token_cache.bin`   | `~/.msgraph-mcp/token_cache.bin`   |
+
+Backward compatibility, so an existing setup keeps working without re-authenticating:
+
+- `OUTLOOK_MCP_*` env vars are still read as a fallback.
+- If `~/.msgraph-mcp/token_cache.bin` does not exist but `~/.outlook-mcp/token_cache.bin` does, the legacy cache is used. To move to the new location: `mv ~/.outlook-mcp ~/.msgraph-mcp`.
+
+You do need to update anything that launches the server by script name (MCP host configs): `outlook-mcp` → `msgraph-mcp`.
+
+## Security
+
+- The token cache contains your **refresh token**, which can mint access tokens for your mail, calendar, and Teams data. Treat it like a credential.
+- Default location: `~/.msgraph-mcp/token_cache.bin`, mode `0600`, parent dir mode `0700`.
+- To **revoke** access: sign in to https://account.microsoft.com or your org's identity portal, revoke the app, then `rm ~/.msgraph-mcp/token_cache.bin`.
+- To **switch accounts**: `rm ~/.msgraph-mcp/token_cache.bin` and re-run `msgraph-mcp-login`.
+
+## Recipes
+
+### Route a sender into a new folder
+
+```
+# 1. Make a folder for the notifications.
+create_folder(display_name="Notifications")
+# -> {"id": "AAMkFolderId", "display_name": "Notifications", ...}
+
+# 2. Create an inbox rule that moves matching senders into it.
+create_rule(
+    display_name="Notifications",
+    sender_contains=["example.com"],
+    move_to_folder="AAMkFolderId",
+    stop_processing_rules=True,
+)
+```
+
+Conditions inside one rule are AND-ed by Outlook. Pass a list to a single condition (e.g. `sender_contains=["example.com", "monitor.io"]`) for OR within that condition. Rules only run against the inbox — Graph's `messageRules` endpoint is hardcoded there and does not support per-folder rules.
+
+`create_rule` requires at least one condition and one action. `update_rule` patches a rule in place but **replaces** the `conditions` or `actions` block whenever you pass any condition/action arg — call `get_rule` first if you need to preserve existing values.
+
+## Microsoft Teams (read-only)
+
+Read Teams message history as the signed-in user:
+
+- `list_chats`, `list_chat_messages`: your 1:1 and group chats.
+- `list_joined_teams`, `list_channels`, `list_channel_messages`, `list_message_replies`: team channels and their threads.
+- `download_hosted_content`: download an inline image referenced by a message (`hosted_content_refs`). Images come back as a native MCP image block the agent can view directly; pass `save_path` (file or existing directory) to write the bytes to disk and get back a path instead.
+
+### Permissions and consent
+
+These delegated scopes are required (already listed in `SCOPES`):
+
+- `Chat.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`: user-consentable.
+- `ChannelMessage.Read.All`: requires tenant administrator consent.
+
+Setup:
+
+1. Add the four delegated permissions to the app registration.
+2. Grant tenant admin consent for `ChannelMessage.Read.All`.
+3. Because the scope set changed, re-run the device-code login so the cached token carries the new scopes.
+
+### Notes and limits
+
+- Reading is delegated-only: you can read your own chats, not other users' chats.
+- Channel message and reply pages are capped at 50 by Graph.
+- SharePoint/OneDrive-backed file attachments are not downloadable here. In Teams, shared files are attachments whose `contentUrl` points into SharePoint, which is a different Graph surface (needs `Files.Read.All` / `Sites.Read.All` and the driveItem APIs). `download_hosted_content` covers inline hosted content (images), not shared files. This is deferred.
+
+## Future work
+
+Not implemented; reasonable additions:
+
+- **Graph `$batch` requests.** Performance optimization that bundles multiple Graph calls into one HTTP round-trip; would speed up multi-step workflows but adds complexity. Defer until profiling proves the win.
+
+Other known gaps (intentionally out of scope): chunked attachment upload (>3 MB), category master-list management, mail signatures, contacts/To-Do/OneNote, multi-account switching, change-notification subscriptions, force-delete of non-empty folders.
+
+## Development
+
+```bash
+# Run unit tests
+uv run pytest
+
+# Run unit + live integration smoke (requires a valid token cache)
+MSGRAPH_MCP_INTEGRATION=1 uv run pytest
+
+# Type check
+uv run pyright src tests
+
+# Lint
+uv run ruff check .
+```
+
+## Troubleshooting
+
+| Symptom                                                                                                     | Fix                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `NotAuthenticatedError: Not authenticated. Run \`msgraph-mcp-login\`...`                                    | Run `uv run msgraph-mcp-login`.                                                                                                                                                                                                                               |
+| `ConfigError: Missing required env var: MSGRAPH_MCP_CLIENT_ID`                                              | Set the var in `.env` or in your MCP host's env config.                                                                                                                                                                                                       |
+| `Graph API 403: ErrorAccessDenied — ...`                                                                    | Permission mismatch on the Entra app. Verify the delegated permissions list above and re-consent.                                                                                                                                                             |
+| `Graph API 400: BadRequest — Syntax error: character ... is not valid at position N` from `search_messages` | The query is passed to Graph's `$search` as-is. Wrap literal/multi-character tokens in double quotes (e.g. `"weekly report"`), or use KQL fielded forms (e.g. `from:alice subject:"report"`). Bare alphanumeric strings with embedded digits are invalid KQL. |
+| Server boots but tools 404 in the host                                                                      | Confirm the host is launching `uv run msgraph-mcp` with the right working directory.                                                                                                                                                                          |
+
+---
+
+Spec: `docs/specs/2026-05-19-outlook-mcp-design.md` (gitignored — local working doc).

msgraph_mcp_server-0.3.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+msgraph_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msgraph_mcp/config.py,sha256=VVw3qHv2Q16VjNQssa56zlcVNHMCPedakKHMe5yXRzE,2175
+msgraph_mcp/server.py,sha256=oiUxFJ_vMcqumqmonXN5meGZN6_5k3nk00e60z4A9Pk,2234
+msgraph_mcp/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msgraph_mcp/auth/cli.py,sha256=46izPWtNAaddzDeLgeM3luHD4rerRFVApYJ2x_01OA0,1270
+msgraph_mcp/auth/msal_app.py,sha256=LTiUEt5srNIQTFTtbPE6O6RhU_dLxFwKbfwI3PmC8BY,1652
+msgraph_mcp/auth/token.py,sha256=WJ438Avi7LDc5TZeXYNO7VLRraM0vlZPXQ1EX5rZVo4,986
+msgraph_mcp/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msgraph_mcp/graph/auth_provider.py,sha256=kaB3UYSeS0hDu3xGdJn6bm39HS0iIhut8dvLozvRwVs,1065
+msgraph_mcp/graph/batch.py,sha256=4bZedIQJBT5MaGz54r1L1afXsstx_4ZBEffPtqf9sqk,7412
+msgraph_mcp/graph/client.py,sha256=ZzaHNecrrS79gDDbGddgyuDoocd0hqB4Cq8tf_GX5yM,1108
+msgraph_mcp/graph/errors.py,sha256=93weFyp_QlVxoKVLMULGexTXUgpdx0Qm8F_5nQkpTiM,1525
+msgraph_mcp/graph/pagination.py,sha256=ITj63_VTMRmOdVvRLiaEQc7ucnubewiDtaOPiId-27g,1438
+msgraph_mcp/graph/serialize.py,sha256=8LakliwK7ldYL_y-x5atW2GDTKVPe0QBU6a5MhOIqKY,14288
+msgraph_mcp/graph/trimming.py,sha256=3e57kBe_1sXmo4zNeu3p0uCixmr19zXvQWXkra79JoM,13049
+msgraph_mcp/tools/__init__.py,sha256=qJbwUSS3BZyu-NFp20RWNPYZfJGO7XLt2N263rHS1N8,944
+msgraph_mcp/tools/_binary.py,sha256=7Gz4nZHwzPHi6-0UlkWC-ERx949s7DWcUB_j-yMmqJw,1582
+msgraph_mcp/tools/calendar.py,sha256=MMdTiBx1e4LC7rjULpdIXzftBiS57U65B3i5-rLPGtw,21208
+msgraph_mcp/tools/mail_actions.py,sha256=nib4cmd4HIgXGkIIqhfdnKBhcSS9UTjD_eA8G5ajzso,3464
+msgraph_mcp/tools/mail_batch.py,sha256=HJt4QLS-NjE5uJLsg6LUmeuAvckifPnDg5hh-kdIDsA,7457
+msgraph_mcp/tools/mail_folders.py,sha256=-i717AC9_f6j1P5MaLxQLta78kMgOpASSj459jE9wH4,9403
+msgraph_mcp/tools/mail_read.py,sha256=YpbsB9QM4PntT9iJ2arCzlEU65UKIVQXNUaIr0PLxIY,12027
+msgraph_mcp/tools/mail_rules.py,sha256=Gj5kbHYpNZ2Wdyiz8tFGfwY_zfScqT4JlufJWcAExPQ,17665
+msgraph_mcp/tools/mail_write.py,sha256=UoyD3IP90vPaTWGdU8kq7neDrNEQA4bQRk5jC_f5mx0,13979
+msgraph_mcp/tools/teams_channels.py,sha256=DzSwDhPwMedQqP31eKIwWQjJwwdzjwuylnGcWnUYL9U,9367
+msgraph_mcp/tools/teams_chats.py,sha256=eVm0-hkGkkWamm6rJojAZjIkH_uXv_wD1O3MdzPN_bs,5556
+msgraph_mcp/tools/teams_content.py,sha256=XpNnAIaaxux36wuP7kAnJcmoslAgMtQB9YVXVhhf6aA,6123
+msgraph_mcp/tools/util.py,sha256=fCAIZCxph47vA_APrIWD-Eb3-mHHg-Gsjw4Ff6_7_u4,1203
+msgraph_mcp_server-0.3.0.dist-info/METADATA,sha256=5Y4gBKk-Iuogwy4wunq5hynEySWefkrqWhwQGbj-6l4,14650
+msgraph_mcp_server-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+msgraph_mcp_server-0.3.0.dist-info/entry_points.txt,sha256=PMHqZ65ru-Znc4qmLqiCNBIpEN6OL6mRcK8RkDem2Nw,102
+msgraph_mcp_server-0.3.0.dist-info/licenses/LICENSE,sha256=0eHAEVNIZbTK0y1z0-MUmfjxhtN7bsJnJNCTieeHWgQ,1068
+msgraph_mcp_server-0.3.0.dist-info/RECORD,,

msgraph_mcp_server-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

msgraph_mcp_server-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+msgraph-mcp = msgraph_mcp.server:main
+msgraph-mcp-login = msgraph_mcp.auth.cli:main

msgraph_mcp_server-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Furlong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.