universal-mcp-applications 0.1.25__py3-none-any.whl → 0.1.26__py3-none-any.whl

universal_mcp/applications/outlook/app.py

@@ -10,143 +10,176 @@ class OutlookApp(APIApplication):
         super().__init__(name="outlook", integration=integration, **kwargs)
         self.base_url = "https://graph.microsoft.com/v1.0"
 
-    def reply_to_message(
+    def reply_to_email(
         self,
         message_id: str,
+        comment: str,
         user_id: str | None = None,
-        comment: str | None = None,
-        message: dict[str, Any] | None = None,
-    ) -> Any:
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
         """
-        Replies to an email using its message ID, with either a simple comment or a full message object including attachments. Unlike `send_mail`, which creates a new email, this function targets an existing message. It defaults to the current user if no user ID is specified.
+        Replies to a specific email message.
 
         Args:
-            message_id (string): message-id
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            comment (string): A comment to include in the reply. Example: 'Thank you for your email. Here is my reply.'.
-            message (object): A message object to specify additional properties for the reply, such as attachments. Example: {'subject': 'RE: Project Update', 'body': {'contentType': 'Text', 'content': 'Thank you for the update. Looking forward to the next steps.'}, 'toRecipients': [{'emailAddress': {'address': 'alice@contoso.com'}}], 'attachments': [{'@odata.type': '#microsoft.graph.fileAttachment', 'name': 'agenda.pdf', 'contentType': 'application/pdf', 'contentBytes': 'SGVsbG8gV29ybGQh'}]}.
+            message_id (str): The ID of the email message to reply to.
+            comment (str): The body of the reply.
+            user_id (str, optional): The ID of the user to send the reply from. Defaults to the authenticated user.
+            attachments (list[dict[str, Any]], optional): A list of attachment objects to include in the reply.
+                Each attachment dictionary should conform to the Microsoft Graph API specification.
+                Example:
+                [
+                    {
+                        "@odata.type": "#microsoft.graph.fileAttachment",
+                        "name": "attachment.txt",
+                        "contentType": "text/plain",
+                        "contentBytes": "SGVsbG8gV29ybGQh"
+                    }
+                ]
 
         Returns:
-            Any: Success
+            dict[str, Any]: A dictionary confirming the reply action.
 
         Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
+            HTTPStatusError: If the API request fails.
+            ValueError: If the user_id cannot be retrieved or message_id is missing.
 
         Tags:
-            users.message, important
+            important
         """
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        if message_id is None:
-            raise ValueError("Missing required parameter 'message-id'.")
-        request_body_data = None
-        request_body_data = {
-            "comment": comment,
-            "message": message,
-        }
-        request_body_data = {k: v for k, v in request_body_data.items() if v is not None}
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+        if not message_id:
+            raise ValueError("Missing required parameter 'message_id'.")
+
+        request_body_data = {"comment": comment}
+        if attachments:
+            request_body_data["message"] = {"attachments": attachments}
+
         url = f"{self.base_url}/users/{user_id}/messages/{message_id}/reply"
-        query_params = {}
+
         response = self._post(
             url,
             data=request_body_data,
-            params=query_params,
+            params={},
             content_type="application/json",
         )
         return self._handle_response(response)
 
-    def send_mail(
+    def send_email(
         self,
-        message: dict[str, Any],
+        subject: str,
+        body: str,
+        to_recipients: list[str],
         user_id: str | None = None,
-        saveToSentItems: bool | None = None,
-    ) -> Any:
+        cc_recipients: list[str] | None = None,
+        bcc_recipients: list[str] | None = None,
+        attachments: list[dict[str, Any]] | None = None,
+        body_content_type: str = "Text",
+        save_to_sent_items: bool = True,
+    ) -> dict[str, Any]:
         """
-        Sends a new email on behalf of a specified or current user, using a dictionary for content like recipients and subject. Unlike `reply_to_message`, which replies to an existing message, this function composes and sends an entirely new email from scratch.
+        Sends a new email.
 
         Args:
-            message (object): message Example: {'subject': 'Meet for lunch?', 'body': {'contentType': 'Text', 'content': 'The new cafeteria is open.'}, 'toRecipients': [{'emailAddress': {'address': 'frannis@contoso.com'}}], 'ccRecipients': [{'emailAddress': {'address': 'danas@contoso.com'}}], 'bccRecipients': [{'emailAddress': {'address': 'bccuser@contoso.com'}}], 'attachments': [{'@odata.type': '#microsoft.graph.fileAttachment', 'name': 'attachment.txt', 'contentType': 'text/plain', 'contentBytes': 'SGVsbG8gV29ybGQh'}]}.
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            saveToSentItems (boolean): saveToSentItems Example: 'False'.
+            subject (str): The subject of the email.
+            body (str): The body of the email.
+            to_recipients (list[str]): A list of email addresses for the 'To' recipients.
+            user_id (str, optional): The ID of the user to send the email from. Defaults to the authenticated user.
+            cc_recipients (list[str], optional): A list of email addresses for the 'Cc' recipients.
+            bcc_recipients (list[str], optional): A list of email addresses for the 'Bcc' recipients.
+            attachments (list[dict[str, Any]], optional): A list of attachment objects. See `reply_to_email` for an example.
+            body_content_type (str, optional): The content type of the email body, e.g., "Text" or "HTML". Defaults to "Text".
+            save_to_sent_items (bool, optional): Whether to save the email to the 'Sent Items' folder. Defaults to True.
 
         Returns:
-            Any: Success
+            dict[str, Any]: A dictionary confirming the send action.
 
         Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
+            HTTPStatusError: If the API request fails.
+            ValueError: If the user_id cannot be retrieved.
 
         Tags:
-            users.user.Actions, important
+            important
         """
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        request_body_data = None
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+
+        message = {
+            "subject": subject,
+            "body": {"contentType": body_content_type, "content": body},
+            "toRecipients": [{"emailAddress": {"address": email}} for email in to_recipients],
+        }
+        if cc_recipients:
+            message["ccRecipients"] = [{"emailAddress": {"address": email}} for email in cc_recipients]
+        if bcc_recipients:
+            message["bccRecipients"] = [{"emailAddress": {"address": email}} for email in bcc_recipients]
+        if attachments:
+            message["attachments"] = attachments
+
         request_body_data = {
             "message": message,
-            "saveToSentItems": saveToSentItems,
+            "saveToSentItems": save_to_sent_items,
         }
-        request_body_data = {k: v for k, v in request_body_data.items() if v is not None}
+
         url = f"{self.base_url}/users/{user_id}/sendMail"
-        query_params = {}
+
         response = self._post(
             url,
             data=request_body_data,
-            params=query_params,
+            params={},
             content_type="application/json",
         )
         return self._handle_response(response)
 
-    def get_mail_folder(
+    def get_email_folder(
         self,
-        mailFolder_id: str,
+        folder_id: str,
         user_id: str | None = None,
-        includeHiddenFolders: bool | None = None,
+        include_hidden: bool | None = None,
         select: list[str] | None = None,
         expand: list[str] | None = None,
-    ) -> Any:
+    ) -> dict[str, Any]:
         """
-        Retrieves a specific mail folder's metadata by its ID for a given user. The response can be customized to include hidden folders or select specific properties. Unlike `list_user_messages`, this function fetches folder details, not the emails contained within it.
+        Retrieves a specific email folder's metadata by its ID.
 
         Args:
-            mailFolder_id (string): mailFolder-id
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            includeHiddenFolders (boolean): Include Hidden Folders
-            select (array): Select properties to be returned
-            expand (array): Expand related entities
+            folder_id (str): The unique identifier for the mail folder.
+            user_id (str, optional): The ID of the user who owns the folder. Defaults to the authenticated user.
+            include_hidden (bool, optional): If true, includes hidden folders in the results.
+            select (list[str], optional): A list of properties to return.
+            expand (list[str], optional): A list of related entities to expand.
 
         Returns:
-            Any: Retrieved navigation property
+            dict[str, Any]: A dictionary containing the mail folder's metadata.
 
         Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+            HTTPStatusError: If the API request fails.
+            ValueError: If user_id cannot be retrieved or folder_id is missing.
         Tags:
-            users.mailFolder, important
+            important
         """
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        if mailFolder_id is None:
-            raise ValueError("Missing required parameter 'mailFolder-id'.")
-        url = f"{self.base_url}/users/{user_id}/mailFolders/{mailFolder_id}"
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+        if not folder_id:
+            raise ValueError("Missing required parameter 'folder_id'.")
+
+        url = f"{self.base_url}/users/{user_id}/mailFolders/{folder_id}"
         select_str = ",".join(select) if select else None
         expand_str = ",".join(expand) if expand else None
 
         query_params = {
             k: v
             for k, v in [
-                ("includeHiddenFolders", includeHiddenFolders),
+                ("includeHiddenFolders", include_hidden),
                 ("$select", select_str),
                 ("$expand", expand_str),
             ]
@@ -155,11 +188,11 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def list_user_messages(
+    def list_emails(
         self,
         user_id: str | None = None,
         select: list[str] = ["bodyPreview"],
-        includeHiddenMessages: bool | None = None,
+        include_hidden: bool | None = None,
         top: int | None = None,
         skip: int | None = None,
         search: str | None = None,
@@ -169,70 +202,44 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> dict[str, Any]:
         """
-        Retrieves a list of messages from a user's mailbox. This function supports powerful querying using optional parameters for filtering, searching, sorting, and pagination, unlike `get_user_message`, which fetches a single email by its ID.
-
-        IMPORTANT LIMITATIONS (Microsoft Graph API restrictions):
-        - `search` cannot be used with `filter`
-        - `search` cannot be used with `orderby`
-        - `search` cannot be used with `skip` (use pagination via @odata.nextLink and get_next_page instead)
-        - When using `search`, pagination uses $skiptoken instead of $skip
+        Retrieves a list of emails from a user's mailbox.
 
         Args:
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            select (list): Select properties to be returned. Defaults to ['bodyPreview'].
-                Example: [
-                    'id', 'categories', 'receivedDateTime', 'sentDateTime', 'hasAttachments', 'internetMessageId',
-                    'subject', 'body', 'bodyPreview', 'importance', 'parentFolderId', 'conversationId',
-                    'conversationIndex', 'isDeliveryReceiptRequested', 'isReadReceiptRequested', 'isRead', 'isDraft',
-                    'webLink', 'inferenceClassification', 'sender', 'from', 'toRecipients', 'ccRecipients',
-                    'bccRecipients', 'replyTo', 'flag', 'attachments', 'extensions', 'mentions', 'uniqueBody'
-                ]
-            includeHiddenMessages (boolean): Include Hidden Messages
-            top (integer): Specify the number of items to be included in the result Example: '50'.
-            skip (integer): Specify the number of items to skip in the result. Cannot be used with 'search'. Example: '10'.
-            search (string): Search items by search phrases. Cannot be used with 'filter', 'orderby', or 'skip'.
-            filter (string): Filter items by property values. Cannot be used with 'search'.
-            count (boolean): Include count of items
-            orderby (array): Order items by property values. Cannot be used with 'search'.
-            expand (array): Expand related entities
+            user_id (str, optional): The ID of the user. Defaults to the authenticated user.
+            select (list[str], optional): A list of properties to return for each email. Defaults to ['bodyPreview'].
+            include_hidden (bool, optional): If true, includes hidden messages.
+            top (int, optional): The maximum number of emails to return.
+            skip (int, optional): The number of emails to skip. Cannot be used with 'search'.
+            search (str, optional): A search query. Cannot be used with 'filter', 'orderby', or 'skip'.
+            filter (str, optional): A filter query. Cannot be used with 'search'.
+            count (bool, optional): If true, includes the total count of emails in the response.
+            orderby (list[str], optional): A list of properties to sort the results by. Cannot be used with 'search'.
+            expand (list[str], optional): A list of related entities to expand.
 
         Returns:
-            dict[str, Any]: Retrieved collection
+            dict[str, Any]: A dictionary containing a list of emails and pagination information.
 
         Raises:
-            ValueError: If incompatible parameters are used together (search with filter/orderby/skip).
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+            ValueError: If incompatible parameters are used together (e.g., 'search' with 'filter').
+            HTTPStatusError: If the API request fails.
         Tags:
-            users.message, important
+            important
         """
         if search:
             if filter:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'filter'. "
-                    "This is a Microsoft Graph API restriction. Please use either search or filter, not both."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'filter'.")
             if orderby:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'orderby'. "
-                    "This is a Microsoft Graph API restriction. When using search, results are sorted by relevance."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'orderby'.")
             if skip:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'skip'. "
-                    "When using search, use pagination via @odata.nextLink and the get_next_page function instead."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'skip'. Use pagination via @odata.nextLink instead.")
 
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
 
         url = f"{self.base_url}/users/{user_id}/messages"
-
-        # Handle list parameters by joining with commas
         select_str = ",".join(select) if select else None
         orderby_str = ",".join(orderby) if orderby else None
         expand_str = ",".join(expand) if expand else None
@@ -240,7 +247,7 @@ class OutlookApp(APIApplication):
         query_params = {
             k: v
             for k, v in [
-                ("includeHiddenMessages", includeHiddenMessages),
+                ("includeHiddenMessages", include_hidden),
                 ("$top", top),
                 ("$skip", skip),
                 ("$search", search),
@@ -256,41 +263,41 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_user_message(
+    def get_email(
         self,
         message_id: str,
         user_id: str | None = None,
-        includeHiddenMessages: bool | None = None,
+        include_hidden: bool | None = None,
         select: list[str] | None = None,
         expand: list[str] | None = None,
-    ) -> Any:
+    ) -> dict[str, Any]:
         """
-        Retrieves a specific email message by its ID for a given user, with options to select specific fields or expand related data. Unlike `list_user_messages`, which fetches a collection of emails with advanced filtering, this function is designed to retrieve a single, known message.
+        Retrieves a specific email by its ID.
 
         Args:
-            message_id (string): message-id
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            includeHiddenMessages (boolean): Include Hidden Messages
-            select (array): Select properties to be returned
-            expand (array): Expand related entities
+            message_id (str): The unique identifier for the email.
+            user_id (str, optional): The ID of the user who owns the email. Defaults to the authenticated user.
+            include_hidden (bool, optional): If true, includes hidden messages.
+            select (list[str], optional): A list of properties to return.
+            expand (list[str], optional): A list of related entities to expand.
 
         Returns:
-            Any: Retrieved navigation property
+            dict[str, Any]: A dictionary containing the email's details.
 
         Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+            HTTPStatusError: If the API request fails.
+            ValueError: If user_id cannot be retrieved or message_id is missing.
         Tags:
-            users.message, important
+            important
         """
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        if message_id is None:
-            raise ValueError("Missing required parameter 'message-id'.")
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+        if not message_id:
+            raise ValueError("Missing required parameter 'message_id'.")
+
         url = f"{self.base_url}/users/{user_id}/messages/{message_id}"
         select_str = ",".join(select) if select else None
         expand_str = ",".join(expand) if expand else None
@@ -298,7 +305,7 @@ class OutlookApp(APIApplication):
         query_params = {
             k: v
             for k, v in [
-                ("includeHiddenMessages", includeHiddenMessages),
+                ("includeHiddenMessages", include_hidden),
                 ("$select", select_str),
                 ("$expand", expand_str),
             ]
@@ -307,37 +314,36 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def user_delete_message(self, message_id: str, user_id: str | None = None) -> Any:
+    def delete_email(self, message_id: str, user_id: str | None = None) -> dict[str, Any]:
         """
-        Permanently deletes a specific email, identified by `message_id`, from a user's mailbox. If `user_id` is not provided, it defaults to the current authenticated user. Unlike retrieval functions such as `get_user_message`, this performs a destructive action to remove the specified email from Outlook.
+        Permanently deletes a specific email by its ID.
 
         Args:
-            message_id (string): message-id
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
+            message_id (str): The unique identifier for the email to be deleted.
+            user_id (str, optional): The ID of the user who owns the email. Defaults to the authenticated user.
 
         Returns:
-            Any: Success
+            dict[str, Any]: A dictionary confirming the deletion.
 
         Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+            HTTPStatusError: If the API request fails.
+            ValueError: If user_id cannot be retrieved or message_id is missing.
         Tags:
-            users.message, important
+            important
         """
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        if message_id is None:
-            raise ValueError("Missing required parameter 'message-id'.")
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+        if not message_id:
+            raise ValueError("Missing required parameter 'message_id'.")
+
         url = f"{self.base_url}/users/{user_id}/messages/{message_id}"
-        query_params = {}
-        response = self._delete(url, params=query_params)
+        response = self._delete(url, params={})
         return self._handle_response(response)
 
-    def list_message_attachments(
+    def list_email_attachments(
         self,
         message_id: str,
         user_id: str | None = None,
@@ -351,60 +357,44 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> dict[str, Any]:
         """
-        Retrieves attachments for a specific email message, identified by its ID. Supports advanced querying for filtering, sorting, and pagination, allowing users to select specific fields to return in the result set, focusing only on attachments rather than the full message content.
-
-        IMPORTANT LIMITATIONS (Microsoft Graph API restrictions):
-        - `search` cannot be used with `filter`
-        - `search` cannot be used with `orderby`
-        - `search` cannot be used with `skip` (use pagination via @odata.nextLink and get_next_page instead)
+        Retrieves attachments for a specific email.
 
         Args:
-            message_id (string): message-id
-            user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
-            top (integer): Show only the first n items Example: '50'.
-            skip (integer): Skip the first n items. Cannot be used with 'search'.
-            search (string): Search items by search phrases. Cannot be used with 'filter', 'orderby', or 'skip'.
-            filter (string): Filter items by property values. Cannot be used with 'search'.
-            count (boolean): Include count of items
-            orderby (array): Order items by property values. Cannot be used with 'search'.
-            select (array): Select properties to be returned
-            expand (array): Expand related entities
+            message_id (str): The unique identifier for the email.
+            user_id (str, optional): The ID of the user who owns the email. Defaults to the authenticated user.
+            top (int, optional): The maximum number of attachments to return.
+            skip (int, optional): The number of attachments to skip. Cannot be used with 'search'.
+            search (str, optional): A search query. Cannot be used with 'filter', 'orderby', or 'skip'.
+            filter (str, optional): A filter query. Cannot be used with 'search'.
+            count (bool, optional): If true, includes the total count of attachments.
+            orderby (list[str], optional): A list of properties to sort by. Cannot be used with 'search'.
+            select (list[str], optional): A list of properties to return.
+            expand (list[str], optional): A list of related entities to expand.
 
         Returns:
-            dict[str, Any]: Retrieved collection
+            dict[str, Any]: A dictionary containing a list of attachments.
 
         Raises:
-            ValueError: If incompatible parameters are used together (search with filter/orderby/skip).
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+            ValueError: If incompatible parameters are used together.
+            HTTPStatusError: If the API request fails.
         Tags:
-            users.message, important
+            important
         """
         if search:
             if filter:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'filter'. "
-                    "This is a Microsoft Graph API restriction. Please use either search or filter, not both."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'filter'.")
             if orderby:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'orderby'. "
-                    "This is a Microsoft Graph API restriction. When using search, results are sorted by relevance."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'orderby'.")
             if skip:
-                raise ValueError(
-                    "The 'search' parameter cannot be used together with 'skip'. "
-                    "When using search, use pagination via @odata.nextLink and the get_next_page function instead."
-                )
+                raise ValueError("The 'search' parameter cannot be used with 'skip'. Use pagination via @odata.nextLink instead.")
 
-        # If user_id is not provided, get it automatically
         if user_id is None:
-            user_info = self.get_current_user_profile()
+            user_info = self.get_my_profile()
             user_id = user_info.get("userPrincipalName")
             if not user_id:
-                raise ValueError("Could not retrieve user ID from get_current_user_profile response.")
-        if message_id is None:
-            raise ValueError("Missing required parameter 'message-id'.")
+                raise ValueError("Could not retrieve user ID from get_my_profile response.")
+        if not message_id:
+            raise ValueError("Missing required parameter 'message_id'.")
 
         url = f"{self.base_url}/users/{user_id}/messages/{message_id}/attachments"
         orderby_str = ",".join(orderby) if orderby else None
@@ -428,53 +418,107 @@ class OutlookApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_current_user_profile(
+    def get_attachment(
         self,
+        message_id: str,
+        attachment_id: str,
+        user_id: str | None = None,
     ) -> dict[str, Any]:
         """
-        Fetches the `userPrincipalName` for the currently authenticated user from the `/me` endpoint. This internal helper is used by other methods to automatically obtain the user's ID for API calls when a `user_id` is not explicitly provided.
+        Retrieves a specific attachment from an email message and formats it as a dictionary.
 
+        Args:
+            message_id (str): The ID of the email message.
+            attachment_id (str): The ID of the attachment.
+            user_id (str, optional): The ID of the user. Defaults to the authenticated user.
 
         Returns:
-            dict[str, Any]: Current user information
+            dict[str, Any]: A dictionary containing the attachment details:
+                - 'type' (str): The general type of the attachment (e.g., "image", "audio", "video", "file").
+                - 'data' (str): The base64 encoded content of the attachment.
+                - 'mime_type' (str): The MIME type of the attachment.
+                - 'file_name' (str): The name of the attachment file.
+        Tags:
+            important
+        """
+        if user_id is None:
+            user_info = self.get_my_profile()
+            user_id = user_info.get("userPrincipalName")
+            if not user_id:
+                raise ValueError("Could not retrieve user ID.")
+        if not message_id or not attachment_id:
+            raise ValueError("Missing required parameter 'message_id' or 'attachment_id'.")
 
-        Raises:
-            HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
+        url = f"{self.base_url}/users/{user_id}/messages/{message_id}/attachments/{attachment_id}"
 
-        Tags:
-            me, important
+        response = self._get(url, params={})
+        attachment_data = self._handle_response(response)
+
+        content_type = attachment_data.get("contentType", "application/octet-stream")
+        attachment_type = content_type.split("/")[0] if "/" in content_type else "file"
+        if attachment_type not in ["image", "audio", "video", "text"]:
+            attachment_type = "file"
+
+        return {
+            "type": attachment_type,
+            "data": attachment_data.get("contentBytes"),
+            "mime_type": content_type,
+            "file_name": attachment_data.get("name"),
+        }
+
+    def get_my_profile(self) -> dict[str, Any]:
+        """
+        Fetches the userPrincipalName for the currently authenticated user.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the user's principal name.
+
+        Raises:
+            HTTPStatusError: If the API request fails.
         """
         url = f"{self.base_url}/me"
-        query_params = {
-            "$select": "userPrincipalName",
-        }
+        query_params = {"$select": "userPrincipalName"}
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_next_page(self, url: str) -> dict[str, Any]:
+    def get_next_page_results(self, url: str) -> dict[str, Any]:
         """
-        Executes a GET request for a full URL, typically the `@odata.nextLink` from a previous paginated API response. It simplifies retrieving subsequent pages of data from list functions by handling URL validation and parsing before fetching the results for the next page.
+        Retrieves the next page of results from a paginated API response.
+
+        Args:
+            url (str): The full URL for the next page of results (@odata.nextLink).
+
+        Returns:
+            dict[str, Any]: A dictionary containing the next page of results.
+
+        Raises:
+            ValueError: If the URL is missing or invalid.
+        Tags:
+            important
         """
         if not url:
             raise ValueError("Missing required parameter 'url'.")
         if not url.startswith(self.base_url):
-            raise ValueError(f"The provided URL '{url}' does not start with the expected base URL '{self.base_url}'.")
+            raise ValueError(f"The provided URL must start with '{self.base_url}'.")
+
         relative_part = url[len(self.base_url) :]
         parsed_relative = urlparse(relative_part)
         path_only = parsed_relative.path
         params = {k: v[0] for k, v in parse_qs(parsed_relative.query).items()}
+
         response = self._get(path_only, params=params)
         return self._handle_response(response)
 
     def list_tools(self):
         return [
-            self.reply_to_message,
-            self.send_mail,
-            self.get_mail_folder,
-            self.list_user_messages,
-            self.get_user_message,
-            self.user_delete_message,
-            self.list_message_attachments,
-            self.get_current_user_profile,
-            self.get_next_page,
+            self.reply_to_email,
+            self.send_email,
+            self.get_email_folder,
+            self.list_emails,
+            self.get_email,
+            self.delete_email,
+            self.list_email_attachments,
+            self.get_attachment,
+            self.get_my_profile,
+            self.get_next_page_results,
         ]

universal_mcp/applications/reddit/app.py

@@ -44,9 +44,7 @@ class RedditApp(APIApplication):
             "User-Agent": "agentr-reddit-app/0.1 by AgentR",
         }
 
-    def get_subreddit_posts(
-        self, subreddit: str, limit: int = 5, timeframe: str = "day"
-    ) -> dict[str, Any]:
+    def get_subreddit_posts(self, subreddit: str, limit: int = 5, timeframe: str = "day") -> dict[str, Any]:
         """
         Fetches a specified number of top-rated posts from a particular subreddit, allowing results to be filtered by a specific timeframe (e.g., 'day', 'week'). This is a simplified version compared to `get_subreddit_top_posts`, which uses more complex pagination parameters instead of a direct time filter.
 
@@ -56,7 +54,7 @@ class RedditApp(APIApplication):
             timeframe: The time period for top posts. Valid options: 'hour', 'day', 'week', 'month', 'year', 'all' (default: 'day')
 
         Returns:
-            A formatted string containing a numbered list of top posts, including titles, authors, scores, and URLs, or an error message if the request fails
+            A dictionary containing a list of top posts with their details, or an error message if the request fails.
 
         Raises:
             RequestException: When the HTTP request to the Reddit API fails
@@ -69,34 +67,29 @@ class RedditApp(APIApplication):
         if timeframe not in valid_timeframes:
             return f"Error: Invalid timeframe '{timeframe}'. Please use one of: {', '.join(valid_timeframes)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/r/{subreddit}/top"
         params = {"limit": limit, "t": timeframe}
-        logger.info(
-            f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'"
-        )
+        logger.info(f"Requesting top {limit} posts from r/{subreddit} for timeframe '{timeframe}'")
         response = self._get(url, params=params)
         return self._handle_response(response)
 
-    def search_subreddits(
-        self, query: str, limit: int = 5, sort: str = "relevance"
-    ) -> str:
+    def search_subreddits(self, query: str, limit: int = 5, sort: str = "relevance") -> dict[str, Any]:
         """
-        Searches for subreddits by name and description using a query string, with results sortable by relevance or activity. Unlike the broader `search_reddit` function, this method exclusively discovers subreddits, not posts, comments, or users.
+        Finds subreddits based on a query string, searching their names and descriptions.
+        Results can be sorted by relevance or activity. This function is for discovering communities and does not search for posts or users, unlike the more general `search_reddit` function.
 
         Args:
-            query: The text to search for in subreddit names and descriptions
-            limit: The maximum number of subreddits to return, between 1 and 100 (default: 5)
-            sort: The order of results, either 'relevance' or 'activity' (default: 'relevance')
+            query: The search query for subreddit names and descriptions.
+            limit: The maximum number of subreddits to return (1-100, default is 5).
+            sort: The sorting order for results. Can be 'relevance' or 'activity' (default is 'relevance').
 
         Returns:
-            A formatted string containing a list of matching subreddits with their names, subscriber counts, and descriptions, or an error message if the search fails or parameters are invalid
+            A dictionary containing a list of matching subreddits, including their names, subscriber counts, and descriptions. Returns an error message on failure.
 
         Raises:
-            RequestException: When the HTTP request to Reddit's API fails
-            JSONDecodeError: When the API response contains invalid JSON
+            RequestException: If the API request to Reddit fails.
+            JSONDecodeError: If the API response is not valid JSON.
 
         Tags:
             search, important, reddit, api, query, format, list, validation
@@ -105,18 +98,14 @@ class RedditApp(APIApplication):
         if sort not in valid_sorts:
             return f"Error: Invalid sort option '{sort}'. Please use one of: {', '.join(valid_sorts)}"
         if not 1 <= limit <= 100:
-            return (
-                f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
-            )
+            return f"Error: Invalid limit '{limit}'. Please use a value between 1 and 100."
         url = f"{self.base_api_url}/subreddits/search"
         params = {
             "q": query,
             "limit": limit,
             "sort": sort,
         }
-        logger.info(
-            f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})"
-        )
+        logger.info(f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})")
         response = self._get(url, params=params)
         return self._handle_response(response)
 
@@ -193,16 +182,10 @@ class RedditApp(APIApplication):
         logger.info(f"Submitting a new post to r/{subreddit}")
         response = self._post(url_api, data=data)
         response_json = response.json()
-        if (
-            response_json
-            and "json" in response_json
-            and "errors" in response_json["json"]
-        ):
+        if response_json and "json" in response_json and "errors" in response_json["json"]:
             errors = response_json["json"]["errors"]
             if errors:
-                error_message = ", ".join(
-                    [f"{code}: {message}" for code, message in errors]
-                )
+                error_message = ", ".join([f"{code}: {message}" for code, message in errors])
                 return f"Reddit API error: {error_message}"
         return response_json
 
@@ -317,7 +300,7 @@ class RedditApp(APIApplication):
         Retrieves the full profile information for the currently authenticated user by making a GET request to the `/api/v1/me` Reddit API endpoint. This differs from `get_user_profile`, which requires a username, and `get_current_user_karma`, which specifically fetches karma data.
 
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's profile information.
 
         Tags:
             users
@@ -333,7 +316,7 @@ class RedditApp(APIApplication):
         Fetches the karma breakdown for the authenticated user from the Reddit API. This function specifically targets the `/api/v1/me/karma` endpoint, returning karma statistics per subreddit, which is more specific than `get_current_user_info` that retrieves general profile information.
 
         Returns:
-            Any: API response data.
+            A dictionary containing the authenticated user's karma breakdown by subreddit.
 
         Tags:
             account
@@ -349,10 +332,10 @@ class RedditApp(APIApplication):
         Fetches a specific Reddit post's details and its complete comment tree using the post's unique ID. This function returns the entire discussion, including the original post and all associated comments, providing broader context than `get_comment_by_id` which only retrieves a single comment.
 
         Args:
-            post_id (string): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
+            post_id (str): The Reddit post ID ( e.g. '1m734tx' for https://www.reddit.com/r/mcp/comments/1m734tx/comment/n4occ77/)
 
         Returns:
-            Any: API response data containing post details and comments.
+            A dictionary containing the post details and its comment tree.
 
         Tags:
             listings, comments, posts, important
@@ -384,7 +367,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of controversial posts.
+            A dictionary containing a listing of controversial posts.
 
         Tags:
             listings, posts, controversial, read-only
@@ -429,7 +412,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts.
+            A dictionary containing a listing of hot posts.
 
         Tags:
             listings, posts, hot, read-only
@@ -473,7 +456,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts.
+            A dictionary containing a listing of new posts.
 
         Tags:
             listings, posts, new, read-only
@@ -520,7 +503,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of hot posts from the subreddit.
+            A dictionary containing a listing of hot posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, hot, read-only
@@ -568,7 +551,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of new posts from the subreddit.
+            A dictionary containing a listing of new posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, new, read-only
@@ -615,7 +598,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts from the subreddit.
+            A dictionary containing a listing of top posts from the specified subreddit.
 
         Tags:
             listings, posts, subreddit, top, read-only
@@ -660,7 +643,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of rising posts.
+            A dictionary containing a listing of rising posts.
 
         Tags:
             listings, posts, rising, read-only
@@ -703,7 +686,7 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
 
         Returns:
-            Any: API response data containing a list of top posts.
+            A dictionary containing a listing of top posts.
 
         Tags:
             listings, posts, top, read-only
@@ -760,7 +743,7 @@ class RedditApp(APIApplication):
             type: Optional. A comma-separated list of result types ('sr', 'link', 'user').
 
         Returns:
-            Any: API response data containing search results.
+            A dictionary containing the search results.
 
         Tags:
             search, reddit, posts, comments, users, read-only

{universal_mcp_applications-0.1.25.dist-info → universal_mcp_applications-0.1.26.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-mcp-applications
-Version: 0.1.25
+Version: 0.1.26
 Summary: A Universal MCP Application: universal_mcp_applications
 Project-URL: Homepage, https://github.com/universal-mcp/applications
 Project-URL: Repository, https://github.com/universal-mcp/applications

{universal_mcp_applications-0.1.25.dist-info → universal_mcp_applications-0.1.26.dist-info}/RECORD

@@ -170,7 +170,7 @@ universal_mcp/applications/openai/__init__.py,sha256=7h2xDZdb1pRh7ZDLtFK9BNDEbRH
 universal_mcp/applications/openai/app.py,sha256=5pW85lC5SsojpQNPTZO4QkGkDAcLk8M3nvl1m1Bi0Vk,34123
 universal_mcp/applications/outlook/README.md,sha256=gEdQckOduZHCjLYACZtN3ApFC41y1YdcT0uFCiNvuvk,2830
 universal_mcp/applications/outlook/__init__.py,sha256=yExFpo0apWqcpP7l4qCjAYwMyzomUaEeNDhY7Gi-We0,28
-universal_mcp/applications/outlook/app.py,sha256=RBlncTgS9eLrb1SAY7Rw7g0AYnWSqHsfthxEyWgNk4E,22470
+universal_mcp/applications/outlook/app.py,sha256=3LvFRBKzlA_Gzkj07eyFiuCcKRBTd7-9WIhdrYpLOO8,20885
 universal_mcp/applications/perplexity/README.md,sha256=3DTRkkaGKmAyZz3Rpdo5OUyEXogWqzZ228gxrixO2pI,554
 universal_mcp/applications/perplexity/__init__.py,sha256=f4uz8qlw-uek6AlyWxoWxukubaHb6YV4riTcvQhfvO0,31
 universal_mcp/applications/perplexity/app.py,sha256=M47xUTRJbnd7zDxVG1R3nkX46aI7GZ-aVPphNQjMkvA,2815
@@ -182,7 +182,7 @@ universal_mcp/applications/posthog/__init__.py,sha256=2j8vH09Xqz51BlfNehaEvY2A2L
 universal_mcp/applications/posthog/app.py,sha256=-T0hOSxPT3qQEVG8IrRY0MVi0YI8yHHeKPgl5jRexGY,275182
 universal_mcp/applications/reddit/README.md,sha256=RzGOX8sFJldmLsrjFG1FHmWzL7RddZTylb-m8XjSKQI,6558
 universal_mcp/applications/reddit/__init__.py,sha256=JHA_BMVnuQyoDMbQt5dRNxKPrAxyZZL6zzQyNbvyjHs,27
-universal_mcp/applications/reddit/app.py,sha256=jC5ha7sszKNypIRiX19ZYMEMafGxBe9nVZqiKKu8lO0,35841
+universal_mcp/applications/reddit/app.py,sha256=HUqYRJ7U07uMg-U5c5VDrboSlSSB1_gD_dtDiwqDSDo,35648
 universal_mcp/applications/resend/README.md,sha256=zfKzut3KCw9JlX3crspSjRsLZyoN9uly_yZWjWA4LUU,8409
 universal_mcp/applications/resend/__init__.py,sha256=4me7YQFrYTNvqbJawBrsrJlzyFRwXZA6u4E09IPWjlk,27
 universal_mcp/applications/resend/app.py,sha256=bPW5wgl7wf2m4tgygSwdfRCaKKBEPwMrLWm3yhOP9kk,34879
@@ -276,7 +276,7 @@ universal_mcp/applications/youtube/app.py,sha256=eqgqe0b53W9Mj0FZGW3ZqY3xkGF4NbO
 universal_mcp/applications/zenquotes/README.md,sha256=FJyoTGRCaZjF_bsCBqg1CrYcvIfuUG_Qk616G1wjhF8,512
 universal_mcp/applications/zenquotes/__init__.py,sha256=C5nEHZ3Xy6nYUarq0BqQbbJnHs0UtSlqhk0DqmvWiHk,58
 universal_mcp/applications/zenquotes/app.py,sha256=7xIEnSZWAGYu5583Be2ZjSCtLUAfMWRzucSpp7hw_h4,1299
-universal_mcp_applications-0.1.25.dist-info/METADATA,sha256=yI7SU0Crz1RSAHM8JMGShgf-SJqMYzMwE4AQFm9rk4c,2956
-universal_mcp_applications-0.1.25.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-universal_mcp_applications-0.1.25.dist-info/licenses/LICENSE,sha256=NweDZVPslBAZFzlgByF158b85GR0f5_tLQgq1NS48To,1063
-universal_mcp_applications-0.1.25.dist-info/RECORD,,
+universal_mcp_applications-0.1.26.dist-info/METADATA,sha256=0Ae_g0zJq4xSsdekTvbRe5hTweEP3hMBVXMTYiDrmmM,2956
+universal_mcp_applications-0.1.26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+universal_mcp_applications-0.1.26.dist-info/licenses/LICENSE,sha256=NweDZVPslBAZFzlgByF158b85GR0f5_tLQgq1NS48To,1063
+universal_mcp_applications-0.1.26.dist-info/RECORD,,