universal-mcp-applications 0.1.17__py3-none-any.whl → 0.1.18__py3-none-any.whl

universal_mcp/applications/outlook/app.py

@@ -18,7 +18,7 @@ class OutlookApp(APIApplication):
         message: dict[str, Any] | None = None,
     ) -> Any:
         """
-        Replies to a specific email message identified by its ID. The reply can contain a simple comment or a full message object with attachments. If no user ID is provided, it defaults to the current user, distinguishing it from `user_send_mail` which sends a new email.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -70,7 +70,7 @@ class OutlookApp(APIApplication):
         saveToSentItems: bool | None = None,
     ) -> Any:
         """
-        Sends a new email on behalf of a user, using a provided dictionary for content like recipients and subject. Unlike `users_message_reply`, which replies to an existing message, this function is used to compose and send an entirely new email from scratch.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -121,7 +121,7 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> Any:
         """
-        Retrieves a specific mail folder by its ID for a given user. Allows customization of the response by optionally including hidden folders, selecting specific properties to return, or expanding related entities. It specifically targets folder metadata, not the messages within.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -176,7 +176,7 @@ 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 `user_get_message`, which fetches a single email by its ID.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -250,7 +250,7 @@ class OutlookApp(APIApplication):
         expand: list[str] | None = None,
     ) -> Any:
         """
-        Retrieves a specific message by its ID for a user, with options to select fields or expand related data. This function fetches a single item, in contrast to `user_list_message` which retrieves a collection of messages.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -293,7 +293,7 @@ class OutlookApp(APIApplication):
 
     def user_delete_message(self, message_id: str, user_id: str | None = None) -> Any:
         """
-        Deletes a specific Outlook message for a user, identified by its unique `message_id`. If `user_id` is not provided, it automatically targets the currently authenticated user's mailbox. It makes a DELETE request to the corresponding Microsoft Graph API endpoint to permanently remove the message.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -337,7 +337,7 @@ 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.
+        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.
         
         Args:
             user_id (string, optional): user-id. If not provided, will automatically get the current user's ID.
@@ -392,7 +392,7 @@ class OutlookApp(APIApplication):
         self,
     ) -> dict[str, Any]:
         """
-        Fetches the `userPrincipalName` for the currently authenticated user from the `/me` endpoint. It is a helper function used internally by other methods to automatically obtain the user's ID for API calls when one is not explicitly provided.
+        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.
         
         
         Returns:
@@ -413,7 +413,7 @@ class OutlookApp(APIApplication):
 
     def get_next_page(self, url: str) -> dict[str, Any]:
         """
-        Executes a GET request using a full URL, typically a pagination link (`@odata.nextLink`) from a previous API response. It validates the URL, extracts the relative path and query parameters, and fetches the corresponding data, simplifying navigation through paginated API results.
+        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.
         """
         if not url:
             raise ValueError("Missing required parameter 'url'.")

universal_mcp/applications/reddit/app.py

@@ -49,20 +49,20 @@ class RedditApp(APIApplication):
         self, subreddit: str, limit: int = 5, timeframe: str = "day"
     ) -> dict[str, Any]:
         """
-        Fetches top posts from a given subreddit, filterable by time.
-
+        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.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix
             limit: The maximum number of posts to return (default: 5, max: 100)
             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
-
+        
         Raises:
             RequestException: When the HTTP request to the Reddit API fails
             JSONDecodeError: When the API response contains invalid JSON
-
+        
         Tags:
             fetch, reddit, api, list, social-media, important, read-only
         """
@@ -85,20 +85,20 @@ class RedditApp(APIApplication):
         self, query: str, limit: int = 5, sort: str = "relevance"
     ) -> str:
         """
-        Searches Reddit for subreddits matching a given query string and returns a formatted list of results including subreddit names, subscriber counts, and descriptions.
-
+        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.
+        
         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')
-
+        
         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
-
+        
         Raises:
             RequestException: When the HTTP request to Reddit's API fails
             JSONDecodeError: When the API response contains invalid JSON
-
+        
         Tags:
             search, important, reddit, api, query, format, list, validation
         """
@@ -123,18 +123,18 @@ class RedditApp(APIApplication):
 
     def get_post_flairs(self, subreddit: str):
         """
-        Retrieves a list of available post flairs for a specified subreddit using the Reddit API.
-
+        Fetches a list of available post flairs (tags) for a specified subreddit. This is primarily used to discover the correct `flair_id` needed to categorize a new submission when using the `create_post` function. It returns flair details or a message if none are available.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix
-
+        
         Returns:
             A list of dictionaries containing flair details if flairs exist, or a string message indicating no flairs are available
-
+        
         Raises:
             RequestException: When the API request fails or network connectivity issues occur
             JSONDecodeError: When the API response contains invalid JSON data
-
+        
         Tags:
             fetch, get, reddit, flair, api, read-only
         """
@@ -156,8 +156,8 @@ class RedditApp(APIApplication):
         flair_id: str = None,
     ):
         """
-        Creates a new Reddit post in a specified subreddit with support for text posts, link posts, and image posts
-
+        Creates a new Reddit post in a specified subreddit. It supports text ('self') or link posts, requiring a title and corresponding content (text or URL). An optional flair can be assigned. Returns the API response or a formatted error message on failure.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'
             title: The title of the post
@@ -165,13 +165,13 @@ class RedditApp(APIApplication):
             text: The text content of the post; required if kind is 'self'
             url: The URL of the link or image; required if kind is 'link'. Must end with valid image extension for image posts
             flair_id: The ID of the flair to assign to the post
-
+        
         Returns:
             The JSON response from the Reddit API, or an error message as a string if the API returns an error
-
+        
         Raises:
             ValueError: Raised when kind is invalid or when required parameters (text for self posts, url for link posts) are missing
-
+        
         Tags:
             create, post, social-media, reddit, api, important
         """
@@ -209,18 +209,18 @@ class RedditApp(APIApplication):
 
     def get_comment_by_id(self, comment_id: str) -> dict:
         """
-        Retrieves a specific Reddit comment using its unique identifier.
-
+        Retrieves a single Reddit comment's data, such as author and score, using its unique 't1_' prefixed ID. Unlike `get_post_comments_details` which fetches all comments for a post, this function targets one specific comment directly, returning an error dictionary if it is not found.
+        
         Args:
             comment_id: The full unique identifier of the comment (prefixed with 't1_', e.g., 't1_abcdef')
-
+        
         Returns:
             A dictionary containing the comment data including attributes like author, body, score, etc. If the comment is not found, returns a dictionary with an error message.
-
+        
         Raises:
             HTTPError: When the Reddit API request fails due to network issues or invalid authentication
             JSONDecodeError: When the API response cannot be parsed as valid JSON
-
+        
         Tags:
             retrieve, get, reddit, comment, api, fetch, single-item, important
         """
@@ -235,19 +235,19 @@ class RedditApp(APIApplication):
 
     def post_comment(self, parent_id: str, text: str) -> dict:
         """
-        Posts a comment to a Reddit post or comment using the Reddit API
-
+        Posts a new comment as a reply to a specified Reddit post or another comment. Using the parent's full ID and the desired text, it submits the comment via the API and returns the response containing the new comment's details.
+        
         Args:
             parent_id: The full ID of the parent comment or post (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
             text: The text content of the comment to be posted
-
+        
         Returns:
             A dictionary containing the Reddit API response with details about the posted comment
-
+        
         Raises:
             RequestException: If the API request fails or returns an error status code
             JSONDecodeError: If the API response cannot be parsed as JSON
-
+        
         Tags:
             post, comment, social, reddit, api, important
         """
@@ -262,19 +262,19 @@ class RedditApp(APIApplication):
 
     def edit_content(self, content_id: str, text: str) -> dict:
         """
-        Edits the text content of an existing Reddit post or comment using the Reddit API
-
+        Modifies the text of a specific Reddit post or comment via its unique ID. Unlike creation or deletion functions, this method specifically handles updates to existing user-generated content, submitting the new text to the API and returning a JSON response detailing the edited item.
+        
         Args:
             content_id: The full ID of the content to edit (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
             text: The new text content to replace the existing content
-
+        
         Returns:
             A dictionary containing the API response with details about the edited content
-
+        
         Raises:
             RequestException: When the API request fails or network connectivity issues occur
             ValueError: When invalid content_id format or empty text is provided
-
+        
         Tags:
             edit, update, content, reddit, api, important
         """
@@ -289,18 +289,18 @@ class RedditApp(APIApplication):
 
     def delete_content(self, content_id: str) -> dict:
         """
-        Deletes a specified Reddit post or comment using the Reddit API.
-
+        Deletes a specified Reddit post or comment using its full identifier (`content_id`). It sends a POST request to the `/api/del` endpoint for permanent removal, unlike `edit_content` which only modifies. On success, it returns a confirmation message.
+        
         Args:
             content_id: The full ID of the content to delete (e.g., 't3_abc123' for a post, 't1_def456' for a comment)
-
+        
         Returns:
             A dictionary containing a success message with the deleted content ID
-
+        
         Raises:
             HTTPError: When the API request fails or returns an error status code
             RequestException: When there are network connectivity issues or API communication problems
-
+        
         Tags:
             delete, content-management, api, reddit, important
         """
@@ -315,10 +315,11 @@ class RedditApp(APIApplication):
 
     def get_current_user_info(self) -> Any:
         """
-        Get the current user's information.
+        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.
-
+        
         Tags:
             users
         """
@@ -330,11 +331,11 @@ class RedditApp(APIApplication):
 
     def get_current_user_karma(self) -> Any:
         """
-        Get the current user's karma.
-
+        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.
-
+        
         Tags:
             account
         """
@@ -346,14 +347,14 @@ class RedditApp(APIApplication):
 
     def get_post_comments_details(self, post_id: str) -> Any:
         """
-        Get post details and comments like title, author, score, etc.
-
+        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/)
-
+        
         Returns:
             Any: API response data containing post details and comments.
-
+        
         Tags:
             listings, comments, posts, important
         """
@@ -373,8 +374,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the most controversial posts across Reddit.
-
+        Fetches a global list of the most controversial posts from across all of Reddit, distinct from subreddit-specific queries. Optional parameters allow for pagination and customization of the results, returning the direct API response data with the post listings.
+        
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
             before: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results before.
@@ -382,10 +383,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of controversial posts.
-
+        
         Tags:
             listings, posts, controversial, read-only
         """
@@ -417,8 +418,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the hottest posts across Reddit.
-
+        Retrieves trending 'hot' posts from the global Reddit feed. Unlike `get_subreddit_hot_posts`, this operates across all of Reddit, not a specific subreddit. It supports pagination and optional filtering by geographical region to customize the listing of returned posts.
+        
         Args:
             g: Optional. A geographical region to filter posts by (e.g., 'GLOBAL', 'US', 'GB').
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -427,10 +428,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of hot posts.
-
+        
         Tags:
             listings, posts, hot, read-only
         """
@@ -462,8 +463,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the newest posts across Reddit.
-
+        Fetches a list of the newest posts from across all of Reddit, not limited to a specific subreddit. This function supports optional pagination and filtering parameters to customize the API response, differentiating it from `get_subreddit_new_posts` which targets a single subreddit.
+        
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
             before: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results before.
@@ -471,10 +472,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of new posts.
-
+        
         Tags:
             listings, posts, new, read-only
         """
@@ -507,8 +508,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the hottest posts in a specified subreddit.
-
+        Retrieves a list of 'hot' posts from a specified subreddit, supporting pagination and geographical filtering. Unlike `get_hot_posts`, which queries all of Reddit, this function targets a single subreddit to fetch its currently trending content, distinct from top or new posts.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
             g: Optional. A geographical region to filter posts by (e.g., 'GLOBAL', 'US', 'GB').
@@ -518,10 +519,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of hot posts from the subreddit.
-
+        
         Tags:
             listings, posts, subreddit, hot, read-only
         """
@@ -556,8 +557,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the newest posts in a specified subreddit.
-
+        Retrieves a list of the newest posts from a specified subreddit, sorted chronologically. Unlike `get_new_posts` which targets all of Reddit, this function is subreddit-specific and supports standard pagination parameters like `limit` and `after` to navigate through the listing of recent submissions.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -566,10 +567,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of new posts from the subreddit.
-
+        
         Tags:
             listings, posts, subreddit, new, read-only
         """
@@ -603,8 +604,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the top posts in a specified subreddit.
-
+        Fetches top-rated posts from a specific subreddit using standard API pagination parameters. Unlike the simpler `get_subreddit_posts` which filters by timeframe, this function offers more direct control over retrieving listings, distinguishing it from the site-wide `get_top_posts` which queries all of Reddit.
+        
         Args:
             subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix.
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
@@ -613,10 +614,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of top posts from the subreddit.
-
+        
         Tags:
             listings, posts, subreddit, top, read-only
         """
@@ -649,8 +650,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the rising posts across Reddit.
-
+        Retrieves a list of rising posts from across all of Reddit. Unlike subreddit-specific listing functions (e.g., `get_subreddit_hot_posts`), this operates globally. It supports optional pagination and filtering parameters, such as `limit` and `after`, to customize the API response and navigate through results.
+        
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
             before: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results before.
@@ -658,10 +659,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of rising posts.
-
+        
         Tags:
             listings, posts, rising, read-only
         """
@@ -692,8 +693,8 @@ class RedditApp(APIApplication):
         sr_detail: str = None,
     ) -> Any:
         """
-        Retrieves a list of the top posts across Reddit.
-
+        Fetches top-rated posts from across all of Reddit, distinct from `get_subreddit_top_posts`, which operates on a specific subreddit. The function supports standard API pagination parameters like `limit`, `after`, and `before` to navigate results, providing a broad, site-wide view of top content.
+        
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
             before: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results before.
@@ -701,10 +702,10 @@ class RedditApp(APIApplication):
             limit: Optional. The maximum number of items desired (default: 25, maximum: 100).
             show: Optional. The string "all" to show all posts.
             sr_detail: Optional. Expand subreddit details.
-
+        
         Returns:
             Any: API response data containing a list of top posts.
-
+        
         Tags:
             listings, posts, top, read-only
         """
@@ -742,8 +743,8 @@ class RedditApp(APIApplication):
         type: str = None,
     ) -> Any:
         """
-        Searches for posts, comments, and users across Reddit.
-
+        Executes a broad, keyword-based search across Reddit for various content types like posts, comments, or users. This general-purpose function offers extensive filtering options, distinguishing it from the more specialized `search_subreddits` which only finds communities.
+        
         Args:
             after: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results after.
             before: Optional. The fullname of a thing (e.g., 't3_xxxxxx') to return results before.
@@ -758,10 +759,10 @@ class RedditApp(APIApplication):
             sr_detail: Optional. Expand subreddit details.
             t: Optional. One of ('hour', 'day', 'week', 'month', 'year', 'all') to filter by time.
             type: Optional. A comma-separated list of result types ('sr', 'link', 'user').
-
+        
         Returns:
             Any: API response data containing search results.
-
+        
         Tags:
             search, reddit, posts, comments, users, read-only
         """
@@ -791,14 +792,14 @@ class RedditApp(APIApplication):
 
     def get_user_profile(self, username: str) -> Any:
         """
-        Retrieves the profile information for a given Reddit user.
-
+        Retrieves public profile information for a specified Reddit user via the `/user/{username}/about` endpoint. Unlike `get_current_user_info`, which targets the authenticated user, this function fetches data like karma and account age for any user identified by their username.
+        
         Args:
             username: The username of the user to look up.
-
+        
         Returns:
             A dictionary containing the user's profile data.
-
+        
         Tags:
             users, profile, fetch
         """