universal-mcp-applications 0.1.33__py3-none-any.whl → 0.1.39rc16__py3-none-any.whl

universal_mcp/applications/aws_s3/app.py

@@ -1,7 +1,6 @@
 import base64
 import json
 from typing import Any
-
 import boto3
 from botocore.exceptions import ClientError
 from universal_mcp.applications.application import BaseApplication
@@ -26,36 +25,34 @@ class AwsS3App(BaseApplication):
         self._client = client
         self.integration = integration
 
-    @property
-    def client(self):
+    async def get_client(self):
         """
         Lazily initializes and returns a cached Boto3 S3 client instance. It retrieves authentication credentials from the associated `integration` object. This property is the core mechanism used by all other methods in the class to interact with AWS S3, raising an error if the integration is not set.
         """
         if not self.integration:
             raise ValueError("Integration not initialized")
         if not self._client:
-            credentials = self.integration.get_credentials()
+            credentials = await self.integration.get_credentials_async()
             credentials = {
-                "aws_access_key_id": credentials.get("access_key_id")
-                or credentials.get("username"),
-                "aws_secret_access_key": credentials.get("secret_access_key")
-                or credentials.get("password"),
+                "aws_access_key_id": credentials.get("access_key_id") or credentials.get("username"),
+                "aws_secret_access_key": credentials.get("secret_access_key") or credentials.get("password"),
                 "region_name": credentials.get("region"),
             }
             self._client = boto3.client("s3", **credentials)
         return self._client
 
-    def list_buckets(self) -> list[str]:
+    async 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.
         """
-        response = self.client.list_buckets()
+        client = await self.get_client()
+        response = await client.list_buckets()
         return [bucket["Name"] for bucket in response["Buckets"]]
 
-    def create_bucket(self, bucket_name: str, region: str | None = None) -> bool:
+    async 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.
 
@@ -69,18 +66,16 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
+            client = await self.get_client()
             if region:
-                self.client.create_bucket(
-                    Bucket=bucket_name,
-                    CreateBucketConfiguration={"LocationConstraint": region},
-                )
+                await client.create_bucket(Bucket=bucket_name, CreateBucketConfiguration={"LocationConstraint": region})
             else:
-                self.client.create_bucket(Bucket=bucket_name)
+                await client.create_bucket(Bucket=bucket_name)
             return True
         except ClientError:
             return False
 
-    def delete_bucket(self, bucket_name: str) -> bool:
+    async 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.
 
@@ -93,12 +88,13 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            self.client.delete_bucket(Bucket=bucket_name)
+            client = await self.get_client()
+            await client.delete_bucket(Bucket=bucket_name)
             return True
         except ClientError:
             return False
 
-    def get_bucket_policy(self, bucket_name: str) -> dict[str, Any]:
+    async 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.
 
@@ -111,12 +107,13 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            response = self.client.get_bucket_policy(Bucket=bucket_name)
+            client = await self.get_client()
+            response = await client.get_bucket_policy(Bucket=bucket_name)
             return json.loads(response["Policy"])
         except ClientError as e:
             return {"error": str(e)}
 
-    def set_bucket_policy(self, bucket_name: str, policy: dict[str, Any]) -> bool:
+    async 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.
 
@@ -130,14 +127,13 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            self.client.put_bucket_policy(Bucket=bucket_name, Policy=json.dumps(policy))
+            client = await self.get_client()
+            await client.put_bucket_policy(Bucket=bucket_name, Policy=json.dumps(policy))
             return True
         except ClientError:
             return False
 
-    def list_subdirectories(
-        self, bucket_name: str, prefix: str | None = None
-    ) -> list[str]:
+    async 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.
 
@@ -150,23 +146,20 @@ class AwsS3App(BaseApplication):
         Tags:
             important
         """
-        paginator = self.client.get_paginator("list_objects_v2")
+        paginator = (await self.get_client()).get_paginator("list_objects_v2")
         operation_parameters = {"Bucket": bucket_name}
         if prefix:
             operation_parameters["Prefix"] = prefix
             operation_parameters["Delimiter"] = "/"
         else:
             operation_parameters["Delimiter"] = "/"
-
         prefixes = []
         for page in paginator.paginate(**operation_parameters):
             for cp in page.get("CommonPrefixes", []):
                 prefixes.append(cp.get("Prefix"))
         return prefixes
 
-    def create_prefix(
-        self, bucket_name: str, prefix_name: str, parent_prefix: str | None = None
-    ) -> bool:
+    async def create_prefix(self, bucket_name: str, prefix_name: str, parent_prefix: str | None = None) -> 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.
 
@@ -184,10 +177,10 @@ class AwsS3App(BaseApplication):
             key = f"{parent_prefix.rstrip('/')}/{prefix_name}/"
         else:
             key = f"{prefix_name}/"
-        self.client.put_object(Bucket=bucket_name, Key=key)
+        await (await self.get_client()).put_object(Bucket=bucket_name, Key=key)
         return True
 
-    def list_objects(self, bucket_name: str, prefix: str) -> list[dict[str, Any]]:
+    async 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.
 
@@ -200,7 +193,8 @@ class AwsS3App(BaseApplication):
         Tags:
             important
         """
-        paginator = self.client.get_paginator("list_objects_v2")
+        client = await self.get_client()
+        paginator = client.get_paginator("list_objects_v2")
         operation_parameters = {"Bucket": bucket_name, "Prefix": prefix}
         objects = []
         for page in paginator.paginate(**operation_parameters):
@@ -218,9 +212,7 @@ class AwsS3App(BaseApplication):
                     )
         return objects
 
-    def put_text_object(
-        self, bucket_name: str, prefix: str, object_name: str, content: str
-    ) -> bool:
+    async def put_text_object(self, bucket_name: str, prefix: str, object_name: str, content: str) -> 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.
 
@@ -236,14 +228,11 @@ class AwsS3App(BaseApplication):
             important
         """
         key = f"{prefix.rstrip('/')}/{object_name}" if prefix else object_name
-        self.client.put_object(
-            Bucket=bucket_name, Key=key, Body=content.encode("utf-8")
-        )
+        client = await self.get_client()
+        await client.put_object(Bucket=bucket_name, Key=key, Body=content.encode("utf-8"))
         return True
 
-    def put_object_from_base64(
-        self, bucket_name: str, prefix: str, object_name: str, base64_content: str
-    ) -> bool:
+    async def put_object_from_base64(self, bucket_name: str, prefix: str, object_name: str, base64_content: str) -> 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.
 
@@ -261,12 +250,13 @@ class AwsS3App(BaseApplication):
         try:
             key = f"{prefix.rstrip('/')}/{object_name}" if prefix else object_name
             content = base64.b64decode(base64_content)
-            self.client.put_object(Bucket=bucket_name, Key=key, Body=content)
+            client = await self.get_client()
+            await client.put_object(Bucket=bucket_name, Key=key, Body=content)
             return True
         except Exception:
             return False
 
-    def get_object_with_content(self, bucket_name: str, key: str) -> dict[str, Any]:
+    async 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.
 
@@ -280,26 +270,18 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            obj = self.client.get_object(Bucket=bucket_name, Key=key)
+            client = await self.get_client()
+            obj = await client.get_object(Bucket=bucket_name, Key=key)
             content = obj["Body"].read()
-            is_text_file = key.lower().endswith(
-                (".txt", ".csv", ".json", ".xml", ".html", ".md", ".js", ".css", ".py")
-            )
+            is_text_file = key.lower().endswith((".txt", ".csv", ".json", ".xml", ".html", ".md", ".js", ".css", ".py"))
             content_dict = (
-                {"content": content.decode("utf-8")}
-                if is_text_file
-                else {"content_base64": base64.b64encode(content).decode("ascii")}
+                {"content": content.decode("utf-8")} if is_text_file else {"content_base64": base64.b64encode(content).decode("ascii")}
             )
-            return {
-                "name": key.split("/")[-1],
-                "content_type": "text" if is_text_file else "binary",
-                **content_dict,
-                "size": len(content),
-            }
+            return {"name": key.split("/")[-1], "content_type": "text" if is_text_file else "binary", **content_dict, "size": len(content)}
         except ClientError as e:
             return {"error": str(e)}
 
-    def get_object_metadata(self, bucket_name: str, key: str) -> dict[str, Any]:
+    async 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.
 
@@ -313,14 +295,13 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            response = self.client.head_object(Bucket=bucket_name, Key=key)
+            client = await self.get_client()
+            response = await client.head_object(Bucket=bucket_name, Key=key)
             return {
                 "key": key,
                 "name": key.split("/")[-1],
                 "size": response.get("ContentLength", 0),
-                "last_modified": response.get("LastModified", "").isoformat()
-                if response.get("LastModified")
-                else "",
+                "last_modified": response.get("LastModified", "").isoformat() if response.get("LastModified") else "",
                 "content_type": response.get("ContentType", ""),
                 "etag": response.get("ETag", ""),
                 "metadata": response.get("Metadata", {}),
@@ -328,9 +309,7 @@ class AwsS3App(BaseApplication):
         except ClientError as e:
             return {"error": str(e)}
 
-    def copy_object(
-        self, source_bucket: str, source_key: str, dest_bucket: str, dest_key: str
-    ) -> bool:
+    async def copy_object(self, source_bucket: str, source_key: str, dest_bucket: str, dest_key: str) -> 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.
 
@@ -347,16 +326,12 @@ class AwsS3App(BaseApplication):
         """
         try:
             copy_source = {"Bucket": source_bucket, "Key": source_key}
-            self.client.copy_object(
-                CopySource=copy_source, Bucket=dest_bucket, Key=dest_key
-            )
+            self.client.copy_object(CopySource=copy_source, Bucket=dest_bucket, Key=dest_key)
             return True
         except ClientError:
             return False
 
-    def move_object(
-        self, source_bucket: str, source_key: str, dest_bucket: str, dest_key: str
-    ) -> bool:
+    async def move_object(self, source_bucket: str, source_key: str, dest_bucket: str, dest_key: str) -> 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.
 
@@ -371,11 +346,11 @@ class AwsS3App(BaseApplication):
         Tags:
             important
         """
-        if self.copy_object(source_bucket, source_key, dest_bucket, dest_key):
+        if await self.copy_object(source_bucket, source_key, dest_bucket, dest_key):
             return self.delete_object(source_bucket, source_key)
         return False
 
-    def delete_single_object(self, bucket_name: str, key: str) -> bool:
+    async 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.
 
@@ -394,7 +369,7 @@ class AwsS3App(BaseApplication):
         except ClientError:
             return False
 
-    def delete_objects(self, bucket_name: str, keys: list[str]) -> dict[str, Any]:
+    async 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.
 
@@ -409,9 +384,8 @@ class AwsS3App(BaseApplication):
         """
         try:
             delete_dict = {"Objects": [{"Key": key} for key in keys]}
-            response = self.client.delete_objects(
-                Bucket=bucket_name, Delete=delete_dict
-            )
+            client = await self.get_client()
+            response = await client.delete_objects(Bucket=bucket_name, Delete=delete_dict)
             return {
                 "deleted": [obj.get("Key") for obj in response.get("Deleted", [])],
                 "errors": [obj for obj in response.get("Errors", [])],
@@ -419,13 +393,7 @@ class AwsS3App(BaseApplication):
         except ClientError as e:
             return {"error": str(e)}
 
-    def generate_presigned_url(
-        self,
-        bucket_name: str,
-        key: str,
-        expiration: int = 3600,
-        http_method: str = "GET",
-    ) -> str:
+    async def generate_presigned_url(self, bucket_name: str, key: str, expiration: int = 3600, http_method: str = "GET") -> 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.
 
@@ -441,28 +409,17 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            method_map = {
-                "GET": "get_object",
-                "PUT": "put_object",
-                "DELETE": "delete_object",
-            }
-
-            response = self.client.generate_presigned_url(
-                method_map.get(http_method.upper(), "get_object"),
-                Params={"Bucket": bucket_name, "Key": key},
-                ExpiresIn=expiration,
+            method_map = {"GET": "get_object", "PUT": "put_object", "DELETE": "delete_object"}
+            client = await self.get_client()
+            response = await client.generate_presigned_url(
+                method_map.get(http_method.upper(), "get_object"), Params={"Bucket": bucket_name, "Key": key}, ExpiresIn=expiration
             )
             return response
         except ClientError as e:
             return f"Error: {str(e)}"
 
-    def search_objects(
-        self,
-        bucket_name: str,
-        prefix: str = "",
-        name_pattern: str = "",
-        min_size: int | None = None,
-        max_size: int | None = None,
+    async def search_objects(
+        self, bucket_name: str, prefix: str = "", name_pattern: str = "", min_size: int | None = None, max_size: int | None = None
     ) -> 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.
@@ -479,25 +436,19 @@ class AwsS3App(BaseApplication):
         Tags:
             important
         """
-        all_objects = self.list_objects(bucket_name, prefix)
+        all_objects = await self.list_objects(bucket_name, prefix)
         filtered_objects = []
-
         for obj in all_objects:
-            # Filter by name pattern
             if name_pattern and name_pattern.lower() not in obj["name"].lower():
                 continue
-
-            # Filter by size
             if min_size and obj["size"] < min_size:
                 continue
             if max_size and obj["size"] > max_size:
                 continue
-
             filtered_objects.append(obj)
-
         return filtered_objects
 
-    def get_storage_summary(self, bucket_name: str, prefix: str = "") -> dict[str, Any]:
+    async 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').
 
@@ -510,11 +461,9 @@ class AwsS3App(BaseApplication):
         Tags:
             important
         """
-        objects = self.list_objects(bucket_name, prefix)
-        total_size = sum(obj["size"] for obj in objects)
+        objects = await self.list_objects(bucket_name, prefix)
+        total_size = sum((obj["size"] for obj in objects))
         object_count = len(objects)
-
-        # Convert to human-readable format
         for unit in ["B", "KB", "MB", "GB", "TB"]:
             if total_size < 1024.0:
                 human_size = f"{total_size:.2f} {unit}"
@@ -522,12 +471,7 @@ class AwsS3App(BaseApplication):
             total_size /= 1024.0
         else:
             human_size = f"{total_size:.2f} PB"
-
-        return {
-            "total_size_bytes": sum(obj["size"] for obj in objects),
-            "human_readable_size": human_size,
-            "object_count": object_count,
-        }
+        return {"total_size_bytes": sum((obj["size"] for obj in objects)), "human_readable_size": human_size, "object_count": object_count}
 
     def list_tools(self):
         return [