A modular Kiro Power that gives developers unified, AI-assisted access to the fragmented geospatial landscape across open, free-tier, and proprietary sources.
It is built on a dual-fragmentation framing: in geospatial work, data
access (discover/read) and processing/compute (transform/analyze) are
equally fragmented and receive equal weight, plus a third pillar for
GeoAI (foundation-model embeddings, segmentation, semantic and vector
search). The architecture mirrors the
Kiro for Life Sciences pack:
one central Power acts as the hub, and users install only the standalone MCP
servers they need, each runnable via uvx.
See
POWER.mdfor the Power overview, keywords, and the full install matrix, andbundle-manifest.jsonfor the machine-readable declaration of every server, skill, steering workflow, and wrapped external.
- Power Hub (
kiro-geospatial) — the central coordinator: an Onboarding Dashboard, a searchable Resource Catalog, a Credential Manager (singlemcp.jsonsurface), and a "discover → process → analyze" Orchestration Router that fans a single natural-language request across multiple sources/tools in parallel with graceful degradation. - Modular MCP servers — standalone Python packages, one per domain,
installed à la carte via
uvx. geo-commonshared base — one async HTTP client (built onhttpx) with retry + exponential backoff, a commonError_Taxonomy, rate-limit handling, and theBaseGeoServercontract every server inherits.- Skills and steering — context/file-pattern-activated best practices
(
skills/) plus executable multi-step workflow guides (steering/). aws-geo-computepeer Power — orchestrates heavy/distributed compute on AWS Batch, Amazon ECS with AWS Fargate, Amazon EMR with Apache Sedona, and Amazon SageMaker AI via a deterministic task-type → execution-target mapping.
- Pillar A — Data Connectors: catalogs, imagery, vector, geocoding/routing, terrain, weather/climate, biodiversity.
- Pillar B — Processing & Compute: CRS transforms, geometry operations, format conversion, spatial SQL, raster/zonal statistics, point clouds, spatial indexing.
- Pillar C — GeoAI: foundation-model embeddings, segmentation, vector search, change detection.
By design, the Pillar B (processing/compute) server count is never smaller than Pillar A (data access).
┌──────────────────────────────────────────────────────────────┐
│ Kiro IDE │
├──────────────────────────────────────────────────────────────┤
│ kiro-geospatial Power (Hub) │
│ ┌────────────┐ ┌────────────┐ ┌──────────────────────────┐ │
│ │ Dashboard │ │ Catalog │ │ Credential Manager │ │
│ └────────────┘ └────────────┘ └──────────────────────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────────────────┐ │
│ │ Skills │ │ Steering │ │ Orchestration Router │ │
│ │ (7 guides) │ │(5 workflows│ │ discover → process → │ │
│ │ │ │ │ │ analyze (graceful degrade)│ │
│ └────────────┘ └────────────┘ └──────────────────────────┘ │
├──────────────────────────────────────────────────────────────┤
│ Modular MCP servers (install as needed via uvx) │
│ A: stac · vector · geocode-route · terrain · │
│ weather-climate · biodiversity · ogc │
│ B: ops · formats · query · raster · pointcloud · index · 3d │
│ C: foundation-models · embedding-search │
│ Credentialed: warehouse · commercial-imagery │
├──────────────────────────────────────────────────────────────┤
│ geo-common (shared base: HttpClient, Error_Taxonomy, │
│ BaseGeoServer) │
├──────────────────────────────────────────────────────────────┤
│ Peer Power: aws-geo-compute │
└──────────────────────────────────────────────────────────────┘
A request flows strictly in pillar order: every discover step precedes every process step, which precedes every analyze step. Discovery sources are queried concurrently; on a per-source failure the router records provenance and continues, labelling any degraded result partial.
geospatial-kiro-power-pack/
├── README.md # this file
├── POWER.md # Power overview, keywords, install matrix
├── bundle-manifest.json # servers, skills, steering, wrapped externals
├── pyproject.toml # repo-wide pytest config + shared test deps
├── conftest.py # Hypothesis profile + shared mock fixtures
├── packages/ # one standalone, uvx-installable package per server
│ ├── kiro-geospatial/ # the Power Hub
│ ├── geo-common/ # shared base (dependency of every server)
│ ├── geo-stac/ geo-vector/ … (Pillar A)
│ ├── geo-ops/ geo-formats/ … (Pillar B)
│ ├── geo-foundation-models/ geo-embedding-search/ (Pillar C)
│ ├── geo-warehouse/ geo-commercial-imagery/ … (credentialed)
│ └── aws-geo-compute/ # peer compute Power
├── skills/ # encoded best-practice skill files
├── steering/ # file-pattern-triggered workflow guides
└── docs/ # supporting documentation
21 packages — the Power Hub, the geo-common shared base, and 19 MCP
servers exposing 56 tools across Pillars A (data access), B
(processing/compute), and C (GeoAI), plus credentialed and peer-Power servers.
Per-server credential keys are in the Credentials reference below.
| # | Server | Pillar | Tier | Tools | Key capabilities |
|---|---|---|---|---|---|
| — | kiro-geospatial |
Hub | Open | — | dashboard, catalog, credential manager, orchestration router |
| — | geo-common |
Shared base | Open | — | HttpClient, retry/backoff, Error_Taxonomy, BaseGeoServer |
| 1 | geo-stac |
A | Open | 3 | STAC search — one catalog (stac_search) or federated round-robin merge (stac_search_multi) across Earth Search & USGS/Landsat (answer bbox+datetime directly), Planetary Computer & NASA CMR-STAC (LPCLOUD: HLS/MODIS — need a collections filter), and Copernicus Data Space (CLMS land-monitoring products, not raw Sentinel). Collection ids differ per catalog, so list_collections discovers what each catalog offers (the ids stac_search accepts, optionally filtered by a substring like sentinel) |
| 2 | geo-vector |
A | Open | 1 | vector features from OpenStreetMap (Overpass); optional configured Overture endpoint |
| 3 | geo-geocode-route |
A | Open / Free-Tier | 4 | geocode + reverse-geocode (Nominatim, Photon), routing (OSRM, Valhalla), isochrones (Valhalla); Amazon Location selectable via source (credentialed) |
| 4 | geo-terrain |
A | Open | 5 | elevation, slope, aspect, hillshade from SRTM (default) and USGS 3DEP (public OpenTopoData; endpoint/dataset overridable); dem_zonal — per-zone elevation/slope/aspect statistics over a DEM COG via byte-range reads, by dem_href or a named dem_source (glo30 — Copernicus GLO-30; 3dep — USGS 3DEP 1/3 arc-second, US; tiles auto-resolved and mosaicked) |
| 5 | geo-weather-climate |
A | Open / Free-Tier | 1 | observations from Open-Meteo weather (default) and Open-Meteo air-quality (source="air-quality": PM2.5/PM10/CO/NO2/SO2/O3), NOAA/NWS; NOAA CDO (credentialed). ERA5 reanalysis is covered via the Open-Meteo archive, not a direct CDS client |
| 6 | geo-biodiversity |
A | Open | 1 | species occurrences from GBIF + iNaturalist; IUCN Red List conservation status (credentialed) |
| 7 | geo-ogc |
A | Open | 1 | fetch GeoJSON features from any OGC API - Features service (pygeoapi, GeoServer OGC API, ldproxy) by endpoint + collection |
| 8 | geo-ops |
B | Open | 7 | CRS transforms, geometry validation/ops, spatial join, overlay, buffer, convex hull, simplify (shape-preserving vertex reduction) (PyProj, Shapely/GEOS, GeoPandas) |
| 9 | geo-formats |
B | Open | 3 | COG / GeoParquet conversion + validation; to_geoparquet src takes inline GeoJSON or a path/href (local, or s3:///https:// via the [remote] extra) so large vectors are referenced by location, not pasted inline |
| 10 | geo-query |
B | Open | 1 | ad-hoc, in-process spatial SQL via DuckDB Spatial (open default, opt-in [duckdb] extra) / Amazon Athena over S3 (bring-your-own AWS creds; Athena also requires ATHENA_S3_STAGING_DIR) — for warehouse-scale SQL see geo-warehouse |
| 11 | geo-raster |
B | Open | 4 | windowed COG reads (uncompressed/DEFLATE/LZW; int + float, incl. floating-point predictor) + band math (NDVI/NDWI/NBR); zonal statistics over vector zones; zonal band math (per-pixel index across separate single-band COGs, reduced per zone). Pure-Python by default; geo-raster[fast] adds a numpy-accelerated zonal engine |
| 12 | geo-pointcloud |
B | Open | 2 | point-cloud read/write. Real Cloud-Optimized Point Cloud / LAZ read (octree-windowed) via laspy+lazrs ([copc] extra — light, no native GDAL/PDAL; remote s3:///https:// via [remote]); standards-compliant COPC write via PDAL ([pdal] extra). With no extra, falls back to a portable, lossless local container (explicitly not interoperable COPC) |
| 13 | geo-index |
B | Open | 1 | H3 (0-15) and S2 (0-30) spatial indexing |
| 14 | geo-3d |
B | Open | 4 | inspect 3D Tiles + glTF/GLB; tile point clouds → 3D Tiles .pnts (optional octree LOD); mesh DEM grids → glTF/GLB terrain (with normals) |
| 15 | geo-foundation-models |
C | Open | 9 | foundation-model embeddings, change detection, segmentation. Server-side COG-window reads (embed_asset; embed_assets for separate single-band COGs), change from two dates (detect_change_from_assets) or a per-tile/zone change_map. Backends pluggable for real weights — in-process callable or remote HTTPS/SageMaker — with honest provenance/caveats (stand-in by default); lookup_embeddings returns real published Clay v1.5 vectors. See POWER.md + the embedding-change-detection steering guide for wiring |
| 16 | geo-embedding-search |
C | Open | 2 | embedding store + similarity search: zero-config in-memory by default; local durable LanceDB ([lancedb] extra, set LANCEDB_URI); or managed/hosted Amazon OpenSearch ([opensearch] extra, credentialed via OPENSEARCH_URL) — the OpenSearch engine runs as a managed service, never locally |
| 17 | geo-warehouse |
Credentialed (B-class) | Proprietary | 1 | warehouse-scale spatial SQL against managed cloud warehouses (BigQuery, Snowflake, Redshift, Databricks) — for open/ad-hoc SQL see geo-query |
| 18 | geo-commercial-imagery |
Credentialed | Proprietary | 2 | commercial imagery search + ordering, routed by provider: Maxar via Sentinel Hub TPDI, Planet via Planet's Data/Orders APIs |
| 19 | aws-geo-compute |
Peer Power | Open (AWS account) | 4 | engine selection + job submit/status on AWS Batch, AWS Fargate, Amazon EMR, and Amazon SageMaker AI |
All servers above are fully implemented, with passing unit, property-based, and integration test suites.
Recommended starter set (a working discover → process → analyze pipeline):
geo-common, geo-stac, geo-vector, geo-ops, geo-foundation-models, and
the Power Hub (kiro-geospatial). Common next additions: geo-warehouse.
These third-party MCP servers pair well with the pack. They are not part of the Geospatial Power Pack and are not redistributed with it — install them yourself; each is governed by its own license. Listed as recommendations, with attribution.
| Companion | Source | License | Use it for |
|---|---|---|---|
awslabs.roda-mcp-server |
awslabs/mcp | Apache-2.0 (AWS Labs) | Discovering open datasets on the Registry of Open Data on AWS (1,000+): search by keyword/organization/license, preview/sample public S3 buckets, and search_stac_endpoints. The natural discovery front-door upstream of this pack — find the dataset, then read/analyze it here (pairs directly with geo-stac) |
gdal-mcp |
JordanGunn/gdal-mcp | MIT | Local-file GDAL/Rasterio ops: file-level raster/vector reproject + convert, and vector clip (for buffer/convex_hull/simplify use this pack's geo-ops) |
gis-mcp |
mahdin75/gis-mcp | MIT | Spatial statistics / ESDA you don't get here (PySAL: Moran's I, Geary's C, Getis-Ord, LISA, spatial regression) and map rendering (static Matplotlib + interactive Folium web maps) |
awslabs.roda-mcp-server is AWS Labs' own MCP server for the Registry of Open
Data on AWS. It sits upstream of this pack's
discover → process → analyze flow: use it to find the right open dataset
(natural-language search across 1,000+ datasets, license always surfaced, plus
public-bucket preview/sample), then hand the dataset's S3/STAC references to
this pack to read and analyze cloud-natively. Its search_stac_endpoints tool
pairs directly with geo-stac, and the open, credential-free datasets it
surfaces (e.g. Sentinel-2 COGs) are exactly what the pack's default paths read.
Install it separately from PyPI:
uvx awslabs.roda-mcp-server@latestgis-mcp is a single local server built on the classic desktop Python GIS
stack (Shapely/PyProj/GeoPandas/Rasterio/PySAL). Its geometry, CRS, raster,
and connector functions overlap with this pack's native servers (geo-ops,
geo-raster, geo-stac, …) — prefer this pack's cloud-native versions for
those. Reach for gis-mcp for the parts this pack does not cover:
PySAL spatial statistics and visualization. Install it separately from
PyPI:
uvx gis-mcpgdal-mcp is the local-file complement to this pack's cloud-native
connectors. Install it separately from PyPI:
uvx --from gdal-mcp gdal --transport stdioTwo things to know before using it:
- It is scoped by
GDAL_MCP_WORKSPACES(a colon-separated directory allowlist). If unset, all paths are allowed — set it to constrain file access. - Its reflection middleware requires a structured justification before methodology-sensitive tools (reprojection, resampling, query extent) run — an opinionated UX distinct from this pack's validate-then-run tools.
To wire it into Kiro, it needs uv installed
(brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh) — this
is the first server launched via uvx rather than a .venv console script. Use
the absolute uvx path in mcp.json, because Kiro launched from Finder/Dock
does not inherit your shell PATH and a bare "uvx" fails with
spawn uvx ENOENT (run which uvx to find it):
"gdal-mcp": {
"command": "/opt/homebrew/bin/uvx",
"args": ["--from", "gdal-mcp", "gdal", "--transport", "stdio"],
"env": { "GDAL_MCP_WORKSPACES": "/path/to/your/geo/data" }
}Rule of thumb: use gdal-mcp for local/desktop file processing; use this pack
for cloud-native reads (STAC, COG byte-range, open APIs).
The companions above are open-source, locally-run tools. The servers below are
third-party, commercial, hosted MCP services — not part of this Power, not
redistributed with it, and not affiliated with or endorsed by AWS. Each needs
its own account/license and is configured by you. They are listed for awareness
because they offer managed, at-scale capabilities the open servers here do not.
Unlike the pack's local uvx servers, these are remote MCP endpoints. Esri,
Wherobots, and Felt are members of the AWS Partner Network.
Esri offers two hosted MCP servers (both public beta):
-
ArcGIS Enterprise MCP — public beta — Esri's MCP server over your ArcGIS Enterprise content: item/layer search and describe, attribute and spatial
query_data, map-image export, and geocoding. This is a beta — not GA; the API and endpoints may change without notice, and it is not for production use. Commercial; requires an ArcGIS Enterprise deployment and an API key. It is a remote HTTP endpoint; because Kiro launches MCP servers as local stdio child processes, bridge to it with themcp-remotenpx proxy and pass the key as a header (keeps the secret out of the URL):"arcgis-enterprise": { "command": "npx", "args": [ "-y", "mcp-remote", "https://<host>/<context>/platform/mcp", "--header", "Authorization: Bearer <API_KEY>" ] }
See the ArcGIS Enterprise MCP beta docs.
-
ArcGIS Location Services MCP — public beta — Esri's hosted MCP server over the ArcGIS Location Platform: geocoding (
find_address_candidates,reverse_geocode), routing (solve_route), elevation (elevation_at_locations), and static maps (map_with_points,map_with_polyline). Beta — not GA; may change without notice, not for production. Commercial and metered: every call bills against your ArcGIS Location Platform usage. Requires a Location Platform account and an access token with beta-access plus Geocoding/Routing/Elevation/Static-maps privileges. Remote HTTP endpoint; bridge to it with themcp-remotenpx proxy and pass the token as a Bearer header:"arcgis-location-services": { "command": "npx", "args": [ "-y", "mcp-remote", "https://location-services-mcp.arcgis.com/beta/mcp", "--header", "Authorization: Bearer <ACCESS_TOKEN>" ] }
See the ArcGIS Location Services MCP docs.
- Wherobots Cloud MCP — gives an agent a managed spatial lakehouse it can
drive with plain language: explore a catalog, run Spatial SQL or Python over
planetary-scale datasets, and submit distributed jobs, all without
provisioning or tuning a cluster. Physical-world data is structurally different
from ordinary tables, and the engine underneath is built for it — by the
original creators of Apache Sedona and 100% code-compatible across every
spatial function. Commercial; the MCP server requires a Wherobots Professional
organization (available on AWS Marketplace). To self-manage the same compute
instead, use the EMR + OSS Apache Sedona path in
aws-geo-compute. Configure it in Kiro directly through themcpServersurl+ header schema:See the Wherobots Kiro setup docs."wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "headers": { "x-api-key": "YOUR_WHEROBOTS_API_KEY" } }
- Felt MCP — gives an agent the human-facing end of the workflow: a
collaborative web map where the artifacts this pack produces get seen, styled,
and reviewed. Create and share maps; add layers from files, URLs, or cloud
data warehouses (Postgres/PostGIS, Snowflake, BigQuery, Redshift, Databricks,
SQL Server); run spatial queries against live layers; style them with Felt
Style Language; and drop annotations for teammates to react to — the review
step between an agent's output and its next iteration. Commercial with a free
tier; requires a Felt workspace, and Felt is available on AWS Marketplace and
AWS GovCloud (US). Remote MCP endpoint with browser-based OAuth (no API keys
to manage), configured in Kiro directly through the
mcpServersurlschema:See the Felt MCP server docs."felt": { "url": "https://felt.com/mcp" }
All credentials are configured once in mcp.json and flagged Required,
Optional, or License-Needed. The MVP servers are open and need no
credentials. Notable keys:
| Server | Key(s) | Classification |
|---|---|---|
geo-stac |
PC_SDK_SUBSCRIPTION_KEY, EARTHDATA_TOKEN |
Optional |
geo-foundation-models |
HF_TOKEN |
Optional |
geo-formats / geo-query / geo-raster / geo-pointcloud |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (+ ATHENA_S3_STAGING_DIR) |
Optional |
geo-embedding-search |
OPENSEARCH_URL / OPENSEARCH_USERNAME / OPENSEARCH_PASSWORD |
Optional |
geo-warehouse |
BIGQUERY_CREDENTIALS, SNOWFLAKE_CONNECTION, REDSHIFT_CONNECTION, DATABRICKS_CONNECTION |
License-Needed |
geo-commercial-imagery |
SENTINELHUB_CLIENT_ID, SENTINELHUB_CLIENT_SECRET (Maxar via Sentinel Hub), PL_API_KEY (Planet) |
License-Needed |
aws-geo-compute |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION |
Optional (enforced at job submit/status) |
Secret values never appear in any status report, error, or log.
Prerequisites
- Kiro IDE
- Python 3.10 or higher
- The
uvpackage manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
Create an environment and install the shared base, hub, and the servers you want:
cd geospatial-kiro-power-pack
uv venv .venv
source .venv/bin/activate
# 1) Shared base first (every server depends on it)
uv pip install -e ./packages/geo-common
# 2) The Power Hub
uv pip install -e ./packages/kiro-geospatial
# 3) The MVP servers (a working discover → process → analyze pipeline)
uv pip install -e ./packages/geo-stac
uv pip install -e ./packages/geo-vector
uv pip install -e ./packages/geo-ops
uv pip install -e ./packages/geo-foundation-models
uv pip install -e ./packages/aws-geo-compute
# 4) Any expansion / credentialed servers you need, e.g.
uv pip install -e ./packages/geo-formats
uv pip install -e ./packages/geo-warehouseEach install pulls in geo-common and nothing else, so you install only what
you need.
-
Copy the Power directory (which holds
POWER.md,bundle-manifest.json,skills/, andsteering/) into Kiro's powers directory:mkdir -p ~/.kiro/powers/kiro-geospatial cp -r POWER.md bundle-manifest.json skills steering ~/.kiro/powers/kiro-geospatial/
-
Register the MCP servers in your workspace
.kiro/settings/mcp.json, with eachcommandpointing at the console entry point installed in your venv (add only the servers you installed):{ "mcpServers": { "geo-stac": { "command": "/abs/path/.venv/bin/geo-stac" }, "geo-vector": { "command": "/abs/path/.venv/bin/geo-vector" }, "geo-ops": { "command": "/abs/path/.venv/bin/geo-ops" } } } -
Add credentials for any License-Needed / Required servers via
env:{ "mcpServers": { "geo-warehouse": { "command": "/abs/path/.venv/bin/geo-warehouse", "env": { "BIGQUERY_CREDENTIALS": "/abs/path/service-account.json" } }, "aws-geo-compute": { "command": "/abs/path/.venv/bin/aws-geo-compute", "env": { "AWS_REGION": "us-east-1" } } } }Prefer short-lived credentials. Avoid putting long-term AWS access keys in
mcp.json. For AWS-backed servers (aws-geo-compute, and the optional S3 paths ofgeo-formats/geo-query/geo-raster/geo-pointcloud), leave the key fields unset and let the server pick up credentials from the standard AWS provider chain — an IAM role (on EC2/ECS/Lambda) or anaws configureprofile (AWS_PROFILE) for local development. Where a server reads a key directly frommcp.json(e.g.BIGQUERY_CREDENTIALS), point it at a file restricted withchmod 600, never commit that file, and rotate the credential regularly. Secret values never appear in any status report, error, or log. -
Activate the kiro-geospatial Power from the Kiro Powers panel.
Each domain server's console entry point (e.g. geo-stac) runs the startup
credential guard and then serves its registered tools over an MCP stdio
connection via the shared geo-common runtime, so Kiro launches it directly
from the command you configure. The kiro-geospatial hub entry point is a
readiness/summary command — the hub is the Power Kiro activates (via POWER.md,
bundle-manifest.json, skills/, steering/), not a tool server, so it is not
listed in mcp.json.
The pack runs on Windows-based Kiro. Differences from the Unix examples above:
- Console scripts live in the venv
Scriptsdir with.exe, somcp.jsoncommandis e.g.C:\\path\\.venv\\Scripts\\geo-stac.exe. - Activate with
.venv\\Scripts\\activate; copy the Power files into%USERPROFILE%\\.kiro\\powers\\kiro-geospatial\\(Explorer orCopy-Item). - The
Makefileandscripts/build_wheels.share Unix shell wrappers — use WSL/Git Bash, or run the underlyingpython/pipcommands directly. The Python smoke scripts (scripts/smoke_*.py) run natively on Windows. - Heavy wheels (rasterio/GDAL, shapely, pyproj, geopandas, pyarrow, h3, duckdb)
have Windows wheels. The optional
geo-pointcloudPDAL backend needs conda (conda install -c conda-forge pdal python-pdal); the default COPC backend is pure-Python.
Test configuration lives in the root pyproject.toml
([tool.pytest.ini_options]) and conftest.py (Hypothesis profile enforcing
≥100 generated cases per property test, plus shared httpx mock-transport and
moto fixtures).
# Install the shared dev/test dependency group
uv sync --group test
# Run the whole suite (discovers everything under packages/)
uv run pytestAlternatively, each package declares a dev extra, so you can install a single
package with its test tools (life-sciences style):
uv pip install -e "./packages/geo-formats[dev]"
uv run pytest packages/geo-formatsMore selections:
uv run pytest packages/geo-raster # one package
uv run pytest -m property # only Hypothesis property tests
uv run pytest -m "not integration" # skip integration/moto tests
HYPOTHESIS_PROFILE=ci uv run pytest -m property # deeper 1000-case searchIf you prefer not to install the packages, you can run a single package against
the source tree with PYTHONPATH:
PYTHONPATH="packages/geo-common:packages/geo-formats" python -m pytest packages/geo-formatsProperty-based tests use Hypothesis and
are tagged Feature: geospatial-power-pack, Property {n}. Integration tests
that need AWS use moto and skip
automatically when it is not installed.
Two layered smoke tests give deploy confidence beyond the unit suites. A
Makefile wraps them (make help lists all targets).
Layer 1 — import + construction (scripts/smoke_import.py): imports every
package, asserts each server constructs and registers tools, and checks each
console entry point resolves. No network, no mcp SDK, no AWS.
make smoke-import # or: python3 scripts/smoke_import.pyLayer 2/3 — MCP stdio handshake + local tool calls (scripts/smoke_mcp.py):
launches a server's console entry point over MCP stdio exactly as Kiro does,
runs the initialize + tools/list handshake, and calls one no-network local
tool. This requires the mcp SDK and the target servers installed in a Python
≥3.10 environment. Since uv may not be present, the Makefile builds a plain
venv:
make venv # python3.12 -m venv .venv; pip install mcp + test tools + geo-common
make install-smoke # editable-install geo-index + geo-embedding-search (lightweight)
make smoke-mcp # handshake + call_tool against those serversTo get the SDK without the Makefile:
python3.12 -m venv .venv && . .venv/bin/activate
pip install mcp pytest pytest-asyncio hypothesis
pip install -e ./packages/geo-common -e ./packages/geo-index
python scripts/smoke_mcp.py geo-index
# expected: [PASS] geo-index tools/list -> index_cell; call_tool(index_cell) OK -> '89283082803ffff'Add a server to the handshake run with make smoke-mcp SERVERS="geo-index geo-ops"
(install it first; servers with heavy native deps — GDAL/rasterio, PDAL — need
those wheels available).
Heavy / native-dependency servers (GDAL/rasterio, shapely, pyproj, numpy, pyarrow) have their own targets, since their wheels are larger:
make install-heavy # editable-install geo-ops, geo-formats, geo-raster,
# geo-pointcloud, geo-foundation-models, geo-query
make smoke-heavy # MCP handshake for all of them; geo-ops also runs a reprojection callAll of these were verified serving over MCP, including a geo-ops
transform_crs call returning a reprojected geometry. Note geo-query runs the
open DuckDB Spatial engine in-process when its optional [duckdb] extra is
installed (pip install -e "./packages/geo-query[duckdb]"), wired through the
server's entry point; without the extra it still serves and lists spatial_sql
but reports the engine as not available; Amazon Athena is now a shipped
concrete engine too (the [athena] extra, wired when AWS is configured).
geo-pointcloud's default COPC backend is pure-Python
(PDAL is an optional, lazily-imported production backend).
Credentialed / peer servers (geo-commercial-imagery, geo-warehouse,
aws-geo-compute) are all httpx-only, so
they install and verify with no credentials:
make install-credentialed
make smoke-credentialed # handshake + credential-guard probe; needs no accountssmoke-credentialed runs each tool with the relevant key unset and asserts the
credential guard returns a taxonomy AuthenticationError naming the missing
mcp.json key (e.g. SENTINELHUB_*, BIGQUERY_CREDENTIALS). Each credentialed
capability also ships a concrete success path verified at Layer 1 (fake-client
unit tests, no account) and exercisable live at Layer 2 with an account — see
"Phase 10 — credentialed success paths" in docs/testing-workflows.md:
geo-commercial-imagery (Maxar via Sentinel Hub TPDI + Planet via Planet's own
Data/Orders APIs),
geo-warehouse (BigQuery via the free sandbox; [bigquery] extra — plus
concrete Redshift, Snowflake, and Databricks engines via their
[redshift]/[snowflake]/[databricks] extras),
geo-query (Athena; [athena] extra), and aws-geo-compute (AWS Batch +
Fargate targets; [aws] extra). Only the Amazon EMR with Apache Sedona and
Amazon SageMaker AI compute targets
stay bring-your-own.
Packaging check — build a wheel for every package (validates packaging metadata) and optionally install + serve one from its wheel in a throwaway env:
make build # builds all 21 wheels into dist/
make build-verify # + installs geo-common/geo-index from wheels and MCP-smokes themOptional PDAL backend — geo-pointcloud's production COPC path needs the
native PDAL library (brew install pdal / conda install -c conda-forge pdal python-pdal), then pip install -e "./packages/geo-pointcloud[pdal]". Until
installed, its PDAL test skips and the default pure-Python backend is used.
See docs/testing-workflows.md for step-by-step
in-Kiro manual acceptance (with example prompts and expected results) and
PDAL enablement.
Layer 4 — live sources is reserved for opt-in network tests tagged with the
live marker (registered in the root pyproject.toml); the default
-m "not integration" / -m "not live" selections keep CI hermetic.
- Single credential surface — configure keys once in
mcp.json. - Modular installation — install only the servers you need via
uvx. - Federated search with fair merging —
stac_search_multiqueries multiple STAC catalogs concurrently and round-robin merges the results (one item per catalog in turn) up to the limit, so every responding catalog is represented rather than the first one filling the quota. By default (dedupe="scene") it also collapses the same physical scene served by multiple catalogs under different id schemes (matching on acquisition instant- MGRS tile, conservatively); pass
dedupe="id"to keep each catalog's copy (e.g. when the per-catalog asset format matters). Each endpoint's outcome is reported as provenance, and a failed catalog marks the result partial rather than failing the whole search (graceful degradation).
- MGRS tile, conservatively); pass
- Cloud-optimized formats — COG, GeoParquet, Zarr, COPC.
- AWS-native "bring compute to the data" — read only the byte ranges
required from S3; delegate heavy jobs to
aws-geo-compute. - Reuse vs build — every connector is implemented natively on the shared
geo-commonbase for one consistent error/credential/catalog surface; mature external MCP servers (gdal-mcp,gis-mcp) are recommended as companions rather than wrapped or redistributed. - Property-based testing — Hypothesis-backed correctness properties for the logic-bearing components.
See CONTRIBUTING.md for how to add or change servers and
tools, the BaseGeoServer contract, the error taxonomy, and the static checks
that keep the manifest and code in sync.
See CONTRIBUTING.md for how to
report a potential security issue — please notify AWS/Amazon Security via the
vulnerability reporting page
rather than opening a public GitHub issue. Credentials are configured only in
mcp.json (or a 0600 file referenced from it), never committed; servers
enforce TLS on outbound calls and never echo secret values into errors or logs.
This project is licensed under the MIT-0 License. See LICENSE for
details.