universal-mcp-applications 0.1.30__py3-none-any.whl → 0.1.36rc1__py3-none-any.whl

universal_mcp/applications/serpapi/app.py

@@ -1,18 +1,16 @@
-from typing import Any  # For type hinting
-
+from typing import Any
 import httpx
 from loguru import logger
 from universal_mcp.applications.application import APIApplication
-from universal_mcp.exceptions import NotAuthorizedError  # For auth errors
-from universal_mcp.integrations import Integration  # For integration type hint
-
-from serpapi import SerpApiClient as SerpApiSearch  # Added SerpApiError
+from universal_mcp.exceptions import NotAuthorizedError
+from universal_mcp.integrations import Integration
+from serpapi import SerpApiClient as SerpApiSearch
 
 
 class SerpapiApp(APIApplication):
     def __init__(self, integration: Integration | None = None, **kwargs: Any) -> None:
         super().__init__(name="serpapi", integration=integration, **kwargs)
-        self._serpapi_api_key: str | None = None  # Cache for the API key
+        self._serpapi_api_key: str | None = None
         self.base_url = "https://serpapi.com/search"
 
     @property
@@ -23,54 +21,33 @@ class SerpapiApp(APIApplication):
         if self._serpapi_api_key is None:
             if not self.integration:
                 logger.error("SerpApi App: Integration not configured.")
-                raise NotAuthorizedError(
-                    "Integration not configured for SerpApi App. Cannot retrieve API key."
-                )
-
+                raise NotAuthorizedError("Integration not configured for SerpApi App. Cannot retrieve API key.")
             try:
                 credentials = self.integration.get_credentials()
             except NotAuthorizedError as e:
-                logger.error(
-                    f"SerpApi App: Authorization error when fetching credentials: {e.message}"
-                )
-                raise  # Re-raise the original NotAuthorizedError
+                logger.error(f"SerpApi App: Authorization error when fetching credentials: {e.message}")
+                raise
             except Exception as e:
-                logger.error(
-                    f"SerpApi App: Unexpected error when fetching credentials: {e}",
-                    exc_info=True,
-                )
+                logger.error(f"SerpApi App: Unexpected error when fetching credentials: {e}", exc_info=True)
                 raise NotAuthorizedError(f"Failed to get SerpApi credentials: {e}")
-
-            api_key = (
-                credentials.get("api_key")
-                or credentials.get("API_KEY")  # Check common variations
-                or credentials.get("apiKey")
-            )
-
+            api_key = credentials.get("api_key") or credentials.get("API_KEY") or credentials.get("apiKey")
             if not api_key:
                 logger.error("SerpApi App: API key not found in credentials.")
-                action_message = "API key for SerpApi is missing. Please ensure it's set in the store (e.g., SERPAPI_API_KEY in credentials)."
-                if hasattr(self.integration, "authorize") and callable(
-                    self.integration.authorize
-                ):
+                action_message = (
+                    "API key for SerpApi is missing. Please ensure it's set in the store (e.g., SERPAPI_API_KEY in credentials)."
+                )
+                if hasattr(self.integration, "authorize") and callable(self.integration.authorize):
                     try:
                         auth_details = self.integration.authorize()
                         if isinstance(auth_details, str):
                             action_message = auth_details
                         elif isinstance(auth_details, dict) and "url" in auth_details:
-                            action_message = (
-                                f"Please authorize via: {auth_details['url']}"
-                            )
-                        elif (
-                            isinstance(auth_details, dict) and "message" in auth_details
-                        ):
+                            action_message = f"Please authorize via: {auth_details['url']}"
+                        elif isinstance(auth_details, dict) and "message" in auth_details:
                             action_message = auth_details["message"]
                     except Exception as auth_e:
-                        logger.warning(
-                            f"Could not retrieve specific authorization action for SerpApi: {auth_e}"
-                        )
+                        logger.warning(f"Could not retrieve specific authorization action for SerpApi: {auth_e}")
                 raise NotAuthorizedError(action_message)
-
             self._serpapi_api_key = api_key
             logger.info("SerpApi API Key successfully retrieved and cached.")
         return self._serpapi_api_key
@@ -93,27 +70,15 @@ class SerpapiApp(APIApplication):
             search, async, web-scraping, api, serpapi, important
         """
         request_params = params or {}
-
         try:
-            current_api_key = self.serpapi_api_key  # This can raise NotAuthorizedError
+            current_api_key = self.serpapi_api_key
             logger.info("Attempting SerpApi search.")
-
-            serpapi_call_params = {
-                "api_key": current_api_key,
-                "engine": "google_light",  # Fastest engine by default
-                **request_params,  # Include any additional parameters from the user
-            }
-
-            # SerpApiSearch (SerpApiClient) uses the 'requests' library and its get_dict() is synchronous.
-            # If true async behavior is needed, this call should be wrapped with asyncio.to_thread.
+            serpapi_call_params = {"api_key": current_api_key, "engine": "google_light", **request_params}
             search_client = SerpApiSearch(serpapi_call_params)
             data = search_client.get_dict()
-
-            # Check for errors returned in the API response body
             if "error" in data:
                 error_message = data["error"]
                 logger.error(f"SerpApi API returned an error: {error_message}")
-                # Keywords indicating authorization/authentication issues
                 auth_error_keywords = [
                     "invalid api key",
                     "authorization failed",
@@ -122,76 +87,42 @@ class SerpapiApp(APIApplication):
                     "account disabled",
                     "private api key is missing",
                 ]
-                if any(
-                    keyword in error_message.lower() for keyword in auth_error_keywords
-                ):
+                if any((keyword in error_message.lower() for keyword in auth_error_keywords)):
                     raise NotAuthorizedError(f"SerpApi Error: {error_message}")
-                return f"SerpApi API Error: {error_message}"  # Other API errors (e.g., missing parameters)
-
-            # Process organic search results if available
+                return f"SerpApi API Error: {error_message}"
             if "organic_results" in data:
                 formatted_results = []
                 for result in data.get("organic_results", []):
                     title = result.get("title", "No title")
                     link = result.get("link", "No link")
                     snippet = result.get("snippet", "No snippet")
-                    formatted_results.append(
-                        f"Title: {title}\nLink: {link}\nSnippet: {snippet}\n"
-                    )
-                return (
-                    "\n".join(formatted_results)
-                    if formatted_results
-                    else "No organic results found."
-                )
+                    formatted_results.append(f"Title: {title}\nLink: {link}\nSnippet: {snippet}\n")
+                return "\n".join(formatted_results) if formatted_results else "No organic results found."
             else:
                 return "No organic results found."
-
-        except (
-            NotAuthorizedError
-        ):  # Catches from self.serpapi_api_key or explicit raise above
+        except NotAuthorizedError:
             logger.error("SerpApi search failed due to an authorization error.")
-            raise  # Re-raise to be handled by the MCP framework
-
-        except httpx.HTTPStatusError as e:  # Kept from original for robustness, though SerpApiClient uses 'requests'
+            raise
+        except httpx.HTTPStatusError as e:
             logger.warning(
                 f"SerpApi search encountered httpx.HTTPStatusError (unexpected with default SerpApiClient): {e.response.status_code}",
                 exc_info=True,
             )
             if e.response.status_code == 429:
                 return "Error: Rate limit exceeded (HTTP 429). Please try again later."
-            elif (
-                e.response.status_code == 401
-            ):  # Key was fetched but rejected by API with HTTP 401
-                raise NotAuthorizedError(
-                    "Error: Invalid API key (HTTP 401). Please check your SERPAPI_API_KEY."
-                )
+            elif e.response.status_code == 401:
+                raise NotAuthorizedError("Error: Invalid API key (HTTP 401). Please check your SERPAPI_API_KEY.")
             else:
                 return f"HTTP Error: {e.response.status_code} - {e.response.text}"
-
-        except Exception as e:  # General catch-all, similar to E2B's final catch
+        except Exception as e:
             error_message_lower = str(e).lower()
             logger.error(f"Unexpected error during SerpApi search: {e}", exc_info=True)
-            # Infer auth error from generic exception message
-            auth_error_keywords = [
-                "authentication",
-                "api key",
-                "unauthorized",
-                "401",
-                "forbidden",
-                "invalid key",
-            ]
-            if any(keyword in error_message_lower for keyword in auth_error_keywords):
-                raise NotAuthorizedError(
-                    f"SerpApi authentication/authorization failed: {str(e)}"
-                )
+            auth_error_keywords = ["authentication", "api key", "unauthorized", "401", "forbidden", "invalid key"]
+            if any((keyword in error_message_lower for keyword in auth_error_keywords)):
+                raise NotAuthorizedError(f"SerpApi authentication/authorization failed: {str(e)}")
             return f"An unexpected error occurred during search: {str(e)}"
 
-    async def google_maps_search(
-        self,
-        q: str | None = None,
-        ll: str | None = None,
-        place_id: str | None = None,
-    ) -> dict[str, Any]:
+    async def google_maps_search(self, q: str | None = None, ll: str | None = None, place_id: str | None = None) -> dict[str, Any]:
         """
         Executes a Google Maps search via SerpApi using a query, coordinates, or place ID. It enhances the results by adding a `google_maps_url` to each location, distinguishing it from `get_google_maps_reviews` which retrieves reviews for a known place.
 
@@ -210,43 +141,23 @@ class SerpapiApp(APIApplication):
         Tags:
             google-maps, search, location, places, important
         """
-
         query_params = {}
-        query_params = {
-            "engine": "google_maps",
-            "api_key": self.serpapi_api_key,
-        }
-
+        query_params = {"engine": "google_maps", "api_key": self.serpapi_api_key}
         if q is not None:
             query_params["q"] = q
-
         if ll is not None:
             query_params["ll"] = ll
-
         if place_id is not None:
             query_params["place_id"] = place_id
-
-        response = self._get(
-            self.base_url,
-            params=query_params,
-        )
+        response = self._get(self.base_url, params=query_params)
         data = self._handle_response(response)
-
-        # Add Google Maps URLs for each place in the results
         if "local_results" in data:
             for place in data["local_results"]:
                 if "place_id" in place:
-                    place["google_maps_url"] = (
-                        f"https://www.google.com/maps/place/?q=place_id:{place['place_id']}"
-                    )
-
+                    place["google_maps_url"] = f"https://www.google.com/maps/place/?q=place_id:{place['place_id']}"
         return data
 
-    async def get_google_maps_reviews(
-        self,
-        data_id: str,
-        hl: str | None = None,
-    ) -> dict[str, Any]:
+    async def get_google_maps_reviews(self, data_id: str, hl: str | None = None) -> dict[str, Any]:
         """
         Fetches Google Maps reviews for a specific location via SerpApi using its unique `data_id`. This function uses the `google_maps_reviews` engine, unlike `google_maps_search` which finds locations. Results can be returned in a specified language, defaulting to English.
 
@@ -264,28 +175,14 @@ class SerpapiApp(APIApplication):
         Tags:
             google-maps, reviews, ratings, places, important
         """
-
         query_params = {}
-        query_params = {
-            "engine": "google_maps_reviews",
-            "data_id": data_id,
-            "api_key": self.serpapi_api_key,
-        }
-
+        query_params = {"engine": "google_maps_reviews", "data_id": data_id, "api_key": self.serpapi_api_key}
         if hl is not None:
             query_params["hl"] = hl
         else:
             query_params["hl"] = "en"
-
-        response = self._get(
-            self.base_url,
-            params=query_params,
-        )
+        response = self._get(self.base_url, params=query_params)
         return self._handle_response(response)
 
     def list_tools(self) -> list[callable]:
-        return [
-            self.web_search,
-            self.google_maps_search,
-            self.get_google_maps_reviews,
-        ]
+        return [self.web_search, self.google_maps_search, self.get_google_maps_reviews]

universal_mcp/applications/sharepoint/app.py

@@ -1,7 +1,6 @@
 import base64
 import os
 from typing import Any
-
 from loguru import logger
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.integrations import Integration
@@ -17,7 +16,7 @@ class SharepointApp(APIApplication):
         super().__init__(name="sharepoint", integration=integration, **kwargs)
         self.base_url = "https://graph.microsoft.com/v1.0"
 
-    def get_my_profile(self) -> dict[str, Any]:
+    async def get_my_profile(self) -> dict[str, Any]:
         """
         Fetches the profile for the currently authenticated user, specifically retrieving their ID and user principal name. This function confirms user identity, distinguishing it from `get_drive_info`, which returns details about the SharePoint storage space (e.g., quota) rather than the user's personal profile.
 
@@ -35,7 +34,7 @@ class SharepointApp(APIApplication):
         response = self._get(url, params=query_params)
         return self._handle_response(response)
 
-    def get_drive_info(self) -> dict[str, Any]:
+    async def get_drive_info(self) -> dict[str, Any]:
         """
         Fetches high-level information about the user's entire SharePoint. It returns drive-wide details like the owner and storage quota, differing from `get_item_metadata` which describes a specific item, and `get_my_profile` which retrieves general user account information.
 
@@ -63,7 +62,7 @@ class SharepointApp(APIApplication):
         response = self._get(url)
         return self._handle_response(response)
 
-    def search_files(self, query: str) -> dict[str, Any]:
+    async def search_files(self, query: str) -> dict[str, Any]:
         """
         Searches the user's entire SharePoint for files and folders matching a specified text query. This function performs a comprehensive search from the drive's root, distinguishing it from `list_files` or `list_folders` which only browse the contents of a single directory.
 
@@ -78,12 +77,11 @@ class SharepointApp(APIApplication):
         """
         if not query:
             raise ValueError("Search query cannot be empty.")
-
         url = f"{self.base_url}/me/drive/root/search(q='{query}')"
         response = self._get(url)
         return self._handle_response(response)
 
-    def get_item_metadata(self, item_id: str) -> dict[str, Any]:
+    async def get_item_metadata(self, item_id: str) -> dict[str, Any]:
         """
         Fetches detailed metadata for a specific file or folder using its unique ID. It returns properties like name, size, and type. Unlike `get_document_content`, it doesn't retrieve the file's actual content, focusing solely on the item's attributes for quick inspection without a full download.
 
@@ -98,12 +96,11 @@ class SharepointApp(APIApplication):
         """
         if not item_id:
             raise ValueError("Missing required parameter 'item_id'.")
-
         url = f"{self.base_url}/me/drive/items/{item_id}"
         response = self._get(url)
         return self._handle_response(response)
 
-    def create_folder(self, name: str, parent_id: str = "root") -> dict[str, Any]:
+    async def create_folder(self, name: str, parent_id: str = "root") -> dict[str, Any]:
         """
         Creates a new folder with a specified name within a parent directory, which defaults to the root. Returns metadata for the new folder. Unlike `create_folder_and_list`, this function only creates the folder and returns its specific metadata, not the parent directory's contents.
 
@@ -119,13 +116,12 @@ class SharepointApp(APIApplication):
         """
         if not name:
             raise ValueError("Folder name cannot be empty.")
-
         url = f"{self.base_url}/me/drive/items/{parent_id}/children"
         data = {"name": name, "folder": {}, "@microsoft.graph.conflictBehavior": "rename"}
         response = self._post(url, data=data)
         return self._handle_response(response)
 
-    def delete_item(self, item_id: str) -> dict[str, Any]:
+    async def delete_item(self, item_id: str) -> dict[str, Any]:
         """
         Permanently deletes a specified file or folder from SharePoint using its unique item ID. This versatile function can remove any type of drive item, distinguished from functions that only list or create specific types. A successful deletion returns an empty response, confirming the item's removal.
 
@@ -140,12 +136,11 @@ class SharepointApp(APIApplication):
         """
         if not item_id:
             raise ValueError("Missing required parameter 'item_id'.")
-
         url = f"{self.base_url}/me/drive/items/{item_id}"
         response = self._delete(url)
         return self._handle_response(response)
 
-    def download_file(self, item_id: str) -> dict[str, Any]:
+    async def download_file(self, item_id: str) -> dict[str, Any]:
         """
         Retrieves a temporary, pre-authenticated download URL for a specific file using its item ID. This function provides a link for subsequent download, differing from `get_document_content` which directly fetches the file's raw content. The URL is returned within a dictionary.
 
@@ -160,7 +155,6 @@ class SharepointApp(APIApplication):
         """
         if not item_id:
             raise ValueError("Missing required parameter 'item_id'.")
-
         url = f"{self.base_url}/me/drive/items/{item_id}"
         response = self._get(url)
         metadata = self._handle_response(response)
@@ -169,7 +163,7 @@ class SharepointApp(APIApplication):
             raise ValueError("Could not retrieve download URL for the item.")
         return {"download_url": download_url}
 
-    def upload_file(self, file_path: str, parent_id: str = "root", file_name: str | None = None) -> dict[str, Any]:
+    async def upload_file(self, file_path: str, parent_id: str = "root", file_name: str | None = None) -> dict[str, Any]:
         """
         Uploads a local binary file (under 4MB) from a given path to a specified SharePoint folder. Unlike `upload_text_file`, which uploads string content, this function reads from the filesystem. The destination filename can be customized, and it returns the new file's metadata upon completion.
 
@@ -186,17 +180,15 @@ class SharepointApp(APIApplication):
         """
         if not os.path.exists(file_path):
             raise FileNotFoundError(f"The file was not found at path: {file_path}")
-
         if not file_name:
             file_name = os.path.basename(file_path)
-
         url = f"{self.base_url}/me/drive/items/{parent_id}:/{file_name}:/content"
         with open(file_path, "rb") as f:
             data = f.read()
         response = self._put(url, data=data, content_type="application/octet-stream")
         return self._handle_response(response)
 
-    def list_folders(self, item_id: str = "root") -> dict[str, Any]:
+    async def list_folders(self, item_id: str = "root") -> dict[str, Any]:
         """
         Retrieves a list of only the folders within a specified parent directory in SharePoint. Unlike `_list_drive_items` which returns all items, this function filters the results to exclude files. Defaults to the root directory if no parent `item_id` is provided.
 
@@ -213,7 +205,7 @@ class SharepointApp(APIApplication):
         folders = [item for item in all_items.get("value", []) if "folder" in item]
         return {"value": folders}
 
-    def list_files(self, item_id: str = "root") -> dict[str, Any]:
+    async def list_files(self, item_id: str = "root") -> dict[str, Any]:
         """
         Retrieves a list of files within a specified SharePoint folder, defaulting to the root. Unlike `_list_drive_items` which fetches all items, this function filters the results to exclusively return items identified as files, excluding any subdirectories.
 
@@ -230,7 +222,7 @@ class SharepointApp(APIApplication):
         files = [item for item in all_items.get("value", []) if "file" in item]
         return {"value": files}
 
-    def create_folder_and_list(self, name: str, parent_id: str = "root") -> dict[str, Any]:
+    async def create_folder_and_list(self, name: str, parent_id: str = "root") -> dict[str, Any]:
         """
         Performs a composite action: creates a new folder, then lists all items (files and folders) within that parent directory. This confirms creation by returning the parent's updated contents, distinct from `create_folder` which only returns the new folder's metadata.
 
@@ -247,7 +239,7 @@ class SharepointApp(APIApplication):
         self.create_folder(name=name, parent_id=parent_id)
         return self._list_drive_items(item_id=parent_id)
 
-    def upload_text_file(self, content: str, parent_id: str = "root", file_name: str = "new_file.txt") -> dict[str, Any]:
+    async def upload_text_file(self, content: str, parent_id: str = "root", file_name: str = "new_file.txt") -> dict[str, Any]:
         """
         Creates and uploads a new file to SharePoint directly from a string of text content. Unlike `upload_file`, which requires a local file path, this function is specifically for creating a text file from in-memory string data, with a customizable name and destination folder.
 
@@ -264,13 +256,12 @@ class SharepointApp(APIApplication):
         """
         if not file_name:
             raise ValueError("File name cannot be empty.")
-
         url = f"{self.base_url}/me/drive/items/{parent_id}:/{file_name}:/content"
         data = content.encode("utf-8")
         response = self._put(url, data=data, content_type="text/plain")
         return self._handle_response(response)
 
-    def get_document_content(self, item_id: str) -> dict[str, Any]:
+    async def get_document_content(self, item_id: str) -> dict[str, Any]:
         """
         Retrieves the content of a specific file by its item ID and returns it directly as base64-encoded data. This function is distinct from `download_file`, which only provides a temporary URL for the content, and from `get_item_metadata`, which returns file attributes without the content itself. The function fetches the content by following the file's pre-authenticated download URL.
 
@@ -289,36 +280,23 @@ class SharepointApp(APIApplication):
         """
         if not item_id:
             raise ValueError("Missing required parameter 'item_id'.")
-
         metadata = self.get_item_metadata(item_id=item_id)
         file_metadata = metadata.get("file")
         if not file_metadata:
             raise ValueError(f"Item with ID '{item_id}' is not a file.")
-
         file_mime_type = file_metadata.get("mimeType", "application/octet-stream")
         file_name = metadata.get("name")
-
         download_url = metadata.get("@microsoft.graph.downloadUrl")
         if not download_url:
             logger.error(f"Could not find @microsoft.graph.downloadUrl in metadata for item {item_id}")
             raise ValueError("Could not retrieve download URL for the item.")
-
         response = self._get(download_url)
-
         response.raise_for_status()
-
         content = response.content
-
         attachment_type = file_mime_type.split("/")[0] if "/" in file_mime_type else "file"
         if attachment_type not in ["image", "audio", "video", "text"]:
             attachment_type = "file"
-
-        return {
-            "type": attachment_type,
-            "data": content,
-            "mime_type": file_mime_type,
-            "file_name": file_name,
-        }
+        return {"type": attachment_type, "data": content, "mime_type": file_mime_type, "file_name": file_name}
 
     def list_tools(self):
         return [
@@ -335,4 +313,4 @@ class SharepointApp(APIApplication):
             self.create_folder_and_list,
             self.upload_text_file,
             self.get_document_content,
-        ]
+        ]