tools.microsoft_tools module

Microsoft Graph API tools using per-user OAuth tokens.

Provides OneDrive, Outlook, and Calendar operations via the Microsoft Graph API. Requires the user to have connected their Microsoft account via the OAuth flow.

async tools.microsoft_tools.microsoft_onedrive_list(path='', search='', limit=20, ctx=None)[source]

List files and folders in the calling user’s OneDrive.

Tool handler for microsoft_onedrive_list. Browses a folder, searches by name/content, or lists the drive root, returning a compact JSON summary of each child item (id, name, size, modified time, web URL, and folder/file type metadata). Path and search inputs are validated to reject newlines and .. traversal before building the Graph endpoint.

Resolves the user’s token via _get_token (returning the connect-link message on OAuthNotConnected) and queries the Graph search, /children, or root-children endpoint through _ms_request. Registered in this module’s TOOLS list and dispatched by tool_loader.py (via getattr(module, "TOOLS") → ToolDefinition.handler); no direct in-repo Python callers were found.

Parameters:

  • path (str) – OneDrive folder path to list (e.g. "Documents/Reports"); empty lists the drive root. Ignored when search is provided.

  • search (str) – Query to find files by name or content. Takes precedence over path when non-empty.

  • limit (int) – Maximum number of items to return (capped at 200 by the API call).

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string of the form {"count": int, "items": [...]} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_onedrive_read(item_id='', path='', ctx=None)[source]

Read a OneDrive file’s metadata and text content by item ID or path.

Tool handler for microsoft_onedrive_read. Fetches the item’s Graph metadata, then (if the item exposes a pre-authenticated @microsoft.graph.downloadUrl) downloads the body and decodes it as UTF-8, truncating to 16 000 characters. Either item_id or path must be supplied, and both are validated against traversal/newline injection.

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected), reads metadata through _ms_request, and downloads the content with a separate transient aiohttp.ClientSession against the Graph-issued download URL. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • item_id (str) – OneDrive item ID; mutually exclusive with path. Must not contain /, .., or newlines.

  • path (str) – File path (e.g. "Documents/notes.txt"); used when item_id is empty. Must not contain newlines or ...

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"metadata": {...}, "content": str} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_onedrive_upload(name, content, folder_path='', ctx=None)[source]

Upload a text file to the user’s OneDrive.

Tool handler for microsoft_onedrive_upload. Writes content to a new or overwritten file at name (optionally within folder_path) using a simple Graph content PUT. File name and folder are validated against newline/.. injection before the endpoint is built.

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and performs the upload through _ms_request with the UTF-8-encoded body and an application/octet-stream content type. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • name (str) – Destination file name. Must not contain newlines or ...

  • content (str) – Text content to upload; encoded as UTF-8 bytes.

  • folder_path (str) – Optional destination folder path; empty uploads to the drive root. Must not contain newlines or ...

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"status": "uploaded", "id": ..., "name": ..., "webUrl": ..., "size": ...} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_outlook_list(folder='inbox', search='', limit=15, skip=0, ctx=None)[source]

List messages from one of the user’s Outlook mail folders.

Tool handler for microsoft_outlook_list. Returns a compact JSON summary of messages (id, subject, from, to, received time, body preview, read flag, attachment flag) ordered newest-first, with optional Graph $search and pagination via skip.

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and queries /me/mailFolders/{folder}/messages through _ms_request using $top/$skip/$select/$orderby parameters. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • folder (str) – Mail folder to read ("inbox", "drafts", "sentitems", "deleteditems", etc.).

  • search (str) – Optional free-text Graph search query.

  • limit (int) – Maximum messages to return (capped at 50 by the API call).

  • skip (int) – Number of messages to skip for pagination.

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"count": int, "messages": [...]} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_outlook_read(message_id, ctx=None)[source]

Read a single Outlook email by message ID, returning its full body.

Tool handler for microsoft_outlook_read. Fetches the message via Graph and returns headers plus the body; HTML bodies are stripped of tags and whitespace-collapsed for readability, and the body is truncated to 16 000 characters.

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and fetches /me/messages/{message_id} through _ms_request. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • message_id (str) – The Outlook message ID to read.

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string with id, subject, from, to, receivedDateTime, body, and isRead on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_outlook_send(to, subject, body, content_type='Text', ctx=None)[source]

Send an email from the user’s Outlook account.

Tool handler for microsoft_outlook_send. Normalizes one or more recipients into Graph toRecipients entries and submits the message via the Graph sendMail action, which sends immediately (no draft step).

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and POSTs the message payload to /me/sendMail through _ms_request. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • to (str | list[str]) – A single recipient address or a list of addresses.

  • subject (str) – Email subject line.

  • body (str) – Email body content.

  • content_type (str) – Body format, "Text" (default) or "HTML".

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"status": "sent", "to": [...], "subject": ...} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_calendar_list(start_time='', end_time='', limit=20, ctx=None)[source]

List events from the user’s Microsoft/Outlook calendar.

Tool handler for microsoft_calendar_list. When both start_time and end_time are supplied it uses the Graph calendarView (which expands recurring events within the window); otherwise it lists raw events. Returns a compact JSON summary per event (subject, body preview, start/end with time zones, location, all-day flag, web link, and up to ten attendee addresses).

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and queries the chosen endpoint through _ms_request ordered by start time. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • start_time (str) – ISO 8601 start of the time range; with end_time switches to calendarView.

  • end_time (str) – ISO 8601 end of the time range.

  • limit (int) – Maximum events to return (capped at 100 by the API call).

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"count": int, "events": [...]} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str

async tools.microsoft_tools.microsoft_calendar_create(subject, start_time, start_timezone='UTC', end_time='', end_timezone='UTC', body='', location='', attendees=None, is_all_day=False, ctx=None)[source]

Create a new event on the user’s Microsoft/Outlook calendar.

Tool handler for microsoft_calendar_create. Builds a Graph event payload from the supplied subject, start/end times and time zones, and optional body, location, attendees, and all-day flag (each attendee added as a required invitee). When end_time is empty it defaults to start_time.

Resolves the token via _get_token (returning the connect-link message on OAuthNotConnected) and POSTs the event to /me/events through _ms_request. Registered in this module’s TOOLS list and dispatched by tool_loader.py; no direct in-repo Python callers were found.

Parameters:

  • subject (str) – Event title.

  • start_time (str) – ISO 8601 start time (e.g. "2025-03-15T10:00:00").

  • start_timezone (str) – Start time zone (default "UTC").

  • end_time (str) – ISO 8601 end time; defaults to start_time when empty.

  • end_timezone (str) – End time zone (default "UTC").

  • body (str) – Optional plain-text event description.

  • location (str) – Optional location display name.

  • attendees (list[str] | None) – Optional list of attendee email addresses (added as required).

  • is_all_day (bool) – Whether the event spans the whole day.

  • ctx (ToolContext | None) – The active ToolContext providing user identity and Redis.

Returns:

A JSON string {"status": "created", "id": ..., "subject": ..., "webLink": ..., "start": ..., "end": ...} on success, or a JSON {"error": ...} / connect-link string on failure.

Return type:

str