euparliamentmonitor 0.8.25 → 0.8.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.25",
+  "version": "0.8.27",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -162,7 +162,7 @@
     "prettier": "3.8.2",
     "ts-api-utils": "2.5.0",
     "tsx": "4.21.0",
-    "typedoc": "0.28.18",
+    "typedoc": "0.28.19",
     "typescript": "6.0.2",
     "vitest": "4.1.4"
   },
@@ -170,7 +170,7 @@
     "node": ">=25"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.2.2"
+    "european-parliament-mcp-server": "1.2.4"
   },
   "optionalDependencies": {
     "worldbank-mcp": "1.0.1"

package/scripts/constants/committee-indicator-map.d.ts

@@ -10,12 +10,31 @@
  *
  * Used by news generation strategies to automatically select the right
  * economic indicators when enriching articles with World Bank data.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The 34 indicators in {@link WB_INDICATORS} are a **curated subset** mapped
+ * to EP committee mandates. The full World Bank catalog has **thousands** of
+ * indicators. For dynamic indicator discovery:
+ *
+ * 1. Use `search-indicators` MCP tool to find indicators by keyword on demand
+ * 2. Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator**
+ *    reference organized by 10 EP policy domains
+ * 3. Use `analysis/worldbank/use-cases.md` to decide when indicators add editorial value
+ * 4. Use `analysis/worldbank/chart-integration-guide.md` for visualization templates
+ *
+ * **Never assume the indicators below are exhaustive.** Always consider whether
+ * `search-indicators` would reveal a more specific indicator for the policy topic.
  */
 import { ArticleCategory, AnalysisPerspective } from '../types/common.js';
 /**
  * Extended set of World Bank indicator IDs relevant to EU Parliament policy areas.
  * Superset of {@link PolicyRelevantIndicators} — includes domain-specific indicators
  * that map to individual committee mandates.
+ *
+ * ⚠️ **AI Agents**: This is a **curated subset of 34 indicators**. The World Bank
+ * has thousands more. Use `search-indicators` MCP tool for on-demand discovery.
+ * Full reference: `analysis/worldbank/indicator-catalog.md` (200+ indicators).
  */
 export declare const WB_INDICATORS: {
     /** GDP (current US$) */

package/scripts/constants/committee-indicator-map.js

@@ -12,6 +12,21 @@
  *
  * Used by news generation strategies to automatically select the right
  * economic indicators when enriching articles with World Bank data.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The 34 indicators in {@link WB_INDICATORS} are a **curated subset** mapped
+ * to EP committee mandates. The full World Bank catalog has **thousands** of
+ * indicators. For dynamic indicator discovery:
+ *
+ * 1. Use `search-indicators` MCP tool to find indicators by keyword on demand
+ * 2. Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator**
+ *    reference organized by 10 EP policy domains
+ * 3. Use `analysis/worldbank/use-cases.md` to decide when indicators add editorial value
+ * 4. Use `analysis/worldbank/chart-integration-guide.md` for visualization templates
+ *
+ * **Never assume the indicators below are exhaustive.** Always consider whether
+ * `search-indicators` would reveal a more specific indicator for the policy topic.
  */
 import { ArticleCategory, AnalysisPerspective } from '../types/common.js';
 // ─── Priority Constants ──────────────────────────────────────────────────────
@@ -61,6 +76,10 @@ const N = {
  * Extended set of World Bank indicator IDs relevant to EU Parliament policy areas.
  * Superset of {@link PolicyRelevantIndicators} — includes domain-specific indicators
  * that map to individual committee mandates.
+ *
+ * ⚠️ **AI Agents**: This is a **curated subset of 34 indicators**. The World Bank
+ * has thousands more. Use `search-indicators` MCP tool for on-demand discovery.
+ * Full reference: `analysis/worldbank/indicator-catalog.md` (200+ indicators).
  */
 export const WB_INDICATORS = {
     // ── Macro-economic ──

package/scripts/generators/pipeline/fetch-stage.js

@@ -1072,15 +1072,75 @@ const TIMEFRAME_FALLBACK_CHAIN = new Map([
 function getWiderTimeframe(current) {
     return TIMEFRAME_FALLBACK_CHAIN.get(current);
 }
+/**
+ * Error thrown when the EP MCP server returns a timeout envelope instead of data.
+ * This is distinct from network-level timeouts — the MCP server responds successfully
+ * but reports that the upstream EP API did not respond in time.
+ */
+class UpstreamTimeoutError extends Error {
+    constructor(toolName) {
+        super(`EP MCP upstream timeout for ${toolName} — data may be incomplete`);
+        this.name = 'UpstreamTimeoutError';
+    }
+}
+/**
+ * Check whether a parsed MCP response envelope indicates an upstream timeout
+ * and throw {@link UpstreamTimeoutError} if so.  The EP MCP server returns
+ * `{ timedOut: true, status: "timeout" }` when the upstream EP API did not
+ * respond within the configured timeout window.  Throwing ensures callers
+ * stop timeframe-widening retry loops instead of treating the empty `data: []`
+ * as "no data".
+ *
+ * @param value - Parsed response value (may be an object envelope or a bare array)
+ * @throws {UpstreamTimeoutError} when the response indicates an upstream timeout
+ */
+function checkUpstreamTimeout(value) {
+    if (typeof value !== 'object' || value === null)
+        return;
+    const envelope = value;
+    if (envelope['timedOut'] === true || envelope['status'] === 'timeout') {
+        const toolName = envelope['toolName'] ? String(envelope['toolName']) : 'unknown';
+        console.warn(`${WARN_PREFIX} EP MCP upstream timeout for ${toolName} — data may be incomplete. ` +
+            'Consider using year-based endpoints as fallback.');
+        throw new UpstreamTimeoutError(toolName);
+    }
+}
+/**
+ * Handle errors from feed-fetching functions with timeframe-widening logic.
+ * Encapsulates the common catch-block pattern: upstream timeouts return `undefined`
+ * (caller should stop retrying), errors whose message contains '404' or 'timed out'
+ * widen to the next timeframe, and other errors log and return `undefined`.
+ *
+ * @param error - Caught error
+ * @param tf - Current feed timeframe
+ * @param toolName - Feed tool name for log messages
+ * @returns A wider {@link FeedTimeframe} to retry, or `undefined` to stop
+ */
+function handleFeedFetchError(error, tf, toolName) {
+    if (error instanceof UpstreamTimeoutError)
+        return undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    const wider = getWiderTimeframe(tf);
+    if (wider && (message.includes('404') || message.includes('timed out'))) {
+        console.warn(`${WARN_PREFIX} ${toolName} failed (${tf}): ${message} — retrying with ${wider}`);
+        return wider;
+    }
+    console.warn(`${WARN_PREFIX} ${toolName} failed:`, message);
+    return undefined;
+}
 /**
  * Parse a feed result from MCP into a flat array of items.
  * EP API v2 feeds return items under the `data` key:
  * `{ data: [{ id, type, work_type, identifier, label }], "@context": [...] }`
  *
  * Also handles legacy shapes (`feed`, `entries`, `items`) and bare arrays.
+ * Throws {@link UpstreamTimeoutError} when the MCP server reports an upstream
+ * timeout (`{ timedOut: true, status: "timeout" }`), so callers can stop
+ * timeframe-widening loops instead of treating the empty `data: []` as "no data".
  *
  * @param result - Raw MCP tool result
  * @returns Array of parsed feed entry objects (may be empty)
+ * @throws {UpstreamTimeoutError} when the response indicates an upstream timeout
  */
 function parseFeedResult(result) {
     if (!result?.content?.[0]?.text)
@@ -1088,12 +1148,14 @@ function parseFeedResult(result) {
     const parsed = parseJSON(result.content[0].text, 'feed');
     if (!parsed)
         return [];
+    checkUpstreamTimeout(parsed);
+    const envelope = parsed;
     // EP API v2 feeds use `data` key; also check legacy shapes
     const candidates = [
-        parsed['data'],
-        parsed['feed'],
-        parsed['entries'],
-        parsed['items'],
+        envelope['data'],
+        envelope['feed'],
+        envelope['entries'],
+        envelope['items'],
         parsed,
     ];
     for (const candidate of candidates) {
@@ -1106,9 +1168,13 @@ function parseFeedResult(result) {
  * Parse an EP API v2 feed response envelope in a single JSON parse, returning
  * both the array of feed items and the API-reported total count.
  * Avoids parsing the same JSON payload twice when both values are needed.
+ * Throws {@link UpstreamTimeoutError} when the MCP server reports an upstream
+ * timeout (`{ timedOut: true, status: "timeout" }`), so callers can stop
+ * timeframe-widening loops instead of treating the empty `data: []` as "no data".
  *
  * @param result - Raw MCP tool result
  * @returns Object with `items` array and `total` count from the API
+ * @throws {UpstreamTimeoutError} when the response indicates an upstream timeout
  */
 function parseFeedEnvelope(result) {
     if (!result?.content?.[0]?.text)
@@ -1116,6 +1182,7 @@ function parseFeedEnvelope(result) {
     const parsed = parseJSON(result.content[0].text, 'feed');
     if (!parsed || typeof parsed !== 'object')
         return { items: [], total: 0 };
+    checkUpstreamTimeout(parsed);
     const envelope = parsed;
     const total = typeof envelope['total'] === 'number' ? envelope['total'] : 0;
     const candidates = [
@@ -1178,14 +1245,11 @@ export async function fetchAdoptedTextsFeed(client, timeframe = 'one-week') {
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_adopted_texts_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_adopted_texts_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_adopted_texts_feed failed:`, message);
                 return [];
             }
         }
@@ -1220,14 +1284,11 @@ export async function fetchEventsFeed(client, timeframe = 'one-week') {
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_events_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_events_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_events_feed failed:`, message);
                 return [];
             }
         }
@@ -1261,14 +1322,11 @@ export async function fetchProceduresFeed(client, timeframe = 'one-week') {
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_procedures_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_procedures_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_procedures_feed failed:`, message);
                 return [];
             }
         }
@@ -1319,6 +1377,8 @@ export async function fetchMEPsFeedWithTotal(client, timeframe = 'one-week') {
         return { items, total };
     }
     catch (error) {
+        if (error instanceof UpstreamTimeoutError)
+            return { items: [], total: 0 };
         const message = error instanceof Error ? error.message : String(error);
         console.warn(`${WARN_PREFIX} get_meps_feed failed:`, message);
         return { items: [], total: 0 };
@@ -1348,14 +1408,11 @@ export async function fetchDocumentsFeed(client, timeframe = 'one-week') {
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_documents_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_documents_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_documents_feed failed:`, message);
                 return [];
             }
         }
@@ -1386,14 +1443,11 @@ export async function fetchPlenaryDocumentsFeed(client, timeframe = 'one-week')
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_plenary_documents_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_plenary_documents_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_plenary_documents_feed failed:`, message);
                 return [];
             }
         }
@@ -1424,14 +1478,11 @@ export async function fetchCommitteeDocumentsFeed(client, timeframe = 'one-week'
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_committee_documents_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_committee_documents_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_committee_documents_feed failed:`, message);
                 return [];
             }
         }
@@ -1462,14 +1513,11 @@ export async function fetchPlenarySessionDocumentsFeed(client, timeframe = 'one-
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_plenary_session_documents_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_plenary_session_documents_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_plenary_session_documents_feed failed:`, message);
                 return [];
             }
         }
@@ -1500,14 +1548,11 @@ export async function fetchExternalDocumentsFeed(client, timeframe = 'one-week')
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_external_documents_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_external_documents_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_external_documents_feed failed:`, message);
                 return [];
             }
         }
@@ -1538,14 +1583,11 @@ export async function fetchQuestionsFeed(client, timeframe = 'one-week') {
             currentTimeframe = getWiderTimeframe(currentTimeframe);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const wider = getWiderTimeframe(tf);
-            if (wider && (message.includes('404') || message.includes('timed out'))) {
-                console.warn(`${WARN_PREFIX} get_parliamentary_questions_feed failed (${currentTimeframe}): ${message} — retrying with ${wider}`);
+            const wider = handleFeedFetchError(error, tf, 'get_parliamentary_questions_feed');
+            if (wider) {
                 currentTimeframe = wider;
             }
             else {
-                console.warn(`${WARN_PREFIX} get_parliamentary_questions_feed failed:`, message);
                 return [];
             }
         }
@@ -1568,6 +1610,8 @@ export async function fetchDeclarationsFeed(client, timeframe = 'one-week') {
         return parseFeedResult(result).map((item) => mapFeedItemBase(item));
     }
     catch (error) {
+        if (error instanceof UpstreamTimeoutError)
+            return [];
         const message = error instanceof Error ? error.message : String(error);
         console.warn(`${WARN_PREFIX} get_mep_declarations_feed failed:`, message);
         return [];
@@ -1589,6 +1633,8 @@ export async function fetchCorporateBodiesFeed(client, timeframe = 'one-week') {
         return parseFeedResult(result).map((item) => mapFeedItemBase(item));
     }
     catch (error) {
+        if (error instanceof UpstreamTimeoutError)
+            return [];
         const message = error instanceof Error ? error.message : String(error);
         console.warn(`${WARN_PREFIX} get_corporate_bodies_feed failed:`, message);
         return [];

package/scripts/index.d.ts

@@ -44,7 +44,7 @@ export { assessPoliticalThreats, buildActorThreatProfiles, buildConsequenceTree,
 export { stripHtmlTags, stripScriptBlocks } from './utils/html-sanitize.js';
 export { parseArticleFilename, formatSlug, calculateReadTime, escapeHTML, isSafeURL, validateArticleHTML, type ArticleValidationResult, } from './utils/file-utils.js';
 export { detectCategory } from './utils/article-category.js';
-export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
+export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, COMPARISON_COUNTRIES, WB_AGGREGATE_LABELS, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
 export { generateArticleHTML } from './templates/article-template.js';
 export { computeArticleQualityScore, buildTableOfContents, buildQualityScoreBadge, } from './templates/section-builders.js';
 export { ALL_LANGUAGES, LANGUAGE_PRESETS, LANGUAGE_FLAGS, LANGUAGE_NAMES, getLocalizedString, isSupportedLanguage, getTextDirection, } from './constants/language-core.js';

package/scripts/index.js

@@ -61,7 +61,7 @@ export { parseArticleFilename, formatSlug, calculateReadTime, escapeHTML, isSafe
 // ─── Article Category Detection ──────────────────────────────────────────────
 export { detectCategory } from './utils/article-category.js';
 // ─── World Bank Data Utilities ───────────────────────────────────────────────
-export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
+export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, COMPARISON_COUNTRIES, WB_AGGREGATE_LABELS, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
 // ─── Templates ───────────────────────────────────────────────────────────────
 export { generateArticleHTML } from './templates/article-template.js';
 export { computeArticleQualityScore, buildTableOfContents, buildQualityScoreBadge, } from './templates/section-builders.js';

package/scripts/mcp/ep-mcp-client.js

@@ -29,7 +29,7 @@ const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
 /**
  * Classify an error message into a diagnostic error category.
  *
- * Maps EP MCP Server v1.2.2 structured error codes and generic HTTP/network
+ * Maps EP MCP Server v1.2.4 structured error codes and generic HTTP/network
  * errors into one of six broad categories used for logging and retry decisions:
  *
  * Returned categories (priority order):
@@ -45,7 +45,7 @@ const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
  */
 function classifyToolError(message) {
     const lowerMsg = message.toLowerCase();
-    // EP MCP Server v1.2.2 structured error codes (matched case-insensitively)
+    // EP MCP Server v1.2.4 structured error codes (matched case-insensitively)
     if (lowerMsg.includes('internal_error')) {
         return 'INTERNAL_ERROR';
     }

package/scripts/types/world-bank.d.ts

@@ -69,17 +69,82 @@ export interface PolicyRelevantIndicators {
     gdp: string;
     /** GDP growth (annual %) — NY.GDP.MKTP.KD.ZG */
     gdpGrowth: string;
+    /** GDP per capita (current US$) — NY.GDP.PCAP.CD */
+    gdpPerCapita: string;
+    /** GNI per capita, Atlas method (current US$) — NY.GNP.PCAP.CD */
+    gniPerCapita: string;
     /** Inflation, consumer prices (annual %) — FP.CPI.TOTL.ZG */
     inflation: string;
     /** Unemployment, total (% of total labor force) — SL.UEM.TOTL.ZS */
     unemployment: string;
+    /** Exports of goods and services (% of GDP) — NE.EXP.GNFS.ZS */
+    exportsGdp: string;
+    /** Foreign direct investment, net inflows (BoP, current US$) — BN.KLT.DINV.CD */
+    fdiNet: string;
     /** Trade (% of GDP) — NE.TRD.GNFS.ZS */
     trade: string;
-    /** CO2 emissions (metric tons per capita) — EN.ATM.CO2E.PC */
-    co2Emissions: string;
+    /** Tax revenue (% of GDP) — GC.TAX.TOTL.GD.ZS */
+    taxRevenue: string;
+    /** General government final consumption expenditure (% of GDP) — NE.CON.GOVT.ZS */
+    govExpenditure: string;
+    /** Military expenditure (% of GDP) — MS.MIL.XPND.GD.ZS */
+    militaryExpenditure: string;
     /** Population, total — SP.POP.TOTL */
     population: string;
+    /** Life expectancy at birth, total (years) — SP.DYN.LE00.IN */
+    lifeExpectancy: string;
+    /** Birth rate, crude (per 1,000 people) — SP.DYN.CBRT.IN */
+    birthRate: string;
+    /** Death rate, crude (per 1,000 people) — SP.DYN.CDRT.IN */
+    deathRate: string;
+    /** Individuals using the Internet (% of population) — IT.NET.USER.ZS */
+    internetUsers: string;
+    /** Current health expenditure (% of GDP) — SH.XPD.CHEX.GD.ZS */
+    healthExpenditure: string;
+    /** Physicians (per 1,000 people) — SH.MED.PHYS.ZS */
+    physicians: string;
+    /** Hospital beds (per 1,000 people) — SH.MED.BEDS.ZS */
+    hospitalBeds: string;
+    /** Government expenditure on education, total (% of GDP) — SE.XPD.TOTL.GD.ZS */
+    educationExpenditure: string;
+    /** CO2 emissions (metric tons per capita) — EN.ATM.CO2E.PC */
+    co2Emissions: string;
+    /** Renewable energy consumption (% of total) — EG.FEC.RNEW.ZS */
+    renewableEnergy: string;
     /** Research and development expenditure (% of GDP) — GB.XPD.RSDV.GD.ZS */
     rdExpenditure: string;
+    /** High-technology exports (% of manufactured exports) — TX.VAL.TECH.MF.ZS */
+    hightechExports: string;
+}
+/**
+ * World Bank MCP tool names available for data fetching.
+ * Maps to the tool functions on the worldbank-mcp server.
+ *
+ * These type literals use **kebab-case** (e.g., `get-economic-data`) to match
+ * the underlying tool registration names in worldbank-mcp@1.0.0
+ * (`server.tool('get-economic-data', ...)`).
+ * When called via the MCP gateway prefix in this repository's workflows, use
+ * the corresponding **snake_case** form, for example
+ * `world_bank___get_economic_data(...)`.
+ *
+ * **Note:** The codebase also has a `WorldBankMCPClient.getIndicatorForCountry()`
+ * wrapper (in `src/mcp/wb-mcp-client.ts`) that calls the `get_indicator_for_country`
+ * tool — this is a legacy convenience method not listed in this type union since it
+ * is not part of the standard worldbank-mcp tool surface.
+ */
+export type WBMCPToolName = 'get-economic-data' | 'get-social-data' | 'get-health-data' | 'get-education-data' | 'get-country-info' | 'get-countries' | 'search-indicators';
+/**
+ * World Bank MCP tool indicator key mapping.
+ * Maps each tool to the indicator key literals it accepts.
+ */
+export interface WBToolIndicatorKeys {
+    /** Economic indicators accepted by `get-economic-data` */
+    'get-economic-data': 'GDP' | 'GDP_GROWTH' | 'GDP_PER_CAPITA' | 'GNI' | 'GNI_PER_CAPITA' | 'EXPORTS_GDP' | 'FDI_NET' | 'INFLATION' | 'UNEMPLOYMENT';
+    /** Social indicators accepted by `get-social-data` */
+    'get-social-data': 'POPULATION' | 'LIFE_EXPECTANCY' | 'BIRTH_RATE' | 'DEATH_RATE' | 'INTERNET_USERS';
+    /** Health indicators accepted by `get-health-data` */
+    'get-health-data': 'HEALTH_EXPENDITURE' | 'PHYSICIANS' | 'HOSPITAL_BEDS' | 'IMMUNIZATION' | 'HIV_PREVALENCE' | 'MALNUTRITION' | 'TUBERCULOSIS';
+    /** Education indicators accepted by `get-education-data` */
+    'get-education-data': 'LITERACY_RATE' | 'SCHOOL_ENROLLMENT' | 'SCHOOL_COMPLETION' | 'TEACHERS_PRIMARY' | 'EDUCATION_EXPENDITURE';
 }
 //# sourceMappingURL=world-bank.d.ts.map

package/scripts/utils/world-bank-data.d.ts

@@ -9,6 +9,22 @@
  * Functions in this module are designed to be stateless and avoid observable
  * side effects, with the exception of explicitly recording metadata such as
  * data timestamps in returned objects.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The constants below ({@link POLICY_INDICATORS}, {@link EU_COUNTRY_CODES},
+ * {@link COMPARISON_COUNTRIES}) are a **convenience subset** used by TypeScript
+ * code for formatting and parsing. They do **NOT** represent the full World Bank
+ * indicator inventory.
+ *
+ * **For indicator selection in articles and analysis:**
+ * 1. Read `analysis/worldbank/indicator-catalog.md` — **200+ indicators** by EP policy domain
+ * 2. Use `search-indicators` MCP tool to **discover indicators on demand** by keyword
+ * 3. Read `analysis/worldbank/eu-country-mapping.md` for country codes + comparison groups
+ * 4. Read `analysis/worldbank/chart-integration-guide.md` for Chart.js + Mermaid templates
+ *
+ * The World Bank MCP server has thousands of indicators beyond the ones listed
+ * here. Use `search-indicators` to find the best match for any policy topic.
  */
 import type { EconomicContext, PolicyRelevantIndicators, WorldBankIndicator } from '../types/world-bank.js';
 /**
@@ -18,9 +34,25 @@ import type { EconomicContext, PolicyRelevantIndicators, WorldBankIndicator } fr
 export declare const EU_COUNTRY_CODES: Readonly<Record<string, string>>;
 /** EU aggregate code in World Bank (European Union) */
 export declare const EU_AGGREGATE_CODE = "EUU";
+/**
+ * Comparison country codes for benchmarking EU performance against global peers.
+ * Organized by geopolitical relevance to EU Parliament policy analysis.
+ */
+export declare const COMPARISON_COUNTRIES: Readonly<Record<string, string>>;
+/**
+ * Aggregate/region codes useful for EU benchmarking.
+ * Keys are World Bank group codes; values are human-readable labels.
+ */
+export declare const WB_AGGREGATE_LABELS: Readonly<Record<string, string>>;
 /**
  * World Bank indicator IDs relevant to EU Parliament policy analysis.
- * These indicators map to common policy areas discussed in EP legislation.
+ *
+ * ⚠️ **AI Agents**: This is a convenience subset of 25 core indicators used by
+ * TypeScript formatting code. The World Bank has **thousands** of indicators.
+ * For article/analysis generation:
+ * - Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator** reference
+ * - Use `search-indicators` MCP tool to discover indicators on demand by keyword
+ * - See `analysis/worldbank/use-cases.md` for when each indicator type adds value
  */
 export declare const POLICY_INDICATORS: PolicyRelevantIndicators;
 /**

package/scripts/utils/world-bank-data.js

@@ -37,19 +37,96 @@ export const EU_COUNTRY_CODES = {
 };
 /** EU aggregate code in World Bank (European Union) */
 export const EU_AGGREGATE_CODE = 'EUU';
+/**
+ * Comparison country codes for benchmarking EU performance against global peers.
+ * Organized by geopolitical relevance to EU Parliament policy analysis.
+ */
+export const COMPARISON_COUNTRIES = {
+    // ── G7 Non-EU ──
+    US: 'USA', // United States
+    GB: 'GBR', // United Kingdom (post-Brexit benchmark)
+    JP: 'JPN', // Japan
+    CA: 'CAN', // Canada
+    // ── BRICS ──
+    CN: 'CHN', // China
+    IN: 'IND', // India
+    BR: 'BRA', // Brazil
+    RU: 'RUS', // Russia
+    ZA: 'ZAF', // South Africa
+    // ── EU Candidate States ──
+    UA: 'UKR', // Ukraine
+    TR: 'TUR', // Türkiye
+    RS: 'SRB', // Serbia
+    ME: 'MNE', // Montenegro
+    AL: 'ALB', // Albania
+    MK: 'MKD', // North Macedonia
+    MD: 'MDA', // Moldova
+    BA: 'BIH', // Bosnia & Herzegovina
+    GE: 'GEO', // Georgia
+    // ── Key Trade Partners ──
+    KR: 'KOR', // South Korea
+    AU: 'AUS', // Australia
+    NO: 'NOR', // Norway (EEA)
+    CH: 'CHE', // Switzerland (EFTA)
+    IL: 'ISR', // Israel
+};
+/**
+ * Aggregate/region codes useful for EU benchmarking.
+ * Keys are World Bank group codes; values are human-readable labels.
+ */
+export const WB_AGGREGATE_LABELS = {
+    EUU: 'European Union',
+    EMU: 'Euro area',
+    OED: 'OECD members',
+    WLD: 'World',
+    ECS: 'Europe & Central Asia',
+    NAC: 'North America',
+    EAS: 'East Asia & Pacific',
+    SSF: 'Sub-Saharan Africa',
+};
 /**
  * World Bank indicator IDs relevant to EU Parliament policy analysis.
- * These indicators map to common policy areas discussed in EP legislation.
+ *
+ * ⚠️ **AI Agents**: This is a convenience subset of 25 core indicators used by
+ * TypeScript formatting code. The World Bank has **thousands** of indicators.
+ * For article/analysis generation:
+ * - Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator** reference
+ * - Use `search-indicators` MCP tool to discover indicators on demand by keyword
+ * - See `analysis/worldbank/use-cases.md` for when each indicator type adds value
  */
 export const POLICY_INDICATORS = {
+    // Macro-economic (get-economic-data)
     gdp: 'NY.GDP.MKTP.CD',
     gdpGrowth: 'NY.GDP.MKTP.KD.ZG',
+    gdpPerCapita: 'NY.GDP.PCAP.CD',
+    gniPerCapita: 'NY.GNP.PCAP.CD',
     inflation: 'FP.CPI.TOTL.ZG',
     unemployment: 'SL.UEM.TOTL.ZS',
+    exportsGdp: 'NE.EXP.GNFS.ZS',
+    fdiNet: 'BN.KLT.DINV.CD',
+    // Trade & fiscal
     trade: 'NE.TRD.GNFS.ZS',
-    co2Emissions: 'EN.ATM.CO2E.PC',
+    taxRevenue: 'GC.TAX.TOTL.GD.ZS',
+    govExpenditure: 'NE.CON.GOVT.ZS',
+    militaryExpenditure: 'MS.MIL.XPND.GD.ZS',
+    // Social (get-social-data)
     population: 'SP.POP.TOTL',
+    lifeExpectancy: 'SP.DYN.LE00.IN',
+    birthRate: 'SP.DYN.CBRT.IN',
+    deathRate: 'SP.DYN.CDRT.IN',
+    internetUsers: 'IT.NET.USER.ZS',
+    // Health (get-health-data)
+    healthExpenditure: 'SH.XPD.CHEX.GD.ZS',
+    physicians: 'SH.MED.PHYS.ZS',
+    hospitalBeds: 'SH.MED.BEDS.ZS',
+    // Education (get-education-data)
+    educationExpenditure: 'SE.XPD.TOTL.GD.ZS',
+    // Environment & energy
+    co2Emissions: 'EN.ATM.CO2E.PC',
+    renewableEnergy: 'EG.FEC.RNEW.ZS',
+    // Research & innovation
     rdExpenditure: 'GB.XPD.RSDV.GD.ZS',
+    hightechExports: 'TX.VAL.TECH.MF.ZS',
 };
 // ─── CSV Parsing ─────────────────────────────────────────────────────────────
 /** Known CSV header aliases for each World Bank field */
@@ -194,7 +271,16 @@ export function formatIndicatorValue(value, indicatorId) {
         indicatorId === POLICY_INDICATORS.inflation ||
         indicatorId === POLICY_INDICATORS.unemployment ||
         indicatorId === POLICY_INDICATORS.trade ||
-        indicatorId === POLICY_INDICATORS.rdExpenditure) {
+        indicatorId === POLICY_INDICATORS.taxRevenue ||
+        indicatorId === POLICY_INDICATORS.govExpenditure ||
+        indicatorId === POLICY_INDICATORS.militaryExpenditure ||
+        indicatorId === POLICY_INDICATORS.exportsGdp ||
+        indicatorId === POLICY_INDICATORS.healthExpenditure ||
+        indicatorId === POLICY_INDICATORS.educationExpenditure ||
+        indicatorId === POLICY_INDICATORS.internetUsers ||
+        indicatorId === POLICY_INDICATORS.renewableEnergy ||
+        indicatorId === POLICY_INDICATORS.rdExpenditure ||
+        indicatorId === POLICY_INDICATORS.hightechExports) {
         return `${value.toFixed(1)}%`;
     }
     // CO2 emissions - metric tons per capita
@@ -232,12 +318,29 @@ export function buildEconomicContext(countryCode, countryName, indicatorData) {
     const indicatorNames = {
         [POLICY_INDICATORS.gdp]: 'GDP',
         [POLICY_INDICATORS.gdpGrowth]: 'GDP Growth',
+        [POLICY_INDICATORS.gdpPerCapita]: 'GDP per Capita',
+        [POLICY_INDICATORS.gniPerCapita]: 'GNI per Capita',
         [POLICY_INDICATORS.inflation]: 'Inflation',
         [POLICY_INDICATORS.unemployment]: 'Unemployment',
+        [POLICY_INDICATORS.exportsGdp]: 'Exports (% of GDP)',
+        [POLICY_INDICATORS.fdiNet]: 'FDI Net Inflows',
         [POLICY_INDICATORS.trade]: 'Trade (% of GDP)',
-        [POLICY_INDICATORS.co2Emissions]: 'CO₂ Emissions',
+        [POLICY_INDICATORS.taxRevenue]: 'Tax Revenue (% of GDP)',
+        [POLICY_INDICATORS.govExpenditure]: 'Gov. Expenditure (% of GDP)',
+        [POLICY_INDICATORS.militaryExpenditure]: 'Military Expenditure (% of GDP)',
         [POLICY_INDICATORS.population]: 'Population',
-        [POLICY_INDICATORS.rdExpenditure]: 'R&D Expenditure',
+        [POLICY_INDICATORS.lifeExpectancy]: 'Life Expectancy',
+        [POLICY_INDICATORS.birthRate]: 'Birth Rate',
+        [POLICY_INDICATORS.deathRate]: 'Death Rate',
+        [POLICY_INDICATORS.internetUsers]: 'Internet Users (%)',
+        [POLICY_INDICATORS.healthExpenditure]: 'Health Expenditure (% of GDP)',
+        [POLICY_INDICATORS.physicians]: 'Physicians (per 1,000)',
+        [POLICY_INDICATORS.hospitalBeds]: 'Hospital Beds (per 1,000)',
+        [POLICY_INDICATORS.educationExpenditure]: 'Education Expenditure (% of GDP)',
+        [POLICY_INDICATORS.co2Emissions]: 'CO₂ Emissions',
+        [POLICY_INDICATORS.renewableEnergy]: 'Renewable Energy (%)',
+        [POLICY_INDICATORS.rdExpenditure]: 'R&D Expenditure (% of GDP)',
+        [POLICY_INDICATORS.hightechExports]: 'High-Tech Exports (%)',
     };
     for (const [indicatorId, dataPoints] of indicatorData) {
         const recent = getMostRecentValue(dataPoints);