@cyanheads/gdelt-mcp-server 0.1.1

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview GDELT coverage breakdown tool. Breaks down coverage volume by source
+ * language or source country over time using the GDELT DOC API.
+ * @module mcp-server/tools/definitions/get-coverage-breakdown.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetCoverageBreakdown: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    breakdownBy: z.ZodEnum<{
+        language: "language";
+        country: "country";
+    }>;
+    timespan: z.ZodOptional<z.ZodString>;
+    startDatetime: z.ZodOptional<z.ZodString>;
+    endDatetime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    breakdownBy: z.ZodEnum<{
+        language: "language";
+        country: "country";
+    }>;
+    dateResolution: z.ZodEnum<{
+        hour: "hour";
+        day: "day";
+    }>;
+    topSeries: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        data: z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            value: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    otherAggregated: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        value: z.ZodNumber;
+    }, z.core.$strip>>>;
+    seriesCount: z.ZodNumber;
+    notice: z.ZodOptional<z.ZodString>;
+}, 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: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT DOC API is unreachable or rate-limited.";
+    readonly retryable: true;
+    readonly recovery: "Wait at least 5 seconds before retrying — GDELT enforces 1 request per 5 seconds.";
+}]>;
+//# sourceMappingURL=get-coverage-breakdown.tool.d.ts.map

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

@@ -0,0 +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;AAOjE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+MpC,CAAC"}

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

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview GDELT coverage breakdown tool. Breaks down coverage volume by source
+ * language or source country over time using the GDELT DOC API.
+ * @module mcp-server/tools/definitions/get-coverage-breakdown.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltDocService } from '../../../services/gdelt/gdelt-doc-service.js';
+import { inferDateResolution } from '../date-resolution.js';
+/** Maximum number of series to include before aggregating the rest into "Other". */
+const MAX_SERIES = 10;
+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. ' +
+        '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 },
+    errors: [
+        {
+            reason: 'no_breakdown_data',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No breakdown data returned for the query.',
+            recovery: 'Broaden the query, extend the timespan, or verify the query operators are correct.',
+        },
+        {
+            reason: 'gdelt_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'GDELT DOC API is unreachable or rate-limited.',
+            retryable: true,
+            recovery: 'Wait at least 5 seconds before retrying — GDELT enforces 1 request per 5 seconds.',
+        },
+    ],
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Search query using GDELT syntax. Same operators as gdelt_search_articles: ' +
+            'phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:.'),
+        breakdownBy: z
+            .enum(['language', 'country'])
+            .describe('Breakdown dimension: "language" for source language time series, ' +
+            '"country" for source country time series.'),
+        timespan: z
+            .string()
+            .optional()
+            .describe('Time window relative to now, e.g. "24h", "7d", "1m". ' +
+            'Ignored when startDatetime/endDatetime are set. Maximum 3 months.'),
+        startDatetime: z
+            .string()
+            .optional()
+            .describe('Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime.'),
+        endDatetime: z
+            .string()
+            .optional()
+            .describe('End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime.'),
+    }),
+    output: z.object({
+        query: z.string().describe('Echoed query string.'),
+        breakdownBy: z.enum(['language', 'country']).describe('Breakdown dimension used.'),
+        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.'),
+        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.'),
+        })
+            .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.'),
+        seriesCount: z.number().describe('Total number of series before truncation to top 10.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when no data was returned. Absent on successful responses.'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('gdelt_get_coverage_breakdown', {
+            query: input.query,
+            breakdownBy: input.breakdownBy,
+        });
+        const svc = getGdeltDocService();
+        const modeMap = {
+            language: 'timelinelang',
+            country: 'timelinesourcecountry',
+        };
+        const allSeries = await svc.getBreakdown({
+            query: input.query,
+            mode: modeMap[input.breakdownBy],
+            ...(input.timespan && { timespan: input.timespan }),
+            ...(input.startDatetime && { startDatetime: input.startDatetime }),
+            ...(input.endDatetime && { endDatetime: input.endDatetime }),
+        }, ctx);
+        if (allSeries.length === 0) {
+            throw ctx.fail('no_breakdown_data', `No breakdown data for "${input.query}"`, {
+                recovery: {
+                    hint: `No breakdown data for "${input.query}". Try broadening the query or extending the time range.`,
+                },
+            });
+        }
+        // Sort by total volume descending, take top MAX_SERIES
+        const sorted = allSeries
+            .map((s) => ({
+            ...s,
+            total: s.data.reduce((sum, d) => sum + d.value, 0),
+        }))
+            .sort((a, b) => b.total - a.total);
+        const topSeries = sorted.slice(0, MAX_SERIES).map(({ total: _, ...s }) => s);
+        const remainingSeries = sorted.slice(MAX_SERIES);
+        let otherAggregated;
+        if (remainingSeries.length > 0) {
+            const dateMap = new Map();
+            for (const s of remainingSeries) {
+                for (const d of s.data) {
+                    dateMap.set(d.date, (dateMap.get(d.date) ?? 0) + d.value);
+                }
+            }
+            otherAggregated = Array.from(dateMap.entries())
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([date, value]) => ({ date, value }));
+        }
+        const allDates = topSeries.flatMap((s) => s.data.map((d) => d.date));
+        const dateResolution = inferDateResolution(allDates);
+        ctx.log.info('gdelt_get_coverage_breakdown completed', {
+            totalSeries: allSeries.length,
+            topSeriesCount: topSeries.length,
+        });
+        return {
+            query: input.query,
+            breakdownBy: input.breakdownBy,
+            dateResolution,
+            topSeries,
+            ...(otherAggregated ? { otherAggregated } : {}),
+            seriesCount: allSeries.length,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT Coverage Breakdown by ${result.breakdownBy === 'language' ? 'Language' : 'Country'}`,
+            `**Query:** ${result.query}`,
+            `**Total series:** ${result.seriesCount} | **Showing top:** ${result.topSeries.length}`,
+            `**Date Resolution:** ${result.dateResolution}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        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}`);
+        }
+        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 });
+            lines.push(`\n### Other (${result.seriesCount - result.topSeries.length} series, total: ${otherTotal.toFixed(2)})`);
+            if (otherPeak.date)
+                lines.push(`Peak: ${otherPeak.value.toFixed(3)} at ${otherPeak.date}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-coverage-breakdown.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-coverage-breakdown.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-coverage-breakdown.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview GDELT coverage timeline tool. Retrieves time series of coverage volume
+ * or average tone for a query using the GDELT DOC API.
+ * @module mcp-server/tools/definitions/get-coverage-timeline.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetCoverageTimeline: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<{
+        volume: "volume";
+        volume_with_articles: "volume_with_articles";
+        tone: "tone";
+    }>>;
+    timespan: z.ZodOptional<z.ZodString>;
+    startDatetime: z.ZodOptional<z.ZodString>;
+    endDatetime: z.ZodOptional<z.ZodString>;
+    smoothing: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodEnum<{
+        volume: "volume";
+        volume_with_articles: "volume_with_articles";
+        tone: "tone";
+    }>;
+    dateResolution: z.ZodEnum<{
+        hour: "hour";
+        day: "day";
+    }>;
+    series: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        data: z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            value: z.ZodNumber;
+            articles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_timeline_data";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No timeline data returned for the query and time range.";
+    readonly recovery: "Broaden the query, extend the timespan, or verify query operators are correct.";
+}, {
+    readonly reason: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT DOC API is unreachable or rate-limited.";
+    readonly retryable: true;
+    readonly recovery: "Wait at least 5 seconds before retrying — GDELT enforces 1 request per 5 seconds.";
+}]>;
+//# sourceMappingURL=get-coverage-timeline.tool.d.ts.map

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

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

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

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview GDELT coverage timeline tool. Retrieves time series of coverage volume
+ * or average tone for a query using the GDELT DOC API.
+ * @module mcp-server/tools/definitions/get-coverage-timeline.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltDocService } from '../../../services/gdelt/gdelt-doc-service.js';
+import { inferDateResolution } from '../date-resolution.js';
+export const gdeltGetCoverageTimeline = tool('gdelt_get_coverage_timeline', {
+    title: 'Get GDELT Coverage Timeline',
+    description: 'Retrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. ' +
+        'Use mode "volume" for normalized coverage intensity (% of all global coverage per timestep). ' +
+        'Use mode "volume_with_articles" for the same signal plus the top articles that drove each spike — ' +
+        'this is the primary signal-detection mode: a single call reveals both the spike and its cause, ' +
+        'avoiding a follow-up gdelt_search_articles call. ' +
+        'Use mode "tone" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). ' +
+        'Date resolution is automatically chosen based on timespan: hours for short windows, days for longer ones. ' +
+        'Note: DOC API covers only the last 3 months.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_timeline_data',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No timeline data returned for the query and time range.',
+            recovery: 'Broaden the query, extend the timespan, or verify query operators are correct.',
+        },
+        {
+            reason: 'gdelt_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'GDELT DOC API is unreachable or rate-limited.',
+            retryable: true,
+            recovery: 'Wait at least 5 seconds before retrying — GDELT enforces 1 request per 5 seconds.',
+        },
+    ],
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Search query using GDELT syntax. Same operators as gdelt_search_articles: ' +
+            'phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:, tone<.'),
+        mode: z
+            .enum(['volume', 'volume_with_articles', 'tone'])
+            .default('volume')
+            .describe('Timeline mode: "volume" returns normalized coverage % per timestep, ' +
+            '"volume_with_articles" returns volume plus top articles per spike (best for signal detection), ' +
+            '"tone" returns average sentiment score per timestep.'),
+        timespan: z
+            .string()
+            .optional()
+            .describe('Time window relative to now, e.g. "24h", "7d", "1m". ' +
+            'Ignored when startDatetime/endDatetime are set. Maximum 3 months.'),
+        startDatetime: z
+            .string()
+            .optional()
+            .describe('Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime.'),
+        endDatetime: z
+            .string()
+            .optional()
+            .describe('End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime.'),
+        smoothing: z
+            .number()
+            .int()
+            .min(0)
+            .max(5)
+            .optional()
+            .describe('Smoothing window in timesteps (0 = none, 1–5 = moving average width). ' +
+            'Reduces noise for spotty topics.'),
+    }),
+    output: z.object({
+        query: z.string().describe('Echoed query string.'),
+        mode: z.enum(['volume', 'volume_with_articles', 'tone']).describe('Timeline mode used.'),
+        dateResolution: z
+            .enum(['hour', 'day'])
+            .describe('Temporal resolution of the data points — hour for short windows, day for longer.'),
+        series: z
+            .array(z
+            .object({
+            label: z.string().describe('Series label (e.g. "Volume Intensity" or "Average Tone").'),
+            data: z
+                .array(z
+                .object({
+                date: z.string().describe('Timestep in ISO 8601 format.'),
+                value: z
+                    .number()
+                    .describe('Normalized coverage % (volume mode) or average tone score (tone mode). ' +
+                    'Tone range is approximately -100 to +100.'),
+                articles: z
+                    .array(z
+                    .object({
+                    url: z.string().describe('Article URL.'),
+                    title: z.string().describe('Article title.'),
+                })
+                    .describe('An article linked to this spike.'))
+                    .optional()
+                    .describe('Top articles driving coverage at this timestep. Present only in volume_with_articles mode.'),
+            })
+                .describe('A single time-series data point.'))
+                .describe('Time-ordered data points for this series.'),
+        })
+            .describe('A single time series with a label and data points.'))
+            .describe('One or more time series (typically one for volume/tone, one per label for breakdowns).'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when no data was returned. Absent on successful responses.'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('gdelt_get_coverage_timeline', { query: input.query, mode: input.mode });
+        const svc = getGdeltDocService();
+        const modeMap = {
+            volume: 'timelinevol',
+            volume_with_articles: 'timelinevolinfo',
+            tone: 'timelinetone',
+        };
+        const series = await svc.getTimeline({
+            query: input.query,
+            mode: modeMap[input.mode],
+            ...(input.timespan && { timespan: input.timespan }),
+            ...(input.startDatetime && { startDatetime: input.startDatetime }),
+            ...(input.endDatetime && { endDatetime: input.endDatetime }),
+            ...(input.smoothing != null && { smoothing: input.smoothing }),
+        }, ctx);
+        if (series.length === 0 || series.every((s) => s.data.length === 0)) {
+            throw ctx.fail('no_timeline_data', `No timeline data for "${input.query}"`, {
+                recovery: {
+                    hint: `No coverage data found for "${input.query}". Try broadening the query or extending the time window.`,
+                },
+            });
+        }
+        // Infer date resolution from data point spacing
+        const allDates = series.flatMap((s) => s.data.map((d) => d.date));
+        const dateResolution = inferDateResolution(allDates);
+        ctx.log.info('gdelt_get_coverage_timeline completed', {
+            seriesCount: series.length,
+            pointCount: series[0]?.data.length ?? 0,
+        });
+        return { query: input.query, mode: input.mode, dateResolution, series };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT Coverage Timeline`,
+            `**Query:** ${result.query}`,
+            `**Mode:** ${result.mode}`,
+            `**Date Resolution:** ${result.dateResolution}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        for (const s of result.series) {
+            lines.push(`\n### ${s.label}`);
+            const peakPoint = s.data.reduce((max, d) => (Math.abs(d.value) > Math.abs(max.value) ? d : max), s.data[0] ?? { date: '', value: 0, articles: undefined });
+            lines.push(`**Data points:** ${s.data.length}`);
+            if (peakPoint.date) {
+                lines.push(`**Peak:** ${peakPoint.value.toFixed(3)} at ${peakPoint.date}`);
+            }
+            // Show first 10 data points to orient the agent
+            const preview = s.data.slice(0, 10);
+            for (const d of preview) {
+                const articlesNote = d.articles?.length ? ` (${d.articles.length} articles)` : '';
+                lines.push(`- ${d.date}: ${d.value.toFixed(3)}${articlesNote}`);
+                if (d.articles?.length) {
+                    for (const a of d.articles.slice(0, 3)) {
+                        lines.push(`  - [${a.title}](${a.url})`);
+                    }
+                }
+            }
+            if (s.data.length > 10)
+                lines.push(`- … ${s.data.length - 10} more points`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-coverage-timeline.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-coverage-timeline.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-coverage-timeline.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-tone-distribution.tool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview GDELT tone distribution tool. Returns a histogram of article tone
+ * scores for articles matching a query, revealing emotional distribution of coverage.
+ * @module mcp-server/tools/definitions/get-tone-distribution.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetToneDistribution: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    timespan: z.ZodOptional<z.ZodString>;
+    startDatetime: z.ZodOptional<z.ZodString>;
+    endDatetime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    histogram: z.ZodArray<z.ZodObject<{
+        bin: z.ZodNumber;
+        count: z.ZodNumber;
+        articles: z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        peakNegativeBin: z.ZodNumber;
+        peakPositiveBin: z.ZodNumber;
+        neutralPct: z.ZodNumber;
+    }, z.core.$strip>;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_tone_data";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No tone histogram data returned for the query.";
+    readonly recovery: "Broaden the query or extend the timespan to include more matching articles.";
+}, {
+    readonly reason: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT DOC API is unreachable or rate-limited.";
+    readonly retryable: true;
+    readonly recovery: "Wait at least 5 seconds before retrying — GDELT enforces 1 request per 5 seconds.";
+}]>;
+//# sourceMappingURL=get-tone-distribution.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-tone-distribution.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-tone-distribution.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-tone-distribution.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiKnC,CAAC"}