universal-mcp-applications 0.1.30rc1__py3-none-any.whl → 0.1.36rc1__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
@@ -36,10 +35,8 @@ class AwsS3App(BaseApplication):
         if not self._client:
             credentials = self.integration.get_credentials()
             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)
@@ -55,7 +52,7 @@ class AwsS3App(BaseApplication):
         response = self.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.
 
@@ -70,17 +67,14 @@ class AwsS3App(BaseApplication):
         """
         try:
             if region:
-                self.client.create_bucket(
-                    Bucket=bucket_name,
-                    CreateBucketConfiguration={"LocationConstraint": region},
-                )
+                self.client.create_bucket(Bucket=bucket_name, CreateBucketConfiguration={"LocationConstraint": region})
             else:
                 self.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.
 
@@ -98,7 +92,7 @@ class AwsS3App(BaseApplication):
         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.
 
@@ -116,7 +110,7 @@ class AwsS3App(BaseApplication):
         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.
 
@@ -135,9 +129,7 @@ class AwsS3App(BaseApplication):
         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.
 
@@ -157,16 +149,13 @@ class AwsS3App(BaseApplication):
             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.
 
@@ -187,7 +176,7 @@ class AwsS3App(BaseApplication):
         self.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.
 
@@ -218,9 +207,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 +223,10 @@ 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")
-        )
+        self.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.
 
@@ -266,7 +249,7 @@ class AwsS3App(BaseApplication):
         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.
 
@@ -282,24 +265,15 @@ class AwsS3App(BaseApplication):
         try:
             obj = self.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.
 
@@ -318,9 +292,7 @@ class AwsS3App(BaseApplication):
                 "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 +300,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 +317,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.
 
@@ -375,7 +341,7 @@ class AwsS3App(BaseApplication):
             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 +360,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 +375,7 @@ class AwsS3App(BaseApplication):
         """
         try:
             delete_dict = {"Objects": [{"Key": key} for key in keys]}
-            response = self.client.delete_objects(
-                Bucket=bucket_name, Delete=delete_dict
-            )
+            response = self.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 +383,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 +399,16 @@ class AwsS3App(BaseApplication):
             important
         """
         try:
-            method_map = {
-                "GET": "get_object",
-                "PUT": "put_object",
-                "DELETE": "delete_object",
-            }
-
+            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(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.
@@ -481,23 +427,17 @@ class AwsS3App(BaseApplication):
         """
         all_objects = 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').
 
@@ -511,10 +451,8 @@ class AwsS3App(BaseApplication):
             important
         """
         objects = self.list_objects(bucket_name, prefix)
-        total_size = sum(obj["size"] for obj in objects)
+        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 +460,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 [