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

universal_mcp/applications/notion/app.py

@@ -6,16 +6,6 @@ from universal_mcp.integrations import Integration
 
 class NotionApp(APIApplication):
     def __init__(self, integration: Integration = None, **kwargs) -> None:
-        """
-        Initializes a new instance of the Notion API app with a specified integration and additional parameters.
-        
-        Args:
-            integration: Optional; an Integration object containing credentials for authenticating with the Notion API. Defaults to None.
-            kwargs: Additional keyword arguments that are passed to the parent class initializer.
-        
-        Returns:
-            None
-        """
         super().__init__(name='notion', integration=integration, **kwargs)
         self.base_url = "https://api.notion.com"
 
@@ -33,15 +23,21 @@ class NotionApp(APIApplication):
 
     def retrieve_a_user(self, id, request_body=None) -> dict[str, Any]:
         """
-        Retrieves user details from the server using the specified user ID.
+        Retrieves a user's details from the server using their unique identifier.
         
         Args:
-            self: Instance of the class containing the method.
-            id: The unique identifier of the user to retrieve.
-            request_body: Optional request body data, provided when needed. Default is None.
+            id: The unique identifier of the user to retrieve
+            request_body: Optional request body data for the request. Defaults to None
         
         Returns:
-            A dictionary containing user details, as retrieved from the server response.
+            A dictionary containing user details retrieved from the server response
+        
+        Raises:
+            ValueError: Raised when the 'id' parameter is None
+            requests.exceptions.HTTPError: Raised when the server returns an unsuccessful status code
+        
+        Tags:
+            retrieve, get, user, api, single-record, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -53,13 +49,20 @@ class NotionApp(APIApplication):
 
     def list_all_users(self, ) -> dict[str, Any]:
         """
-        Fetches a list of all users from the API endpoint and returns the data as a dictionary.
+        Retrieves a complete list of users from the API endpoint.
         
         Args:
             None: This method does not take any parameters.
         
         Returns:
-            A dictionary containing the list of users retrieved from the API. The dictionary keys are strings, and the values can be of any type.
+            dict[str, Any]: A dictionary containing user data where keys are strings and values can be of any type, representing user information retrieved from the API.
+        
+        Raises:
+            HTTPError: Raised when the API request fails or returns a non-200 status code
+            RequestException: Raised when there are network connectivity issues or other request-related problems
+        
+        Tags:
+            list, users, api, fetch, management, important
         """
         url = f"{self.base_url}/v1/users"
         query_params = {}
@@ -69,13 +72,17 @@ class NotionApp(APIApplication):
 
     def retrieve_your_token_sbot_user(self, ) -> dict[str, Any]:
         """
-        Retrieves the authentication token for the current user from the SBOT service.
-        
-        Args:
-            self: Instance of the class containing configuration such as 'base_url' and the '_get' method.
+        Retrieves the current user's authentication token information from the SBOT service.
         
         Returns:
-            A dictionary containing the JSON response of the current user's token information.
+            A dictionary containing the authentication token and related user information from the JSON response.
+        
+        Raises:
+            requests.exceptions.HTTPError: When the API request fails or returns a non-200 status code
+            requests.exceptions.RequestException: When there are network connectivity issues or other request-related problems
+        
+        Tags:
+            retrieve, authentication, token, user, api, important
         """
         url = f"{self.base_url}/v1/users/me"
         query_params = {}
@@ -85,13 +92,20 @@ class NotionApp(APIApplication):
 
     def retrieve_a_database(self, id) -> dict[str, Any]:
         """
-        Retrieves database details from a specified endpoint using the provided database ID.
+        Retrieves detailed information about a specific database using its unique identifier.
         
         Args:
-            id: A unique identifier for the database to be retrieved. Must be a non-null value.
+            id: Unique identifier for the database to retrieve. Must be a non-null value.
         
         Returns:
-            A dictionary containing the details of the requested database.
+            A dictionary containing detailed information about the requested database.
+        
+        Raises:
+            ValueError: Raised when the 'id' parameter is None
+            HTTPError: Raised when the API request fails or returns an error status code
+        
+        Tags:
+            retrieve, get, database, api, data-access, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -103,15 +117,21 @@ class NotionApp(APIApplication):
 
     def update_a_database(self, id, request_body=None) -> dict[str, Any]:
         """
-        Updates a database entry with the given ID using a PATCH request.
+        Updates a database entry with the specified ID using a PATCH request.
         
         Args:
-            self: The instance of the class to which the method belongs.
-            id: The unique identifier of the database entry to be updated.
-            request_body: An optional dictionary containing the data to update the database entry with. Defaults to None.
+            id: The unique identifier of the database entry to update.
+            request_body: Optional dictionary containing the fields and values to update. Defaults to None.
         
         Returns:
-            A dictionary representing the JSON response from the server after the update operation.
+            dict[str, Any]: A dictionary containing the server's JSON response after the update operation.
+        
+        Raises:
+            ValueError: When the 'id' parameter is None.
+            requests.exceptions.HTTPError: When the server returns an unsuccessful status code.
+        
+        Tags:
+            update, database, patch, important, api, management
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -123,14 +143,21 @@ class NotionApp(APIApplication):
 
     def query_a_database(self, id, request_body=None) -> dict[str, Any]:
         """
-        Executes a query on a specified database using an identifier and an optional request body.
+        Executes a database query operation using a specified database ID and optional request parameters
         
         Args:
-            id: The unique identifier of the database to query.
-            request_body: Optional JSON-compatible dictionary representing the body of the query request; if None, no additional query data is sent.
+            id: The unique identifier of the database to query
+            request_body: Optional JSON-compatible dictionary representing the body of the query request; if None, no additional query data is sent
         
         Returns:
-            A dictionary containing the response data from the database query as parsed from JSON.
+            A dictionary containing the response data from the database query as parsed from JSON
+        
+        Raises:
+            ValueError: Raised when the required 'id' parameter is None
+            HTTPError: Raised when the HTTP request fails or returns an error status code
+        
+        Tags:
+            query, database, api, data-retrieval, http, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -142,13 +169,21 @@ class NotionApp(APIApplication):
 
     def create_a_database(self, request_body=None) -> dict[str, Any]:
         """
-        Creates a new database on the server using the specified request body.
+        Creates a new database on the server by sending a POST request to the database endpoint.
         
         Args:
-            request_body: A dictionary containing the data to be sent in the request body. Defaults to None if not provided.
+            request_body: Optional dictionary containing configuration parameters for the new database. Defaults to None.
         
         Returns:
-            A dictionary containing the server's JSON response from the database creation request.
+            A dictionary containing the server's JSON response with details of the created database.
+        
+        Raises:
+            HTTPError: Raised when the server returns a non-200 status code indicating database creation failure
+            RequestException: Raised when network connectivity issues occur during the API request
+            JSONDecodeError: Raised when the server response cannot be parsed as valid JSON
+        
+        Tags:
+            create, database, api, management, important
         """
         url = f"{self.base_url}/v1/databases/"
         query_params = {}
@@ -158,13 +193,20 @@ class NotionApp(APIApplication):
 
     def create_a_page(self, request_body=None) -> dict[str, Any]:
         """
-        Creates a new page by sending a POST request to the specified endpoint.
+        Creates a new page by sending a POST request to the API endpoint.
         
         Args:
-            request_body: Optional; A dictionary containing the data to be sent in the body of the POST request. Defaults to None.
+            request_body: Optional dictionary containing the page data to be sent in the POST request body. Defaults to None.
         
         Returns:
-            A dictionary representing the JSON response from the server, containing the details of the newly created page.
+            Dictionary containing the JSON response from the server with details of the newly created page.
+        
+        Raises:
+            HTTPError: When the server returns a non-200 status code, indicating a failed request
+            RequestException: When network-related issues occur during the API request
+        
+        Tags:
+            create, page, api, http, post, important
         """
         url = f"{self.base_url}/v1/pages/"
         query_params = {}
@@ -174,13 +216,20 @@ class NotionApp(APIApplication):
 
     def retrieve_a_page(self, id) -> dict[str, Any]:
         """
-        Retrieves a page by its unique identifier from a remote server.
+        Retrieves a specific page's data from a remote server using its unique identifier.
         
         Args:
-            id: The unique identifier of the page to retrieve.
+            id: The unique identifier of the page to retrieve
         
         Returns:
-            A dictionary containing the JSON response from the server, which represents the page data.
+            A dictionary containing the page data returned from the server's JSON response
+        
+        Raises:
+            ValueError: When the 'id' parameter is None
+            HTTPError: When the server returns an unsuccessful status code
+        
+        Tags:
+            retrieve, fetch, api, http, get, page, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -192,14 +241,22 @@ class NotionApp(APIApplication):
 
     def update_page_properties(self, id, request_body=None) -> dict[str, Any]:
         """
-        Updates the properties of a page identified by its ID using the provided request body.
+        Updates the properties of a page with the specified ID using the provided request body.
         
         Args:
-            id: The unique identifier of the page whose properties are to be updated. Must not be None.
-            request_body: An optional dictionary representing the request payload containing the properties to be updated. Defaults to None.
+            id: The unique identifier of the page to update. Must not be None.
+            request_body: Optional dictionary containing the properties to be updated. Defaults to None.
         
         Returns:
-            A dictionary containing the updated page properties as returned by the server after the update.
+            Dictionary containing the updated page properties as returned by the server.
+        
+        Raises:
+            ValueError: When the required 'id' parameter is None
+            HTTPError: When the server returns an unsuccessful status code
+            RequestException: When there is an error making the HTTP request
+        
+        Tags:
+            update, api, page-management, http, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -211,14 +268,21 @@ class NotionApp(APIApplication):
 
     def retrieve_a_page_property_item(self, page_id, property_id) -> dict[str, Any]:
         """
-        Retrieves the property item of a page using specified page and property identifiers.
+        Retrieves a specific property item from a Notion page using the page ID and property ID.
         
         Args:
-            page_id: The unique identifier of the page from which the property item is to be retrieved.
-            property_id: The unique identifier of the property associated with the specified page.
+            page_id: The unique identifier of the Notion page from which to retrieve the property
+            property_id: The unique identifier of the specific property to retrieve
         
         Returns:
-            A dictionary representing the JSON response with details of the property item.
+            A dictionary containing the property item's details from the API response
+        
+        Raises:
+            ValueError: When either page_id or property_id is None
+            HTTPError: When the API request fails or returns an error status code
+        
+        Tags:
+            retrieve, get, property, page, api, notion, important
         """
         if page_id is None:
             raise ValueError("Missing required parameter 'page_id'")
@@ -232,14 +296,21 @@ class NotionApp(APIApplication):
 
     def retrieve_block_children(self, id, page_size=None) -> dict[str, Any]:
         """
-        Retrieves the children of a specified block using its unique identifier.
+        Retrieves all child blocks for a specified parent block using its ID via the API.
         
         Args:
-            id: The unique identifier of the block whose children are to be retrieved.
-            page_size: Optional; The maximum number of children to return per page in the response, if specified.
+            id: The unique identifier of the parent block whose children are to be retrieved
+            page_size: Optional integer specifying the maximum number of children to return per page in the response
         
         Returns:
-            A dictionary containing the data representing the children of the specified block.
+            A dictionary containing the API response data with the children blocks information
+        
+        Raises:
+            ValueError: When the required 'id' parameter is None
+            HTTPError: When the API request fails or returns an error status code
+        
+        Tags:
+            retrieve, list, blocks, children, pagination, api-call, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -251,15 +322,21 @@ class NotionApp(APIApplication):
 
     def append_block_children(self, id, request_body=None) -> dict[str, Any]:
         """
-        Appends child elements to a block identified by its ID and returns the updated block data.
+        Appends child elements to a specified block and returns the updated block data.
         
         Args:
-            self: Instance of the class containing this method.
-            id: The identifier of the block to which children will be appended. It must not be None.
-            request_body: Optional dictionary containing the data of the child elements to be appended to the block.
+            id: String identifier of the block to which children will be appended
+            request_body: Optional dictionary containing the child elements to be appended (default: None)
         
         Returns:
-            A dictionary representing the updated block data after appending the child elements.
+            dict[str, Any]: A dictionary containing the updated block data after appending the children
+        
+        Raises:
+            ValueError: When the required 'id' parameter is None
+            HTTPError: When the API request fails or returns an error status code
+        
+        Tags:
+            append, update, blocks, children, api, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -271,13 +348,20 @@ class NotionApp(APIApplication):
 
     def retrieve_a_block(self, id) -> dict[str, Any]:
         """
-        Retrieves a block of data from a given API endpoint using the specified block ID.
+        Retrieves a specific block of data from the API using its unique identifier.
         
         Args:
-            id: The unique identifier for the block to be retrieved. It must be a non-None value, otherwise a ValueError will be raised.
+            id: The unique identifier for the block to be retrieved. Must be a non-None value.
         
         Returns:
-            A dictionary containing the JSON response from the API, representing the block data corresponding to the provided ID.
+            A dictionary containing the block data retrieved from the API, parsed from the JSON response.
+        
+        Raises:
+            ValueError: When the 'id' parameter is None
+            HTTPError: When the API request fails or returns an error status code
+        
+        Tags:
+            retrieve, fetch, api, data, block, single, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -289,13 +373,20 @@ class NotionApp(APIApplication):
 
     def delete_a_block(self, id) -> dict[str, Any]:
         """
-        Deletes a block by its unique identifier and returns the server's response.
+        Deletes a specified block by its ID and returns the server response.
         
         Args:
             id: The unique identifier of the block to be deleted. Must not be None.
         
         Returns:
-            A dictionary containing the response data from the server after attempting to delete the block.
+            A dictionary containing the server's response data after the deletion operation.
+        
+        Raises:
+            ValueError: When the 'id' parameter is None
+            HTTPError: When the server returns an unsuccessful status code
+        
+        Tags:
+            delete, important, management, api, http, block-management
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -307,14 +398,21 @@ class NotionApp(APIApplication):
 
     def update_a_block(self, id, request_body=None) -> dict[str, Any]:
         """
-        Updates a block by sending a PATCH request to the specified endpoint.
+        Updates a specific block resource via a PATCH request to the API endpoint
         
         Args:
-            id: The unique identifier for the block that is to be updated.
-            request_body: Optional; A dictionary containing the data to update the block with. Defaults to None.
+            id: The unique identifier of the block to update
+            request_body: Optional dictionary containing the update data for the block. Defaults to None
         
         Returns:
-            A dictionary containing the JSON response from the server after updating the block.
+            Dictionary containing the server's JSON response with the updated block information
+        
+        Raises:
+            ValueError: When the required 'id' parameter is None
+            HTTPError: When the server responds with an error status code
+        
+        Tags:
+            update, patch, api, block-management, important
         """
         if id is None:
             raise ValueError("Missing required parameter 'id'")
@@ -326,13 +424,20 @@ class NotionApp(APIApplication):
 
     def search(self, request_body=None) -> dict[str, Any]:
         """
-        Executes a search query using the specified request body and returns the results.
+        Executes a search operation by sending a POST request to the search endpoint and returns the results
         
         Args:
-            request_body: An optional dictionary containing the data to be sent in the search request.
+            request_body: Optional dictionary containing the search parameters and filters to be sent in the request. Defaults to None.
         
         Returns:
-            A dictionary containing the JSON-decoded response from the search operation.
+            A dictionary containing the parsed JSON response from the search operation with search results and metadata
+        
+        Raises:
+            HTTPError: Raised when the search request fails or returns a non-200 status code
+            JSONDecodeError: Raised when the response cannot be parsed as valid JSON
+        
+        Tags:
+            search, important, http, query, api-request, json
         """
         url = f"{self.base_url}/v1/search"
         query_params = {}
@@ -342,15 +447,22 @@ class NotionApp(APIApplication):
 
     def retrieve_comments(self, block_id=None, page_size=None, request_body=None) -> dict[str, Any]:
         """
-        Fetches comments from a remote server for a specified block, with optional pagination.
+        Retrieves comments from a remote server with optional block filtering and pagination support.
         
         Args:
-            block_id: Optional; Identifies the block whose comments should be retrieved. If None, retrieves comments without filtering by block.
-            page_size: Optional; Specifies the number of comments to retrieve per page for pagination. If None, the server's default page size is used.
-            request_body: Unused placeholder for future extensibility; this function currently does not utilize this parameter.
+            block_id: Optional string or ID that specifies which block's comments to retrieve. If None, retrieves all comments.
+            page_size: Optional integer specifying the number of comments to return per page. If None, uses server's default pagination.
+            request_body: Optional dictionary for future extensibility. Currently unused.
         
         Returns:
-            A dictionary containing the response data from the server, parsed from JSON, with keys and values representing comment-related information.
+            Dictionary containing comment data parsed from the server's JSON response.
+        
+        Raises:
+            HTTPError: Raised when the server returns a non-200 status code
+            RequestException: Raised for network-related errors during the HTTP request
+        
+        Tags:
+            retrieve, fetch, comments, api, pagination, http, important
         """
         url = f"{self.base_url}/v1/comments"
         query_params = {k: v for k, v in [('block_id', block_id), ('page_size', page_size)] if v is not None}
@@ -360,13 +472,20 @@ class NotionApp(APIApplication):
 
     def add_comment_to_page(self, request_body=None) -> dict[str, Any]:
         """
-        Adds a comment to a page by sending a POST request with the provided request body.
+        Adds a comment to a page by making an HTTP POST request to the comments endpoint.
         
         Args:
-            request_body: Optional; A dictionary containing the data for the comment to be added. Defaults to None.
+            request_body: Optional dictionary containing the comment data to be posted. If None, an empty comment will be created. Defaults to None.
         
         Returns:
-            A dictionary representing the JSON response from the server, which includes details of the newly added comment.
+            Dictionary containing the server's JSON response with details of the created comment.
+        
+        Raises:
+            HTTPError: Raised when the server returns a non-200 status code, indicating the comment creation failed.
+            RequestException: Raised when there are network connectivity issues or other request-related problems.
+        
+        Tags:
+            add, create, comment, post, api, content-management, important
         """
         url = f"{self.base_url}/v1/comments"
         query_params = {}
@@ -375,15 +494,6 @@ class NotionApp(APIApplication):
         return response.json()
 
     def list_tools(self):
-        """
-        Returns a list of functions related to user and database operations.
-        
-        Args:
-            self: The instance of the class to which the function belongs.
-        
-        Returns:
-            A list of method references that pertain to various operations such as user retrieval, database operations, and page/block management.
-        """
         return [
             self.retrieve_a_user,
             self.list_all_users,

universal_mcp/applications/perplexity/app.py

@@ -1,8 +1,9 @@
 from typing import Any, Literal
 
+from loguru import logger
+
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.integrations import Integration
-from loguru import logger
 
 
 class PerplexityApp(APIApplication):
@@ -58,34 +59,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"]