@cyanheads/earthquake-mcp-server 0.1.16 → 0.3.0

package/CLAUDE.md

@@ -2,8 +2,8 @@
 
 **Server:** earthquake-mcp-server
 **Package:** `@cyanheads/earthquake-mcp-server`
-**Version:** 0.1.16
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.10`
+**Version:** 0.3.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.17`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -136,6 +136,8 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
+For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
+
 ---
 
 ## Context
@@ -145,16 +147,18 @@ Handlers receive a unified `ctx` object. Key properties:
 | Property | Description |
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
-| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
 | `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
+| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.fail` | Throw a typed error checked against the `errors[]` contract — `ctx.fail('reason', message, { recovery? })`. |
 | `ctx.notifyPromptListChanged` | Notify clients that the prompt list changed (call after dynamic prompt registration). |
 | `ctx.notifyToolListChanged` | Notify clients that the tool list changed (call after dynamic tool registration). |
 | `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 
 ---
 
@@ -162,7 +166,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -174,7 +178,7 @@ errors: [
 ],
 async handler(input, ctx) {
   const item = await db.find(input.id);
-  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
   return item;
 }
 ```
@@ -237,7 +241,7 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
+Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -254,30 +258,29 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
-| `tool-defs-analysis` | Read-only audit of definition language: voice, leaks, defaults, recovery hints, examples |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
-| `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` |
-| `git-wrapup` | Version-bump, changelog, commit, and tag workflow |
-| `release-and-publish` | Ship a release: verification gate, push commits+tags, publish to npm / MCP Registry / GHCR / `.mcpb` bundle on GitHub Releases |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
-| `api-linter` | Definition lint rules reference (`format-parity`, `schema-*`, `server-json-*`, …) |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
-| `api-mirror` | MirrorService — persistent local SQLite mirror of a bulk upstream dataset (Tier 3 opt-in) |
 | `api-workers` | Cloudflare Workers runtime |
-| `techniques` | Catalog of reusable response/data-shaping patterns — overflow handling, payload shaping, retrieval — when a payload is too large or awkwardly shaped |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
-| `report-issue-framework` | File bug/feature request against @cyanheads/mcp-ts-core |
-| `report-issue-local` | File bug/feature request against this server's repo |
+| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 
 **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
 
@@ -292,11 +295,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run build` | Compile TypeScript |
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
-| `bun run devcheck` | Lint + format + typecheck + security + packaging alignment |
+| `bun run devcheck` | Lint + format + typecheck + security + packaging alignment + changelog sync |
 | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
 | `bun run tree` | Generate directory structure doc |
-| `bun run format` | Auto-fix formatting |
-| `bun run test` | Run tests |
+| `bun run format` | Auto-fix formatting (safe fixes only) |
+| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
+| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
+| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run lint:mcp` | Validate MCP definitions against spec |
 | `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` (skipped cleanly when `manifest.json` is absent) |
 | `bun run list-skills` | List skills in `skills/` with name + description |
@@ -342,14 +348,16 @@ Each per-version file opens with YAML frontmatter:
 ---
 summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
 breaking: false                            # optional — true flags breaking changes
-security: false                            # optional — true flags security fixes
+security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 
 **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 

package/Dockerfile

@@ -4,15 +4,19 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3 AS build
+FROM oven/bun:1.3.14 AS build
 
 WORKDIR /usr/src/app
 
 # Copy dependency manifests for optimized layer caching
 COPY package.json bun.lock ./
 
-# Install all dependencies (including dev dependencies for building)
-RUN bun install --frozen-lockfile
+# Install all dependencies (including dev dependencies for building).
+# The BuildKit cache mount persists Bun's global package cache across builds.
+# --ignore-scripts keeps a dependency's native postinstall (node-gyp under Bun)
+# from aborting the build; tsc needs type declarations, not compiled bindings.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts
 
 # Copy the rest of the source code
 COPY . .
@@ -29,7 +33,7 @@ RUN bun scripts/build.ts
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3-slim AS production
+FROM oven/bun:1.3.14-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -50,14 +54,16 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
-RUN bun install --production --frozen-lockfile --ignore-scripts
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
 # with: docker build --build-arg OTEL_ENABLED=true
 ARG OTEL_ENABLED=true
-RUN if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add @hono/otel \
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    if [ "$OTEL_ENABLED" = "true" ]; then \
+      bun add --omit=dev --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.16-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/earthquake-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/earthquake-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/earthquake-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.3.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/earthquake-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/earthquake-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/earthquake-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -46,6 +46,8 @@ Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time w
 - Five magnitude tiers: `all` (microseisms), `1.0`, `2.5`, `4.5`, and `significant` (USGS-curated by magnitude, felt reports, and PAGER impact)
 - Four time windows: `hour`, `day`, `week`, `month`
 - Returns event list with counts and the source feed URL
+- Paged with an opaque `cursor`: `limit` bounds a page (default 100, max 1000), `totalCount` reports the whole feed, and `nextCursor` retrieves the rest — the broad tiers run past 10,000 events for `month`
+- The cursor is opaque because these feeds have no upstream paging parameter and USGS regenerates them about once a minute; a numeric offset across two calls would skip or repeat events
 - Best for real-time "what's happening now" queries; use `earthquake_search` for historical or filtered queries
 
 ---
@@ -54,13 +56,15 @@ Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time w
 
 Search earthquakes by time range, magnitude, depth, location radius, PAGER alert level, or felt reports.
 
-- Dual-source: USGS (global, richer metadata) or EMSC (European-Mediterranean, independent catalog for cross-verification)
+- Dual-source: USGS (global, richer metadata) or EMSC (an independent global catalog from the European-Mediterranean Seismological Centre, for cross-verification anywhere)
 - Full FDSN ComCat query API parameters: time range, magnitude, depth, location radius
 - USGS-specific filters: PAGER alert level (`green`/`yellow`/`orange`/`red`), DYFI felt reports count, significance score
 - Location-based queries: provide `latitude`, `longitude`, and `radius_km` together
 - Sort by time (newest first) or magnitude (largest first), ascending or descending
-- Results capped at 20,000 events per query; use `earthquake_count` first to gauge result size
-- USGS-specific filters are silently ignored when `source=emsc`
+- One call returns at most 20,000 events; page beyond that with `offset`, forwarded straight to the upstream FDSN `offset` parameter on both sources
+- `offset` counts from 1, matching both upstream APIs — a capped result carries `totalCount` and the `nextOffset` to pass on the following call
+- Use `earthquake_count` first to gauge result size
+- USGS-specific filters are not supported by EMSC — when `source=emsc` they are dropped and named in `ignoredFilters`, so an unconstrained result set is never mistaken for a filtered one
 
 ---
 
@@ -70,8 +74,10 @@ Count earthquakes matching filters without fetching full records.
 
 - Lightweight alternative to `earthquake_search` for statistical queries ("how many M5+ events in 2025?")
 - Same filter surface as `earthquake_search`: time, magnitude, depth, location radius, PAGER, DYFI, significance
-- Returns `exceeds_limit` flag when count exceeds 20,000 — signals that a full search would be truncated
+- Returns `exceeds_limit` flag when count exceeds 20,000 — signals a full search needs paging
+- Echoes the effective query back as `queryEcho`, including the resolved time window — omitting `start_time` counts only the last 30 days
 - USGS returns the `max_allowed` cap (20,000); EMSC count endpoint does not expose this field (`max_allowed` will be null)
+- USGS-specific filters are dropped and named in `ignoredFilters` when `source=emsc`, the same as on `earthquake_search`
 
 ---
 
@@ -87,7 +93,7 @@ Fetch complete detail for a specific earthquake by USGS event ID.
 
 | Type | URI pattern | Description |
 |:---|:---|:---|
-| Resource | `earthquake://feed/{magnitude_tier}/{time_window}` | USGS real-time earthquake feed as injectable context |
+| Resource | `earthquake://feed/{magnitude_tier}/{time_window}` | USGS real-time earthquake feed as injectable context — returns the whole feed, so use the `earthquake_get_feed` tool for the broad tiers |
 | Resource | `earthquake://event/{event_id}` | Full USGS earthquake event detail by ID as injectable context |
 
 ## Features
@@ -103,7 +109,7 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
 
 Earthquake-specific:
 
-- Two independent data sources: USGS ComCat (global, full metadata) and EMSC SeismicPortal (European-Mediterranean, independent catalog)
+- Two independent global data sources: USGS ComCat (full metadata) and EMSC SeismicPortal (an independent catalog from the European-Mediterranean Seismological Centre, with no PAGER/DYFI/ShakeMap metadata and station coverage densest around Europe and the Mediterranean)
 - USGS real-time GeoJSON feeds (CDN-cached, fast availability) plus FDSN event query API
 - EMSC FDSN-WS event and count endpoints
 - No API key required — both USGS and EMSC are fully public
@@ -112,7 +118,10 @@ Agent-friendly output:
 
 - Source attribution on every response (`usgs` / `emsc`) so agents can reason about data provenance
 - `exceeds_limit` flag on count responses surfaces truncation risk before a full search
-- USGS-specific fields (`alert_level`, `felt`, `mmi`, `tsunami`) clearly labeled as USGS-only to prevent misattribution on EMSC results
+- Fields a source does not publish come back `null`, never as a fabricated zero — `tsunami` and `status` are null on EMSC events, and the rendered text says "not published by source" rather than "no tsunami" or "reviewed"
+- `source_catalog` and `auth` carry provenance (which catalog and which authoritative agency produced a solution) so agents can weigh two sources against each other
+- USGS-only filters dropped for an EMSC query are named in `ignoredFilters` on both `earthquake_search` and `earthquake_count`
+- An upstream 4xx surfaces the service's own explanation (the offending parameter and its accepted format) in the error message, not just a status code
 
 ## Getting started
 

package/dist/index.js

@@ -19,7 +19,7 @@ await createApp({
     instructions: 'Use the earthquake_* tools to query seismic data from USGS ComCat and the EMSC SeismicPortal; no API key required. ' +
         'earthquake_get_feed gives USGS real-time magnitude tiers for current activity; earthquake_search handles historical or filtered queries, sized first with earthquake_count (search caps at 20,000 events). ' +
         'Both emit network-specific event IDs (e.g. us6000sznj) for earthquake_get_event, which returns full USGS detail (EMSC has no per-event endpoint). ' +
-        'USGS carries richer metadata (PAGER, DYFI, ShakeMap); source=emsc uses the independent European-Mediterranean catalog and ignores USGS-only filters.',
+        'USGS carries richer metadata (PAGER, DYFI, ShakeMap); source=emsc is an independent global catalog from the European-Mediterranean Seismological Centre, useful for cross-checking an event of any region against a separate network, and does not apply USGS-only filters (the response names them in ignoredFilters).',
     tools: [earthquakeGetFeed, earthquakeSearch, earthquakeGetEvent, earthquakeCount],
     resources: [earthquakeFeedResource, earthquakeEventResource],
     prompts: [],

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,EAAE,sBAAsB,EAAE,MAAM,gEAAgE,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,yDAAyD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,0DAA0D,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,YAAY,EACV,qHAAqH;QACrH,6MAA6M;QAC7M,oJAAoJ;QACpJ,sJAAsJ;IACxJ,KAAK,EAAE,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,CAAC;IACjF,SAAS,EAAE,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAC5D,OAAO,EAAE,EAAE;IACX,OAAO,EAAE;QACP,0EAA0E;QAC1E,2FAA2F;QAC3F,WAAW,EAAE,KAAK;KACnB;IACD,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACxF,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC1F,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,EAAE,sBAAsB,EAAE,MAAM,gEAAgE,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,yDAAyD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,0DAA0D,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,YAAY,EACV,qHAAqH;QACrH,6MAA6M;QAC7M,oJAAoJ;QACpJ,yTAAyT;IAC3T,KAAK,EAAE,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,CAAC;IACjF,SAAS,EAAE,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAC5D,OAAO,EAAE,EAAE;IACX,OAAO,EAAE;QACP,0EAA0E;QAC1E,2FAA2F;QAC3F,WAAW,EAAE,KAAK;KACnB;IACD,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACxF,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC1F,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/earthquake-event.resource.d.ts

@@ -26,13 +26,15 @@ export declare const earthquakeEventResource: import("@cyanheads/mcp-ts-core").R
             orange: "orange";
             red: "red";
         }>>;
-        tsunami: z.ZodNumber;
+        tsunami: z.ZodNullable<z.ZodNumber>;
         significance: z.ZodNullable<z.ZodNumber>;
-        status: z.ZodEnum<{
+        status: z.ZodNullable<z.ZodEnum<{
             automatic: "automatic";
             reviewed: "reviewed";
             deleted: "deleted";
-        }>;
+        }>>;
+        source_catalog: z.ZodOptional<z.ZodString>;
+        auth: z.ZodOptional<z.ZodString>;
         event_url: z.ZodOptional<z.ZodString>;
         detail_url: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;

package/dist/mcp-server/resources/definitions/earthquake-event.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"earthquake-event.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-event.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMrD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAkClC,CAAC"}
+{"version":3,"file":"earthquake-event.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-event.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMrD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAkClC,CAAC"}

package/dist/mcp-server/resources/definitions/earthquake-feed.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"earthquake-feed.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-feed.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAiBrD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;6BA8FjC,CAAC"}
+{"version":3,"file":"earthquake-feed.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-feed.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAiBrD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;6BAiGjC,CAAC"}

package/dist/mcp-server/resources/definitions/earthquake-feed.resource.js

@@ -18,7 +18,10 @@ export const earthquakeFeedResource = resource('earthquake://feed/{magnitude_tie
     title: 'USGS Earthquake Feed',
     description: 'Direct access to a USGS real-time earthquake feed as injectable context. ' +
         'magnitude_tier: all | 1.0 | 2.5 | 4.5 | significant. ' +
-        'time_window: hour | day | week | month.',
+        'time_window: hour | day | week | month. ' +
+        'Returns the whole feed in one read — the URI carries no paging, so the broad combinations ' +
+        '("all" or "1.0" with "week" or "month") can run to thousands of events. ' +
+        'Use the earthquake_get_feed tool for those: it serves the same data a bounded page at a time.',
     mimeType: 'application/json',
     params: z.object({
         magnitude_tier: z.string().describe('Magnitude tier: all, 1.0, 2.5, 4.5, or significant.'),

package/dist/mcp-server/resources/definitions/earthquake-feed.resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"earthquake-feed.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-feed.resource.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"earthquake-feed.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/earthquake-feed.resource.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/earthquake-count.tool.d.ts

@@ -42,7 +42,39 @@ export declare const earthquakeCount: import("@cyanheads/mcp-ts-core").ToolDefin
 }, {
     readonly reason: "source_unavailable";
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: "Selected source API returns non-2xx or times out.";
+    readonly when: "Selected source API returns a 5xx or is unreachable.";
+    readonly retryable: true;
     readonly recovery: "Try the other source (usgs or emsc) or retry after a short delay.";
-}], undefined>;
+}, {
+    readonly reason: "source_timeout";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "Selected source API did not answer before the request deadline.";
+    readonly retryable: true;
+    readonly recovery: string;
+}, {
+    readonly reason: "upstream_rejected";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "The source API rejected the query parameters with a 4xx response.";
+    readonly recovery: string;
+}], {
+    readonly queryEcho: z.ZodOptional<z.ZodObject<{
+        start_time: z.ZodOptional<z.ZodString>;
+        end_time: z.ZodOptional<z.ZodString>;
+        min_magnitude: z.ZodOptional<z.ZodNumber>;
+        max_magnitude: z.ZodOptional<z.ZodNumber>;
+        latitude: z.ZodOptional<z.ZodNumber>;
+        longitude: z.ZodOptional<z.ZodNumber>;
+        radius_km: z.ZodOptional<z.ZodNumber>;
+        min_depth_km: z.ZodOptional<z.ZodNumber>;
+        max_depth_km: z.ZodOptional<z.ZodNumber>;
+        alert_level: z.ZodOptional<z.ZodString>;
+        min_felt: z.ZodOptional<z.ZodNumber>;
+        min_significance: z.ZodOptional<z.ZodNumber>;
+        source: z.ZodEnum<{
+            usgs: "usgs";
+            emsc: "emsc";
+        }>;
+    }, z.core.$strip>>;
+    readonly ignoredFilters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}>;
 //# sourceMappingURL=earthquake-count.tool.d.ts.map

package/dist/mcp-server/tools/definitions/earthquake-count.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"earthquake-count.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/earthquake-count.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAM3E,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqM1B,CAAC"}
+{"version":3,"file":"earthquake-count.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/earthquake-count.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAO3E,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsV1B,CAAC"}

package/dist/mcp-server/tools/definitions/earthquake-count.tool.js

@@ -4,7 +4,8 @@
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
-import { buildQueryParams } from '../../../mcp-server/tools/query-params.js';
+import { upstreamRejection } from '../../../mcp-server/tools/fdsn-error.js';
+import { buildQueryParams, ignoredUsgsFilters } from '../../../mcp-server/tools/query-params.js';
 import { getEmscService } from '../../../services/emsc/emsc-service.js';
 import { getUsgsService } from '../../../services/usgs/usgs-service.js';
 export const earthquakeCount = tool('earthquake_count', {
@@ -12,11 +13,14 @@ export const earthquakeCount = tool('earthquake_count', {
     description: 'Count earthquakes matching filters without fetching full records. ' +
         'Use for statistical queries ("how many M5+ earthquakes in 2025?") or to gauge result size ' +
         'before calling earthquake_search. ' +
+        'Omitting start_time counts only the last 30 days, so pass an explicit range for any ' +
+        'period-specific question; queryEcho reports the window and filters the count actually covers. ' +
         'When exceeds_limit is true, the count exceeds 20,000 and a full search would be truncated — ' +
         'narrow filters before fetching. ' +
         'USGS returns the max_allowed cap (20,000); EMSC count endpoint does not return this field ' +
         '(max_allowed will be null). ' +
-        'USGS-specific filters (alert_level, min_felt, min_significance) are ignored when source=emsc.',
+        'USGS-specific filters (alert_level, min_felt, min_significance) are not sent when source=emsc — ' +
+        'the response names them in ignoredFilters.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     input: z.object({
         start_time: z
@@ -84,9 +88,12 @@ export const earthquakeCount = tool('earthquake_count', {
         source: z
             .enum(['usgs', 'emsc'])
             .default('usgs')
-            .describe('Data source. ' +
+            .describe('Data source. Both catalogs are global. ' +
             '"usgs" covers global events with PAGER, DYFI, and ShakeMap metadata. ' +
-            '"emsc" covers the European-Mediterranean region.'),
+            '"emsc" is an independent global catalog operated by the European-Mediterranean ' +
+            'Seismological Centre — use it to cross-check a count from a separate network. ' +
+            'It has no PAGER, DYFI, or ShakeMap metadata; its station coverage is densest around ' +
+            'Europe and the Mediterranean, so counts of small events differ most by region.'),
     }),
     output: z.object({
         count: z.number().describe('Number of events matching the query.'),
@@ -102,6 +109,66 @@ export const earthquakeCount = tool('earthquake_count', {
             'For EMSC, evaluated against the known 20000 limit since max_allowed is not returned. ' +
             'Narrow filters to retrieve all matching events.'),
     }),
+    // A count is a single number with no context of its own — the window and filters
+    // it covers have to travel with it, including the server-resolved 30-day default.
+    // Populated via ctx.enrich(...) so it reaches structuredContent and content[].
+    enrichment: {
+        queryEcho: z
+            .object({
+            start_time: z
+                .string()
+                .optional()
+                .describe('Effective query start time sent upstream — server-resolved to a 30-day window when omitted from input.'),
+            end_time: z
+                .string()
+                .optional()
+                .describe('Effective query end time. Absent when omitted from input — the upstream defaults to the current time.'),
+            min_magnitude: z.number().optional().describe('Minimum magnitude filter sent upstream.'),
+            max_magnitude: z.number().optional().describe('Maximum magnitude filter sent upstream.'),
+            latitude: z.number().optional().describe('Radius-search latitude sent upstream.'),
+            longitude: z.number().optional().describe('Radius-search longitude sent upstream.'),
+            radius_km: z
+                .number()
+                .optional()
+                .describe('Search radius in km sent upstream (converted to degrees for EMSC).'),
+            min_depth_km: z.number().optional().describe('Minimum depth filter sent upstream.'),
+            max_depth_km: z.number().optional().describe('Maximum depth filter sent upstream.'),
+            alert_level: z
+                .string()
+                .optional()
+                .describe('PAGER alert filter sent upstream. Absent for EMSC — not supported there.'),
+            min_felt: z
+                .number()
+                .optional()
+                .describe('DYFI felt-report filter sent upstream. Absent for EMSC — not supported there.'),
+            min_significance: z
+                .number()
+                .optional()
+                .describe('Significance filter sent upstream. Absent for EMSC — not supported there.'),
+            source: z.enum(['usgs', 'emsc']).describe('Data source queried.'),
+        })
+            .optional()
+            .describe('Echo of the effective parameters the count covers, including server-resolved defaults. ' +
+            'Read start_time and end_time to know which window the count spans — a filter absent ' +
+            'here was not sent upstream.'),
+        ignoredFilters: z
+            .array(z.string().describe('Name of an input filter that was not applied.'))
+            .optional()
+            .describe('USGS-only filters supplied in the input but not sent upstream because source=emsc ' +
+            'does not support them. The count is NOT constrained by these — re-run with ' +
+            'source=usgs to apply them. Absent when every supplied filter was applied.'),
+    },
+    enrichmentTrailer: {
+        queryEcho: {
+            render: (q) => `**Query echo:** ${Object.entries(q ?? {})
+                .map(([key, value]) => `${key}=${String(value)}`)
+                .join(' · ')}`,
+        },
+        ignoredFilters: {
+            render: (f) => `**Ignored filters (not supported by EMSC, not sent upstream):** ${(f ?? []).join(', ')} — ` +
+                'this count is NOT constrained by the listed filters. Re-run with source=usgs to apply them.',
+        },
+    },
     errors: [
         {
             reason: 'invalid_radius',
@@ -112,9 +179,25 @@ export const earthquakeCount = tool('earthquake_count', {
         {
             reason: 'source_unavailable',
             code: JsonRpcErrorCode.ServiceUnavailable,
-            when: 'Selected source API returns non-2xx or times out.',
+            when: 'Selected source API returns a 5xx or is unreachable.',
+            retryable: true,
             recovery: 'Try the other source (usgs or emsc) or retry after a short delay.',
         },
+        {
+            reason: 'source_timeout',
+            code: JsonRpcErrorCode.Timeout,
+            when: 'Selected source API did not answer before the request deadline.',
+            retryable: true,
+            recovery: 'Narrow the time range or raise min_magnitude so the upstream count scans a smaller ' +
+                'window, then retry. Counts over multi-year spans are the usual cause.',
+        },
+        {
+            reason: 'upstream_rejected',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'The source API rejected the query parameters with a 4xx response.',
+            recovery: 'Read the upstream reason in the error message — it names the offending parameter and ' +
+                'the accepted format. Correct that parameter and call again.',
+        },
     ],
     async handler(input, ctx) {
         const latProvided = input.latitude != null;
@@ -144,6 +227,20 @@ export const earthquakeCount = tool('earthquake_count', {
                     ...ctx.recoveryFor('source_unavailable'),
                 });
             }
+            // A timeout classifies as Timeout, not ServiceUnavailable — it needs its own
+            // branch or it bypasses the contract and reaches the caller with no recovery hint.
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.Timeout) {
+                throw ctx.fail('source_timeout', err.message, {
+                    ...ctx.recoveryFor('source_timeout'),
+                });
+            }
+            // A 4xx means the upstream rejected the parameters, and its body says which one.
+            // The framework leaves that body out of the message, so fold it in here — otherwise
+            // content[]-only clients see a bare status code.
+            const rejection = upstreamRejection(err);
+            if (rejection) {
+                throw ctx.fail('upstream_rejected', `${input.source.toUpperCase()} rejected the query: ${rejection.reason}`, { ...ctx.recoveryFor('upstream_rejected'), status: rejection.status }, { cause: err });
+            }
             throw err;
         }
         ctx.log.info('Count completed', {
@@ -151,6 +248,33 @@ export const earthquakeCount = tool('earthquake_count', {
             count: result.count,
             exceeds_limit: result.exceedsLimit,
         });
+        // Echo the effective upstream parameters — USGS-only filters are excluded for
+        // EMSC because buildFdsnQuery does not send them.
+        const isUsgs = input.source !== 'emsc';
+        ctx.enrich({
+            queryEcho: {
+                ...(params.startTime != null ? { start_time: params.startTime } : {}),
+                ...(params.endTime != null ? { end_time: params.endTime } : {}),
+                ...(params.minMagnitude != null ? { min_magnitude: params.minMagnitude } : {}),
+                ...(params.maxMagnitude != null ? { max_magnitude: params.maxMagnitude } : {}),
+                ...(params.latitude != null ? { latitude: params.latitude } : {}),
+                ...(params.longitude != null ? { longitude: params.longitude } : {}),
+                ...(params.radiusKm != null ? { radius_km: params.radiusKm } : {}),
+                ...(params.minDepthKm != null ? { min_depth_km: params.minDepthKm } : {}),
+                ...(params.maxDepthKm != null ? { max_depth_km: params.maxDepthKm } : {}),
+                ...(isUsgs && params.alertLevel != null ? { alert_level: params.alertLevel } : {}),
+                ...(isUsgs && params.minFelt != null ? { min_felt: params.minFelt } : {}),
+                ...(isUsgs && params.minSignificance != null
+                    ? { min_significance: params.minSignificance }
+                    : {}),
+                source: input.source,
+            },
+        });
+        // An absence from queryEcho is too quiet a signal that a supplied filter never
+        // constrained the count — name the dropped filters outright.
+        const ignoredFilters = ignoredUsgsFilters(input, input.source);
+        if (ignoredFilters.length > 0)
+            ctx.enrich({ ignoredFilters });
         return {
             count: result.count,
             max_allowed: result.maxAllowed,