senado-br-mcp 3.17.0 → 3.18.1

package/README.md

@@ -35,6 +35,18 @@ Point a client at the endpoint and ask in plain language — English or Portugue
 
 The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.
 
+## Compared with the alternatives
+
+Other Brazilian MCP servers also touch the Senate — [mcp-brasil](https://github.com/Mcp-Brasil/mcp-brasil) and [mcp-dados-br](https://github.com/lucianoon/mcp-dados-br) are multi-source aggregators in which the Senate is one source among many. The difference is coverage and how you run it. Measured in each one's source code on 2026-10-11:
+
+| | Senate tools | Covers | Where it runs |
+| --- | --- | --- | --- |
+| **senado-br-mcp** (this) | 69 | legislative, administrative (CEAPS, staff, contracts, budget) and e-Cidadania, with provenance on every answer | hosted, no install or key; or `npx` |
+| [mcp-brasil](https://github.com/Mcp-Brasil/mcp-brasil) 0.14.0 | 26 | legislative (senators, bills, floor votes, committees, agenda) — plus dozens of other government sources | local or self-hosted (Python) |
+| [mcp-dados-br](https://github.com/lucianoon/mcp-dados-br) 0.6.0 | 3 | sitting senators, bill list, vote tally — plus IBGE, BCB, INMET, Chamber of Deputies | local (Python) |
+
+**Pick an aggregator** when the question crosses the Senate with the Chamber of Deputies, the electoral court (TSE) or the Transparency Portal. **Pick this server** for expenses (CEAPS), staff, contracts, budget, speeches, committee votes, vetoes or e-Cidadania — areas the others don't cover. Full per-area table, side-by-side examples and how to re-measure (in Portuguese): [`docs/comparativo-alternativas.md`](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/blob/master/docs/comparativo-alternativas.md).
+
 ## Use it (hosted — no setup)
 
 This is a **remote, hosted, open-access** server. To use it, point any MCP client at the Streamable
@@ -581,7 +593,7 @@ Each release ships one NDJSON resource per entity (one `HarmonizedRecord` per li
 | Resource (`*.ndjson`) | Grain | Key variables | Source(s) |
 |---|---|---|---|
 | `consultas` | 1 public consultation (matéria) | `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentual*`, **`autoria`ⁿ**, **`relator`ⁿ**, `status`, `url`, `firstSeenAt` | `pesquisamateria` listing + **detail** (`visualizacaomateria`)ⁿ + `/processo?tramitando=S` for status |
-| `ideias` | 1 legislative idea (~113.7k) | `titulo`, `apoios`, `status`, **`dataPublicacao`ⁿ**, **`autorUf`ⁿ**, **`descricao`ⁿ**, **`plConvertido`ⁿ**, `url`, `firstSeenAt` | `pesquisaideia` listing + **detail** (`visualizacaoideia`) via a resumable backfillⁿ |
+| `ideias` | 1 legislative idea (~113.7k) | `titulo`, `apoios`, `status`, **`dataPublicacao`ⁿ** (the *support deadline* — the only date the portal publishes; creation ≈ deadline − 120 days, see the dictionary), **`autorUf`ⁿ**, **`descricao`ⁿ**, **`plConvertido`ⁿ**, `url`, `firstSeenAt` | `pesquisaideia` listing + **detail** (`visualizacaoideia`) via a resumable backfillⁿ |
 | `eventos` | 1 interactive event (audiência) | `titulo`, **`data`ᶜ**, **`hora`ᶜ**, `comissao`, **`comissaoNomeCompleto`ⁿ**, **`local`ⁿ**, **`descricao`ⁿ**, **`pauta`ⁿ**, **`convidados`ⁿ**, **`videoUrl`ⁿ**, **`comentarios`ᶜ**, `status`, `url`, `firstSeenAt` | `principalaudiencia` listing + **detail** (`visualizacaoaudiencia`)ⁿ + **AJAX comment fragment**ᶜ |
 | **`eventos_comentarios`ⁿ** | 1 comment (comment-level) | `eventoId`, `comentarioId`, `uf`, `texto`, `data`, `hora`, `momentoVideoUrl`, `convidadoAssociado` | AJAX fragment `ajaxcolecaocomentarioaudiencia?audienciaId=` |
 | `consultas_votos` | 1 matéria (historical acervo) | `materia`, `ementa`, `autoria`, `votosSim`/`votosNao`/`totalVotos`, `votosPorUf`, `status`, `url`, `referencePeriod` | Arquimedes CSV `Proposições-com-votos.csv` (re-ingested weekly) |

package/dist/dataset/schema.js

@@ -191,11 +191,11 @@ const ideiasSchema = {
         {
             name: "dataPublicacao",
             type: "date",
-            description: "Data limite para atingir os 20.000 apoios (única âncora temporal upstream da ideia).",
+            description: "Data limite para atingir os 20.000 apoios (única âncora temporal upstream da ideia). NÃO é a data de criação: o nome é histórico, mantido pela compatibilidade do esquema.",
             sourceEndpoint: EP_IDEIAS_DETALHE,
-            sourceField: "página de detalhe: bloco \"Data limite\" (DD/MM/AAAA)",
-            operationalization: "extractDate sobre a data-limite exibida no detalhe (visualizacaoideia) → ISO YYYY-MM-DD; lido no crawl de detalhe. Reaberto na v2 (era null por design na v1).",
-            caveat: "Detail-only (v2): null nas ideias ainda não enriquecidas pelo backfill de detalhe (censura à esquerda residual nesses campos até o backfill completar).",
+            sourceField: "página de detalhe: bloco \"Data limite para receber 20.000 apoios\" (DD/MM/AAAA)",
+            operationalization: "extractDate sobre a data-limite exibida no detalhe (visualizacaoideia) → ISO YYYY-MM-DD; lido no crawl de detalhe. Reaberto na v2 (era null por design na v1). Data provável de criação = esta data − 120 dias (regra dos 4 meses do portal; medida exata em 4 ideias convertidas de 2017-2020 contra a base de Pereira, UFPE 2024) — derivação do leitor, não variável do dataset.",
+            caveat: "Em ideia aberta esta data está no futuro (é o fim do prazo de apoios). Detail-only (v2): null nas ideias ainda não enriquecidas pelo backfill de detalhe (censura à esquerda residual nesses campos até o backfill completar).",
         },
         {
             name: "autorUf",

package/dist/scraper/ecidadania.js

@@ -253,6 +253,44 @@ export async function obterConsultaInternal(id) {
         linkMateria: null,
     };
 }
+// ── Ideias ─────────────────────────────────────────────────────────────
+/**
+ * Prazo de apoios de uma ideia, em dias. O portal diz que "as ideias ficam abertas por 4 meses"
+ * (`/comofuncionaideia`) e publica UMA data só, a "Data limite para receber 20.000 apoios" — é ela
+ * que o campo `dataPublicacao` guarda (nome histórico; ver `AVISO_DATAS_IDEIA`). Medido em
+ * 09/10/2026 contra a data de proposição de 4 ideias convertidas (base de Pereira, UFPE 2024,
+ * github.com/theus0307/dissertacao): a data limite é SEMPRE a proposição + 120 dias exatos —
+ * SUG 49/2017 12/09/2017 → 10/01/2018; SUG 43/2019 14/10/2019 → 11/02/2020; SUG 49/2019
+ * 31/07/2019 → 28/11/2019; SUG 21/2020 02/06/2020 → 30/09/2020. "4 meses" de calendário erraria
+ * em 2 a 3 dias em todas.
+ */
+export const IDEIA_PRAZO_APOIOS_DIAS = 120;
+/**
+ * Aviso que acompanha as datas de ideia na saída das tools. Vai JUNTO do dado, não só na descrição
+ * da tool: a descrição é lida uma vez, o dado é lido a cada resposta, e a data limite de uma ideia
+ * aberta cai no futuro — sem o aviso o leitor conclui que o servidor errou.
+ */
+export const AVISO_DATAS_IDEIA = "dataPublicacao é a data limite para receber os 20.000 apoios, a única data que o portal publica (o nome do campo é histórico); " +
+    "por isso cai no futuro em ideia aberta. dataCriacaoEstimada = data limite menos 120 dias, calculada pelo servidor " +
+    "(regra dos 4 meses do portal, medida em 4 ideias de 2017-2020): é estimativa, não dado da fonte.";
+/**
+ * Data provável de criação da ideia: data limite (ISO) − `IDEIA_PRAZO_APOIOS_DIAS`. Aritmética em UTC
+ * sobre o dia civil (sem fuso, sem horário de verão). Data ausente ou inválida → null, nunca uma data
+ * inventada (o `Date` "corrige" 31/02 para 03/03; aqui isso é rejeitado).
+ */
+export function estimarCriacaoIdeia(dataLimite) {
+    if (!dataLimite)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dataLimite);
+    if (!m)
+        return null;
+    const [ano, mes, dia] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const t = Date.UTC(ano, mes - 1, dia);
+    const d = new Date(t);
+    if (Number.isNaN(t) || d.getUTCFullYear() !== ano || d.getUTCMonth() !== mes - 1 || d.getUTCDate() !== dia)
+        return null;
+    return new Date(t - IDEIA_PRAZO_APOIOS_DIAS * 86_400_000).toISOString().slice(0, 10);
+}
 /**
  * Canonical `IdeiaResumo` builder — single source of the object's field order, so the JSON payload
  * (and `contentHash`) is byte-identical across the writers into `ecidadania_current`: the 2h highlight

package/dist/tools/ecidadania.js

@@ -16,9 +16,9 @@ import { provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance }
 import { tagUntrustedFields, tagUntrustedList, neutralizeUntrustedText, sanitizeScrapedText } from "../utils/untrusted.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 import { resolveList, writeDetalheThrough } from "../scraper/store.js";
-import { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, } from "../scraper/ecidadania.js";
+import { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, estimarCriacaoIdeia, AVISO_DATAS_IDEIA, IDEIA_PRAZO_APOIOS_DIAS, } from "../scraper/ecidadania.js";
 // Re-export the scraper's pure/IO helpers so existing unit tests keep importing them from here.
-export { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, };
+export { estimarCriacaoIdeia, AVISO_DATAS_IDEIA, IDEIA_PRAZO_APOIOS_DIAS, ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, };
 /** Format an integer with pt-BR thousands separators ("253804" → "253.804").
  *  Avoids toLocaleString, whose Intl data is not guaranteed on Workers (OBS-12). */
 export function formatIntBR(n) {
@@ -163,7 +163,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
         }
     });
     // G5. senado_ecidadania_listar_ideias
-    server.tool("senado_ecidadania_listar_ideias", "Lista ideias legislativas propostas por cidadãos no e-Cidadania — **conjunto completo** (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna `{ count, ideias }`, cada ideia com `id`, `titulo`, `apoios`, `status` (`aberta`/`encerrada`/`convertida`/`removida` — `removida` = retirada do portal, que não a publica mais; o corpus guarda o último estado conhecido) e `url` (`autor` e `dataPublicacao` só aparecem no detalhe, vêm `null` aqui). Aceita filtro por `status` e `limite` (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (`ordenarPor: \"apoios\"`, `ordem: \"desc\"`). Para o detalhe completo de uma ideia (texto, autor, se virou projeto de lei) chame `senado_ecidadania_obter_ideia` com o `id`.", {
+    server.tool("senado_ecidadania_listar_ideias", "Lista ideias legislativas propostas por cidadãos no e-Cidadania — **conjunto completo** (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna `{ count, ideias, avisoDatas }`, cada ideia com `id`, `titulo`, `apoios`, `status` (`aberta`/`encerrada`/`convertida`/`removida` — `removida` = retirada do portal, que não a publica mais; o corpus guarda o último estado conhecido), `url` e os campos lidos do detalhe quando o backfill já passou por ela (`dataPublicacao`, `autorUf`, `descricao`, `plConvertido`; `null` até lá). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; `dataCriacaoEstimada` (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte; `avisoDatas` repete isso na resposta. Aceita filtro por `status` e `limite` (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (`ordenarPor: \"apoios\"`, `ordem: \"desc\"`). Para o detalhe completo de uma ideia (texto, autor, se virou projeto de lei) chame `senado_ecidadania_obter_ideia` com o `id`.", {
         status: z.enum(["aberta", "encerrada", "convertida", "removida", "todas"]).optional().describe("Filtrar por status (`removida` = retirada do portal)"),
         ordenarPor: z.enum(["apoios", "data", "comentarios"]).optional().describe("Campo para ordenação (apoios é o disponível no corpus; data/comentarios só no detalhe)"),
         ordem: z.enum(["asc", "desc"]).optional().describe("Ordem de ordenação"),
@@ -181,19 +181,34 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
             const limite = params.limite ?? 20;
             const offset = ((params.pagina ?? 1) - 1) * limite;
             arr = arr.slice(offset, offset + limite);
-            return resultWithProvenance({ count: arr.length, ideias: tagUntrustedList("ideias", arr), meta }, provLista("/principalideia", "ideias", meta));
+            // Derivado na SAÍDA, nunca no corpus: `IdeiaResumo` é o payload persistido (hash estável).
+            const ideias = arr.map((i) => ({ ...i, dataCriacaoEstimada: estimarCriacaoIdeia(i.dataPublicacao) }));
+            return resultWithProvenance({
+                count: ideias.length,
+                ideias: tagUntrustedList("ideias", ideias),
+                avisoDatas: AVISO_DATAS_IDEIA,
+                meta,
+            }, provLista("/principalideia", "ideias", meta));
         }
         catch (e) {
             return ecidadaniaError(e);
         }
     });
     // G6. senado_ecidadania_obter_ideia
-    server.tool("senado_ecidadania_obter_ideia", "Obtém o detalhe de uma ideia legislativa do e-Cidadania. Retorna um objeto com `id`, `titulo`, `descricao` (texto completo, truncado em ~2000 caracteres), `apoios`, `dataPublicacao`, `status`, `autor`, `url` e `plConvertido` (sigla/número quando virou projeto de lei). O campo `comentarios` vem `null`: a página de ideia não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.", { id: z.number().int().positive().describe("ID da ideia legislativa") }, async (params) => {
+    server.tool("senado_ecidadania_obter_ideia", "Obtém o detalhe de uma ideia legislativa do e-Cidadania. Retorna um objeto com `id`, `titulo`, `descricao` (texto completo, truncado em ~2000 caracteres), `apoios`, `dataPublicacao`, `dataCriacaoEstimada`, `avisoDatas`, `status`, `autor`, `url` e `plConvertido` (sigla/número quando virou projeto de lei). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; `dataCriacaoEstimada` (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte. O campo `comentarios` vem `null`: a página de ideia não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.", { id: z.number().int().positive().describe("ID da ideia legislativa") }, async (params) => {
         try {
             const { value: r, fetchedAt } = await cachedFetchWithMeta("ecidadania_ideia", { id: params.id }, CACHE_ON_DEMAND, () => obterIdeiaInternal(params.id));
             writeDetalheThrough(db, ctx, "ideias", params.id, r);
             // OBS-9: idea pages have no comments resource — serve null instead of a spurious 0.
-            const detalhe = { ...r, comentarios: null };
+            // Datas: `dataCriacaoEstimada` e `avisoDatas` entram SÓ na resposta (não no write-through acima,
+            // que guarda o que a página diz).
+            const ideia = r;
+            const detalhe = {
+                ...r,
+                dataCriacaoEstimada: estimarCriacaoIdeia(ideia.dataPublicacao),
+                comentarios: null,
+                avisoDatas: AVISO_DATAS_IDEIA,
+            };
             return resultWithProvenance(tagUntrustedFields("ideias", detalhe), provDetalhe(r, `/visualizacaoideia?id=${params.id}`, `ideia=${params.id}`, fetchedAt));
         }
         catch (e) {

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.17.0";
+export const VERSION = "3.18.1";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.17.0",
+  "version": "3.18.1",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "senado",
+    "senado-federal",
+    "brazilian-senate",
+    "dados-abertos",
+    "open-data",
+    "brasil",
+    "brazil",
+    "legislativo",
+    "votacoes",
+    "materias-legislativas",
+    "ceaps",
+    "cota-parlamentar",
+    "e-cidadania",
+    "transparencia",
+    "cloudflare-workers"
+  ],
   "license": "MIT",
   "type": "module",
   "mcpName": "io.github.SidneyBissoli/senado-br-mcp-cloudflare",
@@ -61,7 +81,7 @@
     "@cloudflare/workers-types": "^5.20260830.1",
     "@modelcontextprotocol/client": "^2.0.0",
     "@sbissoli/mcp-evals": "^0.2.1",
-    "@sbissoli/mcp-surface": "^0.5.0",
+    "@sbissoli/mcp-surface": "^0.6.0",
     "@types/node": "^26.5.1",
     "agents": "^0.26.0",
     "exceljs": "^4.4.0",