@cyanheads/gdelt-mcp-server 0.2.3 → 0.2.5

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** gdelt-mcp-server
-**Version:** 0.2.3
+**Version:** 0.2.5
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.3-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/gdelt-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/gdelt-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gdelt-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.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.2.5-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/gdelt-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/gdelt-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gdelt-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.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -33,13 +33,13 @@ Nine tools across two GDELT APIs — DOC API for global print/web news (last 3 m
 
 | Tool | Description |
 |:---|:---|
-| `gdelt_search_articles` | Search the last 3 months of global news coverage (65 languages) with full-text and filter operators. Returns up to 250 articles. |
-| `gdelt_get_coverage_timeline` | Retrieve a time series of coverage volume or average tone for a query. `volume_with_articles` mode includes top articles per spike timestep. |
+| `gdelt_search_articles` | Search the last 3 months of global news coverage (65 languages) with full-text and filter operators. Returns up to 250 articles, and hands back the date windows to re-query when that ceiling is hit. |
+| `gdelt_get_coverage_timeline` | Retrieve a time series of coverage volume or average tone for a query. `volume_with_articles` mode includes top articles per spike timestep, with `points` to render a timestep's full article list. |
 | `gdelt_get_tone_distribution` | Get a tone histogram (bins ~−30 to +30) showing whether coverage is uniformly negative, bimodal, or clustered near neutral. |
-| `gdelt_get_coverage_breakdown` | Break down coverage volume by source language or source country — a multi-series time series showing geographic propagation. |
+| `gdelt_get_coverage_breakdown` | Break down coverage volume by source language or source country — a multi-series time series showing geographic propagation. Values are normalized shares of media output, not article counts. |
 | `gdelt_search_tv` | Search US television news closed captions (2009–Oct 2024) and return per-station airtime time series. |
-| `gdelt_get_tv_clips` | Retrieve up to 3,000 matching TV clips with transcript excerpts and Internet Archive viewing links. |
-| `gdelt_get_tv_context` | Get the 200 most frequent co-occurring words and phrases from TV clips matching a query. |
+| `gdelt_get_tv_clips` | Retrieve up to 3,000 matching TV clips with transcript excerpts and Internet Archive viewing links, and the date windows to re-query when that ceiling is hit. |
+| `gdelt_get_tv_context` | Get the most frequent co-occurring words and phrases from TV clips matching a query. |
 | `gdelt_get_tv_trending` | Retrieve trending topics currently dominating US television news (updated every 15 minutes; no query required). |
 | `gdelt_list_tv_stations` | List all TV stations with market, network, and monitoring date ranges to verify station availability before querying. |
 
@@ -52,6 +52,7 @@ Search the last 3 months of global news with GDELT's full query syntax.
 - Proximity and repetition: `near20:"flu virus"`, `repeat3:"outbreak"`
 - Configurable sort (relevance, date) and result count (up to 250)
 - Returns URL, title, publication date, domain, language, source country, and social image URL
+- 250 is a hard per-call ceiling, not a page size — GDELT exposes no cursor. Fill it and the response returns `continuationWindows`: the queried window halved, ready to re-query. The halves overlap by a second so nothing falls through the seam; de-duplicate by `url`
 - Query is echoed in response for chaining
 
 ---
@@ -63,6 +64,7 @@ Retrieve when coverage of a topic spiked, with three modes:
 - `volume` — normalized percentage of all global coverage per timestep
 - `volume_with_articles` — volume plus top articles driving each spike; use for signal detection without a follow-up search call
 - `tone` — average sentiment score per timestep (combine with `gdelt_get_tone_distribution` for the full picture)
+- Every article reference is always in `structuredContent`; the text surface renders the first 3 links per timestep beside that timestep's true count, and `points: ["<date>"]` renders named timesteps in full
 - Configurable smoothing and time range
 
 ---
@@ -82,7 +84,9 @@ Snapshot tone histogram across all articles matching a query.
 Multi-series time series showing which countries or languages drove coverage.
 
 - Break down by `language` or `country`
-- Top 10 series by total volume; remaining series aggregated into an "Other" bucket
+- Top 10 series by total volume; remaining series aggregated into an "Other" bucket and named in `otherSeriesLabels`
+- Nothing is dissolved into "Other" anonymously — pass any label to `series: ["<label>"]` and that series comes back complete under `selectedSeries`, alongside the usual overview
+- Values are normalized — the topic's share of media output, not absolute article counts. Small media markets with concentrated coverage rank above large markets with diverse output, so a high value means the topic dominated that source's coverage rather than that it published the most articles
 - Use to trace how a story propagated geographically
 
 ---
@@ -104,6 +108,7 @@ Retrieve actual TV news clips driving a coverage signal.
 
 - Up to 3,000 clips per call
 - Each clip: show name, station, air timestamp, 15-second transcript excerpt, direct Archive.org link, and optional thumbnail
+- 3,000 is a hard per-call ceiling, not a page size — GDELT exposes no cursor. Fill it and the response returns `continuationWindows`: the queried window halved, ready to re-query. The halves overlap by a second so nothing falls through the seam; de-duplicate by `archiveUrl`
 - Sort by relevance, date descending, or date ascending
 
 ---
@@ -112,7 +117,7 @@ Retrieve actual TV news clips driving a coverage signal.
 
 Vocabulary framing analysis for TV coverage of a topic.
 
-- Returns the 200 most frequent non-stopword terms from matching clips
+- Returns the most frequent non-stopword terms from matching clips
 - Relative frequency scores (query term = 100)
 - Use to identify narrative framing, related concepts, or follow-up search terms
 

package/changelog/0.2.x/0.2.4.md

@@ -0,0 +1,14 @@
+---
+summary: "Fixed: content[] omitted array data five tools returned in full in structuredContent (#19); gdelt_get_coverage_breakdown now documents its normalized values (#10)"
+breaking: false
+security: false
+---
+
+# 0.2.4 — 2026-07-15
+
+## Fixed
+
+- **`gdelt_get_tone_distribution`, `gdelt_get_tv_context`, `gdelt_get_tv_trending`** — `format()` sliced `content[]` to 2/50/50 elements while `structuredContent` carried the full array; clients reading only the text surface lost data. All three now render every element ([#19](https://github.com/cyanheads/gdelt-mcp-server/issues/19)).
+- **`gdelt_get_coverage_timeline`** — removed the 10-point cap on rendered series points; every point's date and value now renders. The per-point article link list stays capped at 3 (`ARTICLES_PER_POINT`), tracked separately in [#24](https://github.com/cyanheads/gdelt-mcp-server/issues/24) ([#19](https://github.com/cyanheads/gdelt-mcp-server/issues/19)).
+- **`gdelt_get_coverage_breakdown`** — `format()` rendered only each series' total and peak; every `topSeries` and `otherAggregated` point now renders. `gdelt_search_tv`'s series points remain unrendered in `content[]`, tracked separately in [#23](https://github.com/cyanheads/gdelt-mcp-server/issues/23) ([#19](https://github.com/cyanheads/gdelt-mcp-server/issues/19)).
+- **`gdelt_get_coverage_breakdown`** — description, `format()` output, and the `topSeries`/`otherAggregated` schema descriptions now state that values are normalized shares of a source's media output, not absolute article counts ([#10](https://github.com/cyanheads/gdelt-mcp-server/issues/10)).

package/changelog/0.2.x/0.2.5.md

@@ -0,0 +1,21 @@
+---
+summary: "Added: selectable series (#20) and named point expansion (#24); search_articles/get_tv_clips return continuationWindows instead of a dead-end cap notice (#21)"
+breaking: false
+security: false
+---
+
+# 0.2.5 — 2026-07-15
+
+## Added
+
+- **`gdelt_get_coverage_breakdown`** — optional `series: string[]` input returns each named label complete under a new `selectedSeries` output, alongside the existing top-10 overview. New optional `otherSeriesLabels` output names every series folded into "Other", ranked by volume. An unmatched label throws `unknown_series`, listing the labels actually available ([#20](https://github.com/cyanheads/gdelt-mcp-server/issues/20)).
+- **`gdelt_get_coverage_timeline`** — optional `points: string[]` input renders a named timestep's complete article list in the text surface, echoed in the new optional `expandedPoints` output. An unmatched date throws `unknown_point`, listing the timeline's actual dates ([#24](https://github.com/cyanheads/gdelt-mcp-server/issues/24)).
+- **`gdelt_search_articles`, `gdelt_get_tv_clips`** — new optional `continuationWindows` enrichment field returns the queried `startDatetime`/`endDatetime` window halved once `maxRecords` is at its ceiling (250 / 3,000), ready to re-query. Halves overlap by one second so a record timestamped exactly on the seam is never silently dropped — de-duplicate by `url` / `archiveUrl` on reassembly. Shared window-partition helpers (`resolveEffectiveWindow`, `splitWindow`, `planWindowContinuation`) added to `src/mcp-server/tools/date-range.ts` ([#21](https://github.com/cyanheads/gdelt-mcp-server/issues/21)).
+
+## Changed
+
+- **`gdelt_get_coverage_timeline`** — capped article rendering now states how many links it showed next to the true count (`"8 articles, 3 shown"`), instead of an unqualified count; a timestep whose articles all fit claims nothing withheld ([#24](https://github.com/cyanheads/gdelt-mcp-server/issues/24)).
+
+## Fixed
+
+- **`gdelt_search_articles`, `gdelt_get_tv_clips`** — the cap-hit notice no longer tells the caller to raise `maxRecords` when it is already at its ceiling; it now states the ceiling is GDELT's own and points to `continuationWindows` ([#21](https://github.com/cyanheads/gdelt-mcp-server/issues/21)).

package/dist/mcp-server/tools/date-range.d.ts

@@ -1,7 +1,8 @@
 /**
- * @fileoverview Shared date-range input constraints for the GDELT tools that accept
- * an explicit startDatetime/endDatetime window — the YYYYMMDDHHMMSS field pattern
- * and the both-or-neither pairing predicate.
+ * @fileoverview Shared date-range handling for the GDELT tools that accept an explicit
+ * startDatetime/endDatetime window — the YYYYMMDDHHMMSS field pattern, the both-or-neither
+ * pairing predicate, and the window partitioning the record-cap tools hand back as a
+ * continuation contract.
  * @module mcp-server/tools/date-range
  */
 /**
@@ -11,6 +12,57 @@
  * Schema as `pattern`, letting a caller see the constraint before it calls.
  */
 export declare const GDELT_DATETIME_PATTERN: RegExp;
+/** A GDELT query window, both boundaries in the 14-digit YYYYMMDDHHMMSS wire format. */
+export type GdeltWindow = {
+    startDatetime: string;
+    endDatetime: string;
+};
+/** Format a Date as GDELT's 14-digit YYYYMMDDHHMMSS wire format (UTC). */
+export declare function toGdeltDatetime(date: Date): string;
+/**
+ * The window a call actually ran against, in GDELT's wire format.
+ *
+ * Mirrors `applyTimeRange()`'s precedence: an explicit boundary pair wins, a timespan
+ * is resolved against now, and a call that pinned neither gets `undefined` rather than
+ * a guessed window — GDELT's own default is not something this server can observe.
+ */
+export declare function resolveEffectiveWindow(args: {
+    timespan?: string | undefined;
+    startDatetime?: string | undefined;
+    endDatetime?: string | undefined;
+}): GdeltWindow | undefined;
+/**
+ * Split a window into two halves whose union covers it exactly, or `undefined` when it
+ * is already too narrow to divide.
+ *
+ * The second half deliberately **overlaps** the first by one second rather than resuming
+ * at the shared midpoint. GDELT documents both boundaries as exclusive — STARTDATETIME
+ * considers "only articles published *after* this date/time stamp" and ENDDATETIME "only
+ * articles published *before*" it (DOC 2.0 and TV 2.0 API docs alike) — so halves that
+ * merely touch at the midpoint would drop every record timestamped exactly there, silently.
+ *
+ * Reaching back one second closes that seam: under the documented exclusive reading the
+ * two halves tile the original window with no gap and no repeat, and if the boundaries
+ * turn out to behave inclusively instead, the overlap costs at most two seconds of
+ * duplicates — which a caller can see and de-duplicate. Gap-free either way.
+ */
+export declare function splitWindow(window: GdeltWindow): [GdeltWindow, GdeltWindow] | undefined;
+/** The next-call windows and the prose explaining them, for a record cap at its ceiling. */
+export type WindowContinuation = {
+    windows?: [GdeltWindow, GdeltWindow];
+    guidance: string;
+};
+/**
+ * How a caller retrieves records left behind once `maxRecords` is already at its ceiling.
+ *
+ * GDELT exposes no offset or cursor, so narrowing the time window is the only lever, and
+ * each outcome is stated rather than implied: halves to re-query when the window divides,
+ * how to pin a window when the call never set one, and — when the window is already too
+ * narrow to divide — that the remaining records are simply unreachable.
+ *
+ * Callers own the record-noun prose; this covers only the window reasoning both tools share.
+ */
+export declare function planWindowContinuation(window: GdeltWindow | undefined): WindowContinuation;
 /**
  * True when exactly one of the two boundaries is present.
  *

package/dist/mcp-server/tools/date-range.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-range.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-range.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAa,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzF"}
+{"version":3,"file":"date-range.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-range.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAa,CAAC;AAEjD,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAaF,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,WAAW,GAAG,SAAS,CAc1B;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,SAAS,CAcvF;AAED,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,kBAAkB,CA4B1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzF"}

package/dist/mcp-server/tools/date-range.js

@@ -1,9 +1,11 @@
 /**
- * @fileoverview Shared date-range input constraints for the GDELT tools that accept
- * an explicit startDatetime/endDatetime window — the YYYYMMDDHHMMSS field pattern
- * and the both-or-neither pairing predicate.
+ * @fileoverview Shared date-range handling for the GDELT tools that accept an explicit
+ * startDatetime/endDatetime window — the YYYYMMDDHHMMSS field pattern, the both-or-neither
+ * pairing predicate, and the window partitioning the record-cap tools hand back as a
+ * continuation contract.
  * @module mcp-server/tools/date-range
  */
+import { resolveTimespan } from '../../services/gdelt/gdelt-fetch.js';
 /**
  * GDELT's datetime wire format: exactly 14 digits, YYYYMMDDHHMMSS, no separators.
  *
@@ -11,6 +13,108 @@
  * Schema as `pattern`, letting a caller see the constraint before it calls.
  */
 export const GDELT_DATETIME_PATTERN = /^\d{14}$/;
+/** GDELT's datetime resolution — the narrowest window a caller can express. */
+const GDELT_RESOLUTION_MS = 1000;
+/** Parse a 14-digit YYYYMMDDHHMMSS string as UTC. Invalid calendar values yield an Invalid Date. */
+function parseGdeltDatetime(value) {
+    return new Date(`${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}` +
+        `T${value.slice(8, 10)}:${value.slice(10, 12)}:${value.slice(12, 14)}Z`);
+}
+/** Format a Date as GDELT's 14-digit YYYYMMDDHHMMSS wire format (UTC). */
+export function toGdeltDatetime(date) {
+    return date.toISOString().slice(0, 19).replace(/[-:T]/g, '');
+}
+/**
+ * The window a call actually ran against, in GDELT's wire format.
+ *
+ * Mirrors `applyTimeRange()`'s precedence: an explicit boundary pair wins, a timespan
+ * is resolved against now, and a call that pinned neither gets `undefined` rather than
+ * a guessed window — GDELT's own default is not something this server can observe.
+ */
+export function resolveEffectiveWindow(args) {
+    if (args.startDatetime && args.endDatetime) {
+        return { startDatetime: args.startDatetime, endDatetime: args.endDatetime };
+    }
+    if (args.timespan) {
+        const range = resolveTimespan(args.timespan);
+        if (range) {
+            return {
+                startDatetime: toGdeltDatetime(range.start),
+                endDatetime: toGdeltDatetime(range.end),
+            };
+        }
+    }
+    return;
+}
+/**
+ * Smallest span that still divides into two strictly-narrower halves. The second half
+ * reaches back a second to cover the seam, so it costs `span - floor(span/2) + 1`
+ * seconds — only under four does that stop shrinking.
+ */
+const MIN_SPLITTABLE_MS = 4 * GDELT_RESOLUTION_MS;
+/**
+ * Split a window into two halves whose union covers it exactly, or `undefined` when it
+ * is already too narrow to divide.
+ *
+ * The second half deliberately **overlaps** the first by one second rather than resuming
+ * at the shared midpoint. GDELT documents both boundaries as exclusive — STARTDATETIME
+ * considers "only articles published *after* this date/time stamp" and ENDDATETIME "only
+ * articles published *before*" it (DOC 2.0 and TV 2.0 API docs alike) — so halves that
+ * merely touch at the midpoint would drop every record timestamped exactly there, silently.
+ *
+ * Reaching back one second closes that seam: under the documented exclusive reading the
+ * two halves tile the original window with no gap and no repeat, and if the boundaries
+ * turn out to behave inclusively instead, the overlap costs at most two seconds of
+ * duplicates — which a caller can see and de-duplicate. Gap-free either way.
+ */
+export function splitWindow(window) {
+    const start = parseGdeltDatetime(window.startDatetime);
+    const spanMs = parseGdeltDatetime(window.endDatetime).getTime() - start.getTime();
+    if (!Number.isFinite(spanMs) || spanMs < MIN_SPLITTABLE_MS)
+        return;
+    const midpointMs = start.getTime() + Math.floor(spanMs / 2 / GDELT_RESOLUTION_MS) * GDELT_RESOLUTION_MS;
+    return [
+        { startDatetime: window.startDatetime, endDatetime: toGdeltDatetime(new Date(midpointMs)) },
+        {
+            startDatetime: toGdeltDatetime(new Date(midpointMs - GDELT_RESOLUTION_MS)),
+            endDatetime: window.endDatetime,
+        },
+    ];
+}
+/**
+ * How a caller retrieves records left behind once `maxRecords` is already at its ceiling.
+ *
+ * GDELT exposes no offset or cursor, so narrowing the time window is the only lever, and
+ * each outcome is stated rather than implied: halves to re-query when the window divides,
+ * how to pin a window when the call never set one, and — when the window is already too
+ * narrow to divide — that the remaining records are simply unreachable.
+ *
+ * Callers own the record-noun prose; this covers only the window reasoning both tools share.
+ */
+export function planWindowContinuation(window) {
+    if (!window) {
+        return {
+            guidance: 'GDELT exposes no offset or cursor, so narrowing the time window is the only way to reach the rest: ' +
+                'pin one with startDatetime/endDatetime (or a timespan), then re-run this query against successively narrower halves of it.',
+        };
+    }
+    const windows = splitWindow(window);
+    if (!windows) {
+        return {
+            guidance: `The window ${window.startDatetime}–${window.endDatetime} is already too narrow to divide at GDELT's ` +
+                'one-second resolution, so the records past this cap are not retrievable through this API.',
+        };
+    }
+    const [first, second] = windows;
+    return {
+        windows,
+        guidance: 'GDELT exposes no offset or cursor. Re-run this query unchanged against each half of the current window — ' +
+            `${first.startDatetime}–${first.endDatetime}, then ${second.startDatetime}–${second.endDatetime} ` +
+            '(both echoed in continuationWindows) — and split a half again if it also hits the cap. ' +
+            'The halves overlap by one second so nothing falls through the seam, so a record on that second can ' +
+            'appear in both: de-duplicate on re-assembly.',
+    };
+}
 /**
  * True when exactly one of the two boundaries is present.
  *

package/dist/mcp-server/tools/date-range.js.map

@@ -1 +1 @@
-{"version":3,"file":"date-range.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-range.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAsB,EAAE,WAAoB;IAC9E,OAAO,OAAO,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"date-range.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-range.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-coverage-breakdown.tool.d.ts

@@ -14,6 +14,7 @@ export declare const gdeltGetCoverageBreakdown: import("@cyanheads/mcp-ts-core")
     timespan: z.ZodOptional<z.ZodString>;
     startDatetime: z.ZodOptional<z.ZodString>;
     endDatetime: z.ZodOptional<z.ZodString>;
+    series: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>, z.ZodObject<{
     dateResolution: z.ZodEnum<{
         hour: "hour";
@@ -30,11 +31,24 @@ export declare const gdeltGetCoverageBreakdown: import("@cyanheads/mcp-ts-core")
         date: z.ZodString;
         value: z.ZodNumber;
     }, z.core.$strip>>>;
+    otherSeriesLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    selectedSeries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        data: z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            value: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>, readonly [{
     readonly reason: "no_breakdown_data";
     readonly code: JsonRpcErrorCode.NotFound;
     readonly when: "No breakdown data returned for the query.";
     readonly recovery: "Broaden the query, extend the timespan, or verify the query operators are correct.";
+}, {
+    readonly reason: "unknown_series";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "A label passed in the series input matches no series in this breakdown.";
+    readonly recovery: "Read the labels listed in the error and retry series with exact matches from that list.";
 }, {
     readonly reason: "invalid_date_range";
     readonly code: JsonRpcErrorCode.ValidationError;

package/dist/mcp-server/tools/definitions/get-coverage-breakdown.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-coverage-breakdown.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-coverage-breakdown.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAQjE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+PpC,CAAC"}
+{"version":3,"file":"get-coverage-breakdown.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-coverage-breakdown.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAkDjE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsUpC,CAAC"}

package/dist/mcp-server/tools/definitions/get-coverage-breakdown.tool.js

@@ -10,13 +10,53 @@ import { GDELT_DATETIME_PATTERN, isUnpairedDateRange } from '../date-range.js';
 import { inferDateResolution } from '../date-resolution.js';
 /** Maximum number of series to include before aggregating the rest into "Other". */
 const MAX_SERIES = 10;
+/**
+ * One language or country coverage series. Shared by the ranked `topSeries` overview and
+ * the `selectedSeries` arm so a label retrieved by name carries the identical shape it
+ * would have had inside the top 10.
+ */
+const breakdownSeriesSchema = z
+    .object({
+    label: z.string().describe('Series label (language name or country name).'),
+    data: z
+        .array(z
+        .object({
+        date: z.string().describe('Timestep in ISO 8601 format.'),
+        value: z
+            .number()
+            .describe("Normalized coverage volume at this timestep — the topic's share of this " +
+            "source's media output, not an absolute article count."),
+    })
+        .describe('A single data point for this series.'))
+        .describe('Time-ordered data points for this series.'),
+})
+    .describe('A single language or country coverage series.');
+/** Render one series in full — header, total, peak, and every data point. */
+function renderSeries(series) {
+    const total = series.data.reduce((sum, d) => sum + d.value, 0);
+    const peak = series.data.reduce((max, d) => (d.value > max.value ? d : max), series.data[0] ?? { date: '', value: 0 });
+    const lines = [
+        `\n### ${series.label} (total: ${total.toFixed(2)})`,
+        `Data points: ${series.data.length}`,
+    ];
+    if (peak.date)
+        lines.push(`Peak: ${peak.value.toFixed(3)} at ${peak.date}`);
+    for (const d of series.data)
+        lines.push(`- ${d.date}: ${d.value.toFixed(3)}`);
+    return lines;
+}
 export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
     title: 'Get GDELT Coverage Breakdown',
     description: 'Break down news coverage volume over time by source language or source country, returning a ' +
         'multi-series time series (one series per language or country). ' +
         'Shows which countries or languages drove early vs. late coverage — useful for tracing how a ' +
         'story propagated geographically or across language communities. ' +
-        'Returns up to 10 series by total volume; remaining series are aggregated into an "Other" bucket. ' +
+        'Returns up to 10 series by total volume and aggregates the rest into an "Other" bucket, naming ' +
+        'every series it folded in there under otherSeriesLabels — pass any of those labels back as the ' +
+        'series input to get that series complete, ranked or not. ' +
+        "Values are normalized: each point is the topic's share of media output, not an absolute article count. " +
+        'Small media markets with concentrated coverage therefore rank above large markets with diverse output — ' +
+        "a high value means the topic dominated that source's coverage, not that it published the most articles. " +
         'Use breakdownBy "country" with the signal-detection chain to map geographic attention, ' +
         'or "language" to detect non-English media surges.',
     annotations: { readOnlyHint: true, openWorldHint: true },
@@ -27,6 +67,12 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
             when: 'No breakdown data returned for the query.',
             recovery: 'Broaden the query, extend the timespan, or verify the query operators are correct.',
         },
+        {
+            reason: 'unknown_series',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'A label passed in the series input matches no series in this breakdown.',
+            recovery: 'Read the labels listed in the error and retry series with exact matches from that list.',
+        },
         {
             reason: 'invalid_date_range',
             code: JsonRpcErrorCode.ValidationError,
@@ -74,33 +120,41 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
             .optional()
             .describe('End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators ' +
             '(e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected.'),
+        series: z
+            .array(z.string())
+            .optional()
+            .describe('Exact series labels to additionally return in full, e.g. ["Portuguese", "Vietnamese"]. ' +
+            'Take them verbatim from otherSeriesLabels (the series folded into "Other") or topSeries[].label ' +
+            'in a response, or from the label list an unknown_series error prints. Each one comes back complete ' +
+            'under selectedSeries, on top of the usual top-10 overview; a label that matches nothing is rejected ' +
+            'rather than silently skipped. Omit to get the overview alone.'),
     }),
     output: z.object({
         dateResolution: z.enum(['hour', 'day']).describe('Temporal resolution of data points.'),
-        topSeries: z
-            .array(z
-            .object({
-            label: z.string().describe('Series label (language name or country name).'),
-            data: z
-                .array(z
-                .object({
-                date: z.string().describe('Timestep in ISO 8601 format.'),
-                value: z.number().describe('Normalized coverage volume at this timestep.'),
-            })
-                .describe('A single data point for this series.'))
-                .describe('Time-ordered data points for this series.'),
-        })
-            .describe('A single language or country coverage series.'))
-            .describe('Top 10 series by total coverage volume.'),
+        topSeries: z.array(breakdownSeriesSchema).describe('Top 10 series by total coverage volume.'),
         otherAggregated: z
             .array(z
             .object({
             date: z.string().describe('Timestep in ISO 8601 format.'),
-            value: z.number().describe('Aggregated coverage volume for all remaining series.'),
+            value: z
+                .number()
+                .describe('Aggregated normalized coverage volume for all remaining series — a share of ' +
+                'media output, not an absolute article count.'),
         })
             .describe('A single aggregated data point for the "Other" bucket.'))
             .optional()
             .describe('Combined time series for all series beyond the top 10. Omitted when all series fit.'),
+        otherSeriesLabels: z
+            .array(z.string())
+            .optional()
+            .describe('Label of every series folded into otherAggregated, ranked by total volume — the identities the ' +
+            '"Other" bucket would otherwise dissolve. Pass any of them to the series input to retrieve that ' +
+            "series' complete data. Omitted when all series fit in the top 10."),
+        selectedSeries: z
+            .array(breakdownSeriesSchema)
+            .optional()
+            .describe('Complete, untruncated time series for each label requested via the series input, in the order ' +
+            'requested. Omitted when series was not supplied.'),
     }),
     // Agent-facing context — query echo, breakdown dimension, total series count, and notice on empty results.
     // Reaches structuredContent and content[] automatically; never in the domain return.
@@ -160,6 +214,7 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
         const topSeries = sorted.slice(0, MAX_SERIES).map(({ total: _, ...s }) => s);
         const remainingSeries = sorted.slice(MAX_SERIES);
         let otherAggregated;
+        let otherSeriesLabels;
         if (remainingSeries.length > 0) {
             const dateMap = new Map();
             for (const s of remainingSeries) {
@@ -170,6 +225,31 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
             otherAggregated = Array.from(dateMap.entries())
                 .sort(([a], [b]) => a.localeCompare(b))
                 .map(([date, value]) => ({ date, value }));
+            otherSeriesLabels = remainingSeries.map((s) => s.label);
+        }
+        // Label selection re-filters the same complete upstream set the ranking sliced, so a
+        // series named on a follow-up call reconstructs statelessly from query + dimension + label.
+        const selectedSeries = [];
+        if (input.series?.length) {
+            const byLabel = new Map(allSeries.map((s) => [s.label, s]));
+            const unknown = [];
+            for (const label of input.series) {
+                const match = byLabel.get(label);
+                if (match)
+                    selectedSeries.push(match);
+                else
+                    unknown.push(label);
+            }
+            if (unknown.length > 0) {
+                const named = unknown.map((label) => `"${label}"`).join(', ');
+                throw ctx.fail('unknown_series', `No ${input.breakdownBy} series named ${named}`, {
+                    unknownLabels: unknown,
+                    recovery: {
+                        hint: `This breakdown has no ${input.breakdownBy} series named ${named}. Labels are exact and ` +
+                            `case-sensitive. Available for "${input.query}": ${sorted.map((s) => s.label).join(', ')}.`,
+                    },
+                });
+            }
         }
         const allDates = topSeries.flatMap((s) => s.data.map((d) => d.date));
         const dateResolution = inferDateResolution(allDates);
@@ -183,26 +263,31 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
         ctx.log.info('gdelt_get_coverage_breakdown completed', {
             totalSeries: allSeries.length,
             topSeriesCount: topSeries.length,
+            selectedSeriesCount: selectedSeries.length,
         });
         return {
             dateResolution,
             topSeries,
             ...(otherAggregated ? { otherAggregated } : {}),
+            ...(otherSeriesLabels ? { otherSeriesLabels } : {}),
+            ...(selectedSeries.length > 0 ? { selectedSeries } : {}),
         };
     },
+    /**
+     * Every arm renders on its own field presence, never as an `if`/`else if` chain — the
+     * format-parity linter populates all optional fields at once in its synthetic sample,
+     * so a mutually-exclusive branch would leave the untaken arm unverified.
+     */
     format: (result) => {
         const lines = [
             `## GDELT Coverage Breakdown`,
             `**Date Resolution:** ${result.dateResolution}`,
+            `**Values:** normalized — each value is the topic's share of that source's media output, ` +
+                `not an article count. Small media markets with concentrated coverage rank above large ` +
+                `markets with diverse output.`,
         ];
-        for (const s of result.topSeries) {
-            const total = s.data.reduce((sum, d) => sum + d.value, 0);
-            lines.push(`\n### ${s.label} (total: ${total.toFixed(2)})`);
-            lines.push(`Data points: ${s.data.length}`);
-            const peak = s.data.reduce((max, d) => (d.value > max.value ? d : max), s.data[0] ?? { date: '', value: 0 });
-            if (peak.date)
-                lines.push(`Peak: ${peak.value.toFixed(3)} at ${peak.date}`);
-        }
+        for (const s of result.topSeries)
+            lines.push(...renderSeries(s));
         if (result.otherAggregated) {
             const otherTotal = result.otherAggregated.reduce((sum, d) => sum + d.value, 0);
             const otherPeak = result.otherAggregated.reduce((max, d) => (d.value > max.value ? d : max), result.otherAggregated[0] ?? { date: '', value: 0 });
@@ -210,6 +295,21 @@ export const gdeltGetCoverageBreakdown = tool('gdelt_get_coverage_breakdown', {
             lines.push(`Total: ${otherTotal.toFixed(2)}`);
             if (otherPeak.date)
                 lines.push(`Peak: ${otherPeak.value.toFixed(3)} at ${otherPeak.date}`);
+            for (const d of result.otherAggregated) {
+                lines.push(`- ${d.date}: ${d.value.toFixed(3)}`);
+            }
+        }
+        if (result.otherSeriesLabels?.length) {
+            lines.push(`\n### Series folded into "Other" (${result.otherSeriesLabels.length})`);
+            lines.push(`Ranked by total volume. Re-call with series: ["<label>"] to get any of them in full.`);
+            for (const label of result.otherSeriesLabels)
+                lines.push(`- ${label}`);
+        }
+        if (result.selectedSeries?.length) {
+            lines.push(`\n## Selected Series (${result.selectedSeries.length})`);
+            lines.push(`Complete series for the labels requested via the series input.`);
+            for (const s of result.selectedSeries)
+                lines.push(...renderSeries(s));
         }
         return [{ type: 'text', text: lines.join('\n') }];
     },