Skip to content

Architecture

flowchart LR
    subgraph client["MCP Client / Agent"]
        A["typed tool call: arguments + optional store"]
    end

    subgraph server["objectstore-mcp (FastMCP)"]
        T1[objects]
        T2[buckets]
        T3[transfer]
        SG["Safety governor<br/>caps + delete flags + dry-run"]
        REG["Store registry<br/>OBJECTSTORE_STORES"]
    end

    subgraph backends["ObjectStoreBackend protocol"]
        FS[FilesystemBackend]
        S3["S3Backend<br/>AWS / MinIO / R2"]
        GCS[GCSBackend]
        AZ[AzureBlobBackend]
    end

    A --> T1
    A --> T2
    A --> T3
    T1 --> SG
    T2 --> SG
    T3 --> SG
    SG --> REG
    REG --> FS
    REG --> S3
    REG --> GCS
    REG --> AZ

Layers

Layer Module Responsibility
Tool surface objectstore_mcp/mcp/mcp_objectstore.py Typed composite, transfer, S3-management and ingest tools (CONCEPT:OB-OS.governance.obj-2); caps and delete guards live in objectstore_mcp/guard.py
Store registry objectstore_mcp/config.py, objectstore_mcp/auth.py OBJECTSTORE_STORES parsing, default-store resolution, per-store backend cache (CONCEPT:OB-OS.config.obj)
Backend protocol and backends scion_sdk.storage (scion-sdk) The provider-neutral contract, error taxonomy, store registry and the filesystem, S3-compatible, GCS, Azure and WebDAV backends; this connector ships no copy

Design decisions

  • Backends are bucket-agnostic. The bucket is a per-call argument; per-store default buckets are a tool-layer convenience. This keeps each backend a thin adapter and lets one store config span multiple buckets.
  • Safety lives in the tool layer, not the backends. Backends accept a max_bytes hint for cheap pre-flight size checks, but every cap, flag, and dry-run decision is made once, uniformly, in mcp_objectstore.py. No backend can accidentally weaken policy.
  • Errors are translated, never leaked. Provider SDK exceptions become the shared taxonomy (NotFoundError, AlreadyExistsError, BucketNotEmptyError, UnsupportedOperationError, MissingDependencyError), so the tool layer and tests treat all providers identically.
  • The filesystem backend is a first-class provider, not a mock. It implements the full protocol (including metadata via .meta/ sidecars and delimiter-folded pagination), which is what makes the conformance suite real coverage rather than mock theater.
  • Conformance lives with the backends. The protocol conformance suite and the per-backend tests live in scion-sdk; tests/test_sdk_backends.py here proves every store routes through the SDK.