universal-mcp 0.1.7rc2__py3-none-any.whl → 0.1.8rc2__py3-none-any.whl

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
+        
+        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.
+            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
         """
-
-        # Define the endpoint URL
         url = f"https://oauth.reddit.com/api/info.json?id={comment_id}"
-
-        # Make the GET request to the Reddit API
-
         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

@@ -25,15 +25,22 @@ class ResendApp(APIApplication):
         }
 
     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

@@ -5,7 +5,7 @@ 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
@@ -35,13 +35,21 @@ class SerpApp(APIApplication):
         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 = {}
@@ -51,7 +59,6 @@ class SerpApp(APIApplication):
             "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

@@ -28,13 +28,21 @@ class TavilyApp(APIApplication):
         }
 
     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"
@@ -50,18 +58,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):

universal_mcp/applications/wrike/README.md

@@ -0,0 +1,71 @@
+
+# Wrike MCP Server
+
+An MCP Server for the Wrike API.
+
+## Supported Integrations
+
+- AgentR
+- API Key (Coming Soon)
+- OAuth (Coming Soon)
+
+## Tools
+
+This is automatically generated from OpenAPI schema for the Wrike API.
+
+## Supported Integrations
+
+This tool can be integrated with any service that supports HTTP requests.
+
+## Tool List
+
+| Tool | Description |
+|------|-------------|
+| get_contacts | Retrieves a list of contacts from the server, with optional filtering and field selection. |
+| get_contacts_by_contactid | Retrieves contact information for a specific contact ID, optionally returning only specified fields. |
+| put_contacts_by_contactid | Updates an existing contact by contact ID with provided details such as metadata, billing and cost rates, job role, custom fields, or additional fields. |
+| get_users_by_userid | Retrieves user information for a given user ID from the API endpoint. |
+| put_users_by_userid | Updates a user's profile information by user ID using a PUT request. |
+| get_groups | Retrieves a list of groups from the API, applying optional filtering and pagination parameters. |
+| post_groups | Creates a new group with the specified title and optional details, sending a POST request to the groups endpoint. |
+| get_groups_by_groupid | Retrieves details for a specific group by its group ID, optionally returning only specified fields. |
+| put_groups_by_groupid | Updates an existing group identified by groupId with new properties and membership changes via a PUT request. |
+| delete_groups_by_groupid | Deletes a group resource identified by the provided groupId using an HTTP DELETE request. |
+| put_groups_bulk | Updates multiple group memberships in bulk by sending a PUT request with the given members data. |
+| get_invitations | Retrieves all invitations from the server using a GET request. |
+| post_invitations | Sends an invitation email to a user with optional details such as name, role, and custom message. |
+| put_invitations_by_invitationid | Updates an existing invitation by invitation ID with optional fields such as resend, role, external, and user type ID. |
+| delete_invitations_by_invitationid | Deletes an invitation specified by its invitation ID. |
+| get_a_ccount | Retrieves account information from the API, optionally including only specified fields. |
+| put_a_ccount | Sends a PUT request to update or create an account with the provided metadata and returns the server response as a JSON object. |
+| get_workflows | Retrieves all workflows from the server using a GET request. |
+| post_workflows | Creates a new workflow by sending a POST request to the workflows endpoint. |
+| put_workflows_by_workflowid | Updates an existing workflow by workflow ID with optional name, hidden status, and request body data. |
+| get_customfields | Retrieves all custom fields from the API and returns them as a parsed JSON object. |
+| post_customfields | Creates a custom field by sending a POST request with the specified parameters to the customfields endpoint and returns the created field's data. |
+| get_customfields_by_customfieldid | Retrieves details for a custom field by its unique identifier from the API. |
+| put_customfields_by_customfieldid | Updates a custom field specified by its ID with the provided parameters using an HTTP PUT request. |
+| delete_customfields_by_customfieldid | Deletes a custom field resource identified by its custom field ID. |
+| get_folders | Retrieves a list of folders from the API, supporting extensive filtering, pagination, and field selection. |
+| get_folders_by_folderid_folders | Retrieves subfolders of a specified folder, applying optional filters and pagination parameters. |
+| post_folders_by_folderid_folders | Creates a new subfolder within a specified folder by folder ID, with configurable attributes such as title, description, sharing, metadata, and permissions. |
+| delete_folders_by_folderid | Deletes a folder resource identified by its folder ID via an HTTP DELETE request. |
+| put_folders_by_folderid | Updates a folder's properties and relationships by folder ID using a PUT request. |
+| get_tasks | Retrieves tasks from the API with optional filtering, sorting, pagination, and field selection parameters. |
+| get_tasks_by_taskid | Retrieves a task by its ID from the remote service, optionally returning only specified fields. |
+| put_tasks_by_taskid | Updates the properties and relationships of a task specified by its ID, applying the given changes and returning the updated task data as a JSON object. |
+| delete_tasks_by_taskid | Deletes a task identified by the given task ID via an HTTP DELETE request and returns the response as a JSON object. |
+| post_folders_by_folderid_tasks | Creates a new task within a specified folder by folder ID, with configurable attributes such as title, description, status, importance, dates, assigned users, metadata, custom fields, and other options. |
+
+
+
+## Usage
+
+- Login to AgentR
+- Follow the quickstart guide to setup MCP Server for your client
+- Visit Apps Store and enable the Wrike app
+- Restart the MCP Server
+
+### Local Development
+
+- Follow the README to test with the local MCP Server