download_asset
Download one asset of an item to local disk, gated by a size check.
SAR products can be multiple GB, so this is a two-step handshake: call it
first with ``confirm=False`` (the default) to get the byte size without
downloading, then again with ``confirm=True`` to actually fetch. Returns
``{asset, path, bytes}`` on download, or a size-and-hint object when
confirmation is still required.
On a public host (``umbra serve --public``, COG streaming off),
``confirm=True`` is refused. The error includes the asset href and its
size in bytes and tells you to download the file locally (or run a local
``uvx --from 'umbra-py[mcp]' umbra-mcp`` server for ``download_asset``).
``confirm=False`` still returns the size.
``url`` is a STAC JSON URL, or a product filename
(``2025-05-17-17-43-46_UMBRA-08_GEC.tif``) or acquisition stem
(``2025-05-17-17-43-46_UMBRA-08``). A filename or stem is resolved through
the catalog index the same way as ``get_item``. The hosted server already
has that index. A local server needs ``umbra index fetch``.
``asset`` selects the file. All of these work:
- a product type, any case: ``GEC``, ``gec``, ``SICD``
- a schema v2 key, including a collision suffix: ``gec``, ``gec_2``,
``csi``, ``sidd``, ``csi_sidd``, ``sicd``, ``cphd``, ``metadata``,
``stac_metadata``, ``di_gif``, ``file``, ``file_tif``
- the original filename (the asset's ``umbra-py:filename``)
``GEC`` and ``gec`` are the primary file. ``gec_2`` is the second GEC,
not the primary. A name that matches nothing raises with the item's v2
keys listed (``gec, sicd, cphd``, …), not the uppercase product types.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| asset | No | GEC | |
| confirm | No | ||
| dest_dir | No | . |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||