universal-mcp-applications 0.1.21__py3-none-any.whl → 0.1.23__py3-none-any.whl

universal_mcp/applications/BEST_PRACTICES.md

@@ -0,0 +1,166 @@
+# Best Practices for Creating MCP Applications
+
+This guide provides best practices for developing new applications for the Universal MCP. We will use the `google_gemini` application as a reference to illustrate key concepts.
+
+## 1. Application Structure
+
+Every application should be a class that inherits from `APIApplication`. This base class provides the necessary foundation for integration with the MCP.
+
+### Basic Class Definition
+
+Your `app.py` file should contain a class definition similar to this:
+
+```python
+from universal_mcp.applications.application import APIApplication
+from universal_mcp.integrations import Integration
+
+class YourApplicationName(APIApplication):
+    def __init__(self, integration: Integration = None, **kwargs) -> None:
+        super().__init__(name="your_application_name", integration=integration, **kwargs)
+        self._api_client = None # Lazy-loaded client
+
+    # ... your tool methods will go here
+```
+
+- **`__init__`**: The constructor initializes the base application with a unique `name` (usually matching the folder name) and the `integration` object, which holds credentials.
+- **`_api_client`**: It's a best practice to lazy-load your API client. Initialize it as `None` and create the client instance only when it's first needed.
+
+## 2. Authentication and API Clients
+
+Credentials should never be hard-coded. They are managed through the `integration` object. Use a property to initialize your API client on its first use. This prevents unnecessary setup if the application is loaded but not used.
+
+```python
+from google import genai
+
+class GoogleGeminiApp(APIApplication):
+    # ... (init method)
+
+    @property
+    def genai_client(self) -> genai.Client:
+        if self._genai_client is not None:
+            return self._genai_client
+        
+        credentials = self.integration.get_credentials()
+        api_key = (
+            credentials.get("api_key")
+            or credentials.get("API_KEY")
+            or credentials.get("apiKey")
+        )
+        if not api_key:
+            raise ValueError("API key not found in integration credentials")
+        
+        self._genai_client = genai.Client(api_key=api_key)
+        return self._genai_client
+```
+
+This `genai_client` property ensures the client is created only once, the first time a tool tries to access it.
+
+## 3. Defining Tools
+
+Public methods within your application class are exposed as tools that the AI can use. For a method to be a valid tool, it must have a detailed docstring and proper type hints.
+
+### Docstrings: The AI's Guide
+
+A well-written docstring is crucial. It's how the AI understands what your tool does, what inputs it needs, and what it returns.
+
+```python
+async def generate_text(
+    self,
+    prompt: Annotated[str, "The prompt to generate text from"],
+    model: str = "gemini-2.5-flash",
+) -> str:
+    """Generates text using the Google Gemini model based on a given prompt.
+    This tool is suitable for various natural language processing tasks such as content generation, summarization, translation, and question answering.
+
+    Args:
+        prompt (str): The text prompt or instruction for the model to follow. For example: "Write a short story about a robot who learns to love."
+        model (str, optional): The Gemini model to use for text generation. Defaults to "gemini-2.5-flash".
+
+    Returns:
+        str: The generated text response from the Gemini model.
+
+    Raises:
+        ValueError: If the API key is not found in the integration credentials.
+        Exception: If the underlying client or API call fails.
+
+    Tags:
+        text, generate, llm, important
+    """
+    response = self.genai_client.models.generate_content(
+        contents=prompt, model=model
+    )
+    return response.text
+```
+
+**Docstring Breakdown:**
+1.  **Summary Line**: A single, concise sentence describing the tool's main function.
+2.  **Detailed Description**: An optional paragraph providing more context, use cases, and why the tool is useful.
+3.  **`Args`**: Describe each parameter. For clarity, use `typing.Annotated` to provide a short, user-friendly description directly in the function signature.
+4.  **`Returns`**: Clearly describe the output of the function.
+5.  **`Raises`**: List any potential exceptions the tool might raise.
+6.  **`Tags`**: A comma-separated list of keywords that help in categorizing and discovering the tool. Use `important` for core tools.
+
+### Return Types
+
+-   **Simple Types**: For simple text or data, return standard Python types like `str`, `dict`, or `list`.
+
+-   **Files/Media (Images, Audio, etc.)**: When a tool generates content that should be treated as a file, return a specific dictionary structure. This allows the MCP to handle the data correctly (e.g., saving it to a file or displaying it).
+
+    The structure is:
+    ```json
+    {
+        "type": "image" | "audio" | "video" | "file",
+        "data": "<base64_encoded_string>",
+        "mime_type": "image/png",
+        "file_name": "suggested_filename.png"
+    }
+    ```
+
+    **Example from `generate_image`:**
+    ```python
+    return {
+        "type": "image",
+        "data": img_base64,
+        "mime_type": "image/png",
+        "file_name": file_name,
+        "text": text, # Optional: any accompanying text
+    }
+    ```
+
+## 4. Listing and Registering Tools
+
+To make your tools available to the MCP, you must list them in the `list_tools` method.
+
+```python
+class GoogleGeminiApp(APIApplication):
+    # ... (tool methods)
+
+    def list_tools(self):
+        return [
+            self.generate_text,
+            self.generate_image,
+            self.generate_audio,
+        ]
+```
+
+This method should return a list of the function objects you want to expose.
+
+## 5. Local Testing
+
+To facilitate rapid development and testing, include a runnable block in your `app.py`. This allows you to test your application's functionality directly without needing the full MCP environment.
+
+```python
+if __name__ == "__main__":
+    import asyncio
+
+    async def test_google_gemini():
+        # NOTE: You may need to set up credentials locally for this to work
+        # e.g., os.environ["GOOGLE_API_KEY"] = "..."
+        app = GoogleGeminiApp()
+        response = await app.generate_text(
+            "Tell me a fun fact about the Roman Empire."
+        )
+        print(response)
+
+    asyncio.run(test_google_gemini())
+```

universal_mcp/applications/airtable/app.py

@@ -14,7 +14,6 @@ from pyairtable.api.types import (
     WritableFields,
 )
 from pyairtable.formulas import Formula, to_formula_str
-
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.integrations import Integration
 

universal_mcp/applications/apollo/app.py

@@ -1,7 +1,6 @@
 from typing import Any
 
 from loguru import logger
-
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.integrations import Integration
 

universal_mcp/applications/aws_s3/app.py

@@ -4,7 +4,6 @@ from typing import Any
 
 import boto3
 from botocore.exceptions import ClientError
-
 from universal_mcp.applications.application import BaseApplication
 from universal_mcp.integrations import Integration
 
@@ -49,7 +48,7 @@ class AwsS3App(BaseApplication):
     def list_buckets(self) -> list[str]:
         """
         Retrieves all S3 buckets accessible by the configured AWS credentials. It calls the S3 API's list_buckets operation and processes the response to return a simple list containing just the names of the buckets.
-        
+
         Returns:
             List[str]: A list of bucket names.
         """
@@ -59,11 +58,11 @@ class AwsS3App(BaseApplication):
     def create_bucket(self, bucket_name: str, region: str | None = None) -> bool:
         """
         Creates a new Amazon S3 bucket with a specified name and optional region. Returns `True` upon successful creation, or `False` if an AWS client error, such as a naming conflict or permission issue, occurs.
-        
+
         Args:
             bucket_name (str): The name of the bucket to create.
             region (str, optional): The region to create the bucket in.
-        
+
         Returns:
             bool: True if the bucket was created successfully.
         Tags:
@@ -84,10 +83,10 @@ class AwsS3App(BaseApplication):
     def delete_bucket(self, bucket_name: str) -> bool:
         """
         Deletes a specified S3 bucket. The operation requires the bucket to be empty to succeed. It returns `True` if the bucket is successfully deleted and `False` if an error occurs, such as the bucket not being found or containing objects.
-        
+
         Args:
             bucket_name (str): The name of the bucket to delete.
-        
+
         Returns:
             bool: True if the bucket was deleted successfully.
         Tags:
@@ -102,10 +101,10 @@ class AwsS3App(BaseApplication):
     def get_bucket_policy(self, bucket_name: str) -> dict[str, Any]:
         """
         Retrieves the IAM resource policy for a specified S3 bucket, parsing the JSON string into a dictionary. If the operation fails due to permissions or a non-existent policy, it returns an error dictionary. This complements `put_bucket_policy`, which applies a new policy.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
-        
+
         Returns:
             Dict[str, Any]: The bucket policy as a dictionary.
         Tags:
@@ -120,11 +119,11 @@ class AwsS3App(BaseApplication):
     def set_bucket_policy(self, bucket_name: str, policy: dict[str, Any]) -> bool:
         """
         Applies or replaces the access policy for a specified S3 bucket. The function accepts the policy as a dictionary, converts it to JSON, and assigns it to the bucket. This write operation is the counterpart to `get_bucket_policy` and returns `True` on success.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             policy (Dict[str, Any]): The bucket policy as a dictionary.
-        
+
         Returns:
             bool: True if the policy was set successfully.
         Tags:
@@ -136,14 +135,16 @@ class AwsS3App(BaseApplication):
         except ClientError:
             return False
 
-    def list_subdirectories(self, bucket_name: str, prefix: str | None = None) -> list[str]:
+    def list_subdirectories(
+        self, bucket_name: str, prefix: str | None = None
+    ) -> list[str]:
         """
         Lists immediate subdirectories (common prefixes) within an S3 bucket. If a prefix is provided, it returns subdirectories under that path; otherwise, it lists top-level directories. This function specifically lists folders, distinguishing it from `list_objects`, which lists files.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str, optional): The prefix to list folders under.
-        
+
         Returns:
             List[str]: A list of folder prefixes.
         Tags:
@@ -168,12 +169,12 @@ class AwsS3App(BaseApplication):
     ) -> bool:
         """
         Creates a prefix (folder) in an S3 bucket, optionally nested under a parent prefix. It simulates a directory by creating a zero-byte object with a key ending in a slash ('/'), distinguishing it from put_object, which uploads content.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix_name (str): The name of the prefix to create.
             parent_prefix (str, optional): The parent prefix (folder path).
-        
+
         Returns:
             bool: True if the prefix was created successfully.
         Tags:
@@ -189,11 +190,11 @@ class AwsS3App(BaseApplication):
     def list_objects(self, bucket_name: str, prefix: str) -> list[dict[str, Any]]:
         """
         Paginates through and lists all objects within a specified S3 bucket prefix. It returns a curated list of metadata for each object (key, name, size, last modified), excluding folder placeholders. This function specifically lists files, distinguishing it from `list_prefixes` which lists folders.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str): The prefix (folder path) to list objects under.
-        
+
         Returns:
             List[Dict[str, Any]]: A list of dictionaries containing object metadata.
         Tags:
@@ -222,13 +223,13 @@ class AwsS3App(BaseApplication):
     ) -> bool:
         """
         Uploads string content to create an object in a specified S3 bucket and prefix. The content is UTF-8 encoded before being written. This method is for text, distinguishing it from `put_object_from_base64` which handles binary data.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str): The prefix (folder path) where the object will be created.
             object_name (str): The name of the object to create.
             content (str): The content to write into the object.
-        
+
         Returns:
             bool: True if the object was created successfully.
         Tags:
@@ -245,13 +246,13 @@ class AwsS3App(BaseApplication):
     ) -> bool:
         """
         Decodes a base64 string into binary data and uploads it as an object to a specified S3 location. This method is designed for binary files, differentiating it from `put_object` which handles plain text content. Returns true on success.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str): The prefix (folder path) where the object will be created.
             object_name (str): The name of the object to create.
             base64_content (str): The base64-encoded content to upload.
-        
+
         Returns:
             bool: True if the object was created successfully.
         Tags:
@@ -268,11 +269,11 @@ class AwsS3App(BaseApplication):
     def get_object_with_content(self, bucket_name: str, key: str) -> dict[str, Any]:
         """
         Retrieves an S3 object's content. It decodes text files as UTF-8 or encodes binary files as base64 based on the object's key. This function downloads the full object body, unlike `get_object_metadata` which only fetches metadata without content, returning the content, name, size, and type.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             key (str): The key (path) to the object.
-        
+
         Returns:
             Dict[str, Any]: A dictionary containing the object's name, content type, content (as text or base64), and size.
         Tags:
@@ -301,11 +302,11 @@ class AwsS3App(BaseApplication):
     def get_object_metadata(self, bucket_name: str, key: str) -> dict[str, Any]:
         """
         Efficiently retrieves metadata for a specified S3 object, such as size and last modified date, without downloading its content. This function uses a HEAD request, making it faster than `get_object_content` for accessing object properties. Returns a dictionary of metadata or an error message on failure.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             key (str): The key (path) to the object.
-        
+
         Returns:
             Dict[str, Any]: A dictionary containing the object's metadata.
         Tags:
@@ -332,13 +333,13 @@ class AwsS3App(BaseApplication):
     ) -> bool:
         """
         Copies an S3 object from a specified source location to a destination, which can be in the same or a different bucket. Unlike `move_object`, the original object remains at the source after the copy operation. It returns `True` for a successful operation.
-        
+
         Args:
             source_bucket (str): The source bucket name.
             source_key (str): The source object key.
             dest_bucket (str): The destination bucket name.
             dest_key (str): The destination object key.
-        
+
         Returns:
             bool: True if the object was copied successfully.
         Tags:
@@ -358,13 +359,13 @@ class AwsS3App(BaseApplication):
     ) -> bool:
         """
         Moves an S3 object from a source to a destination. This is achieved by first copying the object to the new location and subsequently deleting the original. The move can occur within the same bucket or between different ones, returning `True` on success.
-        
+
         Args:
             source_bucket (str): The source bucket name.
             source_key (str): The source object key.
             dest_bucket (str): The destination bucket name.
             dest_key (str): The destination object key.
-        
+
         Returns:
             bool: True if the object was moved successfully.
         Tags:
@@ -377,11 +378,11 @@ class AwsS3App(BaseApplication):
     def delete_single_object(self, bucket_name: str, key: str) -> bool:
         """
         Deletes a single, specified object from an S3 bucket using its key. Returns `True` if successful, otherwise `False`. For bulk deletions in a single request, the `delete_objects` function should be used instead.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             key (str): The key (path) to the object to delete.
-        
+
         Returns:
             bool: True if the object was deleted successfully.
         Tags:
@@ -396,11 +397,11 @@ class AwsS3App(BaseApplication):
     def delete_objects(self, bucket_name: str, keys: list[str]) -> dict[str, Any]:
         """
         Performs a bulk deletion of objects from a specified S3 bucket in a single request. Given a list of keys, it returns a dictionary detailing successful deletions and any errors. This method is the batch-processing counterpart to the singular `delete_object` function, designed for efficiency.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             keys (List[str]): List of object keys to delete.
-        
+
         Returns:
             Dict[str, Any]: Results of the deletion operation.
         Tags:
@@ -427,13 +428,13 @@ class AwsS3App(BaseApplication):
     ) -> str:
         """
         Generates a temporary, secure URL for a specific S3 object. This URL grants time-limited permissions for actions like GET, PUT, or DELETE, expiring after a defined period. It allows object access without sharing permanent AWS credentials.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             key (str): The key (path) to the object.
             expiration (int): Time in seconds for the presigned URL to remain valid (default: 3600).
             http_method (str): HTTP method for the presigned URL (default: 'GET').
-        
+
         Returns:
             str: The presigned URL or error message.
         Tags:
@@ -465,14 +466,14 @@ class AwsS3App(BaseApplication):
     ) -> list[dict[str, Any]]:
         """
         Filters objects within an S3 bucket and prefix based on a name pattern and size range. It retrieves all objects via `list_objects` and then applies the specified criteria client-side, returning a refined list of matching objects and their metadata.
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str): The prefix to search within.
             name_pattern (str): Pattern to match in object names (case-insensitive).
             min_size (int, optional): Minimum object size in bytes.
             max_size (int, optional): Maximum object size in bytes.
-        
+
         Returns:
             List[Dict[str, Any]]: List of matching objects with metadata.
         Tags:
@@ -499,11 +500,11 @@ class AwsS3App(BaseApplication):
     def get_storage_summary(self, bucket_name: str, prefix: str = "") -> dict[str, Any]:
         """
         Calculates and returns statistics for an S3 bucket or prefix. The result includes the total number of objects, their combined size in bytes, and a human-readable string representation of the size (e.g., '15.2 MB').
-        
+
         Args:
             bucket_name (str): The name of the S3 bucket.
             prefix (str): The prefix to calculate size for (default: entire bucket).
-        
+
         Returns:
             Dict[str, Any]: Dictionary containing total size, object count, and human-readable size.
         Tags:

universal_mcp/applications/browser_use/README.md

@@ -0,0 +1 @@
+# Browser Use

universal_mcp/applications/browser_use/app.py

@@ -0,0 +1,71 @@
+from typing import Annotated
+
+from universal_mcp.applications.application import APIApplication
+from universal_mcp.integrations import Integration
+
+from browser_use_sdk import BrowserUse
+
+
+class BrowserUseApp(APIApplication):
+    def __init__(self, integration: Integration | None = None, **kwargs) -> None:
+        super().__init__(name="browser_use", integration=integration, **kwargs)
+        self._browser_client = None
+
+    @property
+    def browser_client(self) -> BrowserUse:
+        if self._browser_client is not None:
+            return self._browser_client
+        if not self.integration:
+            raise ValueError("Integration is required but not provided")
+        credentials = self.integration.get_credentials()
+        api_key = (
+            credentials.get("api_key")
+            or credentials.get("API_KEY")
+            or credentials.get("apiKey")
+        )
+        if not api_key:
+            raise ValueError("API key not found in integration credentials")
+        self._browser_client = BrowserUse(api_key=api_key)
+        return self._browser_client
+
+    async def browser_task(
+        self,
+        task: Annotated[str, "What you want the browser to do"],
+        max_steps: Annotated[int, "Max actions to take (1-10, default: 8)"] = 8,
+        llm: Annotated[str, "The LLM to use for the task"] = "gpt-4.1",
+    ) -> dict:
+        """
+        Creates and runs a browser automation task.
+
+        Args:
+            task (str): The detailed description of the task for the browser to perform.
+            max_steps (int, optional): The maximum number of actions the browser can take. Defaults to 8.
+            llm (str, optional): The language model to use for interpreting the task. Defaults to "gpt-4.1".
+
+        Returns:
+            dict: The result of the completed task, including output and other metadata.
+        """
+        created_task = self.browser_client.tasks.create_task(
+            llm=llm, task=task, max_steps=max_steps
+        )
+        result = created_task.complete()
+        return result.to_dict()
+
+    async def get_browser_task_status(
+        self,
+        task_id: Annotated[str, "Task ID to check"],
+    ) -> dict:
+        """
+        Checks task progress with smart polling.
+
+        Args:
+            task_id (str): The ID of the task to check.
+
+        Returns:
+            dict: The current status and details of the task.
+        """
+        task = self.browser_client.tasks.get_task(task_id)
+        return task.to_dict()
+
+    def list_tools(self):
+        return [self.browser_task, self.get_browser_task_status]