Umbra open SAR archive
Server Details
Search, preview, and measure Umbra open SAR from any MCP client. Umbra ships no search API.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- Repository
- reesehammer/umbra-py
- GitHub Stars
- 0
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 19 tools
Each tool has a distinct purpose, but the surface contains several adjacent families: search_catalog / find_repeat_sites / watch_site / find_similar / find_similar_text, and change_composite / timescan / stack_stats / narrate_change / pick_change_interval. The verbose descriptions explicitly disambiguate these, so misselection is unlikely, but an agent must read carefully to choose correctly.
All names are snake_case and most follow a verb_noun pattern (describe_scene, search_catalog, download_asset). A few noun_noun names (index_stats, stack_stats, stack_provenance) and single-word names (quicklook, timescan) are minor deviations but remain predictable.
Nineteen tools is heavy but defensible for a SAR archive spanning search, retrieval, download, visualization, change analysis, provenance, monitoring, and validation. No tools look like duplicates, though several niche utilities push the set above the ideal 3-15 range.
The set covers a full analyst loop: search, item resolution, asset download, quicklooks, scene description, change measurement, interval selection, narration, monitoring deltas, and provenance stamping. Minor gaps exist, such as no direct full STAC JSON export and no broad task/site listing beyond repeated-site search, but agents can work around them.
Available Tools
19 toolschange_compositeARead-onlyInspect
Composite 2-3 passes of one site into a change image.
Pass the STAC URLs of two or three acquisitions of the *same* site in time
order. Colors encode change: bright green = signal appeared after the first
date, magenta = signal vanished, grey = unchanged. Refuses to mix
polarizations (HH vs VV are not comparable). Returns the image block plus a
caption naming the color semantics and attribution -- and, when a pass carries
no polarization metadata so same-polarization could not be *verified*, a
structured caution text block naming that gap.
Inputs: urls (required), db, asset, max_size.
describe_sceneARead-onlyInspect
Return a SAR-literate reading of the scene at url.
The picture and the metadata card are produced deterministically; a model
only interprets them. How that model is reached depends on whether this
process holds a vision key:
- **No key** (the public community host): this tool does **not** call a
vision model. It returns the PNG plus a reading kit (SAR rules, the
metadata card, the JSON schema). Produce the JSON, then call
:func:`stamp_description` — that is the validation boundary
(provenance-stamped ``{summary, observed_features, confidence,
caveats}``). Until you stamp it, your prose is not pipeline output.
A baked preview is typically 512 px; the kit names the size and
that a local server can stream a higher-resolution GeoTIFF.
- **Key configured** (local stdio): sends the picture to that vision
model, validates through ``parse_description``, and returns the
stamped object directly.
The packaged SAR rules are the value over just looking at ``quicklook``:
brightness is backscatter not sunlight, speckle is not structure, a dark
patch may be radar shadow not water, one frame is not change.
``preview`` defaults to ``"auto"``: a baked catalog preview if this server
has one, else a fresh render. ``"render"`` is refused on the public host.
Inputs: url (required), db, asset, model, +2 more.
download_assetADestructiveInspect
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.
Inputs: url (required), asset, confirm, dest_dir. Returns: object
find_repeat_sitesARead-onlyInspect
Rank sites imaged more than once, before a change tool is pointed at one.
Use this when the site is not already known. Each site's ``hrefs`` are that
site's STAC URLs, oldest first, ready for ``pick_change_interval``,
``change_composite``, or ``stack_stats``. Prefer this, or
``search_catalog(area=..., fuzzy=True)``, over ``semantic=True`` when the
name shares words with a task. No model is called.
Argument reference (ranking, recency, cadence, baseline, return fields):
https://umbra-py.space/find-repeat-sites/
Filters bound which acquisitions are ranked. ``bbox`` is WGS84
``[min_lon, min_lat, max_lon, max_lat]``. ``intersects`` is one GeoJSON
Point, or a Polygon or MultiPolygon (or a Feature, FeatureCollection, or
GeometryCollection wrapping those). A point matches footprints that
contain it. It cannot be combined with ``bbox`` or ``place``. ``place`` is geocoded
only when ``bbox`` is omitted. ``area`` is a task-name substring;
``fuzzy=True`` is a deterministic loose match. When ``area`` matches no
task and ``bbox``, ``intersects``, and ``place`` are omitted, it is
geocoded. The result then adds ``matched_by`` (``geocode``) plus the
resolved place and bbox. A name Nominatim does not know, and a geocoder
that is busy or unreachable, set ``hint`` and return no sites
(``resolved_area`` is the ``area`` that was tried). A task-name hit adds
nothing. ``start`` / ``end`` bound
which passes enter the pool (ISO date, bare year or month, or a relative
expression). ``products`` is any of GEC, CSI, SIDD, SICD, CPHD.
``polarizations``, ``min_incidence``, ``max_incidence``, and
``max_resolution`` (metres) drop passes missing that field.
``top`` (default 20) is how many sites to return. ``min_passes`` (default
2) is the minimum depth: comparable passes when ``rank_by`` is
``comparable``, otherwise raw dated passes. ``rank_by`` is ``passes``
(default), ``comparable`` (largest same-polarization subset), ``recency``
(newest pass), ``span`` (first to last), or ``cadence`` (tightest median
gap). For the three temporal orders, ``min_passes`` still counts raw
passes.
``active_since`` / ``active_before`` select sites by newest pass;
``first_since`` / ``first_before`` select by earliest pass. Those keep
each survivor's full history, unlike ``start`` / ``end``, which truncate
the pool. ``max_revisit_days`` caps the worst gap and
``median_revisit_days`` caps the median gap. ``min_span_days`` /
``max_span_days`` bound the first-to-last span. A non-positive cadence or
span raises ``ValueError``. With ``rank_by="comparable"`` the cadence and
span filters use that subset. A bare year or month on a ``*_before``
bound includes the whole period.
``limit`` (default 500) sizes only a live or Canopy pool. A local index
ranks each task over the whole index and ignores ``limit``. ``local``
matches ``search_catalog``: unset uses the index when present. A Canopy
token (``$UMBRA_CANOPY_TOKEN``) draws the pool from the commercial
archive, and ``local=True`` cannot be combined with it.
Inputs: end, top, area, bbox, +21 more. Returns: object
find_similarARead-onlyInspect
Find archived scenes that look like the acquisition at url.
This is the one search that lives in the pixels, not the metadata: where
``search_catalog`` filters by date/bbox/task-name, this renders the query
item's quicklook, embeds it, and ranks the pre-embedded scene index by visual
(cosine) similarity — "find scenes that look like this flooded field / crowded
berth / runway". The query item is excluded from its own results.
Requires a scene-embedding index built ahead of time with ``umbra embed
build`` (a sidecar ``catalog.embed.db`` beside the catalog index) and a
user-supplied multimodal embedding key (``OPENAI_API_KEY``, optionally
``OPENAI_BASE_URL`` / ``UMBRA_SCENE_EMBED_MODEL``) — the only model call is
turning the query image into a vector; ranking is deterministic. ``asset``
picks which product's quicklook to embed (default ``GEC``; match how the index
was built); ``model`` must match the index's embedding model. Returns the
ranked matches as compact records (each with the acquisition's ``href``, so
hand it to ``get_item`` / ``quicklook`` / ``change_composite`` next) plus the
attribution line.
Inputs: url (required), asset, model, top_k, +1 more. Returns: object
find_similar_textARead-onlyInspect
Find archived scenes matching a plain-language query over their imagery.
Text-to-scene search: embeds ``query`` ("ships at a berth", "a flooded field")
and ranks the stored *image* vectors by cosine similarity. It only works when
the index was built and this query is embedded with the **same** joint
CLIP-family model whose text and image encoders share a vector space (a
dimension mismatch is reported as an error; ``model`` selects it).
Requires the same prebuilt ``catalog.embed.db`` (``umbra embed build``) and
embedding key as ``find_similar``; the only model call is turning the text
query into a vector. Returns the ranked matches as compact records (each with
the acquisition's ``href`` for ``get_item`` / ``quicklook``) plus attribution.
Inputs: query (required), model, top_k, min_score. Returns: object
geocode_placeARead-onlyInspect
Resolve a free-text place name to a bounding box via Nominatim.
Returns ``{"bbox": [min_lon, min_lat, max_lon, max_lat], "display_name":
...}`` so the agent can inspect the box before searching, or pass it
straight to ``search_catalog``'s ``bbox``.
Inputs: query (required). Returns: object
get_itemARead-onlyInspect
Return the full context card for one item.
``url`` is the JSON URL of an open-data STAC sidecar, a GEC/SICD (or other
product) filename such as ``2025-05-17-17-43-46_UMBRA-08_GEC.tif``, or the
acquisition stem ``2025-05-17-17-43-46_UMBRA-08``. A filename or stem is
resolved through the local catalog index: the stem is matched against
asset hrefs, which is what distinguishes ``sar-data/tasks/``,
``sar-data/task-data/``, and ``open-data/`` — the name itself does not.
Zero matches is an error. More than one match lists the candidate STAC
URLs; pass one of those. The hosted server resolves a filename or stem
with the catalog index it already loaded. A local server does the same
after ``umbra index fetch``.
When the index contains a STAC URL, the indexed snapshot is returned —
the same document ``search_catalog`` already answered from — rather than
a live re-fetch that can disagree on asset filenames or product types.
When the server is configured with a token (``$UMBRA_CANOPY_TOKEN``) and
``url`` is a bare acquisition id (no ``://``, and not a filename or stem),
it is instead looked up in Umbra's authenticated commercial archive by a
keyed STAC search — the retrieval complement to ``search_catalog`` over
the paid catalog, since archive cards carry an ``id`` (not a fetchable
sidecar URL) as their hand-off pointer. A filename or stem still resolves
from the local open-data index when a token is set.
On the public host a URL is fetched only when it is https on Umbra's
public open-data bucket. Any other URL is refused before a request.
A bare id that is not in the local index is refused the same way.
The card (:meth:`UmbraItem.to_llm_context`) carries the id, ISO datetime,
place, bbox, resolution, polarization *with the change-detection caveat*,
the per-product-type explanations and asset URLs, and the mandatory
attribution line — everything a model needs to reason about the scene.
Inputs: url (required). Returns: object
index_statsARead-onlyInspect
Report on the local catalog index, if one has been built or fetched.
Lets a long-running agent decide whether searches will be instant (index
present) or pay a live S3 walk, and how stale the snapshot is. ``end`` is
the newest acquisition that is not ``datetime_suspect``.
``datetime_suspect_count`` is how many kept rows carry that flag.
``quarantined_future_count`` is how many source rows the last build
dropped for a datetime more than a day ahead (they are not in the index).
``unique_captures`` is how many rows are the canonical copy of their
collect; it equals ``items`` until republished copies have been linked.
``path`` is the index file locally and ``null`` on the public host, which
does not reveal the server filesystem.
Inputs: no named parameters. Returns: object
narrate_changeARead-onlyInspect
Return a grounded reading of what changed between passes.
Sibling of :func:`describe_scene`. The composite and the per-block dB grid
are produced deterministically; a model only narrates change those numbers
support. Pass the STAC URLs in time order; mixed polarizations are refused.
This tool **streams Umbra COGs** to build the composite, so a public
community host refuses it (use a local ``uvx --from 'umbra-py[mcp]'
umbra-mcp`` server, or describe each pass with :func:`describe_scene` /
:func:`quicklook` on baked previews). On a local server:
- **No vision key:** returns the composite as an MCP image block plus a
reading kit (SAR change primer, the dB grid, the JSON schema). **You**
(the client's model) narrate, grounded in the numbers.
- **Key configured:** sends picture + grid to that vision model, validates
through ``parse_narration``, and returns a provenance-stamped
``{summary, changes[], confidence, caveats[], change_stats}`` object.
Inputs: urls (required), db, asset, model, +1 more.
pick_change_intervalARead-onlyInspect
Scan a site's whole series and name the two passes worth narrating.
The deterministic first half of the "watch a site over time" story, and the
step that turns a wall of passes into an answer. Given the STAC URLs of a
site's passes (2 or more, any order), it co-registers them into a
``to_stack`` cube, reduces it with ``stack_stats``, and returns the *one*
consecutive pass-pair whose measured change stands **furthest clear of the
speckle detection floor** — the pair a reader should look at first. No model
is called: a number picks the frames (the determinism boundary applied to
frame selection), so the choice is reproducible and safe
to quote.
Why this exists as its own tool: ``narrate_change`` reads a *pair* of passes,
but a site has many, and "which two?" is a measurement question, not a model
one — a picture past three dates encodes nothing a model can separate, so the
pair has to be chosen before the model is called. This answers it. The
returned ``urls`` are the two chosen passes in time order, ready to hand
straight to ``narrate_change`` (or ``change_composite`` to see them): the
two tools chain into scan → narrate with no server and no model in the
selection.
Returns ``selected_interval`` (the interval's ``earlier_id`` / ``later_id``,
their datetimes, the ``changed_fraction`` and signed ``mean_delta_db``, the
cube's ``false_alarm_fraction`` speckle floor, the ``excess`` of the change
over that floor, and ``stands_clear`` — whether the change cleared the floor
by a usable margin), ``urls`` (the earlier then the later pass's STAC URL),
and the license/attribution. When ``stands_clear`` is false the series' own
largest change is still inside the speckle, so the pair is offered but the
reader is warned the difference may be interference rather than change.
``selected_interval`` is ``None`` (and ``urls`` empty) when the series has
fewer than two comparable passes or no interval reported any change — there
is no pair to narrate. ``crs="utm"`` (the default) grids the cube in the
site's UTM zone so the change fractions weigh equal ground; ``max_size`` and
``change_threshold_db`` match ``stack_stats``. Refuses to mix polarizations
(HH vs VV are not comparable). Requires the ``load`` extra.
Inputs: urls (required), crs, asset, extent, +2 more. Returns: object
quicklookARead-onlyInspect
Return a scene's quicklook PNG as an image block.
Prefers a baked catalog preview (``preview="auto"``, the default) so a
public host can show the radar scene without proxying Umbra COGs.
**A baked preview is typically 512 px** (the published weekly sidecar).
``max_size`` applies only to a fresh ``preview="render"`` stream; when a
cached thumbnail is smaller than requested, the caption says
``max_size`` was ignored *and* includes a JSON
``{"image": {source, width, height, requested_max_size, substituted}}``
sidecar. For a higher-resolution picture (typically 1024 px), run a
local ``uvx --from 'umbra-py[mcp]' umbra-mcp`` server, or download the
GEC href from ``get_item``. ``preview="baked"`` refuses rather than
stream; ``preview="render"`` always streams (needs ``[viz]``, refused
on ``umbra serve --public``).
Inputs: url (required), db, asset, preview, +1 more.
search_catalogARead-onlyInspect
Search Umbra's catalog and return compact context cards.
Filters (all optional, combine freely): ``bbox`` as
``[min_lon, min_lat, max_lon, max_lat]`` in WGS84 degrees; ``intersects`` as
a GeoJSON object (a ``Point``, ``Polygon``, or ``MultiPolygon``, or a
``Feature`` / ``FeatureCollection`` wrapping one; a point matches footprints
that contain it) to keep only footprints
intersecting it -- a tighter spatial filter than the rectangular ``bbox``,
and mutually exclusive with ``bbox`` / ``place``; ``place`` as a
free-text name geocoded to a bbox; ``area`` as a substring of the Umbra
task (site) name (set ``fuzzy`` to match it loosely -- word-order- and
punctuation-independent and typo-tolerant, resolved deterministically with
no model call, so ``"beet piler"`` still reaches ``"Beet Piler - ND"`` and
``"utah centerfield"`` still reaches ``"Centerfield,
Utah"``). When ``area`` matches no task and ``bbox``, ``intersects``, and
``place`` are omitted, it is geocoded and that footprint is searched; the
result then adds ``matched_by`` (``geocode``), ``resolved_place``, and
``resolved_bbox``. A name Nominatim does not know sets ``hint`` to
``no task named X; try place= or bbox=``. When geocoding is busy (the
Nominatim gate, or the public host's quick outbound pool) or
unreachable, ``hint`` is ``no task named X; geocoding was unavailable``
and ``resolved_area`` is the ``area`` that was tried. A task-name hit
adds nothing. Set ``semantic``
instead to treat ``area`` as a plain-language
*description* of a site whose name you don't know and resolve it to the
closest task names by *meaning* via the prebuilt embedding index, so
``"grain storage north dakota"`` reaches ``"Beet Piler - ND"`` -- a query
that shares no word with the label, which ``fuzzy`` cannot and should not
fake; ``semantic`` and ``fuzzy`` are mutually exclusive, and the resolved
task name is returned as ``resolved_area`` with the ranked candidates in
``semantic_matches`` so you can audit and retry with a different one, and
``min_score`` -- a cosine threshold in ``[0, 1]`` -- drops weak aliases, so
a description that matches nothing confidently returns an empty result
rather than an arbitrary top pick); ``start``/``end`` as acquisition-date
bounds -- an ISO
``YYYY-MM-DD`` date, a bare year/month (``2024``, ``2024-03``), or a
relative expression (``today``, ``yesterday``, ``3 months ago``,
``last month``), resolved deterministically with no model call;
``products`` to restrict to product types
(any of GEC, SICD, SIDD, CPHD); the SAR acquisition-property filters
``polarizations`` (keep items exposing any of these, e.g. ``["VV"]`` -- the
filter that keeps a change comparison like-with-like), ``min_incidence`` /
``max_incidence`` (view incidence-angle bounds in degrees) and
``max_resolution`` (keep items at least this fine, in metres) -- each a hard
predicate that excludes items missing that metadata; ``canonical`` to keep
the preferred copy of a collect Umbra republished under another prefix
(``True``), only the other copies (``False``), or every item when omitted;
``limit`` to cap
results (on the public host a value above 100 is clamped to 100 and the
result includes ``note``; the argument and its default are unchanged);
``max_per_task`` to cap items per site (use 1 for a one-pin-per-site
overview).
``local`` selects the backend: leave it unset to use the on-disk index when
present (instant) and fall back to a live S3 walk otherwise. When the server
is configured with a Canopy token (``$UMBRA_CANOPY_TOKEN``), the search runs
against Umbra's authenticated commercial archive instead and ``source`` is
reported as ``"canopy-archive"``. Returns the per-item context cards, not
full STAC JSON, to protect the context window; call ``get_item`` for one
item's full metadata.
Prefer ``fuzzy=True`` (or :func:`find_repeat_sites`) when ``area`` shares
words with a task name; that path is deterministic and needs no key.
``semantic=True`` is only for a description that shares **no** tokens with
the label. It requires a task-embedding index built ahead of time with
``umbra semantic build`` and a user-supplied embedding key (``OPENAI_API_KEY``,
optionally ``OPENAI_BASE_URL`` / ``UMBRA_EMBED_MODEL``); it raises a helpful
setup error otherwise, so it never runs implicitly. The only model call is
turning ``area`` into a vector -- the resolved search over the chosen backend
stays fully deterministic.
Inputs: end, area, bbox, fuzzy, +14 more. Returns: object
stack_provenanceARead-onlyInspect
Check whether a site's passes are one measurement, before measuring them.
``stack_stats`` refuses a selection whose rasters were made by *different*
``umbra convert`` settings — a calibrated pass differenced against an
uncalibrated one puts the difference between two conversions on the time
axis and reports it as change on the ground. This is the question that
refusal answers, asked ahead of it: it reads each acquisition's ``UMBRA_*``
conversion record straight from its raster header (kilobytes per pass, no
pixels, no co-registration) and groups the selection by what its pixel
values *are*.
Returns ``agrees`` (whether ``stack_stats`` would accept the selection),
``groups`` largest-first — each with the conversion ``record`` its members
share, their ``item_ids`` and the ``hrefs`` to re-run on — plus ``shared``
(the record they all agree on) when they agree, ``refusal`` (verbatim the
error ``stack_stats`` would raise) when they do not, and ``unreadable`` for
any source that could not be opened at all, which is an incomplete answer
rather than a mixed one.
Reach for it in two situations. **After** a ``stack_stats`` call fails with
a provenance refusal: ``groups[0]["hrefs"]`` is the largest set of passes
that *do* agree, so re-running ``stack_stats`` on those is a measurement
rather than a guess — the refusal itself cannot name that subset. And
**before** measuring a long series you did not assemble yourself, since the
check costs a header read per pass and saves the whole cube when the answer
is no.
A series of Umbra's published products as they ship (the common case) agrees
trivially: every pass reads as ``"(unrecorded)"``, which is one value, so
``agrees`` is true and ``shared`` is empty. **No model is called.**
Inputs: urls (required), asset. Returns: object
stack_statsARead-onlyInspect
Measure how much a site changed across its passes, as numbers.
The quantitative counterpart to ``change_composite`` / ``timescan``: those
return a picture of *where* change is, this returns the *how much*. Pass the
STAC URLs of a site's passes (2 or more, any order); they are co-registered
onto one shared grid and reduced to a per-pass statistics series plus a net
baseline-to-latest record — mean/median/spread of each pass, the signed
decibel change against the pass before it, the fraction of ground that moved
past ``change_threshold_db``, and that fraction as an **area in km²**.
Change is always reported in decibels (a ratio of backscatter is a difference
on the log scale). The default ``crs="utm"`` puts the grid in the site's UTM
zone so every cell covers the same ground and the area figures mean
something; pass ``crs="EPSG:4326"`` for a lon/lat grid, and the areas come
back ``None`` rather than wrong. ``extent="intersection"`` (the default)
compares only ground every pass covers; ``"union"`` keeps all of it and
compares per cell where two passes overlap. ``bbox`` (lon/lat
``[min_lon, min_lat, max_lon, max_lat]``) narrows the measurement to a
sub-area, e.g. one facility inside the scene.
``blocks=N`` adds the *where* to the *how much*: the scene is cut into an
N x N grid (6 is a good default; 0, the default, skips it) and the extra
``spatial`` key reports each block's own net change, a compass label and
lon/lat centre to locate it by, and the consecutive pair of passes that
block moved most between — plus ``peak_block`` and an ASCII ``grid_text``
heat-map of the net change. Ask for it whenever the question is *where on
this site* something happened, or when a scene-wide mean looks small but the
picture from ``change_composite`` shows an obvious hot spot: a change
confined to one corner is averaged away scene-wide and stands out per block.
``block_series=True`` (which needs ``blocks``) keeps each block's *whole*
pass-to-pass sequence rather than only its peak interval, so a block that
drifted a little every pass reads differently from one that jumped once and
held. It is the largest payload this tool emits — ``blocks`` × ``blocks`` ×
(passes − 1) records — so ask for it only when the *shape* of the history is
the question, not the size of the change.
``speckle_filter="boxcar"`` or ``"lee"`` averages **speckle** down before
anything is measured. Speckle is not sensor noise: it is the interference
pattern coherent illumination makes on rough ground, and on single-look
imagery it scatters as widely as its own mean — so on a quiet site an
unfiltered per-cell decibel delta is mostly interference rather than change.
``"boxcar"`` averages every window (most variance removed, blind to the edges
it averages across); ``"lee"`` averages only where a window is no more
variable than speckle alone explains, so edges and bright points survive.
Reach for it when the change you are looking for is small, or when the
numbers look noisy against a picture that looks quiet; leave it off when the
question is about *fine* structure, because what it spends is resolution — a
``speckle_window``-cell window (odd, 5 by default) makes each cell report
ground that many cells across. The returned ``caveats`` say so, so a quoted
figure carries the trade with it.
Refuses to mix polarizations (HH and VV are not comparable). **No model is
called** — this is arithmetic over streamed COG overviews, so the numbers are
reproducible and safe to quote. Read the ``caveats`` before interpreting
them: Umbra's open products are not radiometrically calibrated, so a decibel
value is relative to the same ground on another date, and look geometry moves
backscatter too.
Inputs: urls (required), crs, bbox, asset, +7 more. Returns: object
stamp_descriptionARead-onlyInspect
Validate a client-produced scene reading and stamp provenance.
This is the interpretation boundary for the no-key kit path: you read the
picture ``describe_scene`` returned, produce
``{summary, observed_features, confidence, caveats}``, and pass it here.
The library checks the shape, stamps CC-BY and the AI-interpretation
note (the model never sets those), and — when ``image`` is the record
from the kit — appends a deterministic caveat if the picture was a
smaller baked preview. Until this returns, the reading is unvalidated
prose, not pipeline output.
Inputs: reading (required), asset, image, model, +1 more. Returns: object
stamp_narrationARead-onlyInspect
Validate a client-produced change narration and stamp provenance.
Sibling of :func:`stamp_description` for the no-key ``narrate_change``
kit. Pass the JSON you produced plus the ``change_stats`` grid from the
kit so the stamped object carries the numbers the prose was grounded in.
Inputs: reading (required), asset, model, item_ids, +1 more. Returns: object
timescanARead-onlyInspect
Summarize a whole time series into one activity image.
Pass the STAC URLs of a site's passes; the timescan encodes per-pixel
temporal statistics so bright/colored areas are *where activity happened*
over the series. Returns the image block plus attribution.
Inputs: urls (required), db, asset, max_size.
watch_siteADestructiveInspect
Report only the acquisitions new since the last check of this site.
SAR's value for monitoring is its cadence, so the natural workflow is
*standing*: run the same search each time and act only on what changed. This
tool packages that idempotent delta — call it in one turn, come back a day
(or a session) later and call it again, and it returns just the passes
published in between, not the whole list again. The scheduler is you: ask the
agent to check the site, and it reports the delta.
Define the site with the same filters as ``search_catalog`` — ``place``
(geocoded to a bbox), ``area`` (task/site-name substring, loosened by
``fuzzy``), ``bbox``, ``products``, and ``start``/``end`` date bounds. The
watch is identified by a stable ``name`` derived from those filters (pass an
explicit ``name`` to run several independent watches over the same site);
``reset=True`` re-establishes the baseline, reporting everything as new.
State persists in the local catalog index's ``meta`` table (created on first
use), so a watch survives across sessions with no extra setup. ``local``
selects the search backend exactly as in ``search_catalog`` — leave it unset
to use the on-disk index when present and a live S3 walk otherwise; for true
monitoring a live walk (``local=false``) catches freshly published passes.
**No model is called** — this is pure set arithmetic over the deterministic
search — and the returned ``new_items`` are context cards ready to hand
straight to ``change_composite`` / ``timescan``, closing the standing-analyst
loop (new pass → composite → describe) without leaving the conversation.
On the public host (``umbra serve --public``, COG streaming off) nothing
is stored. Every call reports the current matches as new, says so in
``note``, and caps ``new_items`` at 50 (``new_total`` is the full count).
The watch name is capped at 128 characters. A local server still persists
the baseline in the index.
Inputs: end, area, bbox, name, +6 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Search, task, and order SkyFi satellite imagery and geospatial analytics.
Search and preview datasets publicly. Account-required full data via MCP.
Sentinel Hub MCP — satellite / earth-observation statistics as JSON (sentinel-hub.com).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables discovery, analysis, and explanation of open satellite data through MCP, with support for STAC catalogs and NASA GIBS.1MIT
- AlicenseCqualityDmaintenanceMCP server for the Geopera geospatial data platform that enables AI agents to discover imagery, place and manage orders, and run analytics using the same API as other Geopera clients.100MIT
- AlicenseNot gradedqualityCmaintenanceEnables keyless search of the EU Copernicus Data Space catalogue, letting you find Sentinel-1/2/3/5P, DEM, land-cover, and burnt-area products by area and date and retrieve item ids, footprints, dates, and asset paths.94 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables querying Sentinel-1/2, Landsat Collection 2, NAIP, and Copernicus DEM imagery by area and date, returning item IDs, footprints, cloud cover, and cloud-optimized GeoTIFF URLs.85 npmMIT
Glama MCP Gateway
Add one secure layer between your agents and this server.