senado-br-mcp 3.2.1 → 3.3.1

package/README.md

@@ -94,6 +94,18 @@ list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST hig
 `meta.fonte` / `possivelDesatualizacao`; the detail tools (`obter_*`) are identical. Logs go to
 **stderr** — stdout carries only the JSON-RPC protocol stream.
 
+## Agent Skill (optional)
+
+This repo bundles a Claude [Agent Skill](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/overview)
+at [`.claude/skills/senado-br/`](.claude/skills/senado-br/SKILL.md) that teaches Claude **when** to reach for
+this server and **how** to use its 66 tools well — a themed tool map, common question→tool playbooks, the
+provenance contract, and gotchas (dates, the `codigoMateria` bridge, e-Cidadania's open-set listing, pagination).
+It points back to the server's own `senado://catalogo` / `senado://guia` resources rather than duplicating them.
+
+Claude Code auto-discovers it when you work in this repo. To use it elsewhere, copy
+`.claude/skills/senado-br/` into your `~/.claude/skills/`, or zip the folder and upload it in claude.ai
+(Settings → Features). The skill assumes the `senado-br` MCP server is connected (hosted or via npx).
+
 ## Architecture
 
 - **Runtime:** Cloudflare Workers (ESM)

package/README.pt-BR.md

@@ -93,6 +93,19 @@ as ferramentas de lista/corpus do e-Cidadania: sem D1, elas caem no scraping ao
 REST, sinalizado por `meta.fonte` / `possivelDesatualizacao`; as de detalhe (`obter_*`) são idênticas.
 Os logs vão para o **stderr** — o stdout carrega apenas o fluxo do protocolo JSON-RPC.
 
+## Agent Skill (opcional)
+
+Este repositório inclui uma [Agent Skill](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/overview)
+do Claude em [`.claude/skills/senado-br/`](.claude/skills/senado-br/SKILL.md) que ensina o Claude **quando**
+recorrer a este servidor e **como** usar bem as 66 ferramentas — um mapa de ferramentas por tema, playbooks de
+pergunta→ferramenta, o contrato de proveniência e os gotchas (datas, a ponte `codigoMateria`, a listagem
+só-abertas do e-Cidadania, paginação). Ela aponta para os recursos `senado://catalogo` / `senado://guia` do
+próprio servidor em vez de duplicá-los.
+
+O Claude Code a descobre automaticamente ao trabalhar neste repositório. Para usá-la em outro lugar, copie
+`.claude/skills/senado-br/` para o seu `~/.claude/skills/`, ou compacte a pasta e faça upload no claude.ai
+(Configurações → Recursos). A skill pressupõe o servidor MCP `senado-br` conectado (hospedado ou via npx).
+
 ## Arquitetura
 
 - **Runtime:** Cloudflare Workers (ESM)

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.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -29,12 +29,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "agents": "^0.5.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250214.0",
     "@types/node": "^25.9.3",
+    "agents": "^0.5.0",
+    "exceljs": "^4.4.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",