@cyanheads/gdelt-mcp-server 0.1.1

package/README.md

@@ -0,0 +1,336 @@
+<div align="center">
+  <h1>@cyanheads/gdelt-mcp-server</h1>
+  <p><b>Search and analyze global news coverage and US television transcripts via the GDELT Project's real-time APIs via MCP. STDIO or Streamable HTTP.</b>
+  <div>9 Tools</div>
+  </p>
+</div>
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+
+</div>
+
+<div align="center">
+
+[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+
+</div>
+
+---
+
+## Tools
+
+Nine tools across two GDELT APIs — DOC API for global print/web news (last 3 months, 65 languages, no auth) and TV API for US television transcripts (2009–Oct 2024, 150+ stations):
+
+| 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_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_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_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. |
+
+### `gdelt_search_articles`
+
+Search the last 3 months of global news with GDELT's full query syntax.
+
+- Keywords, phrases (`"bird flu"`), boolean OR, and exclusion (`-sports`)
+- Filter operators: `sourcecountry:`, `sourcelang:`, `domain:`, `theme:` (GKG taxonomy), `tone<`/`tone>`
+- 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
+- Query is echoed in response for chaining
+
+---
+
+### `gdelt_get_coverage_timeline`
+
+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)
+- Configurable smoothing and time range
+
+---
+
+### `gdelt_get_tone_distribution`
+
+Snapshot tone histogram across all articles matching a query.
+
+- Bins from approximately −30 to +30; each bin includes representative article URLs
+- Summary fields: `peakNegativeBin`, `peakPositiveBin`, `neutralPct` (% of articles in the −2 to +2 range)
+- Distinct from the tone timeline — distribution across all matching articles, not over time
+
+---
+
+### `gdelt_get_coverage_breakdown`
+
+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
+- Use to trace how a story propagated geographically
+
+---
+
+### `gdelt_search_tv`
+
+Search US television news transcripts (2009–Oct 2024) with per-station airtime analysis.
+
+- Structured `stations` parameter (e.g. `["CNN", "FOXNEWS"]`) — the server embeds station filters in the query string
+- Normalize results to relative % or return raw counts
+- TV-specific operators: `market:`, `show:`, `context:`
+- Use `gdelt_list_tv_stations` to verify station active date ranges before querying recent events
+
+---
+
+### `gdelt_get_tv_clips`
+
+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
+- Sort by relevance, date descending, or date ascending
+
+---
+
+### `gdelt_get_tv_context`
+
+Vocabulary framing analysis for TV coverage of a topic.
+
+- Returns the 200 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
+
+---
+
+### `gdelt_get_tv_trending`
+
+Zero-argument entry point for the current TV news cycle.
+
+- Returns trending topics, keywords, and phrases dominating national networks
+- Updated every 15 minutes
+- Note: coverage data ends Oct 2024; results reflect the archive endpoint, not a live feed
+
+---
+
+### `gdelt_list_tv_stations`
+
+Station metadata lookup before querying.
+
+- All available stations with market, network, monitoring start date, and end date
+- `isActive` flag — `true` when end date is within the last 24 hours
+- Use to verify a station was active during a target time period
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
+
+- Declarative tool definitions — single file per tool, framework handles registration and validation
+- Unified error handling — handlers throw, framework catches, classifies, and formats
+- Pluggable auth: `none`, `jwt`, `oauth`
+- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
+- Structured logging with optional OpenTelemetry tracing
+- STDIO and Streamable HTTP transports
+
+GDELT-specific:
+
+- Shared rate-limit queue (1 req/5s) across all tools — enforces GDELT's published limit without caller coordination
+- Two service layers (`GdeltDocService`, `GdeltTvService`) mapping clean tool parameters to the DOC and TV API URL conventions
+- TV station filter operators embedded in query strings internally — callers pass structured `stations` arrays, not raw query syntax
+
+Agent-friendly output:
+
+- Query echo on every response — searches return the original query and applied timespan so agents can chain calls without re-deriving parameters
+- Discriminated series labels — timeline and breakdown responses carry typed `label` fields (`"Volume Intensity"`, `"Average Tone"`, language/country names) rather than positional arrays
+- Structured station metadata — `isActive` boolean and ISO 8601 date fields let agents reason about TV station availability without parsing date strings
+- Partial-coverage signals in distribution output — `neutralPct`, `peakNegativeBin`, `peakPositiveBin` summary fields let agents branch on sentiment without histogramming the raw bins themselves
+
+## Getting started
+
+Add the following to your MCP client configuration file.
+
+```json
+{
+  "mcpServers": {
+    "gdelt": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/gdelt-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+Or with npx (no Bun required):
+
+```json
+{
+  "mcpServers": {
+    "gdelt": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/gdelt-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "gdelt": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "ghcr.io/cyanheads/gdelt-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+For Streamable HTTP, set the transport and start the server:
+
+```sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
+# Server listens at http://localhost:3010/mcp
+```
+
+### Prerequisites
+
+- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- No API key required — GDELT is a free public API.
+
+### Installation
+
+1. **Clone the repository:**
+
+```sh
+git clone https://github.com/cyanheads/gdelt-mcp-server.git
+```
+
+2. **Navigate into the directory:**
+
+```sh
+cd gdelt-mcp-server
+```
+
+3. **Install dependencies:**
+
+```sh
+bun install
+```
+
+4. **Configure environment:**
+
+```sh
+cp .env.example .env
+# edit .env if you need to override defaults
+```
+
+## Configuration
+
+All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `GDELT_BASE_URL` | Override the GDELT API base URL for both DOC and TV APIs. | `https://api.gdeltproject.org/api/v2` |
+| `GDELT_REQUEST_DELAY_MS` | Minimum milliseconds between GDELT requests (enforces 1 req/5s limit). | `5100` |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
+| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted. | `/mcp` |
+| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | none |
+| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |
+| `MCP_GC_PRESSURE_INTERVAL_MS` | Opt-in Bun-only forced-GC pressure loop in ms. Try `60000` if heap growth is observed under sustained HTTP load. | `0` (disabled) |
+| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
+| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
+| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
+
+See [`.env.example`](./.env.example) for the full list of optional overrides.
+
+## Running the server
+
+### Local development
+
+- **Build and run:**
+
+  ```sh
+  # One-time build
+  bun run rebuild
+
+  # Run the built server
+  bun run start:stdio
+  # or
+  bun run start:http
+  ```
+
+- **Run checks and tests:**
+
+  ```sh
+  bun run devcheck   # Lint, format, typecheck, security audit
+  bun run test       # Vitest test suite
+  bun run lint:mcp   # Validate MCP definitions against spec
+  ```
+
+### Docker
+
+```sh
+docker build -t gdelt-mcp-server .
+docker run --rm -p 3010:3010 gdelt-mcp-server
+```
+
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/gdelt-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
+
+## Project structure
+
+| Directory | Purpose |
+|:----------|:--------|
+| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |
+| `src/config` | Server-specific environment variable parsing and validation with Zod. |
+| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Nine tools across DOC and TV APIs. |
+| `src/services/gdelt-doc` | `GdeltDocService` — wraps the DOC API for article search, timelines, tone, and breakdowns. |
+| `src/services/gdelt-tv` | `GdeltTvService` — wraps the TV API for transcript search, clips, context, and trending. |
+| `src/services/gdelt-rate-limiter` | `GdeltRateLimiter` singleton — shared 1 req/5s queue across both services. |
+| `tests/` | Unit and integration tests mirroring `src/`. |
+
+## Development guide
+
+See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+
+- Handlers throw, framework catches — no `try/catch` in tool logic
+- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
+- Register new tools via the barrels in `src/mcp-server/tools/definitions/index.ts`
+- Wrap GDELT API calls: validate raw JSON → normalize to domain type → return output schema; never fabricate missing fields
+
+## Contributing
+
+Issues and pull requests are welcome. Run checks and tests before submitting:
+
+```sh
+bun run devcheck
+bun run test
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE) for details.

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,23 @@
+---
+summary: "Initial release — 9 tools for GDELT DOC and TV API search, timelines, tone analysis, and TV transcript coverage"
+breaking: false
+security: false
+---
+
+# 0.1.0 — 2026-05-25
+
+## Added
+
+- **`gdelt_search_articles`** — full-text search across the last 3 months of global news (65 languages, up to 250 results) with DOC API query syntax: phrases, boolean OR, `sourcecountry:`, `sourcelang:`, `domain:`, `theme:`, `tone<`/`tone>`, `near:`, `repeat:`
+- **`gdelt_get_coverage_timeline`** — coverage volume and tone time series with three modes: `volume`, `volume_with_articles` (top articles per timestep), and `tone`
+- **`gdelt_get_tone_distribution`** — tone histogram (~−30 to +30 bins) with `peakNegativeBin`, `peakPositiveBin`, and `neutralPct` summary fields
+- **`gdelt_get_coverage_breakdown`** — multi-series coverage timeline broken down by source `language` or `country`; top 10 series plus aggregated "Other" bucket
+- **`gdelt_search_tv`** — US TV transcript search (2009–Oct 2024, 150+ stations) with per-station normalized airtime time series
+- **`gdelt_get_tv_clips`** — retrieves up to 3,000 TV clips with 15-second transcript excerpts and Internet Archive viewing links
+- **`gdelt_get_tv_context`** — top 200 co-occurring words/phrases from TV clips matching a query, with relative frequency scores
+- **`gdelt_get_tv_trending`** — zero-argument tool returning trending topics across national TV networks (updated every 15 minutes)
+- **`gdelt_list_tv_stations`** — station metadata (market, network, date range, `isActive` flag) for verifying availability before querying
+- **`GdeltDocService`** — wraps the DOC API (`/api/v2/doc/doc`); used by article search, timeline, tone, and breakdown tools
+- **`GdeltTvService`** — wraps the TV API (`/api/v2/tv/tv`); used by TV search, clips, context, trending, and station list tools
+- **`GdeltRateLimiter`** singleton — shared 1 req/5s queue across both services, enforcing GDELT's published rate limit
+- `bunfig.toml` for Bun runtime configuration

package/changelog/0.1.x/0.1.1.md

@@ -0,0 +1,18 @@
+---
+summary: "Fix 7 API contract bugs — wrong response keys, invalid query modes, and empty-response handling across TV and DOC tools"
+breaking: false
+security: false
+---
+
+# 0.1.1 — 2026-05-25
+
+## Fixed
+
+- **`gdelt_get_tone_distribution`** — `tonechart` bins expose article URLs under `toparts`, not `articles`; handler now reads the correct key
+- **`gdelt_get_coverage_timeline`** — `volume_with_articles` mode likewise reads `toparts` per timestep instead of `articles`
+- **`gdelt_get_tv_clips`** — thumbnail URL field is `preview_thumb`, not `thumbnail_url`; clips now include thumbnails when available
+- **`gdelt_search_tv`** — TV timeline modes corrected: `timelinevolnorm` (normalized) and `timelinevol` (raw); prior values `timelinenorm`/`timeline` are not valid TV API modes
+- **`gdelt_get_tv_context`** — `RawTvWord` fields are `label`/`count`, not `Label`/`Score`; context words now populate correctly
+- **`gdelt_get_tv_trending`** — trending response key is `OverallTrendingTopics` (with fallback to `OverallTrendingPhrases`); prior key `topics` never matched, always returned empty
+- **`gdelt_list_tv_stations`** — station list response key is `station_details`, not `stations`; station metadata now returns correctly
+- **Empty-response guard** — `gdelt-fetch.ts` now throws `serviceUnavailable` on an empty API response body instead of passing a blank string to `JSON.parse`

package/changelog/template.md

@@ -0,0 +1,119 @@
+---
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. 350 character cap.
+# Default short and scannable. Don't pad, don't stitch unrelated changes with
+# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
+# inside the value as a key separator and fails GitHub's strict parser.
+summary: ""
+
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
+breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+security: false
+---
+
+# <version> — YYYY-MM-DD
+
+<!--
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
+  name the symbol, state what changed, stop. Use a second sentence only when
+  it carries weight. If a bullet feels long, it is.
+
+  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
+  relevant skill), ceremonial framings ("This release introduces…",
+  backwards-compat paragraphs), file-by-file test enumerations, internal
+  implementation notes. Prefer code/symbol names over English re-explanations.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
+
+  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
+  via `gh release create --notes-from-tag`. The tag is a derivative of this
+  changelog entry — a condensed, scannable version, not a copy. Format:
+
+    <theme — omit version number, GitHub prepends it>
+                                                          ← blank line
+    <1-2 sentence context: what this release does>
+                                                          ← blank line
+    Dependency bumps:                                     ← section header
+                                                          ← blank line
+    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
+                                                          ← blank line
+    Changed:                                              ← only sections with entries
+                                                          ← blank line
+    - `format()` output includes `query` in text mode
+                                                          ← blank line
+    Added:
+                                                          ← blank line
+    - `manifest.json` scaffolded for MCPB bundle support
+    - Install badges (Claude Desktop, Cursor, VS Code)
+                                                          ← blank line
+    <N> tests pass; `bun run devcheck` clean.             ← footer
+
+  Never a flat comma-separated string. Always structured markdown with
+  sections. The tag must scan well as a rendered GitHub Release page.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
+## Fixed
+
+-
+
+<!-- ## Security
+
+- -->

package/dist/config/server-config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Server-specific configuration parsed from environment variables.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodDefault<z.ZodString>;
+    requestDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;iBAYtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}

package/dist/config/server-config.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Server-specific configuration parsed from environment variables.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+const ServerConfigSchema = z.object({
+    baseUrl: z
+        .string()
+        .url()
+        .default('https://api.gdeltproject.org/api/v2')
+        .describe('Base URL for GDELT APIs'),
+    requestDelayMs: z.coerce
+        .number()
+        .int()
+        .min(0)
+        .default(5100)
+        .describe('Minimum milliseconds between API requests to satisfy 1 req/5s rate limit'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        baseUrl: 'GDELT_BASE_URL',
+        requestDelayMs: 'GDELT_REQUEST_DELAY_MS',
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,qCAAqC,CAAC;SAC9C,QAAQ,CAAC,yBAAyB,CAAC;IACtC,cAAc,EAAE,CAAC,CAAC,MAAM;SACrB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,0EAA0E,CAAC;CACxF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,gBAAgB;QACzB,cAAc,EAAE,wBAAwB;KACzC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview gdelt-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview gdelt-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from './config/server-config.js';
+import { gdeltGetCoverageBreakdown, gdeltGetCoverageTimeline, gdeltGetToneDistribution, gdeltGetTvClips, gdeltGetTvContext, gdeltGetTvTrending, gdeltListTvStations, gdeltSearchArticles, gdeltSearchTv, } from './mcp-server/tools/definitions/index.js';
+import { initGdeltDocService } from './services/gdelt/gdelt-doc-service.js';
+import { initGdeltTvService } from './services/gdelt/gdelt-tv-service.js';
+import { initRateLimiter } from './services/gdelt/rate-limiter.js';
+await createApp({
+    tools: [
+        gdeltSearchArticles,
+        gdeltGetCoverageTimeline,
+        gdeltGetToneDistribution,
+        gdeltGetCoverageBreakdown,
+        gdeltSearchTv,
+        gdeltGetTvClips,
+        gdeltGetTvContext,
+        gdeltGetTvTrending,
+        gdeltListTvStations,
+    ],
+    resources: [],
+    prompts: [],
+    instructions: 'GDELT MCP Server — global news and TV transcript analysis.\n' +
+        '- gdelt_search_articles: full-text news search (last 3 months, 65+ languages)\n' +
+        '- gdelt_get_coverage_timeline: when did coverage spike? (use mode volume_with_articles for signal detection)\n' +
+        '- gdelt_get_tone_distribution: emotional distribution of coverage (histogram)\n' +
+        '- gdelt_get_coverage_breakdown: which countries/languages drove coverage?\n' +
+        '- gdelt_search_tv: US TV transcript search (2009–Oct 2024, 150+ stations)\n' +
+        '- gdelt_get_tv_clips: read actual TV transcript excerpts with archive links\n' +
+        '- gdelt_get_tv_context: vocabulary framing a topic on television\n' +
+        '- gdelt_get_tv_trending: current trending topics on TV news (Oct 2024 archive cutoff)\n' +
+        '- gdelt_list_tv_stations: verify station IDs and active date ranges before TV queries\n' +
+        'Rate limit: 1 request per 5 seconds — multi-step workflows take 15+ seconds.',
+    setup(core) {
+        const serverConfig = getServerConfig();
+        initRateLimiter(serverConfig.requestDelayMs);
+        initGdeltDocService(core.config, core.storage, serverConfig);
+        initGdeltTvService(core.config, core.storage, serverConfig);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,GACd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAEnE,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,mBAAmB;QACnB,wBAAwB;QACxB,wBAAwB;QACxB,yBAAyB;QACzB,aAAa;QACb,eAAe;QACf,iBAAiB;QACjB,kBAAkB;QAClB,mBAAmB;KACpB;IACD,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,YAAY,EACV,8DAA8D;QAC9D,iFAAiF;QACjF,gHAAgH;QAChH,iFAAiF;QACjF,6EAA6E;QAC7E,6EAA6E;QAC7E,+EAA+E;QAC/E,oEAAoE;QACpE,yFAAyF;QACzF,yFAAyF;QACzF,8EAA8E;IAEhF,KAAK,CAAC,IAAI;QACR,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;QACvC,eAAe,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;QAC7C,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC7D,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC9D,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Shared date resolution inference for GDELT timeline data.
+ * @module mcp-server/tools/date-resolution
+ */
+/** Infer date resolution from a list of GDELT date strings. */
+export declare function inferDateResolution(dates: string[]): 'hour' | 'day';
+//# sourceMappingURL=date-resolution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"date-resolution.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-resolution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,KAAK,CAKnE"}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Shared date resolution inference for GDELT timeline data.
+ * @module mcp-server/tools/date-resolution
+ */
+/** Infer date resolution from a list of GDELT date strings. */
+export function inferDateResolution(dates) {
+    if (dates.length < 2)
+        return 'day';
+    const sample = dates[0] ?? '';
+    // GDELT timeline dates include a time component for hourly data
+    return sample.includes('T') && sample.length > 10 ? 'hour' : 'day';
+}
+//# sourceMappingURL=date-resolution.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"date-resolution.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/date-resolution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,KAAe;IACjD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9B,gEAAgE;IAChE,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AACrE,CAAC"}