universal-mcp-applications 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

universal_mcp/applications/scraper/app.py

@@ -47,8 +47,8 @@ class ScraperApp(APIApplication):
         content_type: Optional[str] = None,
     ) -> dict[str, Any]:
         """
-        Performs a LinkedIn search for posts.
-
+        Performs a general LinkedIn search for posts using keywords and filters like date and content type. It supports pagination and can utilize either the 'classic' or 'sales_navigator' API, searching broadly across the platform rather than fetching posts from a specific user's profile.
+        
         Args:
             category: Type of search to perform (defaults to "posts").
             api: Which LinkedIn API to use - "classic" or "sales_navigator".
@@ -58,13 +58,13 @@ class ScraperApp(APIApplication):
             sort_by: How to sort the results, e.g., "relevance" or "date".
             date_posted: Filter posts by when they were posted.
             content_type: Filter by the type of content in the post. Example: "videos", "images", "live_videos", "collaborative_articles", "documents"
-
+        
         Returns:
             A dictionary containing search results and pagination details.
-
+        
         Raises:
             httpx.HTTPError: If the API request fails.
-
+        
         Tags:
             linkedin, search, posts, api, scrapper, important
         """
@@ -81,31 +81,31 @@ class ScraperApp(APIApplication):
             content_type=content_type,
         )
 
-    def linkedin_list_all_posts(
+    def linkedin_list_profile_posts(
         self,
         identifier: str,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
     ) -> dict[str, Any]:
         """
-        Lists all LinkedIn posts for a given user  identifier
-
+        Fetches a paginated list of all LinkedIn posts from a specific user or company profile using their unique identifier. This function retrieves content directly from a profile, unlike `linkedin_post_search` which finds posts across LinkedIn based on keywords and other filters.
+        
         Args:
             identifier: The entity's provider internal ID (LinkedIn ID).starts with ACo for users, while for companies it's a series of numbers.
             cursor: Pagination cursor for the next page of entries.
             limit: Number of items to return (1-100, though spec allows up to 250).
-
+        
         Returns:
             A dictionary containing a list of post objects and pagination details.
-
+        
         Raises:
             httpx.HTTPError: If the API request fails.
-
+        
         Tags:
             linkedin, post, list, user_posts, company_posts, content, api, important
         """
         
-        return self._unipile_app.list_user_posts(
+        return self._unipile_app.list_profile_posts(
             identifier=identifier,
             account_id=self.account_id,
             cursor=cursor,
@@ -117,23 +117,23 @@ class ScraperApp(APIApplication):
         identifier: str,
     ) -> dict[str, Any]:
         """
-        Retrieves a specific LinkedIn user profile by its identifier.
-
+        Retrieves a specific LinkedIn user's profile by their unique identifier, which can be an internal provider ID or a public username. This function simplifies data access by delegating the actual profile retrieval request to the integrated Unipile application, distinct from functions that list posts or comments.
+        
         Args:
             identifier: Can be the provider's internal id OR the provider's public id of the requested user.
                        For example, for https://www.linkedin.com/in/manojbajaj95/, the identifier is "manojbajaj95".
-
+        
         Returns:
             A dictionary containing the user's profile details.
-
+        
         Raises:
             httpx.HTTPError: If the API request fails.
-
+        
         Tags:
             linkedin, user, profile, retrieve, get, api, important
         """
         
-        return self._unipile_app.retrieve_profile(
+        return self._unipile_app.retrieve_user_profile(
             identifier=identifier,
             account_id=self.account_id,
         )
@@ -147,20 +147,20 @@ class ScraperApp(APIApplication):
         limit: Optional[int] = None,
     ) -> dict[str, Any]:
         """
-        Lists all comments from a specific LinkedIn post. Can also list replies to a specific comment.
-
+        Fetches comments for a specified LinkedIn post. If a `comment_id` is provided, it retrieves replies to that comment instead of top-level comments. This function supports pagination and specifically targets comments, unlike others in the class that search for or list entire posts.
+        
         Args:
             post_id: The social ID of the post. Example rn:li:activity:7342082869034393600
             comment_id: If provided, retrieves replies to this comment ID instead of top-level comments.
             cursor: Pagination cursor.
             limit: Number of comments to return.
-
+        
         Returns:
             A dictionary containing a list of comment objects and pagination details.
-
+        
         Raises:
             httpx.HTTPError: If the API request fails.
-
+        
         Tags:
             linkedin, post, comment, list, content, api, important
         """
@@ -183,7 +183,7 @@ class ScraperApp(APIApplication):
         """
         return [
             self.linkedin_post_search,
-            self.linkedin_list_all_posts,
+            self.linkedin_list_profile_posts,
             self.linkedin_retrieve_profile,
             self.linkedin_list_post_comments,
             ]

universal_mcp/applications/serpapi/app.py

@@ -18,8 +18,7 @@ class SerpapiApp(APIApplication):
     @property
     def serpapi_api_key(self) -> str:
         """
-        Retrieves and caches the SerpApi API key from the integration.
-        Raises NotAuthorizedError if the key cannot be obtained.
+        A property that lazily retrieves the SerpApi API key from the integration and caches it for future use. It fetches credentials on first access, raising a `NotAuthorizedError` if the key is missing. Subsequent calls efficiently return the cached key.
         """
         if self._serpapi_api_key is None:
             if not self.integration:
@@ -76,21 +75,20 @@ class SerpapiApp(APIApplication):
             logger.info("SerpApi API Key successfully retrieved and cached.")
         return self._serpapi_api_key
 
-    async def search(self, params: dict[str, Any] | None = None) -> str:
+    async def web_search(self, params: dict[str, Any] | None = None) -> str:
         """
-        Performs a search using the SerpApi service and returns formatted search results.
-        Note: The underlying SerpApiSearch().get_dict() call is synchronous.
-
+        Performs a general web search via SerpApi, defaulting to the 'google_light' engine. It accepts custom parameters, retrieves organic results, and formats them into a string with titles, links, and snippets. It also handles API authentication and raises `NotAuthorizedError` for credential-related issues.
+        
         Args:
             params: Dictionary of engine-specific parameters (e.g., {'q': 'Coffee', 'engine': 'google_light', 'location': 'Austin, TX'}). Defaults to None.
-
+        
         Returns:
             A formatted string containing search results with titles, links, and snippets, or an error message if the search fails.
-
+        
         Raises:
             NotAuthorizedError: If the API key cannot be retrieved or is invalid/rejected by SerpApi.
             Exception: For other unexpected errors during the search process. (Specific HTTP errors or SerpApiErrors are caught and returned as strings or raise NotAuthorizedError).
-
+        
         Tags:
             search, async, web-scraping, api, serpapi, important
         """
@@ -195,20 +193,20 @@ class SerpapiApp(APIApplication):
         place_id: str | None = None,
     ) -> dict[str, Any]:
         """
-        Performs a Google Maps search using the SerpApi service and returns formatted search results.
-
+        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.
+        
         Args:
             q (string, optional): The search query for Google Maps (e.g., "Coffee", "Restaurants", "Gas stations").
             ll (string, optional): Latitude and longitude with zoom level in format "@lat,lng,zoom" (e.g., "@40.7455096,-74.0083012,14z"). The zoom attribute ranges from 3z (map completely zoomed out) to 21z (map completely zoomed in). Results are not guaranteed to be within the requested geographic location.
             place_id (string, optional): The unique reference to a place in Google Maps. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections. You can find the place_id using our Google Maps API. place_id can be used without any other optional parameter. place_id and data_cid can't be used together.
-
+        
         Returns:
             dict[str, Any]: Formatted Google Maps search results with place names, addresses, ratings, and other details.
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             google-maps, search, location, places, important
         """
@@ -250,19 +248,19 @@ class SerpapiApp(APIApplication):
         hl: str | None = None,
     ) -> dict[str, Any]:
         """
-        Retrieves Google Maps reviews for a specific place using the SerpApi service.
-
+        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.
+        
         Args:
             data_id (string): The data ID of the place to get reviews for (e.g., "0x89c259af336b3341:0xa4969e07ce3108de").
             hl (string, optional): Language parameter for the search results. Defaults to "en".
-
+        
         Returns:
             dict[str, Any]: Google Maps reviews data with ratings, comments, and other review details.
-
+        
         Raises:
             ValueError: Raised when required parameters are missing.
             HTTPStatusError: Raised when the API request fails with detailed error information including status code and response body.
-
+        
         Tags:
             google-maps, reviews, ratings, places, important
         """
@@ -287,7 +285,7 @@ class SerpapiApp(APIApplication):
 
     def list_tools(self) -> list[callable]:
         return [
-            self.search,
+            self.web_search,
             self.google_maps_search,
             self.get_google_maps_reviews,
         ]

universal_mcp/applications/sharepoint/app.py

@@ -35,8 +35,9 @@ class SharepointApp(BaseApplication):
 
     @property
     def client(self):
-        """Gets the GraphClient instance, initializing it if necessary.
-
+        """
+        A lazy-loaded property that gets or creates an authenticated GraphClient instance. On its first call, it uses integration credentials to initialize the client, fetches the user's profile and root site ID, and caches the instance for subsequent use. This ensures efficient connection management.
+        
         Returns:
             GraphClient: The authenticated GraphClient instance.
         """
@@ -49,7 +50,10 @@ class SharepointApp(BaseApplication):
         if not credentials.get("access_token"):
             raise ValueError("No access token found")
 
-        def acquire_token():
+        def _acquire_token():
+            """
+            Formats stored credentials for the `GraphClient` authentication callback. It packages existing access and refresh tokens from the integration into the specific dictionary structure required by the client library for authentication, including a hardcoded 'Bearer' token type.
+            """
             access_token = credentials.get("access_token")
             refresh_token = credentials.get("refresh_token")
             return {
@@ -59,7 +63,7 @@ class SharepointApp(BaseApplication):
             }
 
         if self._client is None:
-            self._client = GraphClient(token_callback=acquire_token)
+            self._client = GraphClient(token_callback=_acquire_token)
             # Get me
             me = self._client.me.get().execute_query()
             logger.debug(me.properties)
@@ -69,14 +73,15 @@ class SharepointApp(BaseApplication):
         return self._client
 
     def list_folders(self, folder_path: str | None = None) -> list[dict[str, Any]]:
-        """Lists folders in the specified directory or root if not specified.
-
+        """
+        Retrieves the names of all immediate subfolders within a specified directory. If a path is not provided, it defaults to listing folders in the root of the user's drive. This function is distinct from `list_documents`, which lists files.
+        
         Args:
             folder_path (Optional[str], optional): The path to the parent folder. If None, lists folders in the root.
-
+        
         Returns:
             List[Dict[str, Any]]: A list of folder names in the specified directory.
-
+        
         Tags:
             important
         """
@@ -88,18 +93,19 @@ class SharepointApp(BaseApplication):
 
         return [folder.properties.get("name") for folder in folders]
 
-    def create_folder(
+    def create_folder_and_list(
         self, folder_name: str, folder_path: str | None = None
     ) -> dict[str, Any]:
-        """Creates a folder in the specified directory or root if not specified.
-
+        """
+        Creates a new folder with a given name inside a specified parent directory on SharePoint. If no path is provided, the folder is created in the root. It then returns an updated list of all folder names within that parent directory.
+        
         Args:
             folder_name (str): The name of the folder to create.
             folder_path (str | None, optional): The path to the parent folder. If None, creates in the root.
-
+        
         Returns:
             Dict[str, Any]: The updated list of folders in the target directory.
-
+        
         Tags:
             important
         """
@@ -110,15 +116,16 @@ class SharepointApp(BaseApplication):
         folder.create_folder(folder_name).execute_query()
         return self.list_folders(folder_path)
 
-    def list_documents(self, folder_path: str) -> list[dict[str, Any]]:
-        """Lists all documents in a specified folder.
-
+    def list_files(self, folder_path: str) -> list[dict[str, Any]]:
+        """
+        Retrieves files from a specified folder path. For each file, it returns a dictionary containing key metadata like its name, URL, size, creation date, and last modified date. This function specifically lists files, distinct from `list_folders` which only lists directories.
+        
         Args:
             folder_path (str): The path to the folder whose documents are to be listed.
-
+        
         Returns:
             List[Dict[str, Any]]: A list of dictionaries containing document metadata.
-
+        
         Tags:
             important
         """
@@ -136,19 +143,20 @@ class SharepointApp(BaseApplication):
             for f in files
         ]
 
-    def create_document(
+    def upload_text_file(
         self, file_path: str, file_name: str, content: str
     ) -> dict[str, Any]:
-        """Creates a document in the specified folder.
-
+        """
+        Uploads string content to a new file within a specified SharePoint folder path. After creation, it returns an updated list of all documents and their metadata residing in that folder, effectively confirming the file was added successfully.
+        
         Args:
             file_path (str): The path to the folder where the document will be created.
             file_name (str): The name of the document to create.
             content (str): The content to write into the document.
-
+        
         Returns:
             Dict[str, Any]: The updated list of documents in the folder.
-
+        
         Tags: important
         """
         file = self.client.me.drive.root.get_by_path(file_path)
@@ -158,14 +166,15 @@ class SharepointApp(BaseApplication):
         return self.list_documents(file_path)
 
     def get_document_content(self, file_path: str) -> dict[str, Any]:
-        """Gets the content of a specified document.
-
+        """
+        Retrieves a document's content from SharePoint. It returns a dictionary with the content, name, and size. Content is decoded as a string for text files or Base64-encoded for binary files. This is distinct from `list_documents` which only returns metadata without content.
+        
         Args:
             file_path (str): The path to the document.
-
+        
         Returns:
             Dict[str, Any]: A dictionary containing the document's name, content type, content (as text or base64), and size.
-
+        
         Tags: important
         """
         file = self.client.me.drive.root.get_by_path(file_path).get().execute_query()
@@ -189,15 +198,16 @@ class SharepointApp(BaseApplication):
             "size": len(content),
         }
 
-    def delete_file(self, file_path: str):
-        """Deletes a file from OneDrive.
-
+    def delete_document(self, file_path: str):
+        """
+        Permanently deletes a specified file from SharePoint/OneDrive. The function takes the file path as an argument and returns True upon successful deletion. An exception is raised if the file is not found or the deletion fails.
+        
         Args:
             file_path (str): The path to the file to delete.
-
+        
         Returns:
             bool: True if the file was deleted successfully.
-
+        
         Tags:
             important
         """
@@ -208,9 +218,9 @@ class SharepointApp(BaseApplication):
     def list_tools(self):
         return [
             self.list_folders,
-            self.create_folder,
-            self.list_documents,
-            self.create_document,
+            self.create_folder_and_list,
+            self.list_files,
+            self.upload_text_file,
             self.get_document_content,
-            self.delete_file,
+            self.delete_document,
         ]