senado-br-mcp 3.2.1 → 3.3.0

package/dist/scraper/ecidadania.js

@@ -11,6 +11,16 @@
  */
 import { UPSTREAM_TIMEOUT_MS } from "../types.js";
 export const ECIDADANIA_BASE = "https://www12.senado.leg.br/ecidadania";
+/**
+ * Error carrying a `retryable` flag, mirroring UpstreamError so the tool layer
+ * (`errorFrom` / `ecidadaniaError`) can surface it. e-Cidadania has its own fetch
+ * (not `upstreamFetch`), so transient conditions are classified here: 5xx / 429 /
+ * timeout / network → retryable; 4xx → not.
+ */
+function ecidadaniaFetchError(message, retryable) {
+    return Object.assign(new Error(message), { retryable });
+}
+const isTransientStatus = (status) => status >= 500 || status === 429;
 /** Fetch an HTML page from e-Cidadania with descriptive errors. */
 export async function fetchPage(path) {
     const url = `${ECIDADANIA_BASE}${path}`;
@@ -25,19 +35,22 @@ export async function fetchPage(path) {
             signal: controller.signal,
         });
         clearTimeout(timeout);
-        if (!resp.ok)
-            throw new Error(`e-Cidadania retornou HTTP ${resp.status} para ${path}`);
+        if (!resp.ok) {
+            throw ecidadaniaFetchError(`e-Cidadania retornou HTTP ${resp.status} para ${path}`, isTransientStatus(resp.status));
+        }
         const text = await resp.text();
         if (!text.trim())
-            throw new Error(`e-Cidadania retornou página vazia para ${path}`);
+            throw ecidadaniaFetchError(`e-Cidadania retornou página vazia para ${path}`, true);
         return text;
     }
     catch (e) {
         clearTimeout(timeout);
         if (e.name === "AbortError") {
-            throw new Error(`e-Cidadania: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`);
+            throw ecidadaniaFetchError(`e-Cidadania: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true);
         }
-        throw e;
+        if (e instanceof Error && "retryable" in e)
+            throw e; // already classified above
+        throw ecidadaniaFetchError(`e-Cidadania: falha de rede ao acessar ${path} (${e.message})`, true);
     }
 }
 /**
@@ -54,14 +67,15 @@ export async function fetchEcidadaniaJson(endpoint) {
             signal: controller.signal,
         });
         clearTimeout(timeout);
-        if (!resp.ok)
-            throw new Error(`e-Cidadania REST API retornou HTTP ${resp.status} para ${endpoint}`);
+        if (!resp.ok) {
+            throw ecidadaniaFetchError(`e-Cidadania REST API retornou HTTP ${resp.status} para ${endpoint}`, isTransientStatus(resp.status));
+        }
         let data;
         try {
             data = await resp.json();
         }
         catch {
-            throw new Error(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`);
+            throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
         }
         if (!Array.isArray(data)) {
             // API returned an object or other non-array — wrap or return empty
@@ -74,9 +88,11 @@ export async function fetchEcidadaniaJson(endpoint) {
     catch (e) {
         clearTimeout(timeout);
         if (e.name === "AbortError") {
-            throw new Error(`e-Cidadania REST API: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${endpoint}`);
+            throw ecidadaniaFetchError(`e-Cidadania REST API: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${endpoint}`, true);
         }
-        throw e;
+        if (e instanceof Error && "retryable" in e)
+            throw e; // already classified above
+        throw ecidadaniaFetchError(`e-Cidadania REST API: falha de rede ao acessar ${endpoint} (${e.message})`, true);
     }
 }
 /** Parse Brazilian number: 1.234.567 -> 1234567 */

package/dist/utils/validation.js

@@ -1,10 +1,25 @@
 /** Shared validation helpers and response builders. */
 import { incr } from "../metrics.js";
 import { logger } from "./logger.js";
-export function toolError(message, isRetryable = false) {
+/** Actionable next-step guidance, derived from whether retrying can help. */
+function defaultHint(isRetryable) {
+    return isRetryable
+        ? "Erro transitório na fonte de dados oficial; repita a chamada em alguns segundos."
+        : "Erro não recuperável por repetição; verifique os parâmetros (códigos, datas, filtros). Se persistir, a fonte oficial pode estar indisponível.";
+}
+/**
+ * Standard error envelope, identical across all tools: `{ error, retryable, hint }`.
+ * `hint` is an actionable next step (additive, defaults from `isRetryable`; callers may
+ * override). The same payload is also returned as `structuredContent` so clients can parse
+ * errors deterministically — symmetric with toolResult() — the permissive outputSchema is
+ * skipped on isError results anyway, and a plain object satisfies it regardless.
+ */
+export function toolError(message, isRetryable = false, hint) {
     incr("toolErrors");
+    const payload = { error: message, retryable: isRetryable, hint: hint ?? defaultHint(isRetryable) };
     return {
-        content: [{ type: "text", text: JSON.stringify({ error: message, retryable: isRetryable }) }],
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        structuredContent: payload,
         isError: true,
     };
 }

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.2.1";
+export const VERSION = "3.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,7 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250214.0",
     "@types/node": "^25.9.3",
+    "exceljs": "^4.4.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",