🌍 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
Hydration harness	/widget/harness?days=7&minMag=4.5
Health	/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)	Every event: magnitude, depth, place, time, coordinates, tsunami flag, felt reports, significance
Open-Meteo Geocoding	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.

{ "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.

{ "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

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

Smoke test:

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.