@cyanheads/gdelt-mcp-server 0.1.1

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

@@ -0,0 +1,143 @@
+/**
+ * @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 { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltDocService } from '../../../services/gdelt/gdelt-doc-service.js';
+export const gdeltGetToneDistribution = tool('gdelt_get_tone_distribution', {
+    title: 'Get GDELT Tone Distribution',
+    description: 'Get the tonal distribution of articles matching a query as a histogram (bins approximately -30 to +30). ' +
+        'Unlike a single average tone score, the histogram reveals whether coverage is uniformly negative, ' +
+        'bimodal (some articles extremely positive and some extremely negative), or clustered near neutral. ' +
+        'Each bin includes representative article URLs. ' +
+        'Distinct from gdelt_get_coverage_timeline (mode: tone) — this is a snapshot distribution ' +
+        'across all matching articles, not a time series. ' +
+        'Use gdelt_get_coverage_timeline with mode "tone" to see how sentiment shifted over time.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_tone_data',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No tone histogram data returned for the query.',
+            recovery: 'Broaden the query or extend the timespan to include more matching articles.',
+        },
+        {
+            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:.'),
+        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.'),
+        histogram: z
+            .array(z
+            .object({
+            bin: z.number().describe('Tone bin integer (typically -30 to +30; 0 is neutral).'),
+            count: z.number().describe('Number of articles in this bin.'),
+            articles: z
+                .array(z
+                .object({
+                url: z.string().describe('Article URL.'),
+                title: z.string().describe('Article title.'),
+            })
+                .describe('A representative article for this tone bin.'))
+                .describe('Representative articles in this tone bin.'),
+        })
+            .describe('A single tone histogram bin with article count and representative articles.'))
+            .describe('Tone histogram sorted from most negative to most positive bin.'),
+        summary: z
+            .object({
+            peakNegativeBin: z
+                .number()
+                .describe('Tone bin with the highest count among negative bins (bin < 0).'),
+            peakPositiveBin: z
+                .number()
+                .describe('Tone bin with the highest count among positive bins (bin > 0).'),
+            neutralPct: z
+                .number()
+                .describe('Percentage of articles in the near-neutral range (bins -2 to +2).'),
+        })
+            .describe('Summary statistics derived from the histogram.'),
+        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_tone_distribution', { query: input.query });
+        const svc = getGdeltDocService();
+        const bins = await svc.getToneDistribution({
+            query: input.query,
+            ...(input.timespan && { timespan: input.timespan }),
+            ...(input.startDatetime && { startDatetime: input.startDatetime }),
+            ...(input.endDatetime && { endDatetime: input.endDatetime }),
+        }, ctx);
+        if (bins.length === 0) {
+            throw ctx.fail('no_tone_data', `No tone data for "${input.query}"`, {
+                recovery: {
+                    hint: `No tone data for "${input.query}". Broaden the query or extend the time range.`,
+                },
+            });
+        }
+        // Compute summary
+        const negativeBins = bins.filter((b) => b.bin < 0);
+        const positiveBins = bins.filter((b) => b.bin > 0);
+        const neutralBins = bins.filter((b) => b.bin >= -2 && b.bin <= 2);
+        const totalCount = bins.reduce((sum, b) => sum + b.count, 0);
+        const neutralCount = neutralBins.reduce((sum, b) => sum + b.count, 0);
+        const peakNeg = negativeBins.reduce((max, b) => (b.count > max.count ? b : max), negativeBins[0] ?? { bin: 0, count: 0, articles: [] });
+        const peakPos = positiveBins.reduce((max, b) => (b.count > max.count ? b : max), positiveBins[0] ?? { bin: 0, count: 0, articles: [] });
+        const summary = {
+            peakNegativeBin: peakNeg.bin,
+            peakPositiveBin: peakPos.bin,
+            neutralPct: totalCount > 0 ? Math.round((neutralCount / totalCount) * 100) : 0,
+        };
+        ctx.log.info('gdelt_get_tone_distribution completed', { bins: bins.length, totalCount });
+        return { query: input.query, histogram: bins, summary };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT Tone Distribution`,
+            `**Query:** ${result.query}`,
+            `**Peak negative bin:** ${result.summary.peakNegativeBin}`,
+            `**Peak positive bin:** ${result.summary.peakPositiveBin}`,
+            `**Neutral articles (bins -2 to +2):** ${result.summary.neutralPct}%`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        lines.push('\n### Histogram');
+        for (const b of result.histogram) {
+            const bar = '█'.repeat(Math.min(Math.ceil(b.count / 5), 20));
+            lines.push(`**Bin ${b.bin > 0 ? '+' : ''}${b.bin}:** ${b.count} articles ${bar}`);
+            for (const a of b.articles.slice(0, 2)) {
+                lines.push(`  - [${a.title}](${a.url})`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-tone-distribution.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/get-tv-clips.tool.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview GDELT TV clips tool. Retrieves matching TV news clips with transcript
+ * excerpts and Internet Archive viewing links.
+ * @module mcp-server/tools/definitions/get-tv-clips.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetTvClips: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    stations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timespan: z.ZodOptional<z.ZodString>;
+    startDatetime: z.ZodOptional<z.ZodString>;
+    endDatetime: z.ZodOptional<z.ZodString>;
+    maxRecords: z.ZodDefault<z.ZodNumber>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        relevance: "relevance";
+        dateDesc: "dateDesc";
+        dateAsc: "dateAsc";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    clips: z.ZodArray<z.ZodObject<{
+        show: z.ZodString;
+        station: z.ZodString;
+        date: z.ZodString;
+        snippet: z.ZodString;
+        archiveUrl: z.ZodString;
+        thumbnail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalReturned: z.ZodNumber;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_clips";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No TV clips matched the query in the specified time range.";
+    readonly recovery: string;
+}, {
+    readonly reason: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT TV 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-tv-clips.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-tv-clips.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-tv-clips.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-tv-clips.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,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJ1B,CAAC"}

package/dist/mcp-server/tools/definitions/get-tv-clips.tool.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview GDELT TV clips tool. Retrieves matching TV news clips with transcript
+ * excerpts and Internet Archive viewing links.
+ * @module mcp-server/tools/definitions/get-tv-clips.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltTvService } from '../../../services/gdelt/gdelt-tv-service.js';
+export const gdeltGetTvClips = tool('gdelt_get_tv_clips', {
+    title: 'Get GDELT TV Clips',
+    description: "Retrieve the top matching TV news clips (up to 3,000) for a query from the Internet Archive's " +
+        'Television News Archive. Each clip includes show name, station, air timestamp, a 15-second ' +
+        'transcript excerpt, and a direct link to view the full one-minute clip. ' +
+        'Use after gdelt_search_tv to read the actual transcript content driving a coverage spike. ' +
+        'Archive coverage spans 2009–October 2024.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_clips',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No TV clips matched the query in the specified time range.',
+            recovery: 'TV data ends October 2024 — supply explicit startDatetime/endDatetime within 2009–2024, ' +
+                'or verify station IDs with gdelt_list_tv_stations.',
+        },
+        {
+            reason: 'gdelt_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'GDELT TV 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 for TV transcript content. Same TV operators as gdelt_search_tv: ' +
+            'station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".'),
+        stations: z
+            .array(z.string())
+            .optional()
+            .describe('Station IDs to filter to (e.g. ["CNN", "FOXNEWS"]). ' +
+            'Omit for all stations. Use gdelt_list_tv_stations to see valid IDs.'),
+        timespan: z
+            .string()
+            .optional()
+            .describe('Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. ' +
+            'TV data spans 2009–October 2024.'),
+        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.'),
+        maxRecords: z
+            .number()
+            .int()
+            .min(1)
+            .max(3000)
+            .default(50)
+            .describe('Maximum number of clips to return (1–3000).'),
+        sort: z
+            .enum(['relevance', 'dateDesc', 'dateAsc'])
+            .default('relevance')
+            .describe('Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first).'),
+    }),
+    output: z.object({
+        query: z.string().describe('Echoed query string.'),
+        clips: z
+            .array(z
+            .object({
+            show: z.string().describe('Show name (e.g. "Anderson Cooper 360").'),
+            station: z.string().describe('Station ID (e.g. "CNN").'),
+            date: z.string().describe('Air datetime in ISO 8601 format.'),
+            snippet: z.string().describe('15-second transcript excerpt surrounding the match.'),
+            archiveUrl: z.string().describe('Internet Archive URL to view the full 1-minute clip.'),
+            thumbnail: z
+                .string()
+                .optional()
+                .describe('Clip thumbnail URL when provided by the archive.'),
+        })
+            .describe('A single TV news clip with transcript excerpt and archive link.'))
+            .describe('Matching TV clips sorted per the sort parameter.'),
+        totalReturned: z.number().describe('Number of clips returned.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when no clips matched. Absent on successful responses.'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('gdelt_get_tv_clips', { query: input.query, maxRecords: input.maxRecords });
+        const svc = getGdeltTvService();
+        const clips = await svc.getTvClips({
+            query: input.query,
+            ...(input.stations?.length && { stations: input.stations }),
+            ...(input.timespan && { timespan: input.timespan }),
+            ...(input.startDatetime && { startDatetime: input.startDatetime }),
+            ...(input.endDatetime && { endDatetime: input.endDatetime }),
+            maxRecords: input.maxRecords,
+            sort: input.sort,
+        }, ctx);
+        if (clips.length === 0) {
+            throw ctx.fail('no_clips', `No TV clips matched "${input.query}"`, {
+                recovery: {
+                    hint: `No TV clips for "${input.query}". TV data ends October 2024 — ` +
+                        `supply explicit startDatetime/endDatetime within 2009–2024, or verify station IDs with gdelt_list_tv_stations.`,
+                },
+            });
+        }
+        ctx.log.info('gdelt_get_tv_clips completed', { count: clips.length });
+        return { query: input.query, clips, totalReturned: clips.length };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT TV Clips`,
+            `**Query:** ${result.query}`,
+            `**Clips returned:** ${result.totalReturned}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        for (const c of result.clips) {
+            lines.push(`\n### ${c.show} — ${c.station}`);
+            lines.push(`**Date:** ${c.date}`);
+            lines.push(`**Snippet:** ${c.snippet}`);
+            lines.push(`**View clip:** ${c.archiveUrl}`);
+            if (c.thumbnail)
+                lines.push(`**Thumbnail:** ${c.thumbnail}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-tv-clips.tool.js.map

package/dist/mcp-server/tools/definitions/get-tv-clips.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-tv-context.tool.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview GDELT TV context tool. Returns co-occurring words and phrases from
+ * TV news clips matching a query — the vocabulary framing a topic on television.
+ * @module mcp-server/tools/definitions/get-tv-context.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetTvContext: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    stations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timespan: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    words: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        score: z.ZodNumber;
+    }, z.core.$strip>>;
+    clipsAnalyzed: z.ZodNumber;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_context";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No context words found — no clips matched the query.";
+    readonly recovery: "Broaden the query, extend the timespan, or verify station IDs with gdelt_list_tv_stations.";
+}, {
+    readonly reason: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT TV 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-tv-context.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-tv-context.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-tv-context.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-tv-context.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,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;GA6H5B,CAAC"}

package/dist/mcp-server/tools/definitions/get-tv-context.tool.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview GDELT TV context tool. Returns co-occurring words and phrases from
+ * TV news clips matching a query — the vocabulary framing a topic on television.
+ * @module mcp-server/tools/definitions/get-tv-context.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltTvService } from '../../../services/gdelt/gdelt-tv-service.js';
+export const gdeltGetTvContext = tool('gdelt_get_tv_context', {
+    title: 'Get GDELT TV Context',
+    description: 'Get the top co-occurring words and phrases from TV news clips matching a query — ' +
+        'the vocabulary framing a topic on television. ' +
+        'Returns the most frequent non-stopword terms from matching clips, with relative frequency scores ' +
+        '(0–100, where 100 = the query term itself). ' +
+        'Use to understand narrative framing, identify related concepts mentioned alongside a topic, ' +
+        'or generate follow-up search terms. ' +
+        'TV data spans 2009–October 2024.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_context',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No context words found — no clips matched the query.',
+            recovery: 'Broaden the query, extend the timespan, or verify station IDs with gdelt_list_tv_stations.',
+        },
+        {
+            reason: 'gdelt_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'GDELT TV 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 for TV transcript content. Same TV operators as gdelt_search_tv: ' +
+            'station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".'),
+        stations: z
+            .array(z.string())
+            .optional()
+            .describe('Station IDs to filter to. Omit for all stations. ' +
+            'Use gdelt_list_tv_stations to see valid IDs.'),
+        timespan: z
+            .string()
+            .optional()
+            .describe('Time window, e.g. "1m", "6m". TV data spans 2009–October 2024.'),
+    }),
+    output: z.object({
+        query: z.string().describe('Echoed query string.'),
+        words: z
+            .array(z
+            .object({
+            label: z.string().describe('Co-occurring word or phrase.'),
+            score: z
+                .number()
+                .describe('Relative frequency score (0–100). The query term itself scores 100; ' +
+                'other terms are proportional to their co-occurrence frequency.'),
+        })
+            .describe('A co-occurring term with its relative frequency score.'))
+            .describe('Co-occurring terms sorted by score descending.'),
+        clipsAnalyzed: z
+            .number()
+            .describe('Number of matching clips from which co-occurrences were computed.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when no context was found. Absent on successful responses.'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('gdelt_get_tv_context', { query: input.query });
+        const svc = getGdeltTvService();
+        const result = await svc.getTvContext({
+            query: input.query,
+            ...(input.stations?.length && { stations: input.stations }),
+            ...(input.timespan && { timespan: input.timespan }),
+        }, ctx);
+        if (result.words.length === 0) {
+            throw ctx.fail('no_context', `No context words for "${input.query}"`, {
+                recovery: {
+                    hint: `No TV context data for "${input.query}". TV data ends October 2024 — ` +
+                        `broaden the query or use gdelt_list_tv_stations to check coverage.`,
+                },
+            });
+        }
+        ctx.log.info('gdelt_get_tv_context completed', { wordCount: result.words.length });
+        return {
+            query: input.query,
+            words: result.words.sort((a, b) => b.score - a.score),
+            clipsAnalyzed: result.clipsAnalyzed,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT TV Context`,
+            `**Query:** ${result.query}`,
+            `**Clips analyzed:** ${result.clipsAnalyzed}`,
+            `**Co-occurring terms:** ${result.words.length}`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        lines.push('\n### Top Terms');
+        for (const w of result.words.slice(0, 50)) {
+            const bar = '█'.repeat(Math.round(w.score / 5));
+            lines.push(`- **${w.label}**: ${w.score.toFixed(1)} ${bar}`);
+        }
+        if (result.words.length > 50) {
+            lines.push(`\n_… ${result.words.length - 50} more terms_`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-tv-context.tool.js.map

package/dist/mcp-server/tools/definitions/get-tv-context.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-tv-trending.tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview GDELT TV trending tool. Returns trending topics currently dominating
+ * US television news — no query required.
+ * @module mcp-server/tools/definitions/get-tv-trending.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gdeltGetTvTrending: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    topics: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        score: z.ZodNumber;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_trending";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No trending topics returned — the endpoint returned an empty list.";
+    readonly recovery: "The TV trending endpoint reflects the October 2024 archive cutoff. Retry after a short delay.";
+}, {
+    readonly reason: "gdelt_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "GDELT TV 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-tv-trending.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-tv-trending.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-tv-trending.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-tv-trending.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,kBAAkB;;;;;;;;;;;;;;;;;;GAoF7B,CAAC"}

package/dist/mcp-server/tools/definitions/get-tv-trending.tool.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview GDELT TV trending tool. Returns trending topics currently dominating
+ * US television news — no query required.
+ * @module mcp-server/tools/definitions/get-tv-trending.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGdeltTvService } from '../../../services/gdelt/gdelt-tv-service.js';
+export const gdeltGetTvTrending = tool('gdelt_get_tv_trending', {
+    title: 'Get GDELT TV Trending',
+    description: 'Retrieve trending topics, keywords, and phrases currently dominating US television news ' +
+        'across national networks. No query required — returns the top memes of the present news cycle. ' +
+        'Updated every 15 minutes. ' +
+        'Note: the GDELT TV archive feed stopped updating around October 2024; results from this endpoint ' +
+        'reflect that most-recent archived data rather than a live feed.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'no_trending',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No trending topics returned — the endpoint returned an empty list.',
+            recovery: 'The TV trending endpoint reflects the October 2024 archive cutoff. Retry after a short delay.',
+        },
+        {
+            reason: 'gdelt_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'GDELT TV 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({}),
+    output: z.object({
+        topics: z
+            .array(z
+            .object({
+            label: z.string().describe('Trending topic, keyword, or phrase.'),
+            score: z
+                .number()
+                .describe('Relative trending score. Higher scores indicate topics with greater current airtime.'),
+        })
+            .describe('A single trending topic with its relative score.'))
+            .describe('Trending topics sorted by score descending.'),
+        totalCount: z.number().describe('Number of trending topics returned.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Recovery hint when no topics were returned. Absent on successful responses.'),
+    }),
+    async handler(_input, ctx) {
+        ctx.log.info('gdelt_get_tv_trending');
+        const svc = getGdeltTvService();
+        const topics = await svc.getTvTrending(ctx);
+        if (topics.length === 0) {
+            throw ctx.fail('no_trending', 'No trending topics returned', {
+                ...ctx.recoveryFor('no_trending'),
+            });
+        }
+        ctx.log.info('gdelt_get_tv_trending completed', { count: topics.length });
+        return {
+            topics: topics.sort((a, b) => b.score - a.score),
+            totalCount: topics.length,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `## GDELT TV Trending Topics`,
+            `**Total topics:** ${result.totalCount}`,
+            `_Note: reflects the October 2024 TV archive cutoff, not a live feed_`,
+        ];
+        if (result.notice)
+            lines.push(`\n> ${result.notice}`);
+        lines.push('\n### Trending Now');
+        for (const t of result.topics.slice(0, 50)) {
+            lines.push(`- **${t.label}** (score: ${t.score.toFixed(2)})`);
+        }
+        if (result.totalCount > 50)
+            lines.push(`\n_… ${result.totalCount - 50} more topics_`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-tv-trending.tool.js.map

package/dist/mcp-server/tools/definitions/get-tv-trending.tool.js.map

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

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Barrel export for all GDELT MCP tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { gdeltGetCoverageBreakdown } from './get-coverage-breakdown.tool.js';
+export { gdeltGetCoverageTimeline } from './get-coverage-timeline.tool.js';
+export { gdeltGetToneDistribution } from './get-tone-distribution.tool.js';
+export { gdeltGetTvClips } from './get-tv-clips.tool.js';
+export { gdeltGetTvContext } from './get-tv-context.tool.js';
+export { gdeltGetTvTrending } from './get-tv-trending.tool.js';
+export { gdeltListTvStations } from './list-tv-stations.tool.js';
+export { gdeltSearchArticles } from './search-articles.tool.js';
+export { gdeltSearchTv } from './search-tv.tool.js';
+//# sourceMappingURL=index.d.ts.map