universal-mcp 0.1.8rc1__py3-none-any.whl → 0.1.8rc3__py3-none-any.whl

universal_mcp/applications/google_drive/app.py

@@ -36,55 +36,73 @@ class GoogleDriveApp(APIApplication):
 
     def get_drive_info(self) -> dict[str, Any]:
         """
-        Get information about the user's Google Drive, including storage quota and user info.
-        
+        Retrieves detailed information about the user's Google Drive storage and account.
+
         Returns:
-            A dictionary containing information about the user's Drive.
-            Includes details like storage quota, user information, and features.
+            A dictionary containing Drive information including storage quota (usage, limit) and user details (name, email, etc.).
+
+        Raises:
+            HTTPError: If the API request fails or returns an error status code
+            ConnectionError: If there are network connectivity issues
+            AuthenticationError: If the authentication credentials are invalid or expired
+
+        Tags:
+            get, info, storage, drive, quota, user, api, important
         """
         url = f"{self.base_url}/about"
         params = {"fields": "storageQuota,user"}
-        
         response = self._get(url, params=params)
         return response.json()
 
-    def list_files(self, page_size: int = 10, query: str = None, order_by: str = None) -> dict[str, Any]:
+    def list_files(
+        self, page_size: int = 10, query: str = None, order_by: str = None
+    ) -> dict[str, Any]:
         """
-        List files in the user's Google Drive.
-        
+        Lists and retrieves files from Google Drive with optional filtering, pagination, and sorting.
+
         Args:
-            page_size: Maximum number of files to return (default: 10)
-            query: Search query using Google Drive query syntax (e.g., "mimeType='image/jpeg'")
-            order_by: Field to sort by (e.g., "modifiedTime desc")
-        
+            page_size: Maximum number of files to return per page (default: 10)
+            query: Optional search query string using Google Drive query syntax (e.g., "mimeType='image/jpeg'")
+            order_by: Optional field name to sort results by, with optional direction (e.g., "modifiedTime desc")
+
         Returns:
-            A dictionary containing the list of files and possibly a nextPageToken.
+            Dictionary containing a list of files and metadata, including 'files' array and optional 'nextPageToken' for pagination
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+            RequestException: Raised when network connectivity issues occur during the API request
+
+        Tags:
+            list, files, search, google-drive, pagination, important
         """
         url = f"{self.base_url}/files"
         params = {
             "pageSize": page_size,
         }
-        
         if query:
             params["q"] = query
-        
         if order_by:
             params["orderBy"] = order_by
-        
         response = self._get(url, params=params)
         response.raise_for_status()
         return response.json()
-    
 
     def get_file(self, file_id: str) -> dict[str, Any]:
         """
-        Get metadata for a specific file.
-        
+        Retrieves detailed metadata for a specific file using its ID.
+
         Args:
-            file_id: The ID of the file to retrieve
-        
+            file_id: String identifier of the file whose metadata should be retrieved
+
         Returns:
-            A dictionary containing the file's metadata.
+            Dictionary containing the file's metadata including properties such as name, size, type, and other attributes
+
+        Raises:
+            HTTPError: When the API request fails due to invalid file_id or network issues
+            JSONDecodeError: When the API response cannot be parsed as JSON
+
+        Tags:
+            retrieve, file, metadata, get, api, important
         """
         url = f"{self.base_url}/files/{file_id}"
         response = self._get(url)
@@ -92,13 +110,19 @@ class GoogleDriveApp(APIApplication):
 
     def delete_file(self, file_id: str) -> dict[str, Any]:
         """
-        Delete a file from Google Drive.
-        
+        Deletes a specified file from Google Drive and returns a status message.
+
         Args:
-            file_id: The ID of the file to delete
-        
+            file_id: The unique identifier string of the file to be deleted from Google Drive
+
         Returns:
-            A simple success message dictionary
+            A dictionary containing either a success message {'message': 'File deleted successfully'} or an error message {'error': 'error description'}
+
+        Raises:
+            Exception: When the DELETE request fails due to network issues, invalid file_id, insufficient permissions, or other API errors
+
+        Tags:
+            delete, file-management, google-drive, api, important
         """
         url = f"{self.base_url}/files/{file_id}"
         try:
@@ -106,108 +130,114 @@ class GoogleDriveApp(APIApplication):
             return {"message": "File deleted successfully"}
         except Exception as e:
             return {"error": str(e)}
-    
+
     def create_file_from_text(
         self,
         file_name: str,
         text_content: str,
         parent_id: str = None,
-        mime_type: str = "text/plain"
+        mime_type: str = "text/plain",
     ) -> dict[str, Any]:
         """
-        Create a new file from text content in Google Drive.
-        
+        Creates a new file in Google Drive with specified text content and returns the file's metadata.
+
         Args:
             file_name: Name of the file to create on Google Drive
             text_content: Plain text content to be written to the file
-            parent_id: ID of the parent folder to create the file in (optional)
-            mime_type: MIME type of the file (default: text/plain)
-        
+            parent_id: Optional ID of the parent folder where the file will be created
+            mime_type: MIME type of the file (defaults to 'text/plain')
+
         Returns:
-            A dictionary containing the created file's metadata.
+            Dictionary containing metadata of the created file including ID, name, and other Google Drive file properties
+
+        Raises:
+            HTTPStatusError: Raised when the API request fails during file creation or content upload
+            UnicodeEncodeError: Raised when the text_content cannot be encoded in UTF-8
+
+        Tags:
+            create, file, upload, drive, text, important, storage, document
         """
-        metadata = {
-            "name": file_name,
-            "mimeType": mime_type
-        }
-        
+        metadata = {"name": file_name, "mimeType": mime_type}
         if parent_id:
             metadata["parents"] = [parent_id]
-            
         create_url = f"{self.base_url}/files"
         create_response = self._post(create_url, data=metadata)
         file_data = create_response.json()
         file_id = file_data.get("id")
-        
-        # Step 2: Update the file with text content
         upload_url = f"https://www.googleapis.com/upload/drive/v3/files/{file_id}?uploadType=media"
         upload_headers = self._get_headers()
         upload_headers["Content-Type"] = f"{mime_type}; charset=utf-8"
-        
         upload_response = httpx.patch(
-            upload_url,
-            headers=upload_headers,
-            content=text_content.encode("utf-8")
+            upload_url, headers=upload_headers, content=text_content.encode("utf-8")
         )
         upload_response.raise_for_status()
-        
         response_data = upload_response.json()
         return response_data
-        
+
     def find_folder_id_by_name(self, folder_name: str) -> str | None:
         """
-        Find a folder's ID by its name.
-        
+        Searches for and retrieves a Google Drive folder's ID using its name.
+
         Args:
-            folder_name: The name of the folder to find
-            
+            folder_name: The name of the folder to search for in Google Drive
+
         Returns:
-            The folder ID if found, None otherwise
+            str | None: The folder's ID if a matching folder is found, None if no folder is found or if an error occurs
+
+        Raises:
+            Exception: Caught internally and logged when API requests fail or response parsing errors occur
+
+        Tags:
+            search, find, google-drive, folder, query, api, utility
         """
         query = f"mimeType='application/vnd.google-apps.folder' and name='{folder_name}' and trashed=false"
         try:
             response = self._get(
                 f"{self.base_url}/files",
-                params={"q": query, "fields": "files(id,name)"}
+                params={"q": query, "fields": "files(id,name)"},
             )
             files = response.json().get("files", [])
             return files[0]["id"] if files else None
         except Exception as e:
             logger.error(f"Error finding folder ID by name: {e}")
             return None
-    
+
     def create_folder(self, folder_name: str, parent_id: str = None) -> dict[str, Any]:
         """
-        Create a new folder in Google Drive.
-        
+        Creates a new folder in Google Drive with optional parent folder specification
+
         Args:
             folder_name: Name of the folder to create
-            parent_id: ID of the parent folder (optional). Can be an actual folder ID
-                       or a folder name that will be looked up.
-                       
+            parent_id: ID or name of the parent folder. Can be either a folder ID string or a folder name that will be automatically looked up
+
         Returns:
-            A dictionary containing the created folder's metadata.
+            Dictionary containing the created folder's metadata including its ID, name, and other Drive-specific information
+
+        Raises:
+            ValueError: Raised when a parent folder name is provided but cannot be found in Google Drive
+
+        Tags:
+            create, folder, drive, storage, important, management
         """
         import re
-        
+
         metadata = {
             "name": folder_name,
-            "mimeType": "application/vnd.google-apps.folder"
+            "mimeType": "application/vnd.google-apps.folder",
         }
-        
         if parent_id:
             if not re.match(r"^[a-zA-Z0-9_-]{28,33}$", parent_id):
                 found_id = self.find_folder_id_by_name(parent_id)
                 if found_id:
                     metadata["parents"] = [found_id]
                 else:
-                    raise ValueError(f"Could not find parent folder with name: {parent_id}")
+                    raise ValueError(
+                        f"Could not find parent folder with name: {parent_id}"
+                    )
             else:
                 metadata["parents"] = [parent_id]
-                
         url = f"{self.base_url}/files"
         params = {"supportsAllDrives": "true"}
-        
         response = self._post(url, data=metadata, params=params)
         return response.json()
 
@@ -216,53 +246,46 @@ class GoogleDriveApp(APIApplication):
         file_name: str,
         file_path: str,
         parent_id: str = None,
-        mime_type: str = None
+        mime_type: str = None,
     ) -> dict[str, Any]:
         """
-        Upload a file to Google Drive from a local binary file.
-        
-        This method is suitable for files under 5MB in size. It automatically
-        reads the file from the provided path.
-        
+        Uploads a file to Google Drive by creating a file metadata entry and uploading the binary content.
+
         Args:
             file_name: Name to give the file on Google Drive
             file_path: Path to the local file to upload
-            parent_id: ID of the parent folder to create the file in (optional)
-            mime_type: MIME type of the file 
-                       Examples: 'image/jpeg', 'image/png', 'application/pdf', 'text/csv'
-        
+            parent_id: Optional ID of the parent folder to create the file in
+            mime_type: MIME type of the file (e.g., 'image/jpeg', 'image/png', 'application/pdf')
+
         Returns:
-            A dictionary containing the created file's metadata.
+            Dictionary containing the uploaded file's metadata from Google Drive
+
+        Raises:
+            FileNotFoundError: When the specified file_path does not exist or is not accessible
+            HTTPError: When the API request fails or returns an error status code
+            IOError: When there are issues reading the file content
+
+        Tags:
+            upload, file-handling, google-drive, api, important, binary, storage
         """
-        
-            
-        metadata = {
-            "name": file_name,
-            "mimeType": mime_type
-        }
-        
+        metadata = {"name": file_name, "mimeType": mime_type}
         if parent_id:
             metadata["parents"] = [parent_id]
-            
         create_url = f"{self.base_url}/files"
         create_response = self._post(create_url, data=metadata)
         file_data = create_response.json()
         file_id = file_data.get("id")
-        
-        with open(file_path, 'rb') as file_content:
+        with open(file_path, "rb") as file_content:
             binary_content = file_content.read()
-            
+
             upload_url = f"https://www.googleapis.com/upload/drive/v3/files/{file_id}?uploadType=media"
             upload_headers = self._get_headers()
             upload_headers["Content-Type"] = mime_type
-            
+
             upload_response = httpx.patch(
-                upload_url,
-                headers=upload_headers,
-                content=binary_content
+                upload_url, headers=upload_headers, content=binary_content
             )
             upload_response.raise_for_status()
-        
         response_data = upload_response.json()
         return response_data
 
@@ -277,4 +300,4 @@ class GoogleDriveApp(APIApplication):
             self.create_folder,
             self.get_file,
             self.delete_file,
-        ]
+        ]

universal_mcp/applications/google_mail/app.py

@@ -30,15 +30,24 @@ class GoogleMailApp(APIApplication):
         }
 
     def send_email(self, to: str, subject: str, body: str) -> str:
-        """Send an email
+        """
+        Sends an email using the Gmail API and returns a confirmation or error message.
 
         Args:
             to: The email address of the recipient
-            subject: The subject of the email
-            body: The body of the email
+            subject: The subject line of the email
+            body: The main content of the email message
 
         Returns:
-            A confirmation message
+            A string containing either a success confirmation message or an error description
+
+        Raises:
+            NotAuthorizedError: When Gmail API authentication is not valid or has expired
+            KeyError: When required configuration keys are missing
+            Exception: For any other unexpected errors during the email sending process
+
+        Tags:
+            send, email, api, communication, important
         """
         try:
             url = f"{self.base_api_url}/messages/send"
@@ -89,15 +98,24 @@ class GoogleMailApp(APIApplication):
             raise
 
     def create_draft(self, to: str, subject: str, body: str) -> str:
-        """Create a draft email
+        """
+        Creates a draft email message in Gmail using the Gmail API and returns a confirmation status.
 
         Args:
             to: The email address of the recipient
-            subject: The subject of the email
-            body: The body of the email
+            subject: The subject line of the draft email
+            body: The main content/message of the draft email
 
         Returns:
-            A confirmation message with the draft ID
+            A string containing either a success message with the draft ID or an error message describing the failure
+
+        Raises:
+            NotAuthorizedError: When the user's Gmail API authorization is invalid or expired
+            KeyError: When required configuration keys are missing
+            Exception: For general API errors, network issues, or other unexpected problems
+
+        Tags:
+            create, email, draft, gmail, api, important
         """
         try:
             url = f"{self.base_api_url}/drafts"
@@ -129,13 +147,22 @@ class GoogleMailApp(APIApplication):
             return f"Error creating draft: {type(e).__name__} - {str(e)}"
 
     def send_draft(self, draft_id: str) -> str:
-        """Send an existing draft email
+        """
+        Sends an existing draft email using the Gmail API and returns a confirmation message.
 
         Args:
-            draft_id: The ID of the draft to send
+            draft_id: The unique identifier of the Gmail draft to be sent
 
         Returns:
-            A confirmation message
+            A string containing either a success message with the sent message ID or an error message detailing the failure reason
+
+        Raises:
+            NotAuthorizedError: When the user's Gmail API authorization is invalid or expired
+            KeyError: When required configuration keys are missing from the API response
+            Exception: For other unexpected errors during the API request or response handling
+
+        Tags:
+            send, email, api, communication, important, draft
         """
         try:
             url = f"{self.base_api_url}/drafts/send"
@@ -165,14 +192,23 @@ class GoogleMailApp(APIApplication):
             return f"Error sending draft: {type(e).__name__} - {str(e)}"
 
     def get_draft(self, draft_id: str, format: str = "full") -> str:
-        """Get a specific draft email by ID
+        """
+        Retrieves and formats a specific draft email from Gmail by its ID
 
         Args:
-            draft_id: The ID of the draft to retrieve
-            format: The format to return the draft in (minimal, full, raw, metadata)
+            draft_id: String identifier of the draft email to retrieve
+            format: Output format of the draft (options: minimal, full, raw, metadata). Defaults to 'full'
 
         Returns:
-            The draft information or an error message
+            A formatted string containing the draft email details (ID, recipient, subject) or an error message if retrieval fails
+
+        Raises:
+            NotAuthorizedError: When the user's Gmail authorization is invalid or expired
+            KeyError: When required configuration keys or response data fields are missing
+            Exception: For any other unexpected errors during draft retrieval
+
+        Tags:
+            retrieve, email, gmail, draft, api, format, important
         """
         try:
             url = f"{self.base_api_url}/drafts/{draft_id}"
@@ -223,15 +259,24 @@ class GoogleMailApp(APIApplication):
     def list_drafts(
         self, max_results: int = 20, q: str = None, include_spam_trash: bool = False
     ) -> str:
-        """List drafts in the user's mailbox
+        """
+        Retrieves and formats a list of email drafts from the user's Gmail mailbox with optional filtering and pagination.
 
         Args:
             max_results: Maximum number of drafts to return (max 500, default 20)
-            q: Search query to filter drafts (same format as Gmail search)
-            include_spam_trash: Include drafts from spam and trash folders
+            q: Search query string to filter drafts using Gmail search syntax (default None)
+            include_spam_trash: Boolean flag to include drafts from spam and trash folders (default False)
 
         Returns:
-            A formatted list of drafts or an error message
+            A formatted string containing the list of draft IDs and count information, or an error message if the request fails
+
+        Raises:
+            NotAuthorizedError: When the Gmail API authentication is missing or invalid
+            KeyError: When required configuration keys are missing
+            Exception: For general errors during API communication or data processing
+
+        Tags:
+            list, email, drafts, gmail, api, search, query, pagination, important
         """
         try:
             url = f"{self.base_api_url}/drafts"
@@ -286,13 +331,22 @@ class GoogleMailApp(APIApplication):
             return f"Error listing drafts: {type(e).__name__} - {str(e)}"
 
     def get_message(self, message_id: str) -> str:
-        """Get a specific email message by ID
+        """
+        Retrieves and formats a specific email message from Gmail API by its ID, including sender, recipient, date, subject, and message preview.
 
         Args:
-            message_id: The ID of the message to retrieve
+            message_id: The unique identifier of the Gmail message to retrieve
 
         Returns:
-            The message information or an error message
+            A formatted string containing the message details (ID, From, To, Date, Subject, Preview) or an error message if the retrieval fails
+
+        Raises:
+            NotAuthorizedError: When the request lacks proper Gmail API authorization
+            KeyError: When required configuration keys or message fields are missing
+            Exception: For general API communication errors or unexpected issues
+
+        Tags:
+            retrieve, email, format, api, gmail, message, important
         """
         try:
             url = f"{self.base_api_url}/messages/{message_id}"
@@ -350,15 +404,24 @@ class GoogleMailApp(APIApplication):
     def list_messages(
         self, max_results: int = 20, q: str = None, include_spam_trash: bool = False
     ) -> str:
-        """List messages in the user's mailbox
+        """
+        Retrieves and formats a list of messages from the user's Gmail mailbox with optional filtering and pagination support.
 
         Args:
             max_results: Maximum number of messages to return (max 500, default 20)
-            q: Search query to filter messages (same format as Gmail search)
-            include_spam_trash: Include messages from spam and trash folders
+            q: Search query string to filter messages using Gmail search syntax
+            include_spam_trash: Boolean flag to include messages from spam and trash folders (default False)
 
         Returns:
-            A formatted list of messages or an error message
+            A formatted string containing the list of message IDs and thread IDs, or an error message if the operation fails
+
+        Raises:
+            NotAuthorizedError: When the Gmail API authentication is invalid or missing
+            KeyError: When required configuration keys are missing
+            Exception: For general API errors, network issues, or other unexpected problems
+
+        Tags:
+            list, messages, gmail, search, query, pagination, important
         """
         try:
             url = f"{self.base_api_url}/messages"
@@ -417,10 +480,21 @@ class GoogleMailApp(APIApplication):
             return f"Error listing messages: {type(e).__name__} - {str(e)}"
 
     def list_labels(self) -> str:
-        """List all labels in the user's Gmail account
+        """
+        Retrieves and formats a list of all labels (both system and user-created) from the user's Gmail account, organizing them by type and sorting them alphabetically.
+
+        Args:
+            None: This method takes no arguments
 
         Returns:
-            A formatted list of labels or an error message
+            A formatted string containing a list of Gmail labels categorized by type (system and user), with their IDs, or an error message if the operation fails.
+
+        Raises:
+            NotAuthorizedError: Raised when the user's Gmail authorization is invalid or missing
+            Exception: Raised when any other unexpected error occurs during the API request or data processing
+
+        Tags:
+            list, gmail, labels, fetch, organize, important, management
         """
         try:
             url = f"{self.base_api_url}/labels"
@@ -486,13 +560,21 @@ class GoogleMailApp(APIApplication):
             return f"Error listing labels: {type(e).__name__} - {str(e)}"
 
     def create_label(self, name: str) -> str:
-        """Create a new Gmail label
+        """
+        Creates a new Gmail label with specified visibility settings and returns creation status details.
 
         Args:
             name: The display name of the label to create
 
         Returns:
-            A confirmation message with the new label details
+            A formatted string containing the creation status, including the new label's name and ID if successful, or an error message if the creation fails
+
+        Raises:
+            NotAuthorizedError: Raised when the request lacks proper Gmail API authorization
+            Exception: Raised for any other unexpected errors during label creation
+
+        Tags:
+            create, label, gmail, management, important
         """
         try:
             url = f"{self.base_api_url}/labels"
@@ -531,13 +613,21 @@ class GoogleMailApp(APIApplication):
             return f"Error creating label: {type(e).__name__} - {str(e)}"
 
     def get_profile(self) -> str:
-        """Retrieve the user's Gmail profile information.
+        """
+        Retrieves and formats the user's Gmail profile information including email address, message count, thread count, and history ID.
 
-        This method fetches the user's email address, message count, thread count,
-        and current history ID from the Gmail API.
+        Args:
+            None: This method takes no arguments besides self
 
         Returns:
-            A formatted string containing the user's profile information or an error message
+            A formatted string containing the user's Gmail profile information or an error message if the request fails
+
+        Raises:
+            NotAuthorizedError: Raised when the user's credentials are invalid or authorization is required
+            Exception: Raised for any other unexpected errors during the API request or data processing
+
+        Tags:
+            fetch, profile, gmail, user-info, api-request, important
         """
         try:
             url = f"{self.base_api_url}/profile"