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

universal_mcp/applications/google_calendar/app.py

@@ -59,7 +59,8 @@ class GoogleCalendarApp(APIApplication):
     def get_today_events(
         self, days: int = 1, max_results: int = None, time_zone: str = None
     ) -> str:
-        """Get events from your Google Calendar for today or a specified number of days
+        """
+        Retrieves and formats events from Google Calendar for today or a specified number of future days, with optional result limiting and timezone specification.
 
         Args:
             days: Number of days to retrieve events for (default: 1, which is just today)
@@ -67,42 +68,36 @@ class GoogleCalendarApp(APIApplication):
             time_zone: Time zone used in the response (optional, default is calendar's time zone)
 
         Returns:
-            A formatted list of events or an error message
+            A formatted string containing a list of calendar events with their times and IDs, or a message indicating no events were found
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+
+        Tags:
+            fetch, list, calendar, events, date-time, important, api, formatting
         """
-        # Get today's date in ISO format
         today = datetime.utcnow().date()
         end_date = today + timedelta(days=days)
-
-        # Format dates for API
         time_min = f"{today.isoformat()}T00:00:00Z"
         time_max = f"{end_date.isoformat()}T00:00:00Z"
-
         url = f"{self.base_api_url}/events"
-
-        # Build query parameters
         params = {
             "timeMin": time_min,
             "timeMax": time_max,
             "singleEvents": "true",
             "orderBy": "startTime",
         }
-
         if max_results is not None:
             params["maxResults"] = max_results
-
         if time_zone:
             params["timeZone"] = time_zone
-
         date_range = "today" if days == 1 else f"the next {days} days"
         logger.info(f"Retrieving calendar events for {date_range}")
-
         response = self._get(url, params=params)
         response.raise_for_status()
-
         events = response.json().get("items", [])
         if not events:
             return f"No events scheduled for {date_range}."
-
         result = f"Events for {date_range}:\n\n"
         for event in events:
             # Extract event date and time
@@ -137,62 +132,51 @@ class GoogleCalendarApp(APIApplication):
             event_id = event.get("id", "No ID")
 
             result += f"- {time_display}: {summary} (ID: {event_id})\n"
-
         return result
 
     def get_event(
         self, event_id: str, max_attendees: int = None, time_zone: str = None
     ) -> str:
-        """Get a specific event from your Google Calendar by ID
+        """
+        Retrieves and formats detailed information about a specific Google Calendar event by its ID
 
         Args:
-            event_id: The ID of the event to retrieve
-            max_attendees: Optional. The maximum number of attendees to include in the response
-            time_zone: Optional. Time zone used in the response (default is calendar's time zone)
+            event_id: The unique identifier of the calendar event to retrieve
+            max_attendees: Optional. The maximum number of attendees to include in the response. If None, includes all attendees
+            time_zone: Optional. The time zone to use for formatting dates in the response. If None, uses the calendar's default time zone
 
         Returns:
-            A formatted event details or an error message
+            A formatted string containing comprehensive event details including summary, time, location, description, creator, organizer, recurrence status, and attendee information
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+            JSONDecodeError: Raised when the API response cannot be parsed as JSON
+
+        Tags:
+            retrieve, calendar, event, format, api, important
         """
         url = f"{self.base_api_url}/events/{event_id}"
-
-        # Build query parameters
         params = {}
         if max_attendees is not None:
             params["maxAttendees"] = max_attendees
         if time_zone:
             params["timeZone"] = time_zone
-
         logger.info(f"Retrieving calendar event with ID: {event_id}")
-
         response = self._get(url, params=params)
         response.raise_for_status()
-
         event = response.json()
-
-        # Extract event details
         summary = event.get("summary", "Untitled event")
         description = event.get("description", "No description")
         location = event.get("location", "No location specified")
-
-        # Format dates
         start = event.get("start", {})
         end = event.get("end", {})
-
         start_time = start.get("dateTime", start.get("date", "Unknown"))
         end_time = end.get("dateTime", end.get("date", "Unknown"))
-
-        # Format datetimes using the helper function
         start_formatted = self._format_datetime(start_time)
         end_formatted = self._format_datetime(end_time)
-
-        # Get creator and organizer
         creator = event.get("creator", {}).get("email", "Unknown")
         organizer = event.get("organizer", {}).get("email", "Unknown")
-
-        # Check if it's a recurring event
         recurrence = "Yes" if "recurrence" in event else "No"
-
-        # Get attendees if any
         attendees = event.get("attendees", [])
         attendee_info = ""
         if attendees:
@@ -211,8 +195,6 @@ class GoogleCalendarApp(APIApplication):
 
                 formatted_status = status_mapping.get(response_status, response_status)
                 attendee_info += f"  {i}. {name} ({email}) - {formatted_status}\n"
-
-        # Format the response
         result = f"Event: {summary}\n"
         result += f"ID: {event_id}\n"
         result += f"When: {start_formatted} to {end_formatted}\n"
@@ -222,7 +204,6 @@ class GoogleCalendarApp(APIApplication):
         result += f"Organizer: {organizer}\n"
         result += f"Recurring: {recurrence}\n"
         result += attendee_info
-
         return result
 
     def list_events(
@@ -236,69 +217,58 @@ class GoogleCalendarApp(APIApplication):
         time_zone: str = None,
         page_token: str = None,
     ) -> str:
-        """List events from your Google Calendar with various filtering options
+        """
+        Retrieves and formats a list of events from Google Calendar with customizable filtering, sorting, and pagination options
 
         Args:
             max_results: Maximum number of events to return (default: 10, max: 2500)
-            time_min: Start time (ISO format, e.g. '2023-12-01T00:00:00Z') - defaults to now if not specified
-            time_max: End time (ISO format, e.g. '2023-12-31T23:59:59Z')
-            q: Free text search terms (searches summary, description, location, attendees, etc.)
-            order_by: How to order results - 'startTime' (default) or 'updated'
-            single_events: Whether to expand recurring events (default: True)
-            time_zone: Time zone used in the response (default is calendar's time zone)
-            page_token: Token for retrieving a specific page of results
+            time_min: Start time in ISO format (e.g., '2023-12-01T00:00:00Z'). Defaults to current time if not specified
+            time_max: End time in ISO format (e.g., '2023-12-31T23:59:59Z')
+            q: Free text search terms to filter events (searches across summary, description, location, attendees)
+            order_by: Sort order for results - either 'startTime' (default) or 'updated'
+            single_events: Whether to expand recurring events into individual instances (default: True)
+            time_zone: Time zone for response formatting (defaults to calendar's time zone)
+            page_token: Token for retrieving a specific page of results in paginated responses
 
         Returns:
-            A formatted list of events or an error message
+            A formatted string containing the list of events with details including summary, ID, start time, and location, or a message if no events are found
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+
+        Tags:
+            list, calendar, events, search, filter, pagination, format, important
         """
         url = f"{self.base_api_url}/events"
-
-        # Build query parameters
         params = {
             "maxResults": max_results,
             "singleEvents": str(single_events).lower(),
             "orderBy": order_by,
         }
-
-        # Set time boundaries if provided, otherwise default to now for time_min
         if time_min:
             params["timeMin"] = time_min
         else:
             # Default to current time if not specified
             now = datetime.utcnow().isoformat() + "Z"  # 'Z' indicates UTC time
             params["timeMin"] = now
-
         if time_max:
             params["timeMax"] = time_max
-
-        # Add optional filters if provided
         if q:
             params["q"] = q
-
         if time_zone:
             params["timeZone"] = time_zone
-
         if page_token:
             params["pageToken"] = page_token
-
         logger.info(f"Retrieving calendar events with params: {params}")
-
         response = self._get(url, params=params)
         response.raise_for_status()
-
         data = response.json()
         events = data.get("items", [])
-
         if not events:
             return "No events found matching your criteria."
-
-        # Extract calendar information
         calendar_summary = data.get("summary", "Your Calendar")
         time_zone_info = data.get("timeZone", "Unknown")
-
         result = f"Events from {calendar_summary} (Time Zone: {time_zone_info}):\n\n"
-
-        # Process and format each event
         for i, event in enumerate(events, 1):
             # Get basic event details
             event_id = event.get("id", "No ID")
@@ -327,75 +297,53 @@ class GoogleCalendarApp(APIApplication):
             # Add a separator between events
             if i < len(events):
                 result += "\n"
-
-        # Add pagination info if available
         if "nextPageToken" in data:
             next_token = data.get("nextPageToken")
             result += (
                 f"\nMore events available. Use page_token='{next_token}' to see more."
             )
-
         return result
 
     def quick_add_event(self, text: str, send_updates: str = "none") -> str:
-        """Create a calendar event using natural language description
-
-        This method allows you to quickly create an event using a simple text string,
-        similar to how you would add events in the Google Calendar UI.
+        """
+        Creates a calendar event using natural language text input and returns a formatted confirmation message with event details.
 
         Args:
-            text: Text describing the event (e.g., "Meeting with John at Coffee Shop tomorrow 3pm-4pm")
-            send_updates: Who should receive notifications - "all", "externalOnly", or "none" (default)
+            text: Natural language text describing the event (e.g., 'Meeting with John at Coffee Shop tomorrow 3pm-4pm')
+            send_updates: Specifies who should receive event notifications: 'all', 'externalOnly', or 'none' (default)
 
         Returns:
-            A confirmation message with the created event details or an error message
+            A formatted string containing the confirmation message with event details including summary, time, location, and event ID
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+
+        Tags:
+            create, calendar, event, quick-add, natural-language, important
         """
         url = f"{self.base_api_url}/events/quickAdd"
-
-        # Use params argument instead of manually constructing URL
         params = {"text": text, "sendUpdates": send_updates}
-
         logger.info(f"Creating event via quickAdd: '{text}'")
-
-        # Pass params to _post method
         response = self._post(url, data=None, params=params)
         response.raise_for_status()
-
         event = response.json()
-
-        # Extract event details
         event_id = event.get("id", "Unknown")
         summary = event.get("summary", "Untitled event")
-
-        # Format dates
         start = event.get("start", {})
         end = event.get("end", {})
-
         start_time = start.get("dateTime", start.get("date", "Unknown"))
         end_time = end.get("dateTime", end.get("date", "Unknown"))
-
-        # Format datetimes using the helper function
         start_formatted = self._format_datetime(start_time)
         end_formatted = self._format_datetime(end_time)
-
-        # Get location if available
         location = event.get("location", "No location specified")
-
-        # Format the confirmation message
         result = "Successfully created event!\n\n"
         result += f"Summary: {summary}\n"
         result += f"When: {start_formatted}"
-
-        # Only add end time if it's different from start (for all-day events they might be the same)
         if start_formatted != end_formatted:
             result += f" to {end_formatted}"
-
         result += f"\nWhere: {location}\n"
         result += f"Event ID: {event_id}\n"
-
-        # Add a note about viewing the event
         result += f"\nUse get_event('{event_id}') to see full details."
-
         return result
 
     def get_event_instances(
@@ -408,57 +356,47 @@ class GoogleCalendarApp(APIApplication):
         show_deleted: bool = False,
         page_token: str = None,
     ) -> str:
-        """Get all instances of a recurring event
-
-        This method retrieves all occurrences of a recurring event within a specified time range.
+        """
+        Retrieves and formats all instances of a recurring calendar event within a specified time range, showing details like time, status, and modifications for each occurrence.
 
         Args:
             event_id: ID of the recurring event
             max_results: Maximum number of event instances to return (default: 25, max: 2500)
-            time_min: Lower bound (inclusive) for event's end time (ISO format)
-            time_max: Upper bound (exclusive) for event's start time (ISO format)
-            time_zone: Time zone used in the response (default is calendar's time zone)
+            time_min: Lower bound (inclusive) for event's end time in ISO format
+            time_max: Upper bound (exclusive) for event's start time in ISO format
+            time_zone: Time zone used in the response (defaults to calendar's time zone)
             show_deleted: Whether to include deleted instances (default: False)
             page_token: Token for retrieving a specific page of results
 
         Returns:
-            A formatted list of event instances or an error message
+            A formatted string containing a list of event instances with details including time, status, instance ID, and modification information, plus pagination token if applicable.
+
+        Raises:
+            HTTPError: Raised when the API request fails or returns an error status code
+            JSONDecodeError: Raised when the API response cannot be parsed as JSON
+
+        Tags:
+            list, retrieve, calendar, events, recurring, pagination, formatting, important
         """
         url = f"{self.base_api_url}/events/{event_id}/instances"
-
-        # Build query parameters
         params = {"maxResults": max_results, "showDeleted": str(show_deleted).lower()}
-
-        # Add optional parameters if provided
         if time_min:
             params["timeMin"] = time_min
-
         if time_max:
             params["timeMax"] = time_max
-
         if time_zone:
             params["timeZone"] = time_zone
-
         if page_token:
             params["pageToken"] = page_token
-
         logger.info(f"Retrieving instances of recurring event with ID: {event_id}")
-
         response = self._get(url, params=params)
         response.raise_for_status()
-
         data = response.json()
         instances = data.get("items", [])
-
         if not instances:
             return f"No instances found for recurring event with ID: {event_id}"
-
-        # Extract event summary from the first instance
         parent_summary = instances[0].get("summary", "Untitled recurring event")
-
         result = f"Instances of recurring event: {parent_summary}\n\n"
-
-        # Process and format each instance
         for i, instance in enumerate(instances, 1):
             # Get instance ID and status
             instance_id = instance.get("id", "No ID")
@@ -500,12 +438,9 @@ class GoogleCalendarApp(APIApplication):
             # Add a separator between instances
             if i < len(instances):
                 result += "\n"
-
-        # Add pagination info if available
         if "nextPageToken" in data:
             next_token = data.get("nextPageToken")
             result += f"\nMore instances available. Use page_token='{next_token}' to see more."
-
         return result
 
     def list_tools(self):

universal_mcp/applications/google_docs/app.py

@@ -11,7 +11,7 @@ class GoogleDocsApp(APIApplication):
     def __init__(self, integration: Integration) -> None:
         super().__init__(name="google-docs", integration=integration)
         self.base_api_url = "https://docs.googleapis.com/v1/documents"
-    
+
     def _get_headers(self):
         if not self.integration:
             raise ValueError("Integration not configured for GoogleDocsApp")
@@ -26,68 +26,81 @@ class GoogleDocsApp(APIApplication):
             "Authorization": f"Bearer {credentials['access_token']}",
             "Content-Type": "application/json",
         }
-    
+
     def create_document(self, title: str) -> dict[str, Any]:
         """
-        Creates a new blank Google Document with the specified title.
-        
+        Creates a new blank Google Document with the specified title and returns the API response.
+
         Args:
-            title: The title of the document to create
-            
+            title: The title for the new Google Document to be created
+
         Returns:
-            The response from the Google Docs API
+            A dictionary containing the Google Docs API response with document details and metadata
+
+        Raises:
+            HTTPError: If the API request fails due to network issues, authentication errors, or invalid parameters
+            RequestException: If there are connection errors or timeout issues during the API request
+
+        Tags:
+            create, document, api, important, google-docs, http
         """
         url = self.base_api_url
         document_data = {"title": title}
         response = self._post(url, data=document_data)
         response.raise_for_status()
         return response.json()
-    
+
     def get_document(self, document_id: str) -> dict[str, Any]:
         """
-        Gets the latest version of the specified document.
-        
+        Retrieves the latest version of a specified document from the Google Docs API.
+
         Args:
-            document_id: The ID of the document to retrieve
-            
+            document_id: The unique identifier of the document to retrieve
+
         Returns:
-            The response from the Google Docs API containing the document data
+            A dictionary containing the document data from the Google Docs API response
+
+        Raises:
+            HTTPError: If the API request fails or the document is not found
+            JSONDecodeError: If the API response cannot be parsed as JSON
+
+        Tags:
+            retrieve, read, api, document, google-docs, important
         """
         url = f"{self.base_api_url}/{document_id}"
         response = self._get(url)
         return response.json()
-    
-    def add_content(self, document_id: str, content: str, index: int = 1) -> dict[str, Any]:
+
+    def add_content(
+        self, document_id: str, content: str, index: int = 1
+    ) -> dict[str, Any]:
         """
-        Adds text content to an existing Google Document.
-        
+        Adds text content at a specified position in an existing Google Document via the Google Docs API.
+
         Args:
-            document_id: The ID of the document to update
-            content: The text content to insert
-            index: The position at which to insert the text (default: 1, beginning of document)
-            
+            document_id: The unique identifier of the Google Document to be updated
+            content: The text content to be inserted into the document
+            index: The zero-based position in the document where the text should be inserted (default: 1)
+
         Returns:
-            The response from the Google Docs API
+            A dictionary containing the Google Docs API response after performing the batch update operation
+
+        Raises:
+            HTTPError: When the API request fails, such as invalid document_id or insufficient permissions
+            RequestException: When there are network connectivity issues or API endpoint problems
+
+        Tags:
+            update, insert, document, api, google-docs, batch, content-management, important
         """
         url = f"{self.base_api_url}/{document_id}:batchUpdate"
         batch_update_data = {
             "requests": [
-                {
-                    "insertText": {
-                        "location": {"index": index},
-                        "text": content
-                    }
-                }
+                {"insertText": {"location": {"index": index}, "text": content}}
             ]
         }
-        
         response = self._post(url, data=batch_update_data)
         response.raise_for_status()
         return response.json()
-    
+
     def list_tools(self):
-        return [
-           self.create_document,
-           self.get_document,
-           self.add_content
-        ]
+        return [self.create_document, self.get_document, self.add_content]