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 fetch it. On a
local or stdio server, ``confirm=True`` returns ``{asset, path, bytes}``.
``confirm=False`` returns a size-and-hint object and does not write a file.
On a public host (``umbra serve --public``, COG streaming off),
``confirm=True`` does not transfer the file. It returns a link plan:
``mode`` ``"link"``, ``downloaded`` false, ``asset``, ``filename`` (a
basename), the direct public ``href``, ``bytes``, and ``how_to_fetch``.
When the href is https on the public open-data bucket, ``how_to_fetch``
is ``curl -L -C - -o <filename> <href>`` and
``umbra download ITEM --asset ASSET --dest DIR``. ``bytes`` is the STAC
``file:size`` or ``size`` when that is a non-negative integer; otherwise
the host HEADs that href for ``Content-Length``, with no redirects and
no retries. A href that is not on that bucket is not requested:
``how_to_fetch.curl`` and ``how_to_fetch.umbra`` are null, ``bytes`` is
null, and ``note`` says the commands were omitted. A 404 or 410 from
an allowlisted HEAD raises. Any other HEAD failure, including a full
quick-request slot, leaves ``bytes`` null and still returns the plan.
The hosted server never transfers the file. A local
``uvx --from 'umbra-py[mcp]' umbra-mcp`` server downloads to your own
disk. ``confirm=False`` on this host returns the same size-and-hint
object and does not write a file. It HEADs for ``Content-Length`` only
when the href is https on the public open-data bucket, with no retries,
and it does not follow redirects. A 404 or 410 raises, and so does any
other non-redirect HEAD error. A redirect leaves ``bytes`` null. A href
outside the bucket is not requested; ``bytes`` is the STAC ``file:size``
or ``size`` when that is a non-negative integer, otherwise null. A local
server still HEADs the href and follows redirects.
On a local server, ``dest_dir`` is unchanged unless ``UMBRA_MCP_DOWNLOAD_ROOT``
is set. When that variable is set, ``dest_dir`` must resolve inside it.
The argument itself is unchanged.
``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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "download_asset"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | STAC JSON URL, product filename, or acquisition stem. A filename or stem is resolved through the catalog index. | |
| asset | No | File to fetch: a product type (GEC), a schema v2 key (gec, gec_2), or the original filename. Default GEC. | GEC |
| confirm | No | False (default) returns the byte size and writes nothing. True downloads on a local server, or returns a link plan on the public host. | |
| dest_dir | No | Local download directory. Default '.'. Must stay inside UMBRA_MCP_DOWNLOAD_ROOT when that is set. On the public host it is only named in the link plan. | . |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||