universal-mcp 0.1.7rc1__py3-none-any.whl → 0.1.8__py3-none-any.whl

universal_mcp/applications/perplexity/app.py

@@ -2,7 +2,6 @@ from typing import Any, Literal
 
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.integrations import Integration
-from loguru import logger
 
 
 class PerplexityApp(APIApplication):
@@ -11,34 +10,6 @@ class PerplexityApp(APIApplication):
         self.api_key: str | None = None
         self.base_url = "https://api.perplexity.ai"
 
-    def _set_api_key(self):
-        if self.api_key:
-            return
-
-        if not self.integration:
-            raise ValueError("Integration is None. Cannot retrieve Perplexity API Key.")
-
-        credentials = self.integration.get_credentials()
-        if not credentials or "apiKey" not in credentials:
-            raise ValueError(
-                f"Failed to retrieve Perplexity API Key using integration '{self.integration.name}'. "
-            )
-
-        # if not isinstance(credentials, str) or not credentials.strip():
-        #     raise ValueError(
-        #         f"Invalid credential format received for Perplexity API Key via integration '{self.integration.name}'. "
-        #     )
-        self.api_key = credentials["apiKey"]
-
-    def _get_headers(self) -> dict[str, str]:
-        self._set_api_key()
-        logger.info(f"Perplexity API Key: {self.api_key}")
-        return {
-            "Authorization": f"Bearer {self.api_key}",
-            "Content-Type": "application/json",
-            "Accept": "application/json",
-        }
-
     def chat(
         self,
         query: str,
@@ -54,34 +25,35 @@ class PerplexityApp(APIApplication):
         system_prompt: str = "Be precise and concise.",
     ) -> dict[str, Any] | str:
         """
-        Sends a query to a Perplexity Sonar online model and returns the response.
-
-        This uses the chat completions endpoint, suitable for conversational queries
-        and leveraging Perplexity's online capabilities.
+        Initiates a chat completion request to generate AI responses using various models with customizable parameters.
 
         Args:
-            query: The user's query or message.
-            model: The specific Perplexity model to use (e.g., "r1-1776","sonar","sonar-pro","sonar-reasoning","sonar-reasoning-pro", "sonar-deep-research").Defaults to 'sonar'.
-            temperature: Sampling temperature for the response generation (e.g., 0.7).
-            system_prompt: An optional system message to guide the model's behavior.
+            query: The input text/prompt to send to the chat model
+            model: The model to use for chat completion. Options include 'r1-1776', 'sonar', 'sonar-pro', 'sonar-reasoning', 'sonar-reasoning-pro', 'sonar-deep-research'. Defaults to 'sonar'
+            temperature: Controls randomness in the model's output. Higher values make output more random, lower values more deterministic. Defaults to 1
+            system_prompt: Initial system message to guide the model's behavior. Defaults to 'Be precise and concise.'
 
         Returns:
-            A dictionary containing 'content' (str) and 'citations' (list) on success, or a string containing an error message on failure.
+            A dictionary containing the generated content and citations, with keys 'content' (str) and 'citations' (list), or a string in some cases
+
+        Raises:
+            AuthenticationError: Raised when API authentication fails due to missing or invalid credentials
+            HTTPError: Raised when the API request fails or returns an error status
+
+        Tags:
+            chat, generate, ai, completion, important
         """
         endpoint = f"{self.base_url}/chat/completions"
-
         messages = []
         if system_prompt:
             messages.append({"role": "system", "content": system_prompt})
         messages.append({"role": "user", "content": query})
-
         payload = {
             "model": model,
             "messages": messages,
             "temperature": temperature,
             # "max_tokens": 512,
         }
-
         data = self._post(endpoint, data=payload)
         response = data.json()
         content = response["choices"][0]["message"]["content"]

universal_mcp/applications/reddit/app.py

@@ -45,48 +45,48 @@ class RedditApp(APIApplication):
     def get_subreddit_posts(
         self, subreddit: str, limit: int = 5, timeframe: str = "day"
     ) -> str:
-        """Get the top posts from a specified subreddit over a given timeframe.
+        """
+        Retrieves and formats top posts from a specified subreddit within a given timeframe using the Reddit API
 
         Args:
-            subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'.
-            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').
+            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 listing the top posts or an error message.
+            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
         """
         valid_timeframes = ["hour", "day", "week", "month", "year", "all"]
         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."
             )
-
         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}'"
         )
         response = self._get(url, params=params)
-
         data = response.json()
-
         if "error" in data:
             logger.error(
                 f"Reddit API error: {data['error']} - {data.get('message', '')}"
             )
             return f"Error from Reddit API: {data['error']} - {data.get('message', '')}"
-
         posts = data.get("data", {}).get("children", [])
-
         if not posts:
             return (
                 f"No top posts found in r/{subreddit} for the timeframe '{timeframe}'."
             )
-
         result_lines = [
             f"Top {len(posts)} posts from r/{subreddit} (timeframe: {timeframe}):\n"
         ]
@@ -100,31 +100,36 @@ class RedditApp(APIApplication):
 
             result_lines.append(f'{i + 1}. "{title}" by u/{author} (Score: {score})')
             result_lines.append(f"   Link: {full_url}")
-
         return "\n".join(result_lines)
 
     def search_subreddits(
         self, query: str, limit: int = 5, sort: str = "relevance"
     ) -> str:
-        """Search for subreddits matching a query string.
+        """
+        Searches Reddit for subreddits matching a given query string and returns a formatted list of results including subreddit names, subscriber counts, and descriptions.
 
         Args:
-            query: The text to search for in subreddit names and descriptions.
-            limit: The maximum number of subreddits to return (default: 5, max: 100).
-            sort: The order of results. Valid options: 'relevance', 'activity' (default: 'relevance').
+            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 listing the found subreddits and their descriptions, or an error message.
+            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
         """
         valid_sorts = ["relevance", "activity"]
         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."
             )
-
         url = f"{self.base_api_url}/subreddits/search"
         params = {
             "q": query,
@@ -133,25 +138,19 @@ class RedditApp(APIApplication):
             # Optionally include NSFW results? Defaulting to false for safety.
             # "include_over_18": "false"
         }
-
         logger.info(
             f"Searching for subreddits matching '{query}' (limit: {limit}, sort: {sort})"
         )
         response = self._get(url, params=params)
-
         data = response.json()
-
         if "error" in data:
             logger.error(
                 f"Reddit API error during subreddit search: {data['error']} - {data.get('message', '')}"
             )
             return f"Error from Reddit API during search: {data['error']} - {data.get('message', '')}"
-
         subreddits = data.get("data", {}).get("children", [])
-
         if not subreddits:
             return f"No subreddits found matching the query '{query}'."
-
         result_lines = [
             f"Found {len(subreddits)} subreddits matching '{query}' (sorted by {sort}):\n"
         ]
@@ -173,28 +172,31 @@ class RedditApp(APIApplication):
             )
             if description:
                 result_lines.append(f"   Description: {description}")
-
         return "\n".join(result_lines)
 
     def get_post_flairs(self, subreddit: str):
-        """Retrieve the list of available post flairs for a specific subreddit.
+        """
+        Retrieves a list of available post flairs for a specified subreddit using the Reddit API.
 
         Args:
-            subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'.
+            subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/' prefix
 
         Returns:
-            A list of dictionaries containing flair details, or an error message.
-        """
+            A list of dictionaries containing flair details if flairs exist, or a string message indicating no flairs are available
 
-        url = f"{self.base_api_url}/r/{subreddit}/api/link_flair_v2"
+        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
+        """
+        url = f"{self.base_api_url}/r/{subreddit}/api/link_flair_v2"
         logger.info(f"Fetching post flairs for subreddit: r/{subreddit}")
         response = self._get(url)
-
         flairs = response.json()
         if not flairs:
             return f"No post flairs available for r/{subreddit}."
-
         return flairs
 
     def create_post(
@@ -206,32 +208,32 @@ class RedditApp(APIApplication):
         url: str = None,
         flair_id: str = None,
     ):
-        """Create a new post in a specified subreddit.
+        """
+        Creates a new Reddit post in a specified subreddit with support for text posts, link posts, and image posts
 
         Args:
-            subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'.
-            title: The title of the post.
-            kind: The type of post; either 'self' (text post) or 'link' (link or image post).
-            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'.
-                For image posts to be displayed correctly, the URL must directly point to an image file
-                and end with a valid image extension (e.g., .jpg, .png, or .gif).
-                Note that .gif support can be inconsistent.
-            flair_id: The ID of the flair to assign to the post.
+            subreddit: The name of the subreddit (e.g., 'python', 'worldnews') without the 'r/'
+            title: The title of the post
+            kind: The type of post; either 'self' (text post) or 'link' (link or image post)
+            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 reddit api returns an error within the json response, that error will be returned as a string.
-        """
+            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
+        """
         if kind not in ["self", "link"]:
             raise ValueError("Invalid post kind. Must be one of 'self' or 'link'.")
-
         if kind == "self" and not text:
             raise ValueError("Text content is required for text posts.")
         if kind == "link" and not url:
             raise ValueError("URL is required for link posts (including images).")
-
         data = {
             "sr": subreddit,
             "title": title,
@@ -241,13 +243,10 @@ class RedditApp(APIApplication):
             "flair_id": flair_id,
         }
         data = {k: v for k, v in data.items() if v is not None}
-
         url_api = f"{self.base_api_url}/api/submit"
         logger.info(f"Submitting a new post to r/{subreddit}")
         response = self._post(url_api, data=data)
         response_json = response.json()
-
-        # Check for Reddit API errors in the response
         if (
             response_json
             and "json" in response_json
@@ -259,27 +258,27 @@ class RedditApp(APIApplication):
                     [f"{code}: {message}" for code, message in errors]
                 )
                 return f"Reddit API error: {error_message}"
-
         return response_json
 
     def get_comment_by_id(self, comment_id: str) -> dict:
         """
-        Retrieve a specific Reddit comment by its full ID (t1_commentid).
+        Retrieves a specific Reddit comment using its unique identifier.
 
         Args:
-            comment_id: The full unique ID of the comment (e.g., 't1_abcdef').
+            comment_id: The full unique identifier of the comment (prefixed with 't1_', e.g., 't1_abcdef')
 
         Returns:
-            A dictionary containing the comment data, or an error message if retrieval fails.
-        """
-
-        # Define the endpoint URL
-        url = f"https://oauth.reddit.com/api/info.json?id={comment_id}"
+            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.
 
-        # Make the GET request to the Reddit API
+        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
+        """
+        url = f"https://oauth.reddit.com/api/info.json?id={comment_id}"
         response = self._get(url)
-
         data = response.json()
         comments = data.get("data", {}).get("children", [])
         if comments:
@@ -289,72 +288,82 @@ class RedditApp(APIApplication):
 
     def post_comment(self, parent_id: str, text: str) -> dict:
         """
-        Post a comment to a Reddit post or another comment.
+        Posts a comment to a Reddit post or comment using the Reddit API
 
         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.
+            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 response from the Reddit API, or an error message if posting fails.
-        """
+            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
+        """
         url = f"{self.base_api_url}/api/comment"
         data = {
             "parent": parent_id,
             "text": text,
         }
-
         logger.info(f"Posting comment to {parent_id}")
         response = self._post(url, data=data)
-
         return response.json()
 
     def edit_content(self, content_id: str, text: str) -> dict:
         """
-        Edit the text content of a Reddit post or comment.
+        Edits the text content of an existing Reddit post or comment using the Reddit API
 
         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.
+            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 response from the Reddit API, or an error message if editing fails.
-        """
+            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
+        """
         url = f"{self.base_api_url}/api/editusertext"
         data = {
             "thing_id": content_id,
             "text": text,
         }
-
         logger.info(f"Editing content {content_id}")
         response = self._post(url, data=data)
-
         return response.json()
 
     def delete_content(self, content_id: str) -> dict:
         """
-        Delete a Reddit post or comment.
+        Deletes a specified Reddit post or comment using the Reddit API.
 
         Args:
-            content_id: The full ID of the content to delete (e.g., 't3_abc123' for a post, 't1_def456' for a comment).
+            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 the response from the Reddit API, or an error message if deletion fails.
-        """
+            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
+        """
         url = f"{self.base_api_url}/api/del"
         data = {
             "id": content_id,
         }
-
         logger.info(f"Deleting content {content_id}")
         response = self._post(url, data=data)
         response.raise_for_status()
-
-        # Reddit's delete endpoint returns an empty response on success.
-        # We'll just return a success message.
         return {"message": f"Content {content_id} deleted successfully."}
 
     def list_tools(self):

universal_mcp/applications/resend/app.py

@@ -6,24 +6,23 @@ class ResendApp(APIApplication):
     def __init__(self, integration: Integration) -> None:
         super().__init__(name="resend", integration=integration)
 
-    def _get_headers(self):
-        credentials = self.integration.get_credentials()
-        if not credentials:
-            raise ValueError("No credentials found")
-        return {
-            "Authorization": f"Bearer {credentials['api_key']}",
-        }
-
     def send_email(self, to: str, subject: str, content: str) -> str:
-        """Send an email using the Resend API
+        """
+        Sends an email using the Resend API with specified recipient, subject, and content
 
         Args:
-            to: The email address to send the email to
-            subject: The subject of the email
-            content: The content of the email
+            to: Email address of the recipient
+            subject: Subject line of the email
+            content: Main body text content of the email
 
         Returns:
-            A message indicating that the email was sent successfully
+            String message confirming successful email delivery ('Sent Successfully')
+
+        Raises:
+            ValueError: Raised when no valid credentials are found for the API
+
+        Tags:
+            send, email, api, communication, important
         """
         credentials = self.integration.get_credentials()
         if not credentials:

universal_mcp/applications/{serp → serpapi}/app.py

@@ -1,49 +1,38 @@
 import httpx
-from loguru import logger
 from serpapi import SerpApiClient as SerpApiSearch
 
 from universal_mcp.applications.application import APIApplication
 
 
-class SerpApp(APIApplication):
+class SerpapiApp(APIApplication):
     def __init__(self, **kwargs):
         super().__init__(name="serpapi", **kwargs)
-        self.api_key: str | None = None
-
-    def _set_api_key(self):
-        if self.api_key is not None:
-            return
-        if not self.integration:
-            raise ValueError("Integration is None. Cannot retrieve SERP API Key.")
-
-        credentials = self.integration.get_credentials()
-        if not credentials:
-            raise ValueError(
-                f"Failed to retrieve SERP API Key using integration '{self.integration.name}'. "
-                f"Check store configuration (e.g., ensure the correct environment variable is set)."
-            )
-
-        self.api_key = credentials
-        logger.info("SERP API Key successfully retrieved via integration.")
 
     async def search(self, params: dict[str, any] = None) -> str:
-        """Perform a search on the specified engine using SerpApi.
+        """
+        Performs an asynchronous search using the SerpApi service and returns formatted search results.
 
         Args:
-            params: Dictionary of engine-specific parameters (e.g., {"q": "Coffee", "engine": "google_light", "location": "Austin, TX"}).
+            params: Dictionary of engine-specific parameters (e.g., {'q': 'Coffee', 'engine': 'google_light', 'location': 'Austin, TX'}). Defaults to None.
 
         Returns:
-            A formatted string of search results or an error message.
+            A formatted string containing search results with titles, links, and snippets, or an error message if the search fails.
+
+        Raises:
+            httpx.HTTPStatusError: Raised when the API request fails due to HTTP errors (401 for invalid API key, 429 for rate limiting)
+            Exception: Raised for general errors such as network issues or invalid parameters
+
+        Tags:
+            search, async, web-scraping, api, serpapi, important
         """
         if params is None:
             params = {}
-        self._set_api_key()
+        api_key = self.integration.get_credentials().get("api_key")
         params = {
-            "api_key": self.api_key,
+            "api_key": api_key,
             "engine": "google_light",  # Fastest engine by default
             **params,  # Include any additional parameters
         }
-
         try:
             search = SerpApiSearch(params)
             data = search.get_dict()

universal_mcp/applications/tavily/app.py

@@ -8,25 +8,23 @@ class TavilyApp(APIApplication):
         self.base_url = "https://api.tavily.com"
         super().__init__(name=name, integration=integration)
 
-    def _get_headers(self):
-        credentials = self.integration.get_credentials()
-        if not credentials:
-            raise ValueError("No credentials found")
-        return {
-            "Authorization": f"Bearer {credentials['api_key']}",
-            "Content-Type": "application/json",
-        }
-
     def search(self, query: str) -> str:
-        """Search the web using Tavily's search API
+        """
+        Performs a web search using Tavily's search API and returns either a direct answer or a summary of top results.
 
         Args:
-            query: The search query
+            query: The search query string to be processed by Tavily's search engine
 
         Returns:
-            str: A summary of search results
+            A string containing either a direct answer from Tavily's AI or a formatted summary of the top 3 search results, with each result containing the title and snippet
+
+        Raises:
+            ValueError: When authentication credentials are invalid or missing (via validate() method)
+            HTTPError: When the API request fails or returns an error response
+
+        Tags:
+            search, ai, web, query, important, api-client, text-processing
         """
-        self.validate()
         url = f"{self.base_url}/search"
         payload = {
             "query": query,
@@ -40,18 +38,13 @@ class TavilyApp(APIApplication):
             "include_domains": [],
             "exclude_domains": [],
         }
-
         response = self._post(url, payload)
         result = response.json()
-
         if "answer" in result:
             return result["answer"]
-
-        # Fallback to combining top results if no direct answer
         summaries = []
         for item in result.get("results", [])[:3]:
             summaries.append(f"• {item['title']}: {item['snippet']}")
-
         return "\n".join(summaries)
 
     def list_tools(self):