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

msgraph_mcp/auth/cli.py

@@ -0,0 +1,45 @@
+"""msgraph-mcp-login entry point: runs the device code flow interactively."""
+
+from __future__ import annotations
+
+import sys
+
+from msgraph_mcp import config
+from msgraph_mcp.auth.msal_app import build_app, persist_cache
+
+
+def run_login() -> int:
+    app, cache = build_app()
+    flow = app.initiate_device_flow(scopes=config.SCOPES)
+    if "user_code" not in flow:
+        print(
+            f"Failed to start device flow: {flow.get('error', flow)}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Message contains the verification URL and the code; print to stdout
+    # so the user sees it in their terminal.
+    print(flow["message"], flush=True)
+
+    result = app.acquire_token_by_device_flow(flow)  # blocks until user completes flow
+    if "error" in result:
+        print(
+            f"Login failed: {result['error']} — {result.get('error_description', '')}",
+            file=sys.stderr,
+        )
+        return 1
+
+    persist_cache(cache)
+
+    username = (
+        result.get("id_token_claims", {}).get("preferred_username")
+        or "<unknown>"
+    )
+    print(f"Logged in as {username}", flush=True)
+    print(f"Token cache saved to {config.token_cache_path()}", flush=True)
+    return 0
+
+
+def main() -> None:
+    sys.exit(run_login())

msgraph_mcp/auth/msal_app.py

@@ -0,0 +1,47 @@
+"""MSAL PublicClientApplication builder + token cache persistence."""
+
+from __future__ import annotations
+
+import os
+
+import msal
+
+from msgraph_mcp import config
+
+
+def build_app() -> tuple[msal.PublicClientApplication, msal.SerializableTokenCache]:
+    """Build the MSAL PublicClientApplication and bind a SerializableTokenCache.
+
+    Returns the (app, cache) tuple. The cache is loaded from disk if a cache
+    file exists at the configured path; otherwise it starts empty.
+
+    Call persist_cache(cache) after any operation that may have mutated it
+    (acquire_token_silent rotates refresh tokens; the cache reports
+    has_state_changed=True in that case).
+    """
+    cache = msal.SerializableTokenCache()
+    cache_path = config.token_cache_path()
+    if cache_path.exists():
+        cache.deserialize(cache_path.read_text())
+    app = msal.PublicClientApplication(
+        client_id=config.client_id(),
+        authority=config.authority(),
+        token_cache=cache,
+    )
+    return app, cache
+
+
+def persist_cache(cache: msal.SerializableTokenCache) -> None:
+    """Write the cache to disk with 0600 permissions, creating parent dirs at 0700.
+
+    Safe to call even if has_state_changed is False; we always write to keep
+    behavior simple and predictable. Caller may guard with `if cache.has_state_changed`
+    if write frequency matters.
+    """
+    cache_path = config.token_cache_path()
+    parent = cache_path.parent
+    parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    # Ensure parent dir perms even if it already existed
+    os.chmod(parent, 0o700)
+    cache_path.write_text(cache.serialize())
+    os.chmod(cache_path, 0o600)

msgraph_mcp/auth/token.py

@@ -0,0 +1,32 @@
+"""Silent token acquisition for the running MCP server.
+
+The server NEVER runs device code flow. If silent acquisition fails,
+get_access_token raises NotAuthenticatedError pointing at the login CLI.
+"""
+
+from __future__ import annotations
+
+from msgraph_mcp import config
+from msgraph_mcp.auth.msal_app import build_app, persist_cache
+
+
+class NotAuthenticatedError(RuntimeError):
+    """Raised when no valid token is available and silent refresh failed."""
+
+
+_LOGIN_HINT = (
+    "Not authenticated. Run `msgraph-mcp-login` in a terminal to sign in."
+)
+
+
+def get_access_token() -> str:
+    app, cache = build_app()
+    accounts = app.get_accounts()
+    if not accounts:
+        raise NotAuthenticatedError(_LOGIN_HINT)
+    result = app.acquire_token_silent(config.SCOPES, account=accounts[0])
+    if not result or "access_token" not in result:
+        raise NotAuthenticatedError(_LOGIN_HINT)
+    if cache.has_state_changed:
+        persist_cache(cache)
+    return result["access_token"]

msgraph_mcp/config.py

@@ -0,0 +1,79 @@
+"""Configuration loading for msgraph_mcp.
+
+Env vars are read once at import-side via require_env. Values are sourced from
+the process environment with .env as a fallback (process wins via override=False).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+# Load .env once at module import; process env takes precedence.
+load_dotenv(override=False)
+
+
+SCOPES: list[str] = [
+    "Mail.ReadWrite",
+    "Mail.ReadWrite.Shared",
+    "Mail.Send",
+    "Calendars.ReadWrite",
+    "Calendars.ReadWrite.Shared",
+    "MailboxSettings.ReadWrite",
+    "User.Read",
+    # Teams read-history (ChannelMessage.Read.All requires tenant admin consent)
+    "Chat.Read",
+    "Team.ReadBasic.All",
+    "Channel.ReadBasic.All",
+    "ChannelMessage.Read.All",
+]
+
+
+DEFAULT_CACHE_PATH = Path.home() / ".msgraph-mcp" / "token_cache.bin"
+
+# Pre-rename (outlook-mcp) locations, honored so existing setups keep working.
+LEGACY_CACHE_PATH = Path.home() / ".outlook-mcp" / "token_cache.bin"
+_LEGACY_ENV_PREFIX = "OUTLOOK_MCP_"
+
+
+class ConfigError(RuntimeError):
+    """Raised when required configuration is missing or invalid."""
+
+
+def _env(name: str) -> str | None:
+    """Read an MSGRAPH_MCP_* env var, falling back to its legacy OUTLOOK_MCP_* name."""
+    value = os.environ.get(name)
+    if value:
+        return value
+    return os.environ.get(name.replace("MSGRAPH_MCP_", _LEGACY_ENV_PREFIX, 1))
+
+
+def require_env(name: str) -> str:
+    value = _env(name)
+    if not value:
+        raise ConfigError(
+            f"Missing required env var: {name}. "
+            f"Set it in the process env or in a .env file at the repo root."
+        )
+    return value
+
+
+def token_cache_path() -> Path:
+    override = _env("MSGRAPH_MCP_TOKEN_CACHE_PATH")
+    if override:
+        return Path(override).expanduser()
+    if not DEFAULT_CACHE_PATH.exists() and LEGACY_CACHE_PATH.exists():
+        return LEGACY_CACHE_PATH
+    return DEFAULT_CACHE_PATH
+
+
+def authority() -> str:
+    tenant = require_env("MSGRAPH_MCP_TENANT_ID")
+    return f"https://login.microsoftonline.com/{tenant}"
+
+
+def client_id() -> str:
+    return require_env("MSGRAPH_MCP_CLIENT_ID")

msgraph_mcp/graph/auth_provider.py

@@ -0,0 +1,29 @@
+"""Bridge our MSAL silent-acquire flow into msgraph-sdk via TokenCredential.
+
+msgraph-sdk's GraphServiceClient takes an azure-core TokenCredential and
+calls .get_token(*scopes) on every authenticated request. We ignore the
+scopes argument — our MSAL PublicClientApplication is pre-configured with
+the right delegated scopes during login, and the cached token already has
+the correct audience.
+"""
+
+from __future__ import annotations
+
+import time
+
+from azure.core.credentials import AccessToken, TokenCredential
+
+from msgraph_mcp.auth.token import get_access_token
+
+
+# Short expiry: MSAL's cache handles real refresh. Each get_token call goes
+# through get_access_token() which calls acquire_token_silent (cheap, cached).
+_BUFFER_SECONDS = 300
+
+
+class MsalTokenCredential(TokenCredential):
+    """TokenCredential that delegates to our MSAL silent-acquire pipeline."""
+
+    def get_token(self, *scopes: str, **kwargs) -> AccessToken:  # type: ignore[override]
+        token = get_access_token()
+        return AccessToken(token, int(time.time() + _BUFFER_SECONDS))

msgraph_mcp/graph/batch.py

@@ -0,0 +1,206 @@
+"""Graph $batch executor.
+
+Provides a generic chunked batch executor against Microsoft Graph's /$batch
+endpoint, decoupled from the SDK via the BatchTransport protocol so it can
+be unit-tested with a fake transport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class BatchRequest:
+    """A single sub-request to include in a Graph $batch call."""
+
+    id: str
+    method: str
+    url: str
+    body: dict[str, Any] | None = None
+    headers: dict[str, str] | None = None
+
+
+@dataclass
+class BatchResult:
+    """Per-sub-request outcome, in the same order as the caller's input."""
+
+    id: str
+    ok: bool
+    status: int = 0
+    error: str | None = None
+    body: dict[str, Any] | None = None
+
+
+@runtime_checkable
+class BatchTransport(Protocol):
+    """Minimal HTTP transport for Graph $batch.
+
+    Implementations POST the payload to https://graph.microsoft.com/v1.0/$batch
+    and return the parsed JSON body.
+    """
+
+    async def post_batch(self, payload: dict[str, Any]) -> dict[str, Any]: ...
+
+
+async def execute_batch(
+    transport: BatchTransport,
+    requests: list[BatchRequest],
+    *,
+    chunk_size: int = 20,
+) -> list[BatchResult]:
+    """Execute Graph $batch in chunks. Preserves input order in results.
+
+    Sub-requests within a single $batch are numbered "1", "2", ... per chunk;
+    that numbering is internal to the executor and never exposed to callers.
+    """
+    if not requests:
+        return []
+
+    results_by_id: dict[str, BatchResult] = {}
+
+    for chunk in _chunked(requests, chunk_size):
+        subid_to_caller: dict[str, str] = {}
+        payload_requests: list[dict[str, Any]] = []
+        for i, req in enumerate(chunk, start=1):
+            sub_id = str(i)
+            subid_to_caller[sub_id] = req.id
+            entry: dict[str, Any] = {
+                "id": sub_id,
+                "method": req.method,
+                "url": req.url,
+            }
+            if req.body is not None:
+                entry["body"] = req.body
+                entry["headers"] = {"Content-Type": "application/json"}
+            if req.headers:
+                merged = dict(entry.get("headers", {}))
+                merged.update(req.headers)
+                entry["headers"] = merged
+            payload_requests.append(entry)
+
+        response = await transport.post_batch({"requests": payload_requests})
+
+        throttled = _throttled_entries(response, payload_requests)
+        if throttled:
+            wait = _max_retry_after(response.get("responses", []))
+            await asyncio.sleep(wait or 0)
+            # Renumber the retry chunk starting at 1 again.
+            retry_payload_requests: list[dict[str, Any]] = []
+            retry_subid_to_caller: dict[str, str] = {}
+            for j, orig in enumerate(throttled, start=1):
+                new_sub_id = str(j)
+                retry_subid_to_caller[new_sub_id] = subid_to_caller[orig["id"]]
+                retry_payload_requests.append({**orig, "id": new_sub_id})
+            retry_response = await transport.post_batch({"requests": retry_payload_requests})
+
+            # Merge non-throttled originals with retry results.
+            keep = [r for r in response.get("responses", []) if r.get("status") != 429]
+            for sub in keep:
+                caller_id = subid_to_caller.get(str(sub.get("id")))
+                if caller_id is not None:
+                    results_by_id[caller_id] = _sub_to_result(caller_id, sub)
+            for sub in retry_response.get("responses", []):
+                caller_id = retry_subid_to_caller.get(str(sub.get("id")))
+                if caller_id is not None:
+                    results_by_id[caller_id] = _sub_to_result(caller_id, sub)
+        else:
+            for sub in response.get("responses", []):
+                caller_id = subid_to_caller.get(str(sub.get("id")))
+                if caller_id is not None:
+                    results_by_id[caller_id] = _sub_to_result(caller_id, sub)
+
+    # Preserve input order; fill in any missing as failures.
+    out: list[BatchResult] = []
+    for req in requests:
+        out.append(
+            results_by_id.get(req.id)
+            or BatchResult(id=req.id, ok=False, status=0, error="No response from $batch")
+        )
+    return out
+
+
+def _chunked(xs: list[BatchRequest], n: int) -> Iterator[list[BatchRequest]]:
+    for i in range(0, len(xs), n):
+        yield xs[i : i + n]
+
+
+def _sub_to_result(caller_id: str, sub: dict[str, Any]) -> BatchResult:
+    status = int(sub.get("status") or 0)
+    ok = 200 <= status < 300
+    body = sub.get("body") if isinstance(sub.get("body"), dict) else None
+    error = None if ok else _format_error(status, body)
+    return BatchResult(id=caller_id, ok=ok, status=status, error=error, body=body)
+
+
+def _format_error(status: int, body: dict[str, Any] | None) -> str:
+    if isinstance(body, dict):
+        err = body.get("error", {}) if isinstance(body.get("error"), dict) else {}
+        code = err.get("code", "")
+        message = err.get("message", "")
+        prefix = " ".join(filter(None, [str(status), code]))
+        return f"{prefix}: {message}" if message else prefix
+    return str(status)
+
+
+def _throttled_entries(response: dict[str, Any], payload_requests: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return the original payload entries whose responses came back 429."""
+    throttled_ids = {
+        str(r.get("id"))
+        for r in response.get("responses", [])
+        if r.get("status") == 429
+    }
+    return [p for p in payload_requests if p["id"] in throttled_ids]
+
+
+def _max_retry_after(responses: list[dict[str, Any]]) -> float | None:
+    max_ra: float | None = None
+    for r in responses:
+        if r.get("status") != 429:
+            continue
+        ra = (r.get("headers") or {}).get("Retry-After")
+        if ra is None:
+            continue
+        try:
+            v = float(ra)
+        except (TypeError, ValueError):
+            continue
+        if max_ra is None or v > max_ra:
+            max_ra = v
+    return max_ra
+
+
+class GraphBatchTransport:
+    """Default BatchTransport using msgraph-sdk's request adapter.
+
+    Posts to https://graph.microsoft.com/v1.0/$batch and returns the parsed
+    JSON. Reuses the existing GraphClient's auth and retry policy.
+
+    Implementation note: if msgraph-sdk grows first-class batch primitives
+    (BatchRequestContentCollection / BatchResponseContent) that fit the
+    BatchTransport contract more cleanly, this class is the only place that
+    needs to change.
+    """
+
+    GRAPH_BATCH_URL = "https://graph.microsoft.com/v1.0/$batch"
+
+    def __init__(self, graph) -> None:
+        self._graph = graph
+
+    async def post_batch(self, payload: dict[str, Any]) -> dict[str, Any]:
+        import json
+
+        from kiota_abstractions.method import Method  # type: ignore[import-untyped]
+        from kiota_abstractions.request_information import RequestInformation  # type: ignore[import-untyped]
+
+        ri = RequestInformation()
+        ri.url = self.GRAPH_BATCH_URL
+        ri.http_method = Method.POST
+        ri.headers.try_add("Content-Type", "application/json")
+        ri.content = json.dumps(payload).encode("utf-8")
+
+        raw = await self._graph.raw.request_adapter.send_primitive_async(ri, "bytes", {})
+        return json.loads(raw)

msgraph_mcp/graph/client.py

@@ -0,0 +1,37 @@
+"""Small wrapper around msgraph-sdk's GraphServiceClient.
+
+Centralizes:
+  - GraphServiceClient construction with our MsalTokenCredential
+  - /me vs /users/{id} routing for shared mailboxes/calendars
+  - A handle to the raw SDK client for cases that need it directly
+"""
+
+from __future__ import annotations
+
+from msgraph.graph_service_client import GraphServiceClient
+
+from msgraph_mcp import config
+from msgraph_mcp.graph.auth_provider import MsalTokenCredential
+
+
+class GraphClient:
+    def __init__(self) -> None:
+        self._sdk = GraphServiceClient(
+            credentials=MsalTokenCredential(),
+            scopes=config.SCOPES,
+        )
+
+    @property
+    def raw(self) -> GraphServiceClient:
+        return self._sdk
+
+    def mailbox(self, mailbox: str | None):
+        """Return the builder rooted at /me or /users/{mailbox}.
+
+        Use it like:
+            await graph.mailbox(mailbox).messages.get(...)
+            await graph.mailbox(mailbox).calendar.events.get(...)
+        """
+        if mailbox is None:
+            return self._sdk.me
+        return self._sdk.users.by_user_id(mailbox)

msgraph_mcp/graph/errors.py

@@ -0,0 +1,43 @@
+"""Graph error mapping.
+
+Kiota / msgraph-sdk raises a variety of exception shapes for HTTP errors.
+We normalize them into a single GraphAPIError class that the tool layer
+can catch and turn into a clean MCP tool error.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class GraphValidationError(RuntimeError):
+    """Raised when tool params fail validation before the Graph call."""
+
+
+class GraphAPIError(RuntimeError):
+    """Raised when Graph returns a non-success response."""
+
+    def __init__(self, *, status: int, code: str, message: str) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"Graph API {status}: {code} — {message}")
+
+
+def map_kiota_error(exc: Any) -> GraphAPIError:
+    """Map an arbitrary kiota/msgraph exception into a GraphAPIError.
+
+    Kiota's ODataError exposes:
+      - response_status_code: int
+      - error: object with .code (str) and .message (str)
+    Some lower-level errors only expose a status and a string. For anything
+    we can't introspect, fall back to status=0 and stringify the exception.
+    """
+    status = int(getattr(exc, "response_status_code", 0) or 0)
+    inner = getattr(exc, "error", None)
+    code = "Unknown"
+    message = str(exc) if status == 0 else f"HTTP {status}"
+    if inner is not None:
+        code = getattr(inner, "code", code) or code
+        message = getattr(inner, "message", message) or message
+    return GraphAPIError(status=status, code=code, message=message)

msgraph_mcp/graph/pagination.py

@@ -0,0 +1,47 @@
+"""Opaque pagination tokens and limit validation.
+
+The agent never sees raw @odata.nextLink URLs. We base64-encode the URL
+and validate on decode that it points at graph.microsoft.com.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from urllib.parse import urlparse
+
+from msgraph_mcp.graph.errors import GraphValidationError
+
+
+_ALLOWED_HOSTS = {"graph.microsoft.com"}
+
+
+def encode_next_link(url: str | None) -> str | None:
+    if not url:
+        return None
+    return base64.urlsafe_b64encode(url.encode("utf-8")).decode("ascii").rstrip("=")
+
+
+def decode_page_token(token: str) -> str:
+    try:
+        # Re-pad
+        padded = token + "=" * (-len(token) % 4)
+        raw = base64.urlsafe_b64decode(padded.encode("ascii"))
+        url = raw.decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError) as exc:
+        raise GraphValidationError(f"Invalid page_token: {exc}") from exc
+
+    parsed = urlparse(url)
+    if parsed.scheme != "https" or parsed.hostname not in _ALLOWED_HOSTS:
+        raise GraphValidationError(
+            f"Invalid page_token: must point at graph.microsoft.com (got {parsed.hostname!r})"
+        )
+    return url
+
+
+def validate_limit(limit: int, *, maximum: int = 100) -> int:
+    if not isinstance(limit, int) or limit < 1 or limit > maximum:
+        raise GraphValidationError(
+            f"limit must be an integer in 1..{maximum} (got {limit!r})"
+        )
+    return limit