euparliamentmonitor 0.8.24 → 0.8.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.24",
+  "version": "0.8.26",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -170,7 +170,7 @@
     "node": ">=25"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.2.1"
+    "european-parliament-mcp-server": "1.2.2"
   },
   "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/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.d.ts

@@ -14,6 +14,15 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
     private readonly _failedTools;
     /** Tracks tools that have been called (attempted) in the current session */
     private readonly _calledTools;
+    /**
+     * Record a tool failure and log a warning.
+     *
+     * @param toolName - MCP tool name that failed
+     * @param errorText - Raw error text from the failure
+     * @param fallbackText - JSON text for the fallback result
+     * @returns Fallback MCPToolResult
+     */
+    private _recordToolFailure;
     /**
      * Generic error-safe wrapper around {@link callToolWithRetry}.
      * Retries transient failures (timeouts, connection drops) with a bounded
@@ -22,6 +31,12 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
      * Catches any error thrown by the tool (or by the args factory), logs a warning,
      * and returns a fallback payload.
      *
+     * Also inspects the tool result for the MCP protocol `isError` flag. When
+     * `isError === true`, the first content item's text is passed through
+     * {@link classifyToolError} for diagnostic categorization, and the tool is
+     * recorded as failed via {@link _recordToolFailure}. This handles EP MCP
+     * Server error responses that are returned (not thrown) as structured results.
+     *
      * Accepts either a plain args object or a factory function `() => object`.
      * Using a factory ensures that options normalization/destructuring runs inside
      * the try/catch so invalid runtime inputs fall back gracefully.

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

@@ -27,21 +27,36 @@ const PROCEDURE_EVENT_FALLBACK = '{"event": null}';
 /** Fallback payload for server health status */
 const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
 /**
- * Classify an error message into a diagnostic error category, aligned with
- * EP MCP Server v1.2.1 standardized error categories.
+ * Classify an error message into a diagnostic error category.
  *
- * Priority:
- * 1. Gateway 5xx → SERVER_ERROR (not TIMEOUT, even for 504 "Gateway Timeout")
- * 2. 429 / rate-limit → RATE_LIMIT
- * 3. 404 → NOT_FOUND
- * 4. Client-side timeout → TIMEOUT
- * 5. Everything else → UNKNOWN
+ * Maps EP MCP Server v1.2.2 structured error codes and generic HTTP/network
+ * errors into one of six broad categories used for logging and retry decisions:
+ *
+ * Returned categories (priority order):
+ * 1. `INTERNAL_ERROR` — EP MCP `INTERNAL_ERROR` (catch-all for DNS, TLS, unclassified upstream failures)
+ * 2. `SERVER_ERROR`   — EP MCP `UPSTREAM_500`/`UPSTREAM_503`/`SERVER_ERROR`, or gateway 5xx patterns
+ * 3. `TIMEOUT`        — EP MCP `UPSTREAM_TIMEOUT`, or generic "timeout" strings
+ * 4. `RATE_LIMIT`     — EP MCP `RATE_LIMITED`, HTTP 429, or "rate limit"/"too many requests" strings
+ * 5. `NOT_FOUND`      — EP MCP `UPSTREAM_404`, or generic "404" strings
+ * 6. `UNKNOWN`        — everything else
  *
  * @param message - Raw error message
  * @returns Diagnostic error category string
  */
 function classifyToolError(message) {
     const lowerMsg = message.toLowerCase();
+    // EP MCP Server v1.2.2 structured error codes (matched case-insensitively)
+    if (lowerMsg.includes('internal_error')) {
+        return 'INTERNAL_ERROR';
+    }
+    if (lowerMsg.includes('upstream_500') ||
+        lowerMsg.includes('upstream_503') ||
+        lowerMsg.includes('server_error')) {
+        return 'SERVER_ERROR';
+    }
+    if (lowerMsg.includes('upstream_timeout')) {
+        return 'TIMEOUT';
+    }
     if (lowerMsg.includes('gateway timeout') ||
         lowerMsg.includes('gateway error 500') ||
         lowerMsg.includes('gateway error 502') ||
@@ -51,10 +66,11 @@ function classifyToolError(message) {
     }
     if (lowerMsg.includes('429') ||
         lowerMsg.includes('rate limit') ||
-        lowerMsg.includes('too many requests')) {
+        lowerMsg.includes('too many requests') ||
+        lowerMsg.includes('rate_limited')) {
         return 'RATE_LIMIT';
     }
-    if (lowerMsg.includes('404'))
+    if (lowerMsg.includes('404') || lowerMsg.includes('upstream_404'))
         return 'NOT_FOUND';
     if (lowerMsg.includes('timeout'))
         return 'TIMEOUT';
@@ -69,6 +85,20 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     _failedTools = new Map();
     /** Tracks tools that have been called (attempted) in the current session */
     _calledTools = new Set();
+    /**
+     * Record a tool failure and log a warning.
+     *
+     * @param toolName - MCP tool name that failed
+     * @param errorText - Raw error text from the failure
+     * @param fallbackText - JSON text for the fallback result
+     * @returns Fallback MCPToolResult
+     */
+    _recordToolFailure(toolName, errorText, fallbackText) {
+        const errorType = classifyToolError(errorText);
+        this._failedTools.set(toolName, `${errorType}: ${errorText.slice(0, 200)}`);
+        console.warn(`⚠️ ${toolName} failed [${errorType}]:`, errorText.slice(0, 200));
+        return { content: [{ type: 'text', text: fallbackText }] };
+    }
     /**
      * Generic error-safe wrapper around {@link callToolWithRetry}.
      * Retries transient failures (timeouts, connection drops) with a bounded
@@ -77,6 +107,12 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
      * Catches any error thrown by the tool (or by the args factory), logs a warning,
      * and returns a fallback payload.
      *
+     * Also inspects the tool result for the MCP protocol `isError` flag. When
+     * `isError === true`, the first content item's text is passed through
+     * {@link classifyToolError} for diagnostic categorization, and the tool is
+     * recorded as failed via {@link _recordToolFailure}. This handles EP MCP
+     * Server error responses that are returned (not thrown) as structured results.
+     *
      * Accepts either a plain args object or a factory function `() => object`.
      * Using a factory ensures that options normalization/destructuring runs inside
      * the try/catch so invalid runtime inputs fall back gracefully.
@@ -91,16 +127,19 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
         try {
             const resolvedArgs = typeof args === 'function' ? args() : args;
             const result = await this.callToolWithRetry(toolName, resolvedArgs);
+            // Inspect the result for structured error responses from the EP MCP server.
+            // The server may return isError: true with JSON content containing errorCode
+            // (e.g., INTERNAL_ERROR, UPSTREAM_500) instead of throwing an exception.
+            if (result.isError === true) {
+                return this._recordToolFailure(toolName, result.content?.[0]?.text ?? '', fallbackText);
+            }
             // Clear from failed tools on success
             this._failedTools.delete(toolName);
             return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            const errorType = classifyToolError(message);
-            this._failedTools.set(toolName, `${errorType}: ${message}`);
-            console.warn(`⚠️ ${toolName} failed [${errorType}]:`, message);
-            return { content: [{ type: 'text', text: fallbackText }] };
+            return this._recordToolFailure(toolName, message, fallbackText);
         }
     }
     /**

package/scripts/mcp/mcp-connection.js

@@ -483,11 +483,18 @@ export class MCPConnection {
             const command = isJavaScriptFile ? process.execPath : this.serverPath;
             const args = isJavaScriptFile ? [this.serverPath] : [];
             // Ensure EP_REQUEST_TIMEOUT_MS is propagated to the MCP server subprocess.
-            // The EP MCP server defaults to only 10 seconds; we need 90+ seconds for
-            // slow EP API feed endpoints (events, procedures, documents, etc.).
+            // The EP MCP server defaults to only 10 seconds (v1.1.x) or 60 seconds (v1.2.x);
+            // we need 90+ seconds for slow EP API feed endpoints (events, procedures, documents, etc.).
             const childEnv = { ...process.env };
-            if (!childEnv['EP_REQUEST_TIMEOUT_MS']) {
-                childEnv['EP_REQUEST_TIMEOUT_MS'] = String(REQUEST_TIMEOUT_MS);
+            const effectiveTimeoutMs = childEnv['EP_REQUEST_TIMEOUT_MS']
+                ? Number(childEnv['EP_REQUEST_TIMEOUT_MS'])
+                : REQUEST_TIMEOUT_MS;
+            childEnv['EP_REQUEST_TIMEOUT_MS'] = String(effectiveTimeoutMs);
+            // Pass --timeout as CLI arg (highest precedence in EP MCP server).
+            // This guarantees the timeout is applied even when the env var is not
+            // read at module load time (e.g. due to import ordering in some versions).
+            if (!isJavaScriptFile) {
+                args.push('--timeout', String(effectiveTimeoutMs));
             }
             this.process = spawn(command, args, {
                 stdio: ['pipe', 'pipe', 'pipe'],

package/scripts/types/mcp.d.ts

@@ -25,6 +25,8 @@ export interface MCPContentItem {
 /** MCP tool call result */
 export interface MCPToolResult {
     content?: MCPContentItem[] | undefined;
+    /** Set to `true` by the MCP server when the tool invocation produced an error response */
+    isError?: boolean | undefined;
 }
 /** JSON-RPC 2.0 request */
 export interface JSONRPCRequest {

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);