objectstore-mcp 0.1.0__py3-none-any.whl

objectstore_mcp/__init__.py

@@ -0,0 +1,63 @@
+"""objectstore-mcp — multi-backend object-storage API + MCP Server + A2A Agent.
+
+One MCP tool surface (objects/buckets/transfer) over S3 and S3-compatible
+stores (MinIO, Cloudflare R2), Google Cloud Storage, Azure Blob Storage, and
+a zero-infra local-filesystem backend (CONCEPT:OBJ-1.0).
+"""
+
+import importlib
+import inspect
+from typing import Any
+
+__version__ = "0.1.0"
+__all__: list[str] = []
+
+CORE_MODULES = ["objectstore_mcp.api_client"]
+OPTIONAL_MODULES = {
+    "objectstore_mcp.agent_server": "agent",
+    "objectstore_mcp.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+_loaded_optional_modules: dict = {}
+
+
+def _import_module_safely(module_name: str):
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        return _import_module_safely(mcp_key) is not None if mcp_key else False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        return _import_module_safely(agent_key) is not None if agent_key else False
+
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            _loaded_optional_modules[module_name] = module
+            if module is not None:
+                _expose_members(module)
+        module = _loaded_optional_modules[module_name]
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+    raise AttributeError(f"module 'objectstore_mcp' has no attribute {name!r}")

objectstore_mcp/__main__.py

@@ -0,0 +1,4 @@
+from objectstore_mcp.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

objectstore_mcp/agent_server.py

@@ -0,0 +1,73 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.1.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    initialize_workspace()
+    meta = load_identity()
+    agent_name = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "Objectstore Mcp"))
+
+    print(f"{agent_name} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        agent_description=os.getenv(
+            "AGENT_DESCRIPTION",
+            meta.get("description", "Objectstore Mcp API + MCP Server + A2A Server"),
+        ),
+        system_prompt=os.getenv(
+            "AGENT_SYSTEM_PROMPT",
+            meta.get("content") or build_system_prompt_from_workspace(),
+        ),
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

objectstore_mcp/api/__init__.py

@@ -0,0 +1,84 @@
+"""Backend factory: map a store's ``backend`` string to an implementation.
+
+Imports are lazy so the core install carries zero cloud dependencies
+(CONCEPT:OBJ-1.5); a missing SDK surfaces as :class:`MissingDependencyError`
+naming the pip extra to install.
+"""
+
+import os
+
+from objectstore_mcp.api.api_client_base import (
+    AlreadyExistsError,
+    BucketInfo,
+    BucketNotEmptyError,
+    InvalidNameError,
+    Metadata,
+    MissingDependencyError,
+    NotFoundError,
+    ObjectInfo,
+    ObjectPage,
+    ObjectStoreBackend,
+    ObjectStoreError,
+    UnsupportedOperationError,
+)
+from objectstore_mcp.config import DEFAULT_FS_ROOT, StoreConfig
+
+__all__ = [
+    "AlreadyExistsError",
+    "BucketInfo",
+    "BucketNotEmptyError",
+    "InvalidNameError",
+    "Metadata",
+    "MissingDependencyError",
+    "NotFoundError",
+    "ObjectInfo",
+    "ObjectPage",
+    "ObjectStoreBackend",
+    "ObjectStoreError",
+    "UnsupportedOperationError",
+    "create_backend",
+    "BACKEND_ALIASES",
+]
+
+BACKEND_ALIASES = {
+    "filesystem": "filesystem",
+    "fs": "filesystem",
+    "local": "filesystem",
+    "s3": "s3",
+    "minio": "s3",
+    "r2": "s3",
+    "gcs": "gcs",
+    "gcp": "gcs",
+    "google": "gcs",
+    "azure": "azure",
+    "azure_blob": "azure",
+    "abs": "azure",
+}
+
+
+def create_backend(store: StoreConfig) -> ObjectStoreBackend:
+    """Instantiate the backend a :class:`StoreConfig` names."""
+    kind = BACKEND_ALIASES.get(store.backend)
+    if kind == "filesystem":
+        from objectstore_mcp.api.api_client_filesystem import FilesystemBackend
+
+        root = store.root or os.getenv("OBJECTSTORE_FS_ROOT") or DEFAULT_FS_ROOT
+        return FilesystemBackend(root=root)
+    if kind == "s3":
+        from objectstore_mcp.api.api_client_s3 import S3Backend
+
+        return S3Backend(
+            endpoint=store.endpoint, profile=store.profile, region=store.region
+        )
+    if kind == "gcs":
+        from objectstore_mcp.api.api_client_gcs import GCSBackend
+
+        return GCSBackend(project=store.project)
+    if kind == "azure":
+        from objectstore_mcp.api.api_client_azure_blob import AzureBlobBackend
+
+        return AzureBlobBackend(connection_string=store.connection_string)
+    raise ObjectStoreError(
+        f"Unknown backend {store.backend!r} for store {store.name!r}. "
+        f"Valid backends: {sorted(set(BACKEND_ALIASES))}."
+    )

objectstore_mcp/api/api_client_azure_blob.py

@@ -0,0 +1,308 @@
+"""Azure Blob Storage backend (CONCEPT:OBJ-1.5).
+
+Containers map to buckets. Credentials come from
+``AZURE_STORAGE_CONNECTION_STRING`` (or an explicit ``connection_string``
+store option). Presigned URLs are SAS URLs and require an account key in the
+connection string.
+
+Requires the ``azure`` extra: ``pip install objectstore-mcp[azure]``.
+"""
+
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from objectstore_mcp.api.api_client_base import (
+    AlreadyExistsError,
+    BucketInfo,
+    BucketNotEmptyError,
+    Metadata,
+    MissingDependencyError,
+    NotFoundError,
+    ObjectInfo,
+    ObjectPage,
+    ObjectStoreError,
+    validate_bucket_name,
+    validate_key,
+)
+
+
+def _build_client(connection_string: str | None) -> Any:
+    try:
+        from azure.storage.blob import BlobServiceClient
+    except ImportError as exc:  # pragma: no cover - exercised via mocked import
+        raise MissingDependencyError(
+            "The Azure backend requires azure-storage-blob. Install it with "
+            "`pip install objectstore-mcp[azure]`."
+        ) from exc
+    conn = connection_string or os.getenv("AZURE_STORAGE_CONNECTION_STRING")
+    if not conn:
+        raise ObjectStoreError(
+            "Azure backend needs AZURE_STORAGE_CONNECTION_STRING (or a "
+            "'connection_string' store option)."
+        )
+    return BlobServiceClient.from_connection_string(conn)
+
+
+def _is_not_found(exc: Exception) -> bool:
+    return (
+        getattr(exc, "status_code", None) == 404
+        or exc.__class__.__name__ == "ResourceNotFoundError"
+    )
+
+
+def _is_conflict(exc: Exception) -> bool:
+    return (
+        getattr(exc, "status_code", None) == 409
+        or exc.__class__.__name__ == "ResourceExistsError"
+    )
+
+
+class AzureBlobBackend:
+    """Azure Blob Storage object-store backend (containers as buckets)."""
+
+    backend_type = "azure"
+
+    def __init__(self, connection_string: str | None = None, client: Any | None = None):
+        """``client`` injects a pre-built BlobServiceClient (used by tests)."""
+        self.client = client if client is not None else _build_client(connection_string)
+
+    def capabilities(self) -> dict[str, bool]:
+        return {
+            "presigned_urls": True,
+            "object_metadata": True,
+            "bucket_location": False,
+        }
+
+    def _translate(self, exc: Exception, context: str) -> ObjectStoreError:
+        if _is_not_found(exc):
+            return NotFoundError(f"{context} not found.")
+        if _is_conflict(exc):
+            return AlreadyExistsError(f"{context} already exists.")
+        return ObjectStoreError(f"{context}: {exc}")
+
+    # -- buckets -------------------------------------------------------------
+    def list_buckets(self) -> list[BucketInfo]:
+        try:
+            containers = list(self.client.list_containers())
+        except Exception as exc:
+            raise self._translate(exc, "Container listing") from exc
+        results = []
+        for container in containers:
+            modified = getattr(container, "last_modified", None)
+            results.append(
+                BucketInfo(
+                    name=container.name,
+                    created=modified.isoformat() if modified else None,
+                )
+            )
+        return results
+
+    def create_bucket(self, bucket: str, location: str | None = None) -> BucketInfo:
+        validate_bucket_name(bucket)
+        try:
+            self.client.create_container(bucket)
+        except Exception as exc:
+            raise self._translate(exc, f"Container {bucket!r}") from exc
+        return BucketInfo(name=bucket)
+
+    def delete_bucket(self, bucket: str) -> None:
+        container = self.client.get_container_client(bucket)
+        try:
+            # Azure deletes non-empty containers; enforce empty-only parity.
+            if next(iter(container.list_blobs()), None) is not None:
+                raise BucketNotEmptyError(f"Container {bucket!r} is not empty.")
+            container.delete_container()
+        except BucketNotEmptyError:
+            raise
+        except Exception as exc:
+            raise self._translate(exc, f"Container {bucket!r}") from exc
+
+    def bucket_exists(self, bucket: str) -> bool:
+        try:
+            return bool(self.client.get_container_client(bucket).exists())
+        except Exception as exc:
+            raise self._translate(exc, f"Container {bucket!r}") from exc
+
+    def bucket_info(self, bucket: str) -> BucketInfo:
+        container = self.client.get_container_client(bucket)
+        try:
+            props = container.get_container_properties()
+        except Exception as exc:
+            raise self._translate(exc, f"Container {bucket!r}") from exc
+        modified = getattr(props, "last_modified", None)
+        return BucketInfo(
+            name=bucket, created=modified.isoformat() if modified else None
+        )
+
+    # -- objects ---------------------------------------------------------------
+    def list_objects(
+        self,
+        bucket: str,
+        prefix: str = "",
+        delimiter: str | None = None,
+        max_keys: int = 1000,
+        continuation_token: str | None = None,
+    ) -> ObjectPage:
+        container = self.client.get_container_client(bucket)
+        try:
+            if delimiter:
+                iterator = container.walk_blobs(
+                    name_starts_with=prefix or None,
+                    delimiter=delimiter,
+                    results_per_page=max_keys,
+                )
+            else:
+                iterator = container.list_blobs(
+                    name_starts_with=prefix or None, results_per_page=max_keys
+                )
+            pager = iterator.by_page(continuation_token=continuation_token)
+            entries = list(next(pager, []))
+        except Exception as exc:
+            raise self._translate(exc, f"Container {bucket!r}") from exc
+        next_token = getattr(pager, "continuation_token", None) or None
+        page = ObjectPage(next_token=next_token, truncated=bool(next_token))
+        for entry in entries:
+            # walk_blobs yields BlobPrefix markers for folded prefixes.
+            if entry.__class__.__name__ == "BlobPrefix" or not hasattr(entry, "size"):
+                page.prefixes.append(entry.name)
+            else:
+                page.objects.append(self._blob_info(entry))
+        page.prefixes.sort()
+        return page
+
+    @staticmethod
+    def _blob_info(blob: Any) -> ObjectInfo:
+        modified = getattr(blob, "last_modified", None)
+        settings = getattr(blob, "content_settings", None)
+        return ObjectInfo(
+            key=blob.name,
+            size=getattr(blob, "size", 0) or 0,
+            etag=(getattr(blob, "etag", None) or "").strip('"') or None,
+            last_modified=modified.isoformat() if modified else None,
+            content_type=getattr(settings, "content_type", None),
+            metadata=dict(getattr(blob, "metadata", None) or {}),
+            storage_class=getattr(blob, "blob_tier", None),
+        )
+
+    def _blob_client(self, bucket: str, key: str) -> Any:
+        return self.client.get_blob_client(container=bucket, blob=key)
+
+    def _get_properties(self, bucket: str, key: str) -> Any:
+        try:
+            return self._blob_client(bucket, key).get_blob_properties()
+        except Exception as exc:
+            raise self._translate(exc, f"Blob {bucket!r}/{key!r}") from exc
+
+    def head_object(self, bucket: str, key: str) -> ObjectInfo:
+        props = self._get_properties(bucket, key)
+        info = self._blob_info(props)
+        info.key = key
+        return info
+
+    def get_object(self, bucket: str, key: str, max_bytes: int | None = None) -> bytes:
+        info = self.head_object(bucket, key)
+        if max_bytes is not None and info.size > max_bytes:
+            raise ObjectStoreError(
+                f"Blob {bucket!r}/{key!r} is {info.size} bytes, over the "
+                f"{max_bytes}-byte read cap."
+            )
+        try:
+            return self._blob_client(bucket, key).download_blob().readall()
+        except Exception as exc:
+            raise self._translate(exc, f"Blob {bucket!r}/{key!r}") from exc
+
+    def put_object(
+        self,
+        bucket: str,
+        key: str,
+        data: bytes,
+        content_type: str | None = None,
+        metadata: Metadata | None = None,
+    ) -> ObjectInfo:
+        validate_key(key)
+        kwargs: dict[str, Any] = {"overwrite": True}
+        if metadata:
+            kwargs["metadata"] = dict(metadata)
+        if content_type:
+            try:
+                from azure.storage.blob import ContentSettings
+
+                kwargs["content_settings"] = ContentSettings(content_type=content_type)
+            except ImportError:
+                # Injected-client mode (tests) without the SDK installed:
+                # pass the raw content type through.
+                kwargs["content_type"] = content_type
+        try:
+            self._blob_client(bucket, key).upload_blob(data, **kwargs)
+        except Exception as exc:
+            raise self._translate(exc, f"Blob {bucket!r}/{key!r}") from exc
+        return ObjectInfo(
+            key=key,
+            size=len(data),
+            content_type=content_type,
+            metadata=dict(metadata or {}),
+        )
+
+    def copy_object(
+        self, src_bucket: str, src_key: str, dst_bucket: str, dst_key: str
+    ) -> ObjectInfo:
+        validate_key(dst_key)
+        source_url = self._blob_client(src_bucket, src_key).url
+        try:
+            self._blob_client(dst_bucket, dst_key).start_copy_from_url(source_url)
+        except Exception as exc:
+            raise self._translate(
+                exc, f"Copy {src_bucket!r}/{src_key!r} -> {dst_bucket!r}/{dst_key!r}"
+            ) from exc
+        return self.head_object(dst_bucket, dst_key)
+
+    def delete_object(self, bucket: str, key: str) -> None:
+        try:
+            self._blob_client(bucket, key).delete_blob()
+        except Exception as exc:
+            raise self._translate(exc, f"Blob {bucket!r}/{key!r}") from exc
+
+    def get_object_metadata(self, bucket: str, key: str) -> dict[str, str]:
+        return self.head_object(bucket, key).metadata
+
+    def set_object_metadata(
+        self, bucket: str, key: str, metadata: Metadata
+    ) -> ObjectInfo:
+        try:
+            self._blob_client(bucket, key).set_blob_metadata(dict(metadata or {}))
+        except Exception as exc:
+            raise self._translate(exc, f"Blob {bucket!r}/{key!r}") from exc
+        return self.head_object(bucket, key)
+
+    def presigned_url(
+        self, bucket: str, key: str, method: str = "GET", expires_in: int = 3600
+    ) -> str:
+        if method.upper() not in ("GET", "PUT"):
+            raise ObjectStoreError(
+                f"Presign method must be GET or PUT (got {method!r})."
+            )
+        try:
+            from azure.storage.blob import BlobSasPermissions, generate_blob_sas
+        except ImportError as exc:
+            raise MissingDependencyError(
+                "SAS generation requires azure-storage-blob. Install it with "
+                "`pip install objectstore-mcp[azure]`."
+            ) from exc
+        account_key = getattr(self.client.credential, "account_key", None)
+        if not account_key:
+            raise ObjectStoreError(
+                "SAS URLs require an account key in the connection string."
+            )
+        permission = BlobSasPermissions(
+            read=method.upper() == "GET", write=method.upper() == "PUT"
+        )
+        sas = generate_blob_sas(
+            account_name=self.client.account_name,
+            container_name=bucket,
+            blob_name=key,
+            account_key=account_key,
+            permission=permission,
+            expiry=datetime.now(timezone.utc) + timedelta(seconds=expires_in),
+        )
+        return f"{self._blob_client(bucket, key).url}?{sas}"