# 🌍 Earthquake Activity Explorer — Athena MCP Agent

An MCP server that exposes the **live USGS earthquake catalogue** and renders it as an **embedded interactive widget** inside Athena.

Built for the Athena AI Interview Challenge — subject: *Earthquake activity explorer*.

---

## Live endpoints

| | URL |
|---|---|
| **MCP endpoint** | `https://athena-quake-mcp.vercel.app/mcp` |
| Widget preview | [`/widget?days=7&minMag=4.5`](https://athena-quake-mcp.vercel.app/widget?days=7&minMag=4.5) |
| Hydration harness | [`/widget/harness?days=7&minMag=4.5`](https://athena-quake-mcp.vercel.app/widget/harness?days=7&minMag=4.5) |
| Health | [`/health`](https://athena-quake-mcp.vercel.app/health) |

No authentication — any MCP host can connect directly.

---

## Real open/public data sources

No API keys, no scraping — official public feeds.

| Source | Use |
|---|---|
| [USGS Earthquake Catalog (FDSN)](https://earthquake.usgs.gov/fdsnws/event/1/) | Every event: magnitude, depth, place, time, coordinates, tsunami flag, felt reports, significance |
| [Open-Meteo Geocoding](https://open-meteo.com/en/docs/geocoding-api) | Resolves "near Tokyo" into the lat/lon + radius the USGS query needs |

---

## MCP tools

### `explore_earthquakes`
Opens the interactive explorer. Worldwide, or centred on a place.

```json
{ "place": "Tokyo, Japan", "radiusKm": 800, "days": 30, "minMagnitude": 4.5 }
```

Returns a text summary (for the model), `structuredContent` (for the widget and
programmatic use), **and** the interactive widget.

### `list_significant_earthquakes`
The most significant recent events worldwide, ranked by magnitude — used to find
where activity is happening before drilling in.

```json
{ "days": 7, "minMagnitude": 5.0, "limit": 10 }
```

---

## The widget — interactions

Four meaningful interactions (two were required), all relevant to the subject:

1. **Time range** — 24h / 7d / 30d. Re-filters the map and the event list together.
2. **Magnitude threshold** — All / 4+ / 5+ / 6+. Isolates the significant events.
3. **Sort order** — Recent / Strongest / Deepest. Depth sorting surfaces the deep-focus
   subduction events that a magnitude sort buries.
4. **Event selection** — click any list row *or* map circle. Expands full USGS detail
   (UTC time, magnitude type, depth band, coordinates, felt reports, significance
   score, link to USGS) and highlights that epicentre while dimming the rest.

Hovering any map circle scrubs a readout without changing state.

The map is a plain equirectangular projection with a graticule — no tiles, no external
images. Circles are **sized by magnitude** and **coloured by depth band** (shallow
<70km / intermediate 70–300km / deep >300km), which makes the Ring of Fire
resolve out of the data itself.

Selecting an event also emits a follow-up prompt to the host, so the conversation can
continue from what the user clicked.

---

## Design notes

**One dataset, every interaction.** A single generous USGS query (up to 30 days, up to
500 events, ~27KB) backs the widget; every filter, sort and selection runs client-side.
No interaction costs a round-trip, and the widget needs no network access of its own —
which matters because iframe CSP varies between hosts.

**Two render paths, one renderer.** Hosts disagree on how a tool returns UI:

- Some render the **embedded resource** in the tool result → they get `renderWidget(payload)`, data inlined.
- Others resolve the tool's static `_meta.ui.resourceUri` via **`resources/read`**, fetch the widget once as a template, then push data in at runtime → they get `renderWidgetTemplate()`, which hydrates through the ext-apps bridge.

`resources/read` branches on whether the URI carries query params, so both paths serve
the *queried* data rather than a generic sample. Both build from the same `boot()`
renderer, so the UI cannot drift between them.

**Graceful degradation.** Hosts with no widget support still receive a complete text
summary plus `structuredContent`, so the model can answer regardless.

**Safety.** USGS place strings are third-party input and are rendered exclusively via
`textContent` / DOM construction — never `innerHTML`.

---

## Run locally

```bash
npm install
npm run dev      # http://localhost:3000/mcp
```

Smoke test:

```bash
curl -s http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"explore_earthquakes","arguments":{"days":7,"minMagnitude":4.5}}}'
```

Verify the hydration path without a chat client — the harness iframes the data-less
template and posts a payload in exactly as a host does:

```
http://localhost:3000/widget/harness?days=7&minMag=4.5
```

## Stack

Zero runtime dependencies. Hand-rolled JSON-RPC 2.0 over Streamable HTTP
(`POST /mcp`, SSE-framed when the client's `Accept` header asks for it), deployed as a
Node serverless function on Vercel. The ext-apps browser bundle is vendored into
`lib/extAppsBundle.js` via `npm run build:bundle` so it is traced into the serverless
bundle by a static import rather than a runtime `fs` read.