euparliamentmonitor 0.8.19 → 0.8.21

package/scripts/generators/synthesis-summary.js

@@ -0,0 +1,364 @@
+// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @module Generators/SynthesisSummary
+ * @description Aggregation engine that reads per-file analysis outputs and
+ * produces a synthesis summary — a single intelligence briefing consumed by
+ * article generators to determine narrative direction, headline selection,
+ * and publication priority.
+ *
+ * The synthesiser:
+ * 1. Scans the analysis date directory for markdown files
+ * 2. Extracts YAML frontmatter (method, confidence) from each
+ * 3. Counts SWOT mentions and risk-level keywords
+ * 4. Ranks findings by confidence and produces editorial recommendations
+ *
+ * @see analysis/templates/synthesis-summary.md
+ */
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Case-insensitive patterns for detecting SWOT mentions in analysis text */
+const SWOT_PATTERNS = {
+    strengths: /\bstrength/giu,
+    weaknesses: /\bweakness/giu,
+    opportunities: /\bopportunit/giu,
+    threats: /\bthreat/giu,
+};
+/** Case-insensitive patterns for detecting risk-level mentions */
+const RISK_PATTERNS = {
+    critical: /\bcritical\b/giu,
+    high: /\bhigh[- ]risk\b/giu,
+    medium: /\bmedium[- ]risk\b/giu,
+    low: /\blow[- ]risk\b/giu,
+};
+/** Confidence value ordering (higher = better) */
+const CONFIDENCE_RANK = {
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+/** Filename of the synthesis output itself — excluded from scanning to prevent self-contamination */
+const SYNTHESIS_OUTPUT_FILENAME = 'synthesis-summary.md';
+/** Subdirectory containing per-document analysis — excluded to prevent I/O bloat and skewed aggregation */
+const DOCUMENTS_SUBDIR = 'documents';
+// ─── Markdown sanitization ────────────────────────────────────────────────────
+/**
+ * Sanitize untrusted text for safe use in a Markdown table cell.
+ *
+ * Escapes pipe characters, backslashes, and HTML entities, then normalizes
+ * whitespace to prevent table layout corruption.
+ *
+ * @param input - Untrusted cell text
+ * @returns Sanitized text safe for Markdown table cells
+ */
+function sanitizeMdCell(input) {
+    return input
+        .replace(/\\/gu, '\\\\')
+        .replace(/\|/gu, '\\|')
+        .replace(/&/gu, '&')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/[\r\n]+/gu, ' ')
+        .trim();
+}
+/**
+ * Parse YAML frontmatter from a markdown file's content.
+ *
+ * Extracts `method`, `confidence`, and `date` fields from the `---` delimited
+ * YAML block at the start of the file.  Returns null when no valid frontmatter
+ * is found.
+ *
+ * @param content - Raw markdown content
+ * @returns Parsed frontmatter or null
+ */
+export function parseFrontmatter(content) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(content);
+    if (!match)
+        return null;
+    const yaml = match[1] ?? '';
+    const methodMatch = /^method:\s+(\S.*)$/mu.exec(yaml);
+    const confidenceMatch = /^confidence:\s+(\S.*)$/mu.exec(yaml);
+    const dateMatch = /^date:\s+(\S.*)$/mu.exec(yaml);
+    const method = methodMatch?.[1]?.trim() ?? 'unknown';
+    const rawConf = confidenceMatch?.[1]?.trim().toLowerCase() ?? 'low';
+    const confidence = rawConf === 'high' || rawConf === 'medium' ? rawConf : 'low';
+    const date = dateMatch?.[1]?.trim() ?? '';
+    return { method, confidence, date };
+}
+// ─── Text analysis ────────────────────────────────────────────────────────────
+/**
+ * Count regex pattern matches in a body of text.
+ *
+ * @param text - Source text to scan
+ * @param pattern - RegExp with global flag
+ * @returns Number of matches
+ */
+function countMatches(text, pattern) {
+    // Reset lastIndex for global regexps to avoid stale state
+    pattern.lastIndex = 0;
+    const matches = text.match(pattern);
+    return matches ? matches.length : 0;
+}
+/**
+ * Aggregate SWOT mention counts from a body of text.
+ *
+ * @param text - Combined analysis text
+ * @returns SWOT counts
+ */
+export function aggregateSWOT(text) {
+    return {
+        strengths: countMatches(text, SWOT_PATTERNS.strengths),
+        weaknesses: countMatches(text, SWOT_PATTERNS.weaknesses),
+        opportunities: countMatches(text, SWOT_PATTERNS.opportunities),
+        threats: countMatches(text, SWOT_PATTERNS.threats),
+    };
+}
+/**
+ * Aggregate risk-level mention counts from a body of text.
+ *
+ * @param text - Combined analysis text
+ * @returns Risk level counts
+ */
+export function aggregateRisks(text) {
+    return {
+        critical: countMatches(text, RISK_PATTERNS.critical),
+        high: countMatches(text, RISK_PATTERNS.high),
+        medium: countMatches(text, RISK_PATTERNS.medium),
+        low: countMatches(text, RISK_PATTERNS.low),
+    };
+}
+/**
+ * Extract the first non-empty non-frontmatter heading or paragraph as a
+ * one-line summary from a markdown file.
+ *
+ * @param content - Raw markdown content
+ * @returns One-line summary string
+ */
+export function extractSummaryLine(content) {
+    // Strip frontmatter
+    const body = content.replace(/^---[\s\S]*?---\s*/u, '');
+    // Try first heading (# followed by at least one space and then non-space content)
+    const headingMatch = /^#+\s(\S.*)$/mu.exec(body);
+    if (headingMatch?.[1])
+        return headingMatch[1].trim();
+    // Fall back to first non-empty line
+    const lines = body.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0 && !trimmed.startsWith('|') && !trimmed.startsWith('```')) {
+            return trimmed.slice(0, 200);
+        }
+    }
+    return 'No summary available';
+}
+// ─── Confidence aggregation ──────────────────────────────────────────────────
+/**
+ * Determine the overall confidence level from a set of findings.
+ *
+ * Uses majority vote: whichever confidence level appears most often wins.
+ *
+ * @param findings - Findings with individual confidence levels
+ * @returns Aggregated confidence level
+ */
+export function aggregateConfidence(findings) {
+    if (findings.length === 0)
+        return 'low';
+    const counts = { high: 0, medium: 0, low: 0 };
+    for (const f of findings) {
+        counts[f.confidence]++;
+    }
+    if (counts.high >= counts.medium && counts.high >= counts.low)
+        return 'high';
+    if (counts.medium >= counts.low)
+        return 'medium';
+    return 'low';
+}
+// ─── Directory scanning ──────────────────────────────────────────────────────
+/**
+ * Recursively find all `.md` analysis files under a directory.
+ *
+ * Excludes:
+ * - The synthesis output file itself (prevents self-contamination on re-runs)
+ * - The `documents/` subdirectory (per-document analysis can bloat I/O and skew aggregation)
+ *
+ * @param dir - Absolute directory path
+ * @returns Array of absolute file paths
+ */
+export function findMarkdownFiles(dir) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip the documents/ subdirectory to avoid per-document analysis bloat
+            if (entry.name === DOCUMENTS_SUBDIR)
+                continue;
+            results.push(...findMarkdownFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            // Skip the synthesis output itself to prevent self-contamination
+            if (entry.name === SYNTHESIS_OUTPUT_FILENAME)
+                continue;
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+// ─── Editorial recommendations ───────────────────────────────────────────────
+/**
+ * Generate editorial recommendations based on aggregated analysis data.
+ *
+ * @param findings - Ranked findings
+ * @param swot - Aggregated SWOT counts
+ * @param risks - Risk level distribution
+ * @returns Array of recommendation strings
+ */
+export function generateEditorialRecommendations(findings, swot, risks) {
+    const recommendations = [];
+    if (findings.length === 0) {
+        recommendations.push('No analysis files found — verify pipeline execution.');
+        return recommendations;
+    }
+    // High-confidence findings drive lead stories
+    const highConfCount = findings.filter((f) => f.confidence === 'high').length;
+    if (highConfCount > 0) {
+        recommendations.push(`${highConfCount} high-confidence finding(s) available for lead story selection.`);
+    }
+    // Risk-driven recommendations
+    if (risks.critical > 0) {
+        recommendations.push(`${risks.critical} critical-risk mention(s) detected — consider priority coverage.`);
+    }
+    // SWOT balance indicator
+    const totalSwot = swot.strengths + swot.weaknesses + swot.opportunities + swot.threats;
+    if (totalSwot > 0) {
+        const threatRatio = swot.threats / totalSwot;
+        if (threatRatio > 0.4) {
+            recommendations.push('Threat-heavy SWOT balance — narrative may benefit from opportunity framing.');
+        }
+    }
+    // Volume recommendation
+    if (findings.length >= 10) {
+        recommendations.push(`${findings.length} analysis files processed — consider multi-article output.`);
+    }
+    else if (findings.length <= 2) {
+        recommendations.push('Limited analysis coverage — consider consolidating into a single digest article.');
+    }
+    return recommendations;
+}
+// ─── Main synthesis ──────────────────────────────────────────────────────────
+/**
+ * Build a synthesis summary from all analysis files in a date directory.
+ *
+ * Scans the directory recursively for `.md` analysis files, parses their
+ * frontmatter, extracts findings, aggregates SWOT and risk mentions, and
+ * produces a {@link SynthesisSummary} object.
+ *
+ * @param dateOutputDir - Absolute path to the date-scoped analysis directory
+ * @param date - ISO date string (YYYY-MM-DD)
+ * @returns Synthesis summary object
+ */
+export function buildSynthesisSummary(dateOutputDir, date) {
+    const files = findMarkdownFiles(dateOutputDir);
+    const findings = [];
+    let combinedText = '';
+    for (const filePath of files) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const frontmatter = parseFrontmatter(content);
+        combinedText += content + '\n';
+        findings.push({
+            method: frontmatter?.method ?? 'unknown',
+            file: path.basename(filePath),
+            confidence: frontmatter?.confidence ?? 'low',
+            summary: extractSummaryLine(content),
+        });
+    }
+    // Sort findings: high confidence first, then medium, then low.
+    // The heading in the output says "Top Findings by Confidence" to match.
+    findings.sort((a, b) => (CONFIDENCE_RANK[b.confidence] ?? 0) - (CONFIDENCE_RANK[a.confidence] ?? 0));
+    const swot = aggregateSWOT(combinedText);
+    const riskOverview = aggregateRisks(combinedText);
+    const overallConfidence = aggregateConfidence(findings);
+    const editorialRecommendations = generateEditorialRecommendations(findings, swot, riskOverview);
+    return {
+        synthesisId: `SYN-${date}-${randomUUID().slice(0, 8).toUpperCase()}`,
+        date,
+        documentsAnalyzed: files.length,
+        overallConfidence,
+        topFindings: findings.slice(0, 5),
+        swot,
+        riskOverview,
+        editorialRecommendations,
+    };
+}
+/**
+ * Generate a markdown report from a synthesis summary.
+ *
+ * Follows the template format defined in `analysis/templates/synthesis-summary.md`.
+ *
+ * @param summary - Computed synthesis summary
+ * @returns Markdown string
+ */
+export function formatSynthesisMarkdown(summary) {
+    const findingsRows = summary.topFindings
+        .map((f, i) => `| ${i + 1} | ${sanitizeMdCell(f.file)} | ${sanitizeMdCell(f.method)} | ${f.confidence} | ${sanitizeMdCell(f.summary.slice(0, 80))} |`)
+        .join('\n');
+    return `---
+method: synthesis-summary
+date: ${summary.date}
+confidence: ${summary.overallConfidence}
+generated: ${new Date().toISOString()}
+---
+
+# 🧩 Synthesis Summary — ${summary.date}
+
+## 📋 Synthesis Context
+
+| Field | Value |
+|-------|-------|
+| **Synthesis ID** | \`${summary.synthesisId}\` |
+| **Analysis Date** | \`${summary.date}\` |
+| **Documents Analyzed** | ${summary.documentsAnalyzed} |
+| **Overall Confidence** | ${summary.overallConfidence.toUpperCase()} |
+
+---
+
+## 🏆 Top Findings by Confidence
+
+| Rank | File | Method | Confidence | Summary |
+|:----:|------|--------|:----------:|---------|
+${findingsRows || '| — | — | — | — | — |'}
+
+---
+
+## 💪 Aggregated SWOT Summary
+
+| Dimension | Count |
+|-----------|:-----:|
+| ✅ Strengths | ${summary.swot.strengths} |
+| ⚠️ Weaknesses | ${summary.swot.weaknesses} |
+| 🚀 Opportunities | ${summary.swot.opportunities} |
+| 🔴 Threats | ${summary.swot.threats} |
+
+---
+
+## ⚖️ Risk Landscape Summary
+
+| Level | Mentions |
+|-------|:--------:|
+| 🔴 Critical | ${summary.riskOverview.critical} |
+| 🟠 High | ${summary.riskOverview.high} |
+| 🟡 Medium | ${summary.riskOverview.medium} |
+| 🟢 Low | ${summary.riskOverview.low} |
+
+---
+
+## 🎯 Editorial Recommendations
+
+${summary.editorialRecommendations.map((r) => `- ${r}`).join('\n')}
+`;
+}
+//# sourceMappingURL=synthesis-summary.js.map

package/scripts/index.d.ts

@@ -34,12 +34,14 @@ export { type ToolHealthEntry, type HealthSnapshot, MCPHealthMonitor } from './m
 export { scoreVotingAnomaly, analyzeCoalitionCohesion, scoreMEPInfluence, calculateLegislativeVelocity, rankBySignificance, buildIntelligenceSection, buildDefaultStakeholderPerspectives, scoreStakeholderInfluence, buildStakeholderOutcomeMatrix, rankStakeholdersByInfluence, computeVotingIntensity, detectCoalitionShifts, computePolarizationIndex, detectVotingTrends, computeCrossSessionCoalitionStability, rankMEPInfluenceByTopic, buildLegislativeVelocityReport, } from './utils/intelligence-analysis.js';
 export { createEmptyIndex, addArticleToIndex, buildIndexFromEntries, findRelatedArticles, generateCrossReferences, detectTrends, findOrCreateSeries, buildRelatedArticlesHTML, } from './utils/intelligence-index.js';
 export { assessAnalysisDepth, assessStakeholderCoverage, assessVisualizationQuality, calculateOverallScore, generateRecommendations, scoreArticleQuality, } from './utils/article-quality-scorer.js';
+export { scoreSignificance, scoreBatch, clampScore, deriveDecision, formatScoreMarkdown, formatBatchMarkdown, WEIGHT_PARLIAMENTARY, WEIGHT_POLICY, WEIGHT_PUBLIC_INTEREST, WEIGHT_URGENCY, WEIGHT_INSTITUTIONAL, THRESHOLD_PUBLISH, THRESHOLD_HOLD, } from './utils/significance-scoring.js';
+export { parseFrontmatter, aggregateSWOT, aggregateRisks, extractSummaryLine, aggregateConfidence, findMarkdownFiles, generateEditorialRecommendations, buildSynthesisSummary, formatSynthesisMarkdown, } from './generators/synthesis-summary.js';
 export { validateArticleContent, validateTranslationCompleteness, } from './utils/content-validator.js';
 export { enrichMetadataFromContent } from './utils/content-metadata.js';
 export { buildMetadataDatabase, writeMetadataDatabase, readMetadataDatabase, updateMetadataDatabase, updateIntelligenceIndex, } from './utils/news-metadata.js';
 export { pl, pl as pluralizeCount } from './utils/metadata-utils.js';
 export { assessPoliticalThreats, buildActorThreatProfiles, buildConsequenceTree, analyzeLegislativeDisruption, generateThreatAssessmentMarkdown, ALL_THREAT_LANDSCAPE_DIMENSIONS, } from './utils/political-threat-assessment.js';
-export { stripScriptBlocks } from './utils/html-sanitize.js';
+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';
@@ -58,7 +60,8 @@ export { mcpCircuitBreaker, computeRollingDateRange, initializeMCPClient, loadFe
 export { type ValidationResult, validateMCPResponse, normalizeISO8601Date, sanitizeText, isValidCountryCode, isValidLanguageCode, } from './generators/pipeline/transform-stage.js';
 export { type StrategyRegistry, createStrategyRegistry, generateArticleForStrategy, } from './generators/pipeline/generate-stage.js';
 export { type OutputOptions, writeArticleFile, writeSingleArticle, writeGenerationMetadata, } from './generators/pipeline/output-stage.js';
-export type { ArticleData, ArticleMetadata, ArticleStrategyBase, ArticleStrategy, } from './generators/strategies/article-strategy.js';
+export type { ArticleData, ArticleMetadata, ArticleStrategyBase, ArticleStrategy, LoadedAnalysisContext, AnalysisFileContent, } from './generators/strategies/article-strategy.js';
+export { loadAnalysisContext, extractAnalysisSummary, buildAnalysisInsightsSection, } from './generators/strategies/article-strategy.js';
 export { type BreakingNewsArticleData, BreakingNewsStrategy, breakingNewsStrategy, } from './generators/strategies/breaking-news-strategy.js';
 export { type CommitteeReportsArticleData, type CommitteeTheme, AFET_KEYWORDS, LIBE_KEYWORDS, AGRI_KEYWORDS, ENVI_KEYWORDS, ECON_KEYWORDS, categorizeAdoptedText, CommitteeReportsStrategy, committeeReportsStrategy, } from './generators/strategies/committee-reports-strategy.js';
 export { type MonthAheadArticleData, MonthAheadStrategy, monthAheadStrategy, } from './generators/strategies/month-ahead-strategy.js';

package/scripts/index.js

@@ -41,6 +41,10 @@ export { scoreVotingAnomaly, analyzeCoalitionCohesion, scoreMEPInfluence, calcul
 export { createEmptyIndex, addArticleToIndex, buildIndexFromEntries, findRelatedArticles, generateCrossReferences, detectTrends, findOrCreateSeries, buildRelatedArticlesHTML, } from './utils/intelligence-index.js';
 // ─── Article Quality ─────────────────────────────────────────────────────────
 export { assessAnalysisDepth, assessStakeholderCoverage, assessVisualizationQuality, calculateOverallScore, generateRecommendations, scoreArticleQuality, } from './utils/article-quality-scorer.js';
+// ─── Significance Scoring ────────────────────────────────────────────────────
+export { scoreSignificance, scoreBatch, clampScore, deriveDecision, formatScoreMarkdown, formatBatchMarkdown, WEIGHT_PARLIAMENTARY, WEIGHT_POLICY, WEIGHT_PUBLIC_INTEREST, WEIGHT_URGENCY, WEIGHT_INSTITUTIONAL, THRESHOLD_PUBLISH, THRESHOLD_HOLD, } from './utils/significance-scoring.js';
+// ─── Synthesis Summary ───────────────────────────────────────────────────────
+export { parseFrontmatter, aggregateSWOT, aggregateRisks, extractSummaryLine, aggregateConfidence, findMarkdownFiles, generateEditorialRecommendations, buildSynthesisSummary, formatSynthesisMarkdown, } from './generators/synthesis-summary.js';
 // ─── Content Validation ──────────────────────────────────────────────────────
 export { validateArticleContent, validateTranslationCompleteness, } from './utils/content-validator.js';
 // ─── Content Metadata ────────────────────────────────────────────────────────
@@ -52,7 +56,7 @@ export { pl, pl as pluralizeCount } from './utils/metadata-utils.js';
 // ─── Political Threat Assessment ─────────────────────────────────────────────
 export { assessPoliticalThreats, buildActorThreatProfiles, buildConsequenceTree, analyzeLegislativeDisruption, generateThreatAssessmentMarkdown, ALL_THREAT_LANDSCAPE_DIMENSIONS, } from './utils/political-threat-assessment.js';
 // ─── HTML Utilities ──────────────────────────────────────────────────────────
-export { stripScriptBlocks } from './utils/html-sanitize.js';
+export { stripHtmlTags, stripScriptBlocks } from './utils/html-sanitize.js';
 export { parseArticleFilename, formatSlug, calculateReadTime, escapeHTML, isSafeURL, validateArticleHTML, } from './utils/file-utils.js';
 // ─── Article Category Detection ──────────────────────────────────────────────
 export { detectCategory } from './utils/article-category.js';
@@ -80,6 +84,7 @@ export { mcpCircuitBreaker, computeRollingDateRange, initializeMCPClient, loadFe
 export { validateMCPResponse, normalizeISO8601Date, sanitizeText, isValidCountryCode, isValidLanguageCode, } from './generators/pipeline/transform-stage.js';
 export { createStrategyRegistry, generateArticleForStrategy, } from './generators/pipeline/generate-stage.js';
 export { writeArticleFile, writeSingleArticle, writeGenerationMetadata, } from './generators/pipeline/output-stage.js';
+export { loadAnalysisContext, extractAnalysisSummary, buildAnalysisInsightsSection, } from './generators/strategies/article-strategy.js';
 export { BreakingNewsStrategy, breakingNewsStrategy, } from './generators/strategies/breaking-news-strategy.js';
 export { AFET_KEYWORDS, LIBE_KEYWORDS, AGRI_KEYWORDS, ENVI_KEYWORDS, ECON_KEYWORDS, categorizeAdoptedText, CommitteeReportsStrategy, committeeReportsStrategy, } from './generators/strategies/committee-reports-strategy.js';
 export { MonthAheadStrategy, monthAheadStrategy, } from './generators/strategies/month-ahead-strategy.js';

package/scripts/mcp/ep-mcp-client.d.ts

@@ -4,12 +4,16 @@
  * built on top of the generic {@link MCPConnection} transport.
  */
 import { MCPConnection } from './mcp-connection.js';
-import type { MCPClientOptions, MCPToolResult, GetMEPsOptions, GetPlenarySessionsOptions, SearchDocumentsOptions, GetParliamentaryQuestionsOptions, GetCommitteeInfoOptions, MonitorLegislativePipelineOptions, AssessMEPInfluenceOptions, AnalyzeCoalitionDynamicsOptions, DetectVotingAnomaliesOptions, ComparePoliticalGroupsOptions, VotingRecordsOptions, VotingPatternsOptions, GenerateReportOptions, AnalyzeLegislativeEffectivenessOptions, AnalyzeCommitteeActivityOptions, TrackMEPAttendanceOptions, AnalyzeCountryDelegationOptions, GeneratePoliticalLandscapeOptions, GetCurrentMEPsOptions, GetSpeechesOptions, GetProceduresOptions, GetAdoptedTextsOptions, GetEventsOptions, GetMeetingActivitiesOptions, GetMeetingDecisionsOptions, GetMEPDeclarationsOptions, GetIncomingMEPsOptions, GetOutgoingMEPsOptions, GetHomonymMEPsOptions, GetPlenaryDocumentsOptions, GetCommitteeDocumentsOptions, GetPlenarySessionDocumentsOptions, GetPlenarySessionDocumentItemsOptions, GetControlledVocabulariesOptions, GetExternalDocumentsOptions, GetMeetingForeseenActivitiesOptions, GetProcedureEventsOptions, GetMeetingPlenarySessionDocumentsOptions, GetMeetingPlenarySessionDocumentItemsOptions, NetworkAnalysisOptions, SentimentTrackerOptions, EarlyWarningSystemOptions, ComparativeIntelligenceOptions, CorrelateIntelligenceOptions, GetAllGeneratedStatsOptions, GetMEPsFeedOptions, GetEventsFeedOptions, GetProceduresFeedOptions, GetAdoptedTextsFeedOptions, GetMEPDeclarationsFeedOptions, GetDocumentsFeedOptions, GetPlenaryDocumentsFeedOptions, GetCommitteeDocumentsFeedOptions, GetPlenarySessionDocumentsFeedOptions, GetExternalDocumentsFeedOptions, GetParliamentaryQuestionsFeedOptions, GetCorporateBodiesFeedOptions, GetControlledVocabulariesFeedOptions } from '../types/index.js';
+import type { MCPClientOptions, MCPToolResult, GetMEPsOptions, GetPlenarySessionsOptions, SearchDocumentsOptions, GetParliamentaryQuestionsOptions, GetCommitteeInfoOptions, MonitorLegislativePipelineOptions, AssessMEPInfluenceOptions, AnalyzeCoalitionDynamicsOptions, DetectVotingAnomaliesOptions, ComparePoliticalGroupsOptions, VotingRecordsOptions, VotingPatternsOptions, GenerateReportOptions, AnalyzeLegislativeEffectivenessOptions, AnalyzeCommitteeActivityOptions, TrackMEPAttendanceOptions, AnalyzeCountryDelegationOptions, GeneratePoliticalLandscapeOptions, GetCurrentMEPsOptions, GetSpeechesOptions, GetProceduresOptions, GetAdoptedTextsOptions, GetEventsOptions, GetMeetingActivitiesOptions, GetMeetingDecisionsOptions, GetMEPDeclarationsOptions, GetIncomingMEPsOptions, GetOutgoingMEPsOptions, GetHomonymMEPsOptions, GetPlenaryDocumentsOptions, GetCommitteeDocumentsOptions, GetPlenarySessionDocumentsOptions, GetPlenarySessionDocumentItemsOptions, GetControlledVocabulariesOptions, GetExternalDocumentsOptions, GetMeetingForeseenActivitiesOptions, GetProcedureEventsOptions, GetMeetingPlenarySessionDocumentsOptions, GetMeetingPlenarySessionDocumentItemsOptions, NetworkAnalysisOptions, SentimentTrackerOptions, EarlyWarningSystemOptions, ComparativeIntelligenceOptions, CorrelateIntelligenceOptions, GetAllGeneratedStatsOptions, GetMEPsFeedOptions, GetEventsFeedOptions, GetProceduresFeedOptions, GetAdoptedTextsFeedOptions, GetMEPDeclarationsFeedOptions, GetDocumentsFeedOptions, GetPlenaryDocumentsFeedOptions, GetCommitteeDocumentsFeedOptions, GetPlenarySessionDocumentsFeedOptions, GetExternalDocumentsFeedOptions, GetParliamentaryQuestionsFeedOptions, GetCorporateBodiesFeedOptions, GetControlledVocabulariesFeedOptions, GetProcedureEventByIdOptions } from '../types/index.js';
 /**
  * MCP Client for European Parliament data access.
  * Extends {@link MCPConnection} with EP-specific tool wrapper methods.
  */
 export declare class EuropeanParliamentMCPClient extends MCPConnection {
+    /** Tracks tools that returned fallback data in the current session */
+    private readonly _failedTools;
+    /** Tracks tools that have been called (attempted) in the current session */
+    private readonly _calledTools;
     /**
      * Generic error-safe wrapper around {@link callToolWithRetry}.
      * Retries transient failures (timeouts, connection drops) with a bounded
@@ -28,6 +32,19 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
      * @returns Tool result or fallback
      */
     private safeCallTool;
+    /**
+     * Get a summary of tools that returned fallback data in the current session.
+     * Useful for diagnosing feed availability and data quality issues.
+     *
+     * @returns Map of tool name to error description
+     */
+    getFailedTools(): ReadonlyMap<string, string>;
+    /**
+     * Get a human-readable feed health summary for diagnostics.
+     *
+     * @returns Formatted summary of feed availability
+     */
+    getFeedHealthSummary(): string;
     /**
      * Get Members of European Parliament
      *
@@ -456,6 +473,22 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
      * @returns Controlled vocabularies feed data
      */
     getControlledVocabulariesFeed(options?: GetControlledVocabulariesFeedOptions): Promise<MCPToolResult>;
+    /**
+     * Get a specific event linked to a legislative procedure.
+     * Returns a single event for the specified procedure and event identifiers.
+     *
+     * @param options - Options including required processId and eventId
+     * @returns Procedure event data
+     */
+    getProcedureEventById(options: GetProcedureEventByIdOptions): Promise<MCPToolResult>;
+    /**
+     * Check server health and feed availability status.
+     * Returns server version, uptime, per-feed health status, and overall availability.
+     * Does not make upstream API calls — reports cached status from recent tool invocations.
+     *
+     * @returns Server health and feed availability data
+     */
+    getServerHealth(): Promise<MCPToolResult>;
 }
 /**
  * Get or create singleton MCP client instance

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

@@ -22,11 +22,19 @@ const ITEMS_FALLBACK = '{"items": []}';
 const INTELLIGENCE_FALLBACK = '{"analysis": null}';
 /** Fallback payload for precomputed statistics */
 const STATS_FALLBACK = '{"stats": null}';
+/** Fallback payload for single procedure event lookup */
+const PROCEDURE_EVENT_FALLBACK = '{"event": null}';
+/** Fallback payload for server health status */
+const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
 /**
  * MCP Client for European Parliament data access.
  * Extends {@link MCPConnection} with EP-specific tool wrapper methods.
  */
 export class EuropeanParliamentMCPClient extends MCPConnection {
+    /** Tracks tools that returned fallback data in the current session */
+    _failedTools = new Map();
+    /** Tracks tools that have been called (attempted) in the current session */
+    _calledTools = new Set();
     /**
      * Generic error-safe wrapper around {@link callToolWithRetry}.
      * Retries transient failures (timeouts, connection drops) with a bounded
@@ -45,16 +53,88 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
      * @returns Tool result or fallback
      */
     async safeCallTool(toolName, args, fallbackText) {
+        this._calledTools.add(toolName);
         try {
             const resolvedArgs = typeof args === 'function' ? args() : args;
-            return await this.callToolWithRetry(toolName, resolvedArgs);
+            const result = await this.callToolWithRetry(toolName, resolvedArgs);
+            // Clear from failed tools on success
+            this._failedTools.delete(toolName);
+            return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            console.warn(`${toolName} not available:`, message);
+            const lowerMsg = message.toLowerCase();
+            // Classify the error for better diagnostics.
+            // Check gateway 5xx first — a "504 Gateway Timeout" should be SERVER_ERROR,
+            // not TIMEOUT (which is reserved for client-side request timeouts).
+            const isGatewayServerError = lowerMsg.includes('gateway timeout') ||
+                lowerMsg.includes('gateway error 500') ||
+                lowerMsg.includes('gateway error 502') ||
+                lowerMsg.includes('gateway error 503') ||
+                lowerMsg.includes('gateway error 504');
+            const errorType = isGatewayServerError
+                ? 'SERVER_ERROR'
+                : lowerMsg.includes('404')
+                    ? 'NOT_FOUND'
+                    : lowerMsg.includes('timeout')
+                        ? 'TIMEOUT'
+                        : 'UNKNOWN';
+            this._failedTools.set(toolName, `${errorType}: ${message}`);
+            console.warn(`⚠️ ${toolName} failed [${errorType}]:`, message);
             return { content: [{ type: 'text', text: fallbackText }] };
         }
     }
+    /**
+     * Get a summary of tools that returned fallback data in the current session.
+     * Useful for diagnosing feed availability and data quality issues.
+     *
+     * @returns Map of tool name to error description
+     */
+    getFailedTools() {
+        return new Map(this._failedTools);
+    }
+    /**
+     * Get a human-readable feed health summary for diagnostics.
+     *
+     * @returns Formatted summary of feed availability
+     */
+    getFeedHealthSummary() {
+        const feedTools = [
+            'get_meps_feed',
+            'get_events_feed',
+            'get_procedures_feed',
+            'get_adopted_texts_feed',
+            'get_mep_declarations_feed',
+            'get_documents_feed',
+            'get_plenary_documents_feed',
+            'get_committee_documents_feed',
+            'get_plenary_session_documents_feed',
+            'get_external_documents_feed',
+            'get_parliamentary_questions_feed',
+            'get_corporate_bodies_feed',
+            'get_controlled_vocabularies_feed',
+        ];
+        const lines = ['EP MCP Feed Health:'];
+        let operational = 0;
+        let unchecked = 0;
+        for (const tool of feedTools) {
+            const error = this._failedTools.get(tool);
+            if (error) {
+                lines.push(`  ❌ ${tool}: ${error}`);
+            }
+            else if (this._calledTools.has(tool)) {
+                lines.push(`  ✅ ${tool}`);
+                operational++;
+            }
+            else {
+                lines.push(`  ⚪ ${tool} (not checked)`);
+                unchecked++;
+            }
+        }
+        const checked = feedTools.length - unchecked;
+        lines.push(`  Summary: ${operational}/${checked} checked feeds operational${unchecked > 0 ? `, ${unchecked} unchecked` : ''}`);
+        return lines.join('\n');
+    }
     /**
      * Get Members of European Parliament
      *
@@ -707,6 +787,34 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     async getControlledVocabulariesFeed(options = {}) {
         return this.safeCallTool('get_controlled_vocabularies_feed', options, EuropeanParliamentMCPClient.FEED_FALLBACK);
     }
+    /**
+     * Get a specific event linked to a legislative procedure.
+     * Returns a single event for the specified procedure and event identifiers.
+     *
+     * @param options - Options including required processId and eventId
+     * @returns Procedure event data
+     */
+    async getProcedureEventById(options) {
+        if (typeof options.processId !== 'string' || options.processId.trim().length === 0) {
+            console.warn('get_procedure_event_by_id called without valid processId (non-empty string required)');
+            return { content: [{ type: 'text', text: PROCEDURE_EVENT_FALLBACK }] };
+        }
+        if (typeof options.eventId !== 'string' || options.eventId.trim().length === 0) {
+            console.warn('get_procedure_event_by_id called without valid eventId (non-empty string required)');
+            return { content: [{ type: 'text', text: PROCEDURE_EVENT_FALLBACK }] };
+        }
+        return this.safeCallTool('get_procedure_event_by_id', { processId: options.processId.trim(), eventId: options.eventId.trim() }, PROCEDURE_EVENT_FALLBACK);
+    }
+    /**
+     * Check server health and feed availability status.
+     * Returns server version, uptime, per-feed health status, and overall availability.
+     * Does not make upstream API calls — reports cached status from recent tool invocations.
+     *
+     * @returns Server health and feed availability data
+     */
+    async getServerHealth() {
+        return this.safeCallTool('get_server_health', {}, SERVER_HEALTH_FALLBACK);
+    }
 }
 let clientInstance = null;
 /**

package/scripts/mcp/mcp-connection.d.ts

@@ -17,7 +17,8 @@ export declare class MCPRateLimitError extends Error {
 }
 /**
  * Returns true only for transient, retriable failures: request timeouts,
- * network-level connection-closed/reset errors, and "not connected" states.
+ * network-level connection-closed/reset errors, "not connected" states,
+ * and transient HTTP gateway errors (502, 503, 504).
  *
  * Uses an allow-list of known transient error patterns so that unknown or
  * server-level errors (e.g., tool runtime failures) are NOT retried:
@@ -25,6 +26,7 @@ export declare class MCPRateLimitError extends Error {
  * - connection closed / reset / refused — network-level transport failures
  * - not connected — local "not yet connected" guard error
  * - socket hang up — Node.js HTTP socket-level disconnection
+ * - gateway error 502/503/504 — transient upstream server errors
  *
  * Everything else (MCPSessionExpiredError, TypeError, rate-limit errors,
  * unknown errors) returns false so `callToolWithRetry` surfaces them immediately.