euparliamentmonitor 0.8.24 → 0.8.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.24",
+  "version": "0.8.25",
   "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/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 {