boettiger-lab-stack

name	boettiger-lab-stack
description	Map of the boettiger-lab data-and-agent stack — which GitHub repo owns which piece of the data → STAC → MCP → LLM-agent chain. Use when unsure which repo to edit for a given problem, when routing cross-repo issues, or when the root cause could plausibly be in more than one layer.

boettiger-lab Stack Map

The stack is a pipeline. Data flows upward; requests flow downward. Each layer has exactly one primary repo. Edit the repo that owns the behavior, not a downstream consumer that works around it.

  LLM agent (browser)
         │
         ▼
  geo-agent           ← client: map + chat UI. static site from CDN.
         │ MCP over HTTP
         ▼
  mcp-data-server     ← server: DuckDB SQL + STAC tool-use + tile serving
         │ reads
         ▼
  STAC catalog on S3  ← metadata about the data: public-data/stac/catalog.json
         │ generated by
         ▼
  data-workflows      ← pipelines that process datasets and emit STAC JSON
         │
         ▼
  raw + CNG data on S3 (Ceph via NRP)

All of this runs on NRP Nautilus (Kubernetes, Ceph S3 under the biodiversity namespace). Platform concerns live in separate skills: nrp-k8s, nrp-s3.

Per-repo ownership

boettiger-lab/geo-agent — client

The browser app. Configured per-deployment by layers-input.json + system-prompt.md + optional k8s/. JavaScript is loaded from CDN; we do not edit it here. If a user-visible bug is in the chat flow, map rendering from configured layers, or the system prompt, it's here. If the fix needs new JS capabilities, that's the upstream geoagent-app repo (CDN source), not this one. See the geo-agent skill for config details.

boettiger-lab/mcp-data-server — server

The MCP server that LLM agents talk to. Owns: DuckDB SQL execution, STAC tool-use (browse_stac_catalog, get_stac_details, get_collection), PMTiles tile proxy, auth, k8s deployment for duckdb-mcp / dev-duckdb-mcp. Reads the STAC catalog at startup. Does NOT own the catalog content — only how it's presented to agents.

boettiger-lab/data-workflows — STAC catalog and dataset pipelines

Generates and maintains the STAC catalog at s3-west.nrp-nautilus.io/public-data/stac/catalog.json and all per-collection stac-collection.json files. Also owns dataset-import workflows and the legacy pipelines that produced the current catalog shape. If a table:columns is wrong, missing, or a collection is structurally malformed, the fix is here, not in mcp-data-server. Note: the repo name is historical — it's really the data-and-catalog repo. See the cng-datasets skill for the current dataset-processing CLI used inside this repo.

boettiger-lab/cng-datasets — dataset-processing CLI

The tool used inside data-workflows for new datasets: URL verification, raw S3 upload, YAML-driven cloud-native conversion (GeoParquet + PMTiles + H3 hex), deployment to NRP. Emits STAC metadata as a side effect. See the cng-datasets skill for the full workflow.

Common cross-repo scenarios

• "The agent gives the wrong column names for dataset X." First check: does get_stac_details(X) return the right columns? If the STAC has wrong columns → data-workflows. If STAC is fine but the tool output is malformed → mcp-data-server. If the output is fine but the prompt doesn't consume it → geo-agent.
• "The agent didn't find dataset X." Walk the STAC catalog yourself (use the stac-navigation skill). If X is missing from STAC → data-workflows. If X is present but browse_stac_catalog doesn't surface it → mcp-data-server. If it surfaces but the agent doesn't use it → geo-agent (probably a system-prompt / tool-description issue).
• "MCP startup is slow / pod won't come up." Almost always NRP S3 tail latency. mcp-data-server fix if the code can bound the load time; nrp-k8s if it's a rollout / admission issue.
• "Catalog shape is weird for this agent use case." Fix the catalog upstream in data-workflows, don't patch around it in mcp-data-server. Rendering logic should assume a well-formed catalog.

The principle

Edit the repo where the behavior is defined, not a repo that happens to display the symptom. The downstream repos are consumers and should stay thin. When in doubt: trace the data from its source (raw → pipeline → STAC → MCP → agent) and fix the earliest point where the wrong thing enters the chain.