Ovstorage User Read Bytes

Read Bytes Safely

Goal: Load an object's contents into memory with a bounded size.

When to use this: You need the bytes of one object — to parse it, inspect it, hash it, or hand it to another tool. The object fits in memory.

For larger objects (multi-GB, or unknown size), use ovstorage-user-materialize to get a stable on-disk path instead — that lets you stream / mmap without buffering everything.

Recipe

max_bytes is required. Pick a cap large enough for the work but small enough to fail fast on accidental giants.

{
  "tool": "ovstorage_read",
  "arguments": {
    "address": "s3://my-bucket/data/report.json",
    "max_bytes": 1048576
  }
}

What success looks like

{
  "v": "0.1",
  "ok": true,
  "operation": "ovstorage_read",
  "result": {
    "data_base64": "ewogICJyZW...",
    "info": {
      "address": "s3://my-bucket/data/report.json",
      "size": 4231,
      "etag": "\"abc123\"",
      "version": null,
      "mtime_unix_nanos": 1718000000000000000
    }
  }
}

data_base64 is the object's bytes, base64-encoded (MCP results are JSON-shaped; binary data must be encoded). Decode in whatever language you're using.

Optional parameters

• if_match — precondition. Pass the bare etag string (e.g. "abc123") from a prior stat to atomically verify the object hasn't changed. Mismatch surfaces as ObjectModified.
• range_start + range_end — byte-range read (both inclusive). Useful when you only need a slice (e.g., the header of a large file).

When things go wrong

See also

• ovstorage-user-list-and-paginate — find the address first
• ovstorage-user-materialize — for large or unknown-size objects
• ovstorage-user-handle-errors — full envelope error shape