Skip to main content
Glama
Senado BR — Brazilian Federal Senate Open Data

Senado BR — Brazilian Federal Senate Open Data

Senado Brasil MCP Server

Cloudflare Workers MCP Tools CI MCP Registry LobeHub LightNow capabilities senado-br-mcp-cloudflare MCP server GitHub stars GitHub Sponsors License: MIT Status

🇧🇷 Leia em Português

A public, hosted MCP server that gives AI assistants live, structured access to Brazilian Senate open data — no installation, no account, no API key. Point your MCP client at the hosted endpoint and start asking about senators, bills, votes, expenses, and more. It runs on Cloudflare Workers over Streamable HTTP.

It exposes 69 tools, 4 prompts, and 5 resources across two domains:

  • Legislative — senators; bills and their tramitation; votes; committees; plenary sessions, results and presidential vetoes; party-bloc voting orientation; speeches and stenographic transcripts; blocs and leadership; federal legislation; and citizen participation via the e-Cidadania portal.

  • Administrative — CEAPS parliamentary-quota expenses; housing allowance; civil servants and payroll; overtime; interns; procurement contracts and biddings; outsourced staff; petty-cash funds; and budget execution.

Data comes from three official sources — the legislative open-data API, the administrative open-data API, and the e-Cidadania portal. All tool responses are in Portuguese (pt-BR). See CHANGELOG.md for release history.

See it in action

Point a client at the endpoint and ask in plain language — English or Portuguese:

  • "How did São Paulo's senators vote in the most recent floor votes?" → senado_search_votacoes

  • "Show the legislative progress of PEC 45/2019 (a constitutional amendment proposal)." → senado_buscar_materias + senado_obter_materia

  • "How much was spent on the CEAPS parliamentary allowance in 2024, broken down by expense type?" → senado_ceaps

The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.

Related MCP server: mcp-camara

Compared with the alternatives

Other Brazilian MCP servers also touch the Senate — mcp-brasil and 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 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 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.

Use it (hosted — no setup)

This is a remote, hosted, open-access server. To use it, point any MCP client at the Streamable HTTP endpoint — no install, no account, no API key, no configuration:

https://senado.sidneybissoli.com/mcp

OpenAI / ChatGPT app surface

For OpenAI Apps SDK submission and review, the Worker also exposes a curated MCP surface:

https://senado.sidneybissoli.com/mcp/openai-app-v2

This endpoint intentionally keeps the full public MCP server intact at /mcp, but limits tool discovery to 27 high-signal, intent-oriented tools for ChatGPT app use. /mcp/openai-app remains available as a legacy alias, but new ChatGPT app configurations should use /mcp/openai-app-v2 so clients fetch the current tool schema. The tools still call the same handlers and return the same provenance envelope; only the advertised surface is narrower. Any ChatGPT app listing should present this as an independent open-data research app, not as an official Senate, OpenAI or ChatGPT connector.

For ChatGPT Apps, those 27 tools also advertise a shared MCP Apps UI template at ui://senado-br-mcp/openai-app-dashboard-v2.html. The self-contained widget renders the returned structuredContent as a compact dashboard with metrics, main records, and source/provenance, without adding another model-visible data tool.

Public legal URLs for app review:

  • Privacy policy: https://senado.sidneybissoli.com/privacy

  • Terms of use: https://senado.sidneybissoli.com/terms

ChatGPT (Deep Research)

ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the senado_* tools, on the full /mcp surface (not on the curated app profile). Point the connector at the hosted endpoint, no key required:

https://senado.sidneybissoli.com/mcp

search ranks the query against the senators in office and the active committees of the Senate and the National Congress and returns { id, title, url } (sen:<código> / com:<código>); fetch returns the document as readable Markdown — the senator's biography and mandates, or the committee's summary and board — with the canonical public page (the senator's profile on www25.senado.leg.br or the committee page on legis.senado.leg.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool, in structuredContent and _meta (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the senado_* tools remain the ones to use for data.

Install (any client)

For clients that launch MCP servers as a command — and for one-command setup — use the mcp-remote bridge. No build, no config, no key:

npx -y mcp-remote https://senado.sidneybissoli.com/mcp

Everything below Architecture (Prerequisites, Setup, Deploy) is only for optionally self-hosting your own instance — it is not required to use this public server.

Run locally (npx · stdio)

Prefer not to route queries through a third-party host (e.g. a newsroom policy)? The same server also runs as a local stdio process that talks directly to the official government APIs — same 69 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published as senado-br-mcp.

Point a command-based client (Claude Desktop/Code, etc.) at the package — npm fetches and runs it, no clone or build:

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "senado-br-mcp"]
    }
  }
}

To run it directly or hack on it, use the source checkout instead:

git clone https://github.com/SidneyBissoli/senado-br-mcp-cloudflare
cd senado-br-mcp-cloudflare
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

Parity with the hosted server: the legislative and administrative tools are identical (same upstream APIs, same throttle/cache/provenance) — locally the L1 Cloudflare cache is a no-op, but the L0 in-memory cache still works, so results are the same. The only difference is the e-Cidadania list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST highlights, flagged via 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 at .claude/skills/senado-br/ that teaches Claude when to reach for this server and how to use its 69 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)

  • Transport: Streamable HTTP (MCP spec 2025-03-26) via createMcpHandler from agents/mcp

  • Protocol: MCP over JSON-RPC — /mcp handles the full public server; /mcp/openai-app-v2 exposes a curated 27-tool profile plus a shared MCP Apps widget for OpenAI app review/submission (/mcp/openai-app remains as a legacy alias)

  • SDK: @modelcontextprotocol/server 2.x (per-request McpServer instances; the v1 @modelcontextprotocol/sdk is not installed — agents still lists it as a peer, satisfied via legacy-peer-deps)

  • Validation: Zod schemas for all tool inputs

  • Caching: 2-layer (L0 memory + L1 Cache API) with SHA-256 keying

  • e-Cidadania store: D1 database refreshed by a Cron Trigger (every 2h) — list tools read from D1 with a live-scrape fallback and a staleness flag; detail tools stay live with write-through (see e-Cidadania)

  • Rate limiting: Token bucket — global (8 req/s) + per-client (2 req/s)

  • Upstream throttle: Max 6 concurrent requests, 10s budget per trip, retry on 429/5xx/network with exponential backoff and Retry-After (portfolio shared fetch @sbissoli/mcp-upstream); every response's provenance carries the measured retrieval diagnostics (trips, attempts, anomalies)

  • Auth: Optional Bearer token (set the API_KEY secret; open access when unset). Constant-time comparison.

  • Observability: Structured JSON logging + in-memory counters at /metrics; per-tool call telemetry (selection, error rate, cache-vs-live) in Cloudflare Analytics Engine, PII-free

  • Liveness: Runs on Cloudflare's own global network behind a custom domain — no third-party host that can go dark. Public /health and /status (version + last-deploy id/timestamp) make uptime and the current build verifiable; the status badge above pings the live endpoint

  • Tests: Vitest unit tests for parsers, helpers, cache, throttle, and auth

Self-hosting (optional)

Not needed to use the server — it is already hosted at https://senado.sidneybissoli.com/mcp (open access). Follow this section only if you want to run your own private instance.

Prerequisites

  • Node.js 22+ (engines.node)

  • Wrangler CLI v4+

  • Cloudflare account

Setup

1. Install dependencies

npm install

2. Create KV namespace

# Create the KV namespace
wrangler kv namespace create CACHE_KV

# Note the ID from the output, e.g.:
# { binding = "CACHE_KV", id = "abc123..." }

3. Configure wrangler.toml

Replace the placeholder KV namespace ID:

[[kv_namespaces]]
binding = "CACHE_KV"
id = "YOUR_KV_NAMESPACE_ID_HERE"

Optionally set ALLOWED_ORIGIN to restrict CORS:

[vars]
ALLOWED_ORIGIN = "https://your-app.example.com"

The e-Cidadania pipeline needs a D1 database and a Cron Trigger (both already declared in wrangler.toml — replace the database ID):

[[d1_databases]]
binding = "ECIDADANIA_DB"
database_name = "senado-ecidadania"
database_id = "YOUR_D1_DATABASE_ID_HERE"

[triggers]
crons = ["0 */2 * * *"]

Create the database (paste the returned ID above) and apply the schema:

npx wrangler d1 create senado-ecidadania
npx wrangler d1 migrations apply senado-ecidadania --remote

The list tools fall back to live scraping when D1 is empty, so the server works before the first Cron run.

4. (Optional) Enable authentication

wrangler secret put API_KEY
# Clients must then send: Authorization: Bearer <key>
# When API_KEY is not set, the server is open access.

5. Local development

npm run dev
# Dev server runs locally on port 8787 (local only).
# The public MCP endpoint is https://senado.sidneybissoli.com/mcp

6. Tests and typecheck

npm test             # run all tests once
npm run test:watch   # watch mode
npm run typecheck    # tsc --noEmit

7. Deploy

npm run deploy
# Serves at https://senado.sidneybissoli.com (custom domain) and
# https://senado-br-mcp.sidneybissoli.workers.dev (workers.dev fallback)

Endpoints

Path

Methods

Description

/

GET

Landing page (pt-BR) — identifies the client behind the outgoing User-Agent: what the service is, load posture, contact (always public)

/mcp

POST, GET, DELETE, OPTIONS

MCP Streamable HTTP endpoint (managed by createMcpHandler)

/health

GET

Health check — returns ok (always public)

/status

GET

JSON: status, version, and last-deploy metadata (deploy.id/tag/timestamp) — liveness + current build, no MCP handshake needed (always public)

/metrics

GET

JSON counters: requests, tool calls, cache hits/misses, upstream calls/retries/errors, auth failures (always public)

/.well-known/mcp/server-card.json

GET

MCP server card for directory scanners (Smithery): serverInfo, authentication, tools/resources/prompts — generated from the live full profile by @sbissoli/mcp-surface/card (always public)

Surface fingerprint, checkable from the registry

Every release publishes, in its MCP Registry entry, the sha256 of the surface /mcp serves (initialize, tools, resources, prompts of the full profile) and which methods answer there without a credential. A surface change without a version bump fails the build; the fingerprint in the registry lets a client check the same thing on its own side. Canonical form and procedure: SPEC.md of @sbissoli/mcp-surface. To check it yourself (Node 18+, no dependencies):

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/senado-br-mcp-cloudflare

MCP Request Examples

All requests go to POST /mcp with JSON-RPC 2.0 format.

List available tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call a tool — List senators from SP

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "senado_listar_senadores",
    "arguments": {
      "uf": "SP",
      "emExercicio": true
    }
  }
}

Call a tool — Search bills by keyword

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "senado_buscar_materias",
    "arguments": {
      "palavraChave": "inteligência artificial",
      "tramitando": true
    }
  }
}

Call a tool — Get recent plenary votes

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "senado_search_votacoes",
    "arguments": {
      "dias": 7
    }
  }
}
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "senado_ecidadania_listar_ideias",
    "arguments": {
      "ordenarPor": "apoios",
      "ordem": "desc",
      "status": "aberta"
    }
  }
}

Upstream API Endpoints

The server consumes two classes of upstream endpoints from the Senado API:

Legacy endpoints (.json suffix, PascalCase responses)

Used by Groups A, E, F, H, I, J, K, L, M, N. The .json suffix is appended automatically by upstream.ts. None of these is marked deprecated upstream.

Upstream path

Used by

/senador/lista/atual

senado_listar_senadores

/senador/lista/legislatura/{legislatura}

senado_listar_senadores (param legislatura; emExercicio crossed with /senador/lista/atual)

/senador/{codigo} (+ /mandatos)

senado_obter_senador (biografia + mandatos via chamada extra)

/senador/{codigo}/licencas, /comissoes, /cargos, /historicoAcademico, /filiacoes, /profissao

senado_senador_historico (tipo enum)

/senador/afastados

senado_senadores_afastados, senado_listar_senadores (emExercicio: false)

/senador/{codigo}/apartes

senado_discursos_senador (tipo=apartes)

/comissao/lista/colegiados

senado_listar_comissoes (+ sigla-to-code resolution)

/comissao/{codigo}

senado_obter_comissao (secao=resumo; numeric code, not sigla)

/composicao/comissao/{codigo} (+ ?ativas=S)

senado_obter_comissao (secao=membros)

/comissao/agenda/{data}

senado_agenda_comissoes, senado_reunioes_comissao (one read per day)

/comissao/agenda/{dataInicio}/{dataFim}

senado_reuniao_comissao (by sigla, last 14 days)

/comissao/reuniao/{codigoReuniao}

senado_reuniao_comissao

/comissao/cpi/{sigla}/requerimentos

senado_requerimentos_cpi (upstream often empty even for active CPIs — empty result carries an aviso)

/materia/distribuicao/autoria, /distribuicao/relatoria/{sigla}

senado_distribuicao_materias

/plenario/agenda/dia/{data}, /agenda/mes/{data}, /agenda/cn/...

senado_agenda_plenario

/plenario/resultado/{data}, /resultado/cn/{data}, /resultado/mes/{data}

senado_resultado_plenario

/plenario/resultado/veto/{codigo} (+ /materia/, /dispositivo/)

senado_resultado_veto

/plenario/votacao/orientacaoBancada/{data} (+ período)

senado_orientacao_bancada

/plenario/encontro/{codigo} (+ /pauta, /resultado, /resumo)

senado_encontro_plenario

/plenario/tiposSessao, /lista/tiposComparecimento, /lista/legislaturas

senado_tabelas_plenario

/materia/vetos/{ano}, /vetos/aposrcn, /vetos/antesrcn, /vetos/encerrados

senado_vetos

/taquigrafia/notas/{sessao|reuniao}/{id}

senado_notas_taquigraficas

/taquigrafia/videos/{sessao|reuniao}/{id}

senado_videos_taquigrafia

/senador/{codigo}/discursos

senado_discursos_senador

/plenario/lista/discursos/{dataInicio}/{dataFim}

senado_discursos_plenario

/discurso/texto-integral/{codigo}

senado_discurso_texto (plain text, fetched directly)

/senador/lista/tiposUsoPalavra

senado_tabelas_referencia (tabela=tipos-uso-palavra)

/composicao/lista/blocos

senado_listar_blocos

/composicao/bloco/{codigo}

senado_obter_bloco

/composicao/lideranca

senado_liderancas

/composicao/mesaSF

senado_mesa (casa=senado)

/composicao/mesaCN

senado_mesa (casa=congresso)

/orcamento/lista

senado_orcamento_parlamentar (tipo=emendas)

/orcamento/oficios

senado_orcamento_parlamentar (tipo=oficios)

/legislacao/lista

senado_buscar_legislacao

/legislacao/{codigo}

senado_obter_legislacao

/legislacao/tiposNorma

senado_tabelas_referencia (tabela=tipos-norma)

/votacaoComissao/comissao/{sigla}

senado_votacao_comissao (por=comissao)

/votacaoComissao/parlamentar/{codigo}

senado_votacao_comissao (por=senador)

/votacaoComissao/materia/{sigla}/{numero}/{ano}

senado_votacao_comissao (por=materia)

/autor/lista/atual

senado_autores_atuais

v3 endpoints (flat JSON arrays/objects, camelCase)

Used by Groups B, C, D. Dates must be in ISO format (YYYY-MM-DD) — tools accept YYYYMMDD and convert. The codigoMateria query param bridges legacy matéria codes to v3 processes.

Upstream path

Used by

/votacao

senado_obter_votacao, senado_search_votacoes, senado_votos_materia, senado_votacoes_senador

/processo

senado_search_processos, senado_buscar_materias

/processo/{id}

senado_obter_processo, senado_obter_materia (secao=detalhe/tramitacao)

/processo/documento

senado_obter_materia (secao=textos)

/processo/emenda

senado_processo_detalhe (secao=emendas)

/processo/relatoria

senado_processo_detalhe (secao=relatorias), senado_obter_materia (rapporteur)

/processo/prazo

senado_processo_detalhe (secao=prazos)

/processo/{siglas,assuntos,classes,destinos,entes,tipos-*}

senado_tabelas_processo (12 reference tables)

Administrative API (adm.senado.gov.br/adm-dadosabertos, flat snake_case JSON)

Used by Groups O, P, Q, R via admFetch (no .json suffix; HTTP 404 treated as empty collection). Base URL configurable via SENADO_ADM_BASE_URL.

Upstream path

Used by

/api/v1/senadores/despesas_ceaps/{ano}

senado_ceaps (~10 MB/year, cached + aggregated in-Worker)

/api/v1/senadores/{auxilio-moradia-imoveis-funcionais,escritorios-apoio,aposentados}

senado_senadores_admin (tipo enum)

/api/v1/servidores/servidores/{ativos,efetivos,comissionados,inativos}

senado_servidores

/api/v1/servidores/remuneracoes/{ano}/{mes}

senado_remuneracoes_servidores (~5.5 MB/month)

/api/v1/servidores/horas-extras/{ano}/{mes}

senado_horas_extras

/api/v1/servidores/quantitativos/*, /previsao-aposentadoria, /api/v1/senadores/quantitativos/senadores

senado_pessoal_tabelas (quantitativos)

/api/v1/servidores/{pensionistas,lotacoes,cargos}, /api/v1/colaboradores/estagiarios

senado_pessoal_tabelas (listas nominais)

/api/v1/contratacoes/contratos (+ /{id}/aditivos)

senado_contratos, senado_contratacao_detalhe

/api/v1/contratacoes/{tipo}/{id}/{itens,pagamentos,garantias}

senado_contratacao_detalhe

/api/v1/contratacoes/licitacoes

senado_licitacoes

/api/v1/contratacoes/terceirizados

senado_terceirizados

/api/v1/contratacoes/empresas

senado_empresas_contratadas (~13 MB, requires filter)

/api/v1/contratacoes/{atas_registro_preco,notas_empenho,menores_aprendizes}

senado_contratacoes_lista

/api/v1/supridos/{ano} (+ atosConcessao, empenhos, movimentacoes, transacoes)

senado_suprimento_fundos

senado.gov.br/bi-arqs/Arquimedes/Financeiro/{Despesa,Receitas}SenadoDadosAbertos.json

senado_execucao_orcamentaria (daily JSON feeds, Brazilian decimal strings normalized)

e-Cidadania (D1-backed, Cron-refreshed)

The e-Cidadania list data is persisted in a D1 database (ecidadania_current/_history/_scrape_runs, discriminated by entidade; plus ecidadania_comentarios for the audiência comment level and ecidadania_detalhe_cursor for the resumable detail backfill — added in schema v2) and read from there instead of being scraped on every call. Three cadences write into it:

  • a daily off-Worker GitHub Action owns the full corpus of the three live entities (consultas, eventos, ideias; see below) — the source of truth. Daily (not weekly) because the first-seen series MIN(scraped_at) is the only measurable entry-rhythm signal and every skipped day permanently shortens it (ROADMAP Etapa 2, decisão D3);

  • a weekly ingest Action (.github/workflows/verify-consultas-votos.yml — historical filename) for the consultas_votos acervo: the Senado republishes the Arquimedes CSV periodically (confirmed 2026-07-20), so the weekly run re-ingests the current vintage under the same anomaly guards as the other corpora (see below);

  • an in-Worker Cron Trigger (0 */2 * * *, src/scraper/pipeline.ts → refreshEcidadania) does only a targeted metric splice of the ~5 REST highlights per live entity (restcolecaomaismateria/ideia/audiencia — votos/comentários/apoios), recorded as ok-metrica so it never re-breaks the corpus baseline and never touches the long tail. In v2 the eventos splice preserves the corpus's canonical comment count (the daily crawl is the source of truth for comentarios, so the splice can't ping-pong it against the degraded REST count).

Both writers build payloads through the canonical buildXResumo builders + shared contentHash, so their rows are byte-identical. Each write:

  • upserts ecidadania_current (one row per item — what the tools read),

  • appends ecidadania_history only when an item's content_hash changes (time-series-ready),

  • records each run in ecidadania_scrape_runs.

An anomaly guard (src/scraper/anomaly.ts, classifyRun) ensures a failed or anomalous corpus run (zero rows, or fewer than ECIDADANIA_CORPUS_MIN_PCT% of the last good run) never overwrites the last good state.

The list / analysis tools (listar_*, consultas_analise, sugerir_tema_enquete, consultas_votos) read from D1 via resolveList (src/scraper/store.ts): D1-first. Because every entity is now a full corpus, a stale corpus is served from D1 flagged (possivelDesatualizacao: true) rather than collapsing to the ~5-item live highlights (the original coverage bug); the live scrape is reserved for an empty D1 (cold start, before the first weekly run). Staleness uses ECIDADANIA_CORPUS_STALE_MAX_MIN (~10 days). Every list response carries an additive meta (fonte, lastScrapedAt, possivelDesatualizacao) so callers always see the data's real age and never get stale data silently.

The detail tools (obter_*) stay live (HTML scraped with CSS-class-targeted regex) for freshness, and write their richer payload through to ecidadania_detalhe fire-and-forget (deduped by content_hash), so detail history accrues without adding latency to the response.

Full-corpus ingestion (off-Worker)

The three live e-Cidadania corpora are owned by the daily Action (.github/workflows/ingest-ecidadania.yml), each with its own scripts/ingest-ecidadania/index-*.ts orchestrator emitting batched out-*.sql the apply step bulk-loads:

  • consultas — open consultations (detailed below). In v2 each crawled matter is also enriched from its detail page (visualizacaomateria) for autoria/relator; those are immutable, so only rows not yet enriched are fetched.

  • eventos — audiências/eventos from the principalaudiencia?p=N HTML listing; status comes straight from the listing block (no /processo bridge). In v2 every event is enriched from its detail page (canonical data/hora + comissaoNomeCompleto/local/descricao/pauta/convidados/videoUrl) and its AJAX comment fragment (canonical count + one ecidadania_comentarios row per comment, diffed against the stored hashes and emitted as out-eventos-comentarios-*.sql).

  • ideias — ideias legislativas (~113.7k) from pesquisaideia?situacao=N&p=M, crawled per situacao bucket (the listing has no inline status) and emitted in ~10k-statement batches. In v2 the listing crawl preserves the immutable detail fields, and a separate resumable backfill (index-ideias-detalhe.ts, run via ingest:ecidadania:ideias-detalhe) fills them a chunk per run — because ~113.7k detail fetches don't fit one Action, it persists a cursor in ecidadania_detalhe_cursor and wraps around at the end.

The fourth entity, consultas_votos, is a separate historical acervo of votes-by-UF parsed from the ~33 MB Arquimedes CSV (Proposições-com-votos.csv), aggregated to one record per matéria with a votosPorUf breakdown. The CSV's "dados atualizados até" stamp becomes the provenance data_vintage; it is excluded from the row hash (consultaVotoCore) so a re-ingest with unchanged votes doesn't churn _history. STATUS ATUAL is uniformly "Descontinuado", hence archival, not a migration of the open consultations. Served by senado_ecidadania_consultas_votos with provenance pointing at the CSV (ECIDADANIA_ARQUIMEDES). It is excluded from the daily job and owned by its own weekly ingest Action (.github/workflows/verify-consultas-votos.yml — the filename keeps the historical verify- prefix): the acervo was originally treated as a frozen single vintage (ROADMAP Etapa 2, decisão D1) and the weekly run only verified it, but on 2026-07-20 the Senado republished the CSV as a fresh vintage (+43 matérias, 648 updated), so the scheduled run now re-ingests the current vintage under the standard anomaly guards (empty/truncated CSV and the catastrophic floor still fail without writing; force dispatch overrides the floor). The script's verify mode (INGEST_CONSULTAS_VOTOS_VERIFY=1 / --verify) remains available as an on-demand integrity check.

The consultas job is the reference implementation:

consultas covers the full set of OPEN consultations — every matter currently in tramitação (~7.7k), not just the ~5 highlights. Confirmed on the first run: the pesquisamateria listing is in-tramitação-only, so closed/historical consultations are not captured by this source (a pre-ingestion historical backfill is out of scope). Three settled design decisions:

  1. Decoupled ingestion. The open set is acquired by an off-Worker TypeScript job (scripts/ingest-ecidadania/, run by a daily GitHub Action — .github/workflows/ingest-ecidadania.yml) that paginates the HTML listing (pesquisamateria?p=1..N, the only full-coverage source for open consultations) for ids + vote counts and bulk-loads D1; the Worker only reads. The brittle, long crawl is kept out of the request/Cron path.

  2. Status from /processo, not HTML. A consultation runs from presentation until the end of tramitação, so status is a function of the matter: aberta ⟺ the codigoMateria is in the /processo tramitando=S set, derived from robust JSON (never scraped). Every consultation enters as aberta (the listing only yields in-tramitação matters); on each complete run the job re-derives status for all stored rows by /processo membership (not by listing-absence, which can be transient), so a consultation whose matter leaves tramitação flips to encerrada. The encerrada/todas sets therefore grow over time; consultations that closed before the first ingestion aren't captured (out of scope). The list/analysis tools default to status: aberta.

  3. Two reconciled cadences (one shared writer contract). The job reuses contentHash + the ConsultaResumo builder + classifyRun from src/scraper/, so its rows are byte-identical to the Cron's. The daily job owns the long tail; the 2h Cron keeps the ~5 hot/open highlights fresh via a targeted metric splice (recorded as ok-metrica, bypassing the corpus classifyRun baseline). Corpus freshness (possivelDesatualizacao) is computed from the last status='ok' run and uses a larger window (ECIDADANIA_CORPUS_STALE_MAX_MIN), and a stale consultas corpus is served from D1 flagged rather than collapsing back to the live highlights.

Write guards on the load: an incomplete crawl (any page failed) or an incomplete /processo status universe writes only an erro run row; even a complete crawl is rejected by a catastrophic floor (ECIDADANIA_CORPUS_MIN_PCT, default 80% of the last good corpus) to guard against a degraded page — overridable with --force / INGEST_FORCE=1 for a legitimate large shrink. Run daily via the Action, or manually:

CLOUDFLARE_API_TOKEN=… npm run ingest:ecidadania                 # writes scripts/ingest-ecidadania/out.sql
npx wrangler d1 execute senado-ecidadania --remote --file=scripts/ingest-ecidadania/out.sql

Caching

Layer architecture

Layer

Storage

Scope

TTL range

Purpose

L0

In-memory Map

Per-isolate

30-300s

Ultra-fast, eliminates redundant requests within a Worker isolate

L1

Cloudflare Cache API (caches.default)

Per-colo (PoP)

60-600s

Shared across requests at the same edge location

L2

KV (optional)

Global

Variable

Reserved for rare, low-write data

Cache categories

Category

L0 TTL

L1 TTL

Used for

STATIC

300s

600s

Legislation types, static reference

SEMI_STATIC

120s

300s

Party list, UF list, committee details

DYNAMIC

30s

60s

Agendas, recent votes, meeting lists

ON_DEMAND

30s

120s

Specific bill/senator/vote lookups

POST caching approach

MCP uses POST for all tools/call requests. Caching POST responses is not natively supported by the Cache API, which requires GET requests. The solution:

  1. Hash parameters — Tool name + sorted parameters are hashed with SHA-256

  2. Synthetic GET key — A synthetic URL https://senado-br-mcp.internal/__cache/{tool}/{hash} is constructed

  3. Cache API match/put — The synthetic GET URL is used with caches.default.match() and caches.default.put(), allowing standard Cache API operations on POST-originated data

This caching happens at the tool level (inside each tool's callback), not at the MCP transport level.

Provenance

Every tool attaches a provenance envelope so a result is traceable back to its official source — provenance is treated as a first-class part of the answer, not an optional extra (the audience is journalists and political-science researchers, for whom an un-sourced figure is unusable). The envelope implements the portfolio-wide provenance contract (@sbissoli/mcp-provenance): the server builds and validates a full canonical model per response, and emits its concise projection — a fixed-order block with explicit null for unknown fields; responses that merge several upstream reads also list each part with its own extraction instant (field_sources), and the block's retrieved_at is then the oldest of them. The block lives in structuredContent.provenance (parseable by clients; note the advertised per-tool output schema is permissive, so contract validation happens server-side at build time, in the package) and is mirrored as a compact source footer in the text content for clients that only render text — the data JSON itself is not duplicated with the envelope, to keep the per-response token cost low.

Coverage spans all four upstream sources, each with its own source/citation/license (in src/utils/provenance.ts):

  • Senado Federal — Dados Abertos (Legislativo) — legis.senado.leg.br/dadosabertos

  • Senado Federal — Dados Abertos (Administrativo) — adm.senado.gov.br/adm-dadosabertos

  • Senado Federal — Execução Orçamentária e Financeira — Arquimedes/Financeiro feed at senado.gov.br

  • Senado Federal — Portal e-Cidadania — www12.senado.leg.br/ecidadania

Fields of the concise block (contract v1.3 since 3.18.5; per response — one tool, one source; keys in this fixed order; the first seven are always present, with null when the source does not expose the value; the optional ones are absent, never empty, when they do not apply):

Field

Meaning

source

Official source name (e.g. Senado Federal — Dados Abertos (Legislativo))

source_url

Canonical endpoint/item URL consulted (e.g. …/processo/{id})

data_vintage

Vintage/competência of the data (e.g. 2024-03-15, 2019) — named reference_period before v3.5.0

retrieved_at

ISO-8601 of the upstream extraction — carried through the cache, so it reflects when the data was actually fetched, not the build or the cache-hit time; on merged responses, the oldest of the parts

retrieval

Measured diagnostics of the trip to the source (attempts, outcome), or null when nothing was fetched in the call (pure cache, local data) — since 3.11.0 (v1.1)

citation

Ready-to-use citation string (human-readable)

license

Source terms (Dados Abertos do Senado Federal)

field_sources

Optional. Per-field sub-sources, each with its own extraction instant — only on responses that merge reads (v1.2, since 3.17.0; see below)

derived / derivation_note

Optional. true + a fixed pt-BR note naming the calculation whenever the server computed values instead of copying them (since 3.19.0, the whole class): the estatisticas modes (distribution, aggregates, rankings); group sums, counts and averages — CEAPS valorTotal and its per-senator/type/month/supplier modes, the budget execution aggregates (por-ano, the default, included), the payroll resumo, the overtime valorTotal, the relatoria distribution, seated senators per party/UF, the historical e-Cidadania national totals; the payroll gross (bruto, sum of seven components); servants assigned to an org subtree (subordinadasA); a vote tally counted from nominal votes when the source publishes none (plenary open roll calls, committee votes without totals); e-Cidadania percentages, consensus/polarisation rankings and the estimated idea creation date; the current legislature's period. Absent when every number is the source's own (raw lists, detalhe of the budget, published tallies). The individual values cited remain the Senate's

revision

Whether the figure may still change at the source: status is current for every Senate source (the version in force at extraction; none is claimed final), and note says, for the administrative and budget sources, that the Senate may correct published data later

No Senate source publishes notices alongside the data, so notices (also part of v1.3) does not appear. The text footer gains a line only for exceptions — here, the computed-values line on the estatisticas modes.

The canonical model behind the block also carries dataset.id (item/series identifier, e.g. codigoMateria=137808) and api_version; those are validated on every build and inform attribution (below), but are not part of the concise projection.

In addition to the provenance envelope, structuredContent carries a top-level attribution list — the distinct source URLs behind the response. This mirrors the naming proposed in modelcontextprotocol#711 (where attribution is a list of source references at the response level), so the server stays forward-compatible if that RFC lands; the richer provenance object remains this server's own extension.

Out-of-band mirror in _meta. The same provenance and attribution are also mirrored on the result's _meta under namespaced keys (com.sidneybissoli.senado/provenance and com.sidneybissoli.senado/attribution). The MCP spec keeps _meta for metadata about a result that should not steer the model, which is where the still-incubating trust/attribution work from #711 (split into an experimental extensions track, not yet in core) points; mirroring there gives audit and UI consumers the provenance without reading the model-facing data channel, at no model-token cost, while structuredContent keeps it visible so the model can cite the source. The mirror survives the ChatGPT-app profile minimizer (which only strips structuredContent.meta).

Field-level granularity. Most tools are single-source, so one envelope suffices. The few that merge reads in one response fill field_sources — a list of { fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache } attributing specific output fields to their real origin, and the block's retrieved_at is the oldest of them. served_from_cache is true/false for reads through the server cache and null where the notion does not apply (the bundled org-chart snapshot, the e-Cidadania corpus in D1). The merging tools (since 3.18.2): senado_obter_materia secao=detalhe (/processo/{id} + ementa from /processo + relator from /processo/relatoria), senado_obter_senador and the Deep Research fetch of a senator (biography + mandatos/emExercicio from /senador/{codigo}/mandatos), senado_servidores with subordinadasA (payroll + org-chart snapshot), senado_suprimento_fundos statistics on atos-concessao (acts + beneficiary names from the supridos registry), senado_ecidadania_obter_evento (live detail + comentarios from the corpus), senado_listar_senadores with legislatura (since 3.24.0: the legislature list + emExercicio from /senador/lista/atual) and senado_ecidadania_sugerir_tema_enquete (consultas and ideias corpora). Only a read that becomes a field of the answer is a sub-source: a read that only resolves or checks an identifier (a committee acronym → its code, the parent check in senado_contratacao_detalhe) is left out, otherwise a cached lookup table would make the whole answer claim to be as old as it. attribution always lists every distinct underlying source_url.

retrieved_at fidelity is provided by the cache layer (cachedFetchWithMeta), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania list tools (read from D1) use the corpus's lastScrapedAt — the true age of the stored data, or the live scrape instant when the corpus is empty or stale and the list falls back to the portal (since 3.18.3; before, the stale corpus's instant leaked into the live answer) — while e-Cidadania detail tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (senado_tabelas_referencia tipos-materia), which has no upstream extraction instant.

Coverage is universal: all 69 tools carry the envelope — the 67 senado_* tools via resultWithProvenance( (verify with grep -c 'resultWithProvenance(' src/tools/*.ts) and the two Deep Research tools via provenanceExtras (same block, in structuredContent/_meta, since their text channel is the contract's JSON). The ⊕ marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.

Citable dataset (e-Cidadania participation)

Beyond the live server, this project publishes a frozen, versioned, citable dataset of the e-Cidadania participation layer (public consultations, legislative ideas, interactive events + their comments, historical votes by state) — the layer the R package congressbr never covered. Each value carries a per-field provenance envelope ({ value, sourceEndpoint, sourceField, retrievedAt, license, schemaVersion }); the data license (Dados Abertos do Senado Federal) is kept separate from the code license (MIT).

  • How to cite — CITATION.cff (dataset; cite the version-DOI of the snapshot you used, the concept-DOI for the dataset across versions).

  • What's in each release — CHANGELOG-dataset.md (cumulative, append-only; binds each release to its schemaVersion).

  • Variable dictionary & field provenance — docs/dataset-dictionary.md (generated from src/dataset/schema.ts, the single source of truth).

  • Data license — LICENSE-DATA.md.

  • Cutting a release (freeze → checksums → GitHub Release → Zenodo DOI) — docs/release-runbook.md; machinery in src/dataset/, scripts/build-dataset/, and .github/workflows/release-dataset.yml.

Inventory — schema v2 (schemaVersion 2.0.0)

Each release ships one NDJSON resource per entity (one HarmonizedRecord per line: identity + a provenance envelope per field), plus a datapackage.json manifest and a copy of the dictionary. Five resources:

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ⁿ (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)

ⁿ = new/reopened in v2 · ᶜ = source corrected to the canonical one in v2. What v2 (2.0.0) changed — the ingestion moved from listing-only to listing + detail (+ AJAX comments for events):

  • Eventos corrected & enriched. data/hora now come from the detail page (canonical — the estudo A3 found the listing 57% divergent on hora), plus six new detail fields (comissaoNomeCompleto, local, descricao, pauta, convidados, videoUrl). comentarios is now the canonical AJAX count (the listing count was 0-spurious in 82% of events, capturing only ~6.7% of engagement).

  • New comment-level resource eventos_comentarios — one row per audiência comment, the participation signal nobody else publishes versioned.

  • Detail-only fields reopened for ideias (dataPublicacao, autorUf, descricao, plConvertido) and consultas (autoria, relator) — previously always null by design.

  • Privacy posture by data origin. Citizen content (audiência comments, idea authors) keeps UF only — never the name, discarded at the parser; public agents (consulta authorship/rapporteur, event guests) keep the name (public by function). See docs/schema-v2-inventario.md for the field-by-field rationale (approved target).

The frozen NDJSON is not committed (built from the sovereign D1 corpus on demand); a tagged dataset-v* release attaches the tarball + SHA256SUMS + release.json and archives them on Zenodo.

Tool Inventory

Group H — Reference/Metadata (1 tool)

Tool

Description

senado_tabelas_referencia

Tabelas de referência via tabela enum: tipos-materia, partidos, ufs, legislatura-atual, tipos-norma, tipos-uso-palavra

Group A — Senators (5 tools)

Tool

Description

senado_listar_senadores

Lista senadores em exercício, fora de exercício (emExercicio: false) ou por legislatura, com filtros nome (busca parcial sem acento), uf e partido

senado_obter_senador

Detalhe biográfico de um senador: bio, mandatos, partido, contato

senado_votacoes_senador ⊕

Como um senador votou em cada matéria (via v3 /votacao)

senado_senador_historico

Histórico funcional via tipo enum: licencas, comissoes, cargos, historico-academico, filiacoes, profissoes

senado_senadores_afastados

Senadores atualmente afastados (fora de exercício)

Group B — Bills/Matters (2 tools, v3 backend)

Tool

Description

senado_buscar_materias ⊕

Busca matérias por tipo, número, ano, palavra-chave, autor ou tramitação (via v3 /processo)

senado_obter_materia ⊕

Dados de uma matéria via secao enum: detalhe (situação/relator), tramitacao (histórico) ou textos (documentos)

Group C — Processes (5 tools)

Tool

Description

senado_search_processos ⊕

Busca processos legislativos (complementar à busca de matérias)

senado_obter_processo ⊕

Detalhes completos de um processo legislativo específico

senado_processo_detalhe

Aspecto de um processo via secao enum: emendas, relatorias ou prazos

senado_autores_atuais

Parlamentares autores de processos em tramitação, ordenados por produção

senado_tabelas_processo

12 tabelas de referência (siglas, assuntos, classes, tipos-*) via tabela enum

Group D — Votes (3 tools)

Tool

Description

senado_obter_votacao ⊕

Detalhes de uma votação com votos nominais. Aceita codigoVotacao (codigoSessao da sessão plenária).

senado_votos_materia ⊕

Votações de uma matéria (via v3 /votacao?codigoMateria), com votos nominais opcionais

senado_search_votacoes ⊕

Busca/listagem flexível de votações do plenário por dias, período, processo, matéria ou senador

Group E — Committees (7 tools)

Tool

Description

senado_listar_comissoes

Lista comissões (colegiados) ativas, filtráveis por tipo

senado_obter_comissao

Dados de uma comissão via secao enum: resumo (mesa/totais) ou membros (composição). Resolve sigla para código internamente.

senado_reunioes_comissao

Reuniões de uma comissão num período de até 30 dias (lida dia a dia; o que é depois de hoje vem à parte, como agenda prevista)

senado_agenda_comissoes

Agenda de reuniões de todas as comissões numa data

senado_reuniao_comissao

Detalhe completo de uma reunião: partes, itens, convidados, resultados, links pauta/ata

senado_requerimentos_cpi

Requerimentos protocolados numa CPI em atividade, paginados (upstream costuma vir vazio mesmo para CPIs ativas; retorno vazio traz aviso)

senado_distribuicao_materias

Estatísticas de carga por senador numa comissão: autoria ou relatoria

Group F — Plenary (7 tools)

Tool

Description

senado_agenda_plenario

Plenary schedule — by day, month or Congress (escopo dia/mes/cn)

senado_resultado_plenario

Session results: items deliberated, opinions, outcomes (SF/CN/month)

senado_orientacao_bancada

Party leadership voting instructions per vote, with tallies

senado_vetos

Presidential vetoes by year or tramitation status

senado_resultado_veto

Nominal veto vote results (by veto, vetoed bill or device)

senado_encontro_plenario

Legislative session detail, agenda items, results or summary

senado_tabelas_plenario

Session types, attendance types, legislatures list

Group G — e-Cidadania (9 tools)

Tool

Description

senado_ecidadania_listar_consultas

Consultas públicas (conjunto completo das abertas — matérias em tramitação) com votação sim/não; filtro status (padrão aberta)

senado_ecidadania_obter_consulta

Detalhe de uma consulta: votos, autor, relator, comentários

senado_ecidadania_consultas_analise

Analisa o conjunto completo de consultas abertas via modo (consenso/polarizada); status padrão aberta

senado_ecidadania_listar_ideias

Ideias legislativas de cidadãos; ranking das mais apoiadas via ordenarPor: apoios

senado_ecidadania_obter_ideia

Detalhe de uma ideia: texto, apoios, data em que foi proposta, linha do tempo (meta, Sugestão, decisão da CDH, encerramento) e proposições em que virou

senado_ecidadania_listar_eventos

Eventos interativos (audiências, sabatinas, lives); ranking dos mais comentados via ordenarPor

senado_ecidadania_obter_evento

Detalhe de um evento: pauta, convidados, link de vídeo

senado_ecidadania_sugerir_tema_enquete

Sugere temas para enquete mensal a partir de critérios configuráveis

senado_ecidadania_consultas_votos

Acervo histórico de votos das consultas com quebra por UF (CSV Arquimedes); ranking por total/sim/nao, filtro uf/materia

Group I — Speeches (3 tools)

Tool

Description

senado_discursos_senador

Pronunciamentos de um senador via tipo enum: discursos (próprios) ou apartes (intervenções)

senado_discursos_plenario

Todos os discursos em plenário num intervalo de datas

senado_discurso_texto

Texto integral de um pronunciamento/discurso específico

Group J — Blocs & Leadership (4 tools)

Tool

Description

senado_listar_blocos

Blocos parlamentares do Senado e seus partidos membros

senado_obter_bloco

Detalhes de um bloco parlamentar específico

senado_liderancas

Lideranças do Senado/Câmara/Congresso (líderes, vice-líderes) com o bloco/partido liderado, filtráveis

senado_mesa

Membros da Mesa Diretora via casa enum: senado (Mesa do SF) ou congresso (Mesa do CN)

Group K — Budget (1 tool)

Tool

Description

senado_orcamento_parlamentar

Emendas parlamentares ao orçamento via tipo enum: emendas (lotes por autor) ou oficios (indicação de destino — filtrável por ano da emenda, paginado, incluirEmendas opcional)

Group L — Federal Law (2 tools)

Tool

Description

senado_buscar_legislacao

Busca normas jurídicas federais por tipo, número, ano ou data (ao menos um obrigatório)

senado_obter_legislacao

Detalhes de uma norma jurídica federal específica

Group M — Committee Voting (1 tool)

Tool

Description

senado_votacao_comissao

Votações em comissões via por enum: comissao, senador ou materia; período opcional

Group N — Taquigrafia (2 tools)

Tool

Description

senado_notas_taquigraficas

Official transcripts of plenary sessions or committee meetings — summary mode with excerpts, full-text mode paginated in blocks, speaker filter

senado_videos_taquigrafia

Video/audio units per session or meeting, with speaker and media links

Group O — Senadores/Administrativo (2 tools)

Tool

Description

senado_ceaps

CEAPS parliamentary quota expenses by year — aggregated by senator, expense type, month or supplier, or itemized detail; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a group ranking by total spend via agruparPor (senator/type/month/supplier) with topN; filters by senator/month/type/supplier

senado_senadores_admin

Dados administrativos dos senadores via tipo enum: auxilio-moradia, escritorios-apoio ou aposentados

Group P — Servidores / Gestão de Pessoas (4 tools)

Tool

Description

senado_servidores

Civil servants by status (active/effective/commissioned/inactive), filterable by name, unit, position

senado_remuneracoes_servidores

Monthly payroll — summary by payroll type or per-person composition with computed gross; estatisticas=true returns whole-payroll stats (min/max/mean/median/percentiles) + top/bottom ranking, with campo, consolidarPorServidor, agruparPor and topN

senado_horas_extras

Overtime payments by month with totals; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a per-servant ranking by summed value via agruparPor (name/competência), with topN

senado_pessoal_tabelas

Tabelas de pessoal via tabela enum: quantitativos (pessoal, cargos-funcoes, previsao-aposentadoria, senadores) e listas (estagiarios, pensionistas, lotacoes, cargos)

Group Q — Contratações (6 tools)

Tool

Description

senado_contratos

Contracts filtered in-Worker over the full base (accent-insensitive): supplier, CNPJ, year, number, object, labor

senado_contratacao_detalhe

Items, payments, guarantees, amendments or activations of a contract/ata/empenho

senado_licitacoes

Biddings by number or object text

senado_terceirizados

Outsourced collaborators by name, company or unit

senado_empresas_contratadas

Companies contracting with the Senate (requires name/CNPJ filter)

senado_contratacoes_lista

Price-registration atas, commitment notes, young apprentices

Group R — Suprimento de Fundos (1 tool)

Tool

Description

senado_suprimento_fundos

Petty-cash advances by year: recipients, concession acts, commitments, movements, card transactions; estatisticas=true (tipo transacoes/empenhos/atos-concessao) returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a ranking by summed value via agruparPor (e.g. supplier), with contextual campo and topN

Group S — Orçamento do Senado (1 tool)

Tool

Description

senado_execucao_orcamentaria

Budget execution since 2013 (allocation, committed/settled/paid) and own revenues since 2012 (forecast vs collected) — aggregated by year, action, expense group, source or revenue origin; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a group ranking by summed campo via agruparPor, with campo (default paid / collected) and topN

Group T — Estrutura Organizacional (1 tool)

Reads a bundled snapshot of the Senate's organizational tree (crawled from the institutional portal down to serviço level by npm run ingest:estrutura), since the open-data API only publishes units down to Secretaria and never links a leaf unit to its parent. Units the portal lists only by name, without a page of their own (the CONLEG/CONORF núcleos), are captured as synthetic nodes from the page's indented listing. Congress-wide bodies where the servant registry records lotações (CMO, CPCMS, CMMC) come from a curated complement (src/estrutura/complemento-cn.ts, public source: congressonacional.leg.br) under a separate Congresso Nacional root (CN) — never under the Senate tree, so subordinadasA: "DGER" excludes them while subordinadasA: "CN" counts them. Servants recorded under the situational pseudo-units "Servidores Afastados/em Trânsito - SF" are reported separately as afastadosOuEmTransito by senado_servidores.

Tool

Description

senado_estrutura_organizacional

Organizational chart (organograma) resolved for a unidade (sigla like DGER or name): returns its caminho (ancestors) and every subordinate unit (subordinadas[] — secretarias, coordenações, serviços, núcleos — with nivel). Pairs with senado_servidores's subordinadasA filter, which counts/lists all servants under a whole directorate (a servant sits in a leaf serviço, so filtering lotacao by the parent sigla returns 0).

Group U — Deep Research (2 tools)

The OpenAI Deep Research contract: the only two tools without the senado_ prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, the shared output envelope — open data plus required provenance + attribution —, per-tool telemetry) and served on /mcp only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the senado_listar_* tools read, and kept for 24 h.

Tool

Description

search

Ranks the query (natural language or keywords, pt/en, accent-insensitive) against senators in office and active committees; returns up to 10 { id, title, url } — sen:<código> with the public profile URL, com:<código> with the public committee page. Provenance of both lists in structuredContent/_meta.

fetch

Returns the document for an id from search as { id, title, text, url, metadata }: the senator's biography and mandates (same read as senado_obter_senador) or the committee's summary and board (same read as senado_obter_comissao), as Markdown, with that read's provenance. Unknown id → error.

Total: 69 tools

Prompts (4)

Reusable pt-BR workflow templates (MCP prompts capability), defined in src/prompts.ts:

Prompt

Args

What it guides

senado_gastos_senador

senador, ano

Resolve o senador e agrega/detalha despesas CEAPS.

senado_tramitacao_materia

sigla, numero, ano

Obtém situação atual + histórico de tramitação da matéria.

senado_votos_senador

senador, periodo?

Lista os votos nominais do senador no período.

senado_panorama_ecidadania

—

Consolida consultas (consenso/polarização), ideias e eventos populares.

Resources (5)

Static context documents/tables (MCP resources capability), defined in src/resources.ts:

URI

Type

Content

senado://guia

markdown

Visão geral e qual ferramenta usar por objetivo.

senado://catalogo

markdown

As 69 ferramentas agrupadas por domínio.

senado://glossario

markdown

Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…).

senado://tabelas/tipos-materia

json

Tipos de proposição (sigla/nome/descrição).

senado://tabelas/ufs

json

As 27 unidades federativas.

Project Structure

src/
├── index.ts              # Worker entrypoint (fetch handler + scheduled/Cron handler)
├── server.ts             # McpServer factory (creates per-request instance)
├── auth.ts               # Optional Bearer token auth (constant-time compare)
├── metrics.ts            # In-memory counters served at /metrics
├── types.ts              # Env, cache categories, safeguard constants
├── cache/
│   ├── l0-memory.ts      # In-memory Map cache with TTL + LRU eviction
│   ├── l1-cache-api.ts   # Cloudflare Cache API wrapper (synthetic GET keys)
│   └── manager.ts        # Cache orchestrator (L0 → L1 → upstream)
├── throttle/
│   ├── token-bucket.ts   # Token bucket rate limiter (global + per-client)
│   └── upstream.ts       # Upstream fetch with concurrency limit, retry, timeout
├── scraper/
│   ├── ecidadania.ts     # Isolated e-Cidadania scraper (REST lists + regex HTML detail; buildConsultaResumo)
│   ├── pipeline.ts       # 2h Cron: targeted highlight metric splice (consultas/eventos/ideias); corpora owned by the off-Worker jobs
│   ├── anomaly.ts        # Run classification (anomalous run never overwrites current)
│   └── store.ts          # D1 reads (resolveList + per-entity staleness, lastGoodRunAt) + detail write-through
├── instrument.ts         # Per-tool call telemetry (in-memory + Analytics Engine)
├── utils/
│   ├── logger.ts         # Structured JSON logging
│   └── validation.ts     # toolResult, toolError, errorFrom, buildParams, ensureArray helpers
└── tools/
    ├── referencia.ts        # Group H — 1 reference/metadata tool
    ├── senadores.ts         # Group A — 5 senator tools
    ├── materias.ts          # Group B — 2 bill/matter tools (v3 backend)
    ├── processos.ts         # Group C — 5 process tools
    ├── votacoes.ts          # Group D — 3 vote tools
    ├── comissoes.ts         # Group E — 7 committee tools
    ├── plenario.ts          # Group F — 7 plenary tools
    ├── ecidadania.ts        # Group G — 8 e-Cidadania tools (read from D1; see scraper/)
    ├── discursos.ts         # Group I — 3 speech tools
    ├── composicao.ts        # Group J — 4 bloc/leadership tools
    ├── orcamento.ts         # Group K — 1 budget tool
    ├── legislacao.ts        # Group L — 2 federal law tools
    ├── votacao-comissao.ts  # Group M — 1 committee voting tool
    ├── taquigrafia.ts       # Group N — 2 stenographic record tools
    ├── senadores-admin.ts   # Group O — 2 admin senator tools (CEAPS, housing)
    ├── servidores.ts        # Group P — 4 personnel tools
    ├── contratacoes.ts      # Group Q — 6 procurement tools
    ├── supridos.ts          # Group R — 1 petty-cash tool
    ├── orcamento-senado.ts  # Group S — 1 budget execution tool
    └── estrutura.ts         # Group T — 1 org-structure tool (reads src/data/ snapshot via src/estrutura/)
scripts/
└── ingest-ecidadania/    # Off-Worker full-corpus consultas ingestion (run via `npm run ingest:ecidadania`)
    ├── index.ts          # Orchestrator: crawl → status (/processo) → normalize → guards → out.sql
    ├── listing.ts        # Pure listing parser (parseConsultaListingPage, findLastPage)
    ├── status.ts         # tramitando=S set from /processo → aberta/encerrada (deriveStatus)
    ├── restatus.ts       # Linger fix: re-status stored rows by /processo membership (close zombies)
    ├── http.ts           # Polite fetch (retry/backoff) for the unattended crawl
    ├── d1.ts             # D1 pre-reads (existing meta, payloads, last good rows) via wrangler
    ├── verify.ts         # consultas_votos on-demand integrity-check verdict (verifyAcervoIntegrity)
    └── sql.ts            # out.sql generation (mirrors SQL.upsert/SQL.history; reuses SyncRecord)
.github/workflows/        # ingest-ecidadania.yml (daily D1 corpus load), verify-consultas-votos.yml
                          # (weekly frozen-acervo integrity check), publish-mcp.yml (registry),
                          # usage-report.yml (monthly Analytics report), deprecate-registry.yml
                          # (all pinned to current Node 24 action majors — see each YAML for exact versions)
migrations/               # D1 schema (0001 tables, 0002 indexes, 0003 comment level + detail cursor) for the e-Cidadania pipeline
tests/                    # Vitest unit tests mirroring src/ (parsers, cache, throttle, auth, scraper,
                          # pipeline/anomaly/store, listing/sql/highlights, plus e-Cidadania contract tests)

Environment Variables

Variable

Required

Default

Description

SENADO_BASE_URL

No

https://legis.senado.leg.br/dadosabertos

Legislative API base URL

SENADO_ADM_BASE_URL

No

https://adm.senado.gov.br/adm-dadosabertos

Administrative API base URL

ALLOWED_ORIGIN

No

*

CORS allowed origin

API_KEY

No (secret)

—

When set, requires Authorization: Bearer <key> on all requests except /health, /metrics, and CORS preflight

CACHE_KV

Yes (binding)

—

KV namespace for L2 cache

ECIDADANIA_DB

Yes (binding)

—

D1 database for the e-Cidadania pipeline (list persistence + history)

ECIDADANIA_CORPUS_STALE_MAX_MIN

No

14400

Staleness window (minutes, ~10d) for the off-Worker full corpora (all e-Cidadania entities) — served flagged, never collapsed to highlights

ECIDADANIA_CORPUS_MIN_PCT

No

80

Catastrophic floor for the off-Worker corpus jobs: a complete crawl/parse below this % of the last good corpus is rejected

CLOUDFLARE_API_TOKEN

No (secret)

—

GitHub Actions secret (D1 edit scope) for the corpus ingestion / integrity-check jobs; not used by the Worker

CLOUDFLARE_ACCOUNT_ID

No (Actions var)

—

GitHub Actions repo variable so wrangler skips /memberships account auto-discovery (a D1-scoped token can't read it); required alongside CLOUDFLARE_API_TOKEN in the ingestion job

SENADO_ANALYTICS

No (binding)

—

Analytics Engine dataset for per-tool call telemetry

Connecting MCP Clients

This is a remote server (Streamable HTTP, no install, open access) — point any MCP client at https://senado.sidneybissoli.com/mcp. Besides 69 tools, it exposes prompts (ready-made pt-BR workflows: senado_gastos_senador, senado_tramitacao_materia, senado_votos_senador, senado_panorama_ecidadania) and resources (senado://guia, senado://catalogo, senado://glossario, senado://tabelas/tipos-materia, senado://tabelas/ufs).

One-click (LobeHub)

Install from the LobeHub marketplace — open the server page and click Install (it pre-fills the remote endpoint, no config needed).

Claude Desktop / Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "senado-br": {
      "url": "https://senado.sidneybissoli.com/mcp"
    }
  }
}

For command-based clients (or any client without native remote support), use the mcp-remote bridge:

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://senado.sidneybissoli.com/mcp"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector https://senado.sidneybissoli.com/mcp

License

MIT

Credits

Icon: "Amanhecer no Congresso Nacional" — photograph of the Brazilian National Congress, used under a Creative Commons license. (If you are the author, open an issue so we can add full attribution / the license link.)

Available Tools

69 tools
fetchDocumento para Deep ResearchA
Read-onlyIdempotent
Inspect

Returns the full document for an id obtained from search, as { id, title, text, url, metadata }: text is the readable content (Markdown) and url the canonical public page to cite.

Companion of search in the OpenAI Deep Research contract, over the Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress) catalog. Only ids returned by search are valid; an unknown id returns an error. The senado_* tools remain the tools for data queries.

Behavior: read-only and idempotent — a live GET against the public source when the document needs it.

Inputs: id (required). Returns: provenance, attribution

senado_agenda_comissoesAgenda das comissõesA
Read-onlyIdempotent
Inspect

Obtém a agenda de reuniões de todas as comissões numa data (data YYYYMMDD; padrão: hoje), com filtro opcional siglaComissao. Retorna { data, siglaComissao, count, reunioes }, cada reunião com codigo, comissao (sigla, nome), descricao, data, hora, local, tipo e situacao. Para o histórico de uma única comissão por período use senado_reunioes_comissao; para detalhes de uma reunião use senado_reuniao_comissao com o codigo.

Inputs: data, siglaComissao. Returns: provenance, attribution

senado_agenda_plenarioAgenda do plenárioA
Read-onlyIdempotent
Inspect

Obtém a agenda de sessões de plenário (Senado ou Congresso Nacional), por dia ou mês, com a pauta de matérias a votar. Retorna { data, escopo, count, sessoes }, onde cada sessão traz codigo, data, hora, tipo, situacao e pauta (matéria, ementa, autor, parecer). Use escopo dia/mes/cn; sem data assume hoje. Para o resultado já apreciado use senado_resultado_plenario; detalhes de uma sessão via senado_encontro_plenario.

Inputs: data, escopo, dataFim. Returns: provenance, attribution

senado_autores_atuaisAutores em exercícioA
Read-onlyIdempotent
Inspect

Lista parlamentares autores de processos em tramitação, ordenados por produção (maior número de matérias primeiro). Atenção à semântica: 'atual' significa 'com processo AINDA EM TRAMITAÇÃO', não 'mandato vigente' — a lista mistura senadores, deputados e ex-parlamentares, e a mesma pessoa pode aparecer 2× com códigos distintos (ex.: como 'Senador' e como 'Deputado', pelo tratamento); não use como lista de senadores em exercício (para isso, senado_listar_senadores). Retorna { count, total, autores }, cada autor com codigo, nome, tratamento, uf e quantidadeMaterias. Filtros opcionais uf e nome (busca parcial sem acento); limite padrão 50 (máx. 1000). Use o codigo em senado_obter_senador ou senado_search_processos (codigoParlamentarAutor).

Inputs: uf, nome, limite. Returns: provenance, attribution

senado_buscar_legislacaoBuscar legislação federalA
Read-onlyIdempotent
Inspect

Busca normas jurídicas federais já promulgadas (leis, decretos, leis complementares, emendas constitucionais etc.) combinando os filtros tipo, numero, ano e data em modo AND; informe ao menos um: uma chamada sem nenhum filtro retorna erro determinístico, não uma lista vazia. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos, cujos resultados podem variar entre chamadas. Retorna { count, normas } sem paginação: count é o total de normas que casam (0, sem erro, quando nenhuma casa) e cada item traz codigo, tipo, descricaoTipo, numero, ano, data (ISO AAAA-MM-DD), norma, ementa e apelido, com null nos campos ausentes. Passe o codigo a senado_obter_legislacao para obter a indexação temática e a URL do texto integral. Para proposições ainda em tramitação (PEC, PL, PLP, MPV) use senado_buscar_materias; esta ferramenta cobre apenas normas já promulgadas.

Inputs: ano, data, tipo, numero. Returns: provenance, attribution

senado_buscar_materiasBuscar matérias legislativasA
Read-onlyIdempotent
Inspect

Busca matérias legislativas por tipo (PEC, PL, PLP, MPV), número, ano, palavras-chave, autor, período de apresentação ou situação de tramitação; informe ao menos um critério. Para pedidos como 'matérias recentes sobre X', use palavraChave, ano ou dataInicioApresentacao/dataFimApresentacao, ordenarPor: 'dataApresentacao', ordem: 'desc' e limite baixo (ex: 10); não é necessário chamar detalhes para listar resultados. Retorna { count, total, materias[] }, cada item com codigo (codigoMateria), sigla, numero, ano, ementa, autor, situacao, dataApresentacao, url e tramitando. Use codigo em senado_obter_materia apenas quando o usuário pedir detalhe/tramitação/textos. limite padrão 100 (máx. 500); ao truncar inclui aviso. Ex.: { palavraChave: 'inteligência artificial', ano: 2025, limite: 10 } ou { sigla: 'PEC', numero: 45, ano: 2019 } (datas em YYYYMMDD ou ISO).

Inputs: ano, ordem, sigla, limite, +7 more. Returns: provenance, attribution

senado_ceapsGastos CEAPS (cota parlamentar)A
Read-onlyIdempotent
Inspect

Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. A fonte também publica lançamentos NEGATIVOS, sem rótulo próprio (a maioria em passagens aéreas, com jeito de crédito ou estorno): eles entram nas somas e totais como desconto e, nas estatísticas, aparecem como mínimo e no bottom — não leia um valor negativo como erro nem como 'a menor despesa'. Para perguntas de maior/menor/média/mediana/distribuição/ranking ('quem gastou mais CEAPS', 'gasto mediano', 'distribuição das despesas') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre TODAS as despesas filtradas e devolve top/bottom (padrão 10) com identificadores — os modos agregados só somam por grupo e não revelam a distribuição nem o extremo individual. Sem agruparPor → distribuicao das despesas individuais + top/bottom; com agruparPor (senador/tipo/mes/fornecedor) → grupos[] ranqueados por soma decrescente (grupos[0] = maior gastador), cada um com sua mini-distribuição. Sem estatisticas: nos modos agregados (por-senador/por-tipo/por-mes/por-fornecedor, padrão por-senador) traz agregado[] ordenado por total desc com chave, total e despesas (contagem); em modo='detalhe' traz despesas[] (mês, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor). Filtre por mes, codSenador, nomeSenador, tipoDespesa ou fornecedor (busca parcial); limite cap 100 com aviso ao truncar. Obtenha codSenador via senado_listar_senadores.

Inputs: ano (required), mes, modo, topN, +7 more. Returns: provenance, attribution

senado_contratacao_detalheDetalhar contrataçãoA
Read-onlyIdempotent
Inspect

Detalha uma seção específica de uma contratação já identificada pelo id. tipo indica a natureza do registro: contratos (contrato firmado; padrão), atas_registro_preco (compromisso de preços para compras futuras) ou notas_empenho (reserva orçamentária do gasto). secao escolhe o aspecto: itens, pagamentos, garantias (qualquer tipo), aditivos (só contratos) ou acionamentos (só atas_registro_preco). Retorna { id, tipo, secao, count, total, itens } com os registros brutos da seção (campos conforme a API administrativa), limitados a limite (padrão 100, máx 500) — count < total indica truncagem; seção sem registros retorna count 0 e itens vazio (o id é conferido na lista-pai antes, então count 0 significa mesmo seção vazia, não contratação inexistente); id que não existe e combinações secao×tipo inválidas (ex.: aditivos fora de contratos) retornam erro. Atenção: a fonte NÃO publica o valor do contrato em nenhuma seção; apenas aditivos traz valor, referente ao termo aditivo (às vezes nulo) — não procure valor monetário em itens/pagamentos/garantias. Obtenha o id via senado_contratos ou senado_contratacoes_lista — para localizar a contratação (não detalhá-la) use aquelas ferramentas.

Inputs: id (required), secao (required), tipo, limite. Returns: provenance, attribution

senado_contratacoes_listaListar contrataçõesA
Read-onlyIdempotent
Inspect

Lista, conforme tipo, atas de registro de preço, notas de empenho ou menores aprendizes do Senado, com filtro textual opcional aplicado no Worker sobre todos os campos. Retorna { tipo, count, total, registros }; para atas_registro_preco/notas_empenho cada registro segue o formato de contrato (id, numero, objeto, empresa, subEspecie, vigencia...), enquanto menores_aprendizes vêm como registros brutos da API (campos não normalizados). Ordenação por ordem sobre a sequência de id do upstream: desc (padrão) = mais recentes primeiro, asc = mais antigos primeiro; offset pula registros para paginar a cauda. Limitado a limite (padrão 50, máx 500), com aviso ao truncar; tipo sem registros retorna lista vazia. Para aprofundar uma ata/empenho, use o id em senado_contratacao_detalhe.

Inputs: tipo (required), ordem, filtro, limite, +1 more. Returns: provenance, attribution

senado_contratosContratos do SenadoA
Read-onlyIdempotent
Inspect

Busca contratos administrativos do Senado por fornecedor, CNPJ, ano, número, objeto ou mão de obra (base completa baixada e filtrada no Worker; busca parcial sem acento em objeto/fornecedor/número). Retorna { count, total, contratos }, onde cada item traz id, numero, objeto, empresa {nome, cnpj}, subEspecie, dataAssinatura, vigencia e unidadeGestora. Atenção: a fonte NÃO publica o valor do contrato (nenhum campo monetário aqui nem nas seções de detalhe; apenas a seção aditivos de senado_contratacao_detalhe traz valor, referente ao termo aditivo) — não gaste chamadas procurando valor. A lista mistura subespécies (CT = contratos, AC = acordos de cooperação, TD = termos de doação etc.); distinga pelo campo subEspecie retornado. Limitado a limite itens (padrão 50, máx 500), com aviso quando há truncamento. Use o id retornado em senado_contratacao_detalhe para itens, pagamentos, garantias ou aditivos.

Inputs: ano, cnpj, limite, numero, +3 more. Returns: provenance, attribution

senado_discursos_plenarioDiscursos no plenárioA
Read-onlyIdempotent
Inspect

Lista todos os discursos realizados em plenário num período de datas (dataInicio/dataFim obrigatórias, formato YYYYMMDD). Retorna { periodo, count, discursos }, cada item com codigo, data, casa, tipoUsoPalavra, resumo, indexacao, url, nomeParlamentar, codigoParlamentar, partido e uf. Para discursos de um parlamentar específico use senado_discursos_senador; obtenha o texto integral com senado_discurso_texto.

Inputs: dataFim (required), dataInicio (required). Returns: provenance, attribution

senado_discursos_senadorDiscursos de um senadorA
Read-onlyIdempotent
Inspect

Lista pronunciamentos de um senador, filtráveis por período e casa. tipo (padrão discursos) alterna entre discursos (falas próprias) e apartes (intervenções em falas de outros) — muda a fonte upstream e o conteúdo, mantendo a mesma estrutura. Retorna { codigoSenador, tipo, count, discursos, periodosNaoLidos?, aviso? } sem paginação (count 0 e lista vazia quando não há pronunciamentos no período), cada item com codigo, data, casa, tipoUsoPalavra, resumo, indexacao, url e nomeParlamentar — sem o texto integral. ATENÇÃO: para tipo=discursos, omitir dataInicio/dataFim faz a fonte retornar SOMENTE os últimos 30 dias (frequentemente vazio) — para o histórico, informe o período explícito (ex.: desde o início do mandato; períodos de mais de 1 ano são lidos ano a ano por dentro, e um ano que a fonte não entregar aparece em periodosNaoLidos); apartes traz o histórico completo sem período e, com período, só os apartes dentro dele. Obtenha o codigoSenador via senado_listar_senadores e o texto completo em senado_discurso_texto (campo codigo). Para discursos de todos os senadores num período use senado_discursos_plenario, não esta.

Inputs: codigoSenador (required), casa, tipo, dataFim, +1 more. Returns: provenance, attribution

senado_discurso_textoTexto de um discursoA
Read-onlyIdempotent
Inspect

Obtém o texto integral de um único pronunciamento pelo codigoPronunciamento. Retorna { codigoPronunciamento, texto }, onde texto é a transcrição completa (string, podendo ter dezenas de KB — não é truncada nem paginada); codigo inexistente ou discurso sem texto retorna erro. Obtenha o codigoPronunciamento antes via senado_discursos_senador ou senado_discursos_plenario (campo codigo). Para apenas listar/filtrar discursos (resumo, data, autor) use aquelas ferramentas; esta traz o texto de um discurso já identificado.

Inputs: codigoPronunciamento (required). Returns: provenance, attribution

senado_distribuicao_materiasRanking de autoria/relatoria por comissãoA
Read-onlyIdempotent
Inspect

Ranqueia parlamentares pela quantidade de matérias numa comissão (siglaComissao), medindo carga de trabalho legislativo. tipo escolhe o eixo: autoria (matérias de autoria; padrão) ou relatoria (matérias relatadas). Retorna { siglaComissao, tipo, count, parlamentares } ordenado por quantidade desc, sem paginação (count 0 quando a comissão não tem registros), cada item com codigo, nome, partido, uf e quantidade. codigoParlamentar restringe a um parlamentar e só tem efeito em tipo=autoria (ignorado em relatoria). Descubra a sigla via senado_listar_comissoes; use o codigo do parlamentar em senado_obter_senador. Para a lista das matérias em si (não a contagem) use senado_buscar_materias.

Inputs: siglaComissao (required), tipo, codigoParlamentar. Returns: provenance, attribution

senado_ecidadania_consultas_analiseAnálise de consultas públicasA
Read-onlyIdempotent
Inspect

Analisa o conjunto completo de consultas públicas abertas (matérias em tramitação) do e-Cidadania por grau de concordância cidadã, conforme modo: consenso → consultas com alta concentração de votos numa direção, ordenadas da maior para a menor concentração; usa percentualMinimo (padrão 85%). polarizada → consultas com votação equilibrada (~50/50), ordenadas da menor para a maior diferença sim/não; usa margemPolarizacao (padrão 15 pontos). Analisa por padrão consultas aberta (opinião pública atual). Quando a matéria sai de tramitação a consulta passa a encerrada, então status: "encerrada"/"todas" cobrem o conjunto que foi encerrado desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas. Todos os modos aceitam minimoVotos (padrão 1000) e limite (padrão 10). Retorna { modo, criterio, count, consultas }. É esta a ferramenta para 'consultas mais votadas', ranking ou panorama ATUAL da votação das consultas em tramitação — não confundir com senado_ecidadania_consultas_votos, que é o acervo HISTÓRICO (matérias já arquivadas) com quebra por UF. Para o detalhe de uma consulta use senado_ecidadania_obter_consulta.

Inputs: modo, limite, status, minimoVotos, +2 more. Returns: provenance, attribution

senado_ecidadania_consultas_votosVotos em consultas por UFA
Read-onlyIdempotent
Inspect

Acervo histórico de votos das consultas públicas do e-Cidadania, com quebra por UF (fonte: CSV Arquimedes; ~15 mil matérias, atualizado semanalmente). Use apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado (UF); para 'consultas mais votadas', ranking ou opinião ATUAL das consultas em tramitação use senado_ecidadania_consultas_analise. Diferente de senado_ecidadania_listar_consultas (consultas em tramitação): aqui o conjunto é o arquivo de matérias já consultadas — status vem como Descontinuado no arquivo de origem, por isso é tratado como acervo, não como opinião atual. Retorna { count, referencePeriod, consultas }, cada item com id, materia, ementa, autoria, votosSim/votosNao/totalVotos, votosPorUf ({ UF: { sim, nao } }) e url. Use ordenarPor (total/sim/nao, padrão total) e ordem para ranking; uf para recortar e ranquear por aquele estado (só matérias com votos na UF, e cada item ganha recorteUf); materia para filtrar por código (numérico) ou trecho do nome/ementa; limite (padrão 20).

Inputs: uf, ordem, limite, materia, +1 more. Returns: provenance, attribution

senado_ecidadania_listar_consultasListar consultas públicasA
Read-onlyIdempotent
Inspect

Lista consultas públicas do e-Cidadania (conjunto completo das abertas — toda matéria em tramitação, ~7,7 mil), em que cidadãos votam sim/não. Retorna { count, consultas }, cada consulta com id, materia, ementa, votosSim/votosNao/totalVotos, percentualSim/percentualNao, status e url. Toda consulta entra como aberta; quando a matéria sai de tramitação ela passa a encerrada (o conjunto encerrada/todas cresce com o tempo). Consultas encerradas antes da 1ª ingestão não são capturadas. Aceita limite (padrão 20). Para o detalhe de uma consulta chame senado_ecidadania_obter_consulta com o id; para recortes analíticos (consenso/polarização) use senado_ecidadania_consultas_analise.

Inputs: limite, pagina, status. Returns: provenance, attribution

senado_ecidadania_listar_eventosListar eventos interativosA
Read-onlyIdempotent
Inspect

Lista eventos interativos do e-Cidadania (audiências públicas, sabatinas, lives) — conjunto completo (corpus persistido em D1, atualizado semanalmente; ~milhares de eventos, incluindo encerrados). Retorna { count, eventos }, cada evento com id, titulo, data, hora, comissao (sigla), comentarios, status (agendado/encerrado/cancelado) e url; aceita filtro por status, por comissao (sigla) e limite (padrão 20). Para um ranking dos mais comentados, ordene por comentários (ordenarPor: "comentarios", ordem: "desc"). Para o detalhe completo de um evento use senado_ecidadania_obter_evento.

Inputs: ordem, limite, status, comissao, +1 more. Returns: provenance, attribution

senado_ecidadania_listar_ideiasListar ideias legislativasA
Read-onlyIdempotent
Inspect

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 (a categoria da listagem do portal em que a ideia aparece: aberta = "Aberta", "Na comissão" ou "Aguardando envio à CDH"; encerrada = "Encerrada – sem apoio suficiente" ou "Não acatada" pela CDH; convertida = "Transformada em proposição"; 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á; autorUf traz a sigla da UF ou "Exterior", como o portal publica, e null quando o portal não publica a localidade; plConvertido, apesar do nome, é a Sugestão gerada na CDH, "SUG N/AAAA", não o projeto de lei). proposicoes (desde a 3.21.0, ausente até o backfill ler a ideia; [] = lida sem proposição) lista os projetos em que a ideia foi transformada, pela CDH ou adotada por parlamentar: tipo, número, ano, quem transformou, data e link. Datas: dataPublicacao é a DATA LIMITE para receber os 20.000 apoios — a única data que o corpus guarda; 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; a data REAL da proposição sai em senado_ecidadania_obter_ideia (dataProposta); 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, linha do tempo, Sugestão, decisão da CDH, proposições em que virou) chame senado_ecidadania_obter_ideia com o id.

Inputs: ordem, limite, pagina, status, +1 more. Returns: provenance, attribution

senado_ecidadania_obter_consultaDetalhar consulta públicaA
Read-onlyIdempotent
Inspect

Obtém o detalhe de uma consulta pública específica do e-Cidadania. Retorna um objeto com id, materia, ementa, votosSim/votosNao/totalVotos, percentualSim/percentualNao, status, autor, relator, url. O portal não publica o período da consulta: dataAbertura/dataEncerramento (e comissao/linkMateria) vêm sempre null — a consulta abre quando a matéria entra em tramitação e encerra quando sai, refletido em status. O campo comentarios vem null: a página de consulta não possui recurso de comentários. O campo relator vem null: a página da consulta publica só autoria e ementa, não a relatoria — o relator da matéria sai de senado_obter_materia com o mesmo número (codigoMateria = id). Obtenha o id antes via senado_ecidadania_listar_consultas ou senado_ecidadania_consultas_analise.

Inputs: id (required). Returns: provenance, attribution

senado_ecidadania_obter_eventoDetalhar evento interativoA
Read-onlyIdempotent
Inspect

Obtém o detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live). Retorna um objeto com id, titulo, descricao, data, hora, comissao e comissaoNomeCompleto, local, status (agendado/encerrado/cancelado), comentarios, url, mais pauta (até 15 itens), convidados e videoUrl (embed do YouTube quando houver, senão null) — campos não preenchidos vêm null e id inexistente retorna erro. Obtenha o id antes via senado_ecidadania_listar_eventos. Para apenas listar/rankear eventos (sem descrição/pauta/convidados) use senado_ecidadania_listar_eventos, não esta.

Inputs: id (required). Returns: provenance, attribution

senado_ecidadania_obter_ideiaDetalhar ideia legislativaA
Read-onlyIdempotent
Inspect

Obtém o detalhe de uma ideia legislativa do e-Cidadania, lido ao vivo da página da ideia. Retorna id, titulo, descricao, apoios, status, origemStatus, autor ("NOME (UF)", o nome abreviado como o portal publica), url, plConvertido (a Sugestão gerada, "SUG n/ano"), dataEncerramento (fim do período de apoio, quando encerrado) e os campos da linha do tempo do portal: dataProposta (data em que a ideia foi proposta, publicada pela fonte), prazoApoios (data limite para os 20.000 apoios), dataMeta/meta (quando alcançou a meta), sugestao (número, ano, data e link da Sugestão), decisaoCdh (a CDH transformou ou não a Sugestão), encerramento (apoios recebidos e fim do período), oficina (ideia de Oficina Legislativa), proposicoes (cada proposição em que a ideia virou — pela CDH ou adotada por senador/deputado —, com sigla, número, ano, parlamentar e link), linhaDoTempo (os acontecimentos como publicados, mais recente primeiro) e avisos (acontecimento que o servidor não reconheceu, copiado sem interpretação). Situação: status é a categoria do portal guardada no corpus (aberta/encerrada/convertida/removida, as mesmas de senado_ecidadania_listar_ideias); se a ideia ainda não está no corpus, o servidor a classifica pela linha do tempo e origemStatus diz isso. Datas: use dataProposta; dataPublicacao é a data limite (nome histórico, igual a prazoApoios) e dataCriacaoEstimada é estimativa mantida por compatibilidade. comentarios, problema e solucao vêm null: a página não os publica. Obtenha o id antes via senado_ecidadania_listar_ideias.

Inputs: id (required). Returns: provenance, attribution

senado_ecidadania_sugerir_tema_enqueteSugerir tema de enqueteA
Read-onlyIdempotent
Inspect

Sugere temas para uma enquete pública mensal (seleção de pauta): analisa o conjunto completo de consultas (abertas) e as ideias do e-Cidadania e elege as de maior engajamento cidadão, filtrando por polarização/consenso e participação mínima. Retorna { criteriosAplicados, totalAnalisados, count, totalQualificados, sugestoes } (até 10), cada sugestão com tipo (consulta/ideia), id, titulo, motivo, metricas (participação/polarização) e url, ordenadas por participação. count é o número de sugestões retornadas (≤10) e totalQualificados é quantas passaram nos critérios. Critérios opcionais em criterios: evitarPolarizacao/evitarConsenso (padrão true), minimoParticipacao (padrão 500), apenasEmTramitacao (padrão true → considera só consultas abertas, com base no status real). Para investigar uma sugestão, use senado_ecidadania_obter_consulta ou senado_ecidadania_obter_ideia conforme o tipo.

Inputs: criterios. Returns: provenance, attribution

senado_empresas_contratadasEmpresas contratadasA
Read-onlyIdempotent
Inspect

Busca empresas que contratam com o Senado por nome (mín. 3 caracteres) ou CNPJ/CPF (busca parcial). Retorna { count, total, empresas }, cada item com id, nome, cnpj, contratos (até 30 números) e totalContratos. Exige nome ou cnpj (a base completa é grande); limitado a limite (padrão 20, máx 100). Use o id/número de contrato em senado_contratos ou senado_contratacao_detalhe para o detalhamento.

Inputs: cnpj, nome, limite. Returns: provenance, attribution

senado_encontro_plenarioSessões do plenárioA
Read-onlyIdempotent
Inspect

Detalhes de um encontro legislativo (sessão de plenário). Retorna { codigo, secao, encontro }, onde encontro é o objeto bruto da API (ou array, quando o upstream traz vários) cujos campos variam conforme a secao escolhida: detalhes (padrão) traz dados gerais da sessão (tipo, data, situação, presença); pauta traz as matérias previstas; resultado traz os itens apreciados e seus resultados; resumo traz uma síntese. encontro pode vir vazio se a seção não tiver dados, e a chamada retorna erro se o codigo não existir. Obtenha o codigo via senado_agenda_plenario ou senado_resultado_plenario.

Inputs: codigo (required), secao. Returns: provenance, attribution

senado_estrutura_organizacionalEstrutura organizacionalA
Read-onlyIdempotent
Inspect

Estrutura organizacional (organograma) do Senado Federal até o nível de serviço. Dada uma unidade (sigla como 'DGER' ou nome como 'Diretoria-Geral'), retorna { unidade, caminho[], totalSubordinadas, subordinadas[] }: caminho são os órgãos superiores (da cúpula até o superior imediato) e subordinadas são TODAS as unidades da subárvore (secretarias, coordenações, serviços e núcleos), cada uma com sigla, nome e nivel (profundidade relativa). Use para responder 'o que está sob a DGER', 'quais secretarias/serviços pertencem a X' ou para entender a hierarquia administrativa. Para CONTAR ou LISTAR servidores sob uma unidade, use senado_servidores com subordinadasA. Fonte: portal institucional (a API de dados abertos não publica a árvore completa).

Inputs: unidade (required), limite. Returns: provenance, attribution

senado_execucao_orcamentariaExecução orçamentária do SenadoA
Read-onlyIdempotent
Inspect

Execução orçamentária do Senado: despesas (dotação, empenhado, liquidado, pago; desde 2013) ou receitas próprias (previstas e arrecadadas; desde 2012). Para maior/menor/média/mediana/distribuição/ranking ('quanto o Senado pagou/arrecadou com X', 'maior grupo de despesa') use estatisticas=true: SEM agruparPor = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM agruparPor = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o tipo; o resultado já traz o rótulo legível dela em campoAnalisado. Retorna { tipo, modo, ano, totalLinhas, ... }: nos modos agregados, agregado[] com { chave, ...valores } ordenado por valor; em detalhe, despesas[]/receitas[] limitado por limite (padrão 100, com aviso ao truncar). Use tipo=despesas com modo por-ano/por-acao/por-grupo/por-fonte e tipo=receitas com por-origem; filtre por ano para reduzir o volume antes de pedir detalhe. O que cada número é: nas despesas, dotação/empenhado/liquidado/pago são ACUMULADOS no exercício até a data de posição do arquivo (o data_vintage da proveniência diz qual) — o exercício corrente é parcial e cresce; nas receitas, arrecadada é o valor do mês e prevista vem lançada inteira no mês 1. São os valores que o Senado publica na data de posição; lançamentos podem ser corrigidos depois. Única ferramenta de orçamento interno do Senado; não confundir com senado_orcamento_parlamentar (emendas/ofícios parlamentares ao orçamento da União).

Inputs: ano, modo, tipo, topN, +4 more. Returns: provenance, attribution

senado_horas_extrasHoras extras de servidoresA
Read-onlyIdempotent
Inspect

Horas extras pagas a servidores do Senado em ano/mes de referência (a partir de 2013). Para perguntas de maior/menor/média/mediana/distribuição/ranking ('quem recebeu mais horas extras', 'valor mediano de hora extra', 'distribuição dos pagamentos') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre TODAS as linhas filtradas (valorTotal) e devolve top/bottom (padrão 10) com identificadores. Sem agruparPor → distribuicao das linhas individuais + top/bottom; com agruparPor (nome/competencia) → grupos[] ranqueados por soma decrescente (grupos[0] = quem mais recebeu; por nome soma as linhas do mesmo servidor no mês), cada um com sua mini-distribuição. Sem estatisticas: retorna { ano, mes, count, total, valorTotal, horasExtras[] }, onde valorTotal soma o gasto do mês e cada item traz nome, valorTotal, horasExtras, competencia e pagamento. Filtro opcional por nome (busca parcial) e limite (padrão 100, máx 500; ignorado quando estatisticas=true). Para a remuneração completa do servidor use senado_remuneracoes_servidores.

Inputs: ano (required), mes (required), nome, topN, +3 more. Returns: provenance, attribution

senado_licitacoesLicitações do SenadoA
Read-onlyIdempotent
Inspect

Busca licitações do Senado por número exato (ex: 19/2018) ou texto do objeto. Retorna { count, total, licitacoes } com os registros brutos da API administrativa, limitados a limite (padrão 50, máx 500). Exige ao menos numero ou objeto (sem filtro retorna erro). Para o contrato resultante de uma licitação, use senado_contratos.

Inputs: limite, numero, objeto. Returns: provenance, attribution

senado_liderancasLideranças partidáriasA
Read-onlyIdempotent
Inspect

Lista as lideranças do Senado, da Câmara e do Congresso Nacional (líderes, vice-líderes etc.). Retorna { count, liderancas }, cada item com tipo, descricao, unidadeLideranca, casa, dataDesignacao, dataTermino, numeroOrdemViceLider, bloco (codigo/nome/sigla — preenchido quando a liderança é de bloco; o codigo serve em senado_obter_bloco), partido (codigo/sigla/nome — a unidade liderada, quando liderança de partido) e parlamentar (codigo, nome, partido de filiação, uf). A fonte NÃO publica a UF do parlamentar (vem sempre null) — obtenha-a via senado_obter_senador pelo codigo. Filtre por casa (SF/CN/CD), codigoParlamentar, vigente (S/N) ou siglaTipoLideranca; sem filtros retorna todas as casas. Para a composição de blocos use senado_listar_blocos.

Inputs: casa, vigente, codigoParlamentar, siglaTipoLideranca. Returns: provenance, attribution

senado_listar_blocosListar blocos parlamentaresA
Read-onlyIdempotent
Inspect

Lista todos os blocos parlamentares do Senado e seus partidos membros. Retorna { count, blocos }, onde cada bloco traz codigo, nome, nomeApelido, dataCriacao, dataExtincao e a lista partidos (cada um com sigla, nome, dataAdesao, dataDesligamento). A lista inclui a composição HISTÓRICA de cada bloco: partido com dataDesligamento preenchida já saiu (a composição atual são os com dataDesligamento null) e o mesmo partido pode repetir com períodos de adesão distintos — sem esse filtro um partido parece estar em 2 blocos ao mesmo tempo. Use para descobrir o codigo de um bloco e depois detalhá-lo via senado_obter_bloco; para lideranças use senado_liderancas.

Inputs: no named parameters. Returns: provenance, attribution

senado_listar_comissoesListar comissõesA
Read-onlyIdempotent
Inspect

Lista comissões (colegiados) ativas do Senado, com filtros por tipo (permanente, temporaria, cpi, mista) e ativa. Retorna { count, comissoes }, cada item com codigo, sigla, nome, tipo, casa e ativa. O endpoint só traz comissões ativas, logo ativa=false resulta em lista vazia. Use para descobrir a sigla exigida por senado_obter_comissao e senado_reunioes_comissao.

Inputs: tipo, ativa. Returns: provenance, attribution

senado_listar_senadoresListar senadoresA
Read-onlyIdempotent
Inspect

Use para pedidos como 'liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores' ou filtros por UF/partido. Lista senadores em exercício, fora de exercício ou de uma legislatura específica, com filtros opcionais por nome, uf e partido. Retorna { count, senadores }, cada item com codigo, nome, nomeCompleto, partido, uf, foto e emExercicio, mais proveniência oficial da lista lida. emExercicio é a situação de HOJE: sem legislatura, true (padrão) lista os em exercício (titulares e suplentes que assumiram a vaga) e false lista os fora de exercício (titulares licenciados e suplentes fora da vaga — a mesma lista de senado_senadores_afastados); com legislatura, omitido traz a legislatura inteira e true/false filtra pela situação de hoje. nome faz correspondência parcial ignorando acentos/maiúsculas (use quando você só tem o nome e precisa do codigo); uf/partido filtram localmente. Use o codigo em senado_obter_senador ou senado_votacoes_senador.

Inputs: uf, nome, partido, emExercicio, +1 more. Returns: provenance, attribution

senado_mesaMesa DiretoraA
Read-onlyIdempotent
Inspect

Lista os membros da Mesa Diretora (presidente, vice-presidentes, secretários). O parâmetro casa (padrão senado) escolhe entre senado (Mesa do Senado Federal) e congresso (Mesa do Congresso Nacional). Retorna { casa, mesa, count, membros }, cada membro com cargo, codigo, nome, partido e uf. Para lideranças partidárias use senado_liderancas.

Inputs: casa. Returns: provenance, attribution

senado_notas_taquigraficasNotas taquigráficasA
Read-onlyIdempotent
Inspect

Transcrição oficial (notas taquigráficas) de uma sessão plenária ou reunião de comissão, em blocos sequenciais. Retorna { id, tipo, sessao, data, totalBlocos, aviso?, blocos }; id inexistente ou sem transcrição no acervo retorna totalBlocos 0 com aviso explicando. Cobertura: sessões plenárias do SF (deliberativas, não deliberativas, especiais) são transcritas em poucos dias; sessões CONJUNTAS do Congresso, canceladas/não realizadas e algumas solenes NÃO têm notas (a mídia pode existir em senado_videos_taquigrafia). modo governa o payload: resumo (padrão) traz por bloco sequencia, dataInicio/Fim, trecho (200 chars), caracteres e linkAudio, limitado a limite (padrão 20; pagine com sequenciaInicio, aviso sinaliza corte); texto traz o conteúdo integral de até 20 blocos por chamada (janela sequenciaInicio→sequenciaFim) e inclui intervalo. sequenciaFim só atua em modo=texto. Obtenha o id via senado_agenda_plenario/senado_resultado_plenario (sessão) ou senado_reuniao_comissao (reunião); orador filtra blocos pelo nome citado. Para a mídia (vídeo/áudio) use senado_videos_taquigrafia, não esta.

Inputs: id (required), modo, tipo, limite, +3 more. Returns: provenance, attribution

senado_obter_blocoDetalhar bloco parlamentarA
Read-onlyIdempotent
Inspect

Obtém detalhes de um bloco parlamentar específico pelo seu código. Retorna um objeto com codigo, nome, nomeApelido, dataCriacao, dataExtincao e partidos (array com sigla, nome, dataAdesao, dataDesligamento); dataExtincao é null para blocos vigentes. partidos é a composição HISTÓRICA: quem tem dataDesligamento preenchida já saiu do bloco (composição atual = dataDesligamento null). Obtenha o parâmetro codigo primeiro via senado_listar_blocos; código inexistente retorna erro ("Bloco parlamentar não encontrado").

Inputs: codigo (required). Returns: provenance, attribution

senado_obter_comissaoDetalhar comissãoA
Read-onlyIdempotent
Inspect

Obtém dados de uma comissão pela sigla, conforme secao (padrão resumo): resumo → { codigo, sigla, nome, tipo, finalidade, presidente, vicePresidente, totalMembros, titulares, suplentes } (presidente/vice com nome/codigo/bancada). finalidade só vem preenchida para colegiados temporários (CPIs, comissões temporárias e de medida provisória); para comissões permanentes (CCJ, CAE etc.) a fonte não a publica e o campo vem nulo com um aviso — as competências estão no Regimento Interno. membros → { sigla, secao, count, membros }, cada membro com codigo, nome, tipoVaga (titular/suplente), ativo e dataInicio. A sigla é resolvida internamente para código numérico; descubra-a via senado_listar_comissoes.

Inputs: sigla (required), secao. Returns: provenance, attribution

senado_obter_legislacaoDetalhar norma legalA
Read-onlyIdempotent
Inspect

Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos. Retorna um objeto com codigo, tipo, descricaoTipo, numero, ano, data (ISO AAAA-MM-DD), norma, apelido, ementa, indexacao (termos temáticos) e url do texto integral — campos ausentes na norma vêm null, e codigo inexistente retorna erro "Norma não encontrada", não um objeto vazio. Obtenha o codigo antes via senado_buscar_legislacao (é o identificador interno da norma, não o número da lei). Para localizar normas por tipo/número/ano use senado_buscar_legislacao; esta serve só para o detalhe de uma norma já identificada.

Inputs: codigo (required). Returns: provenance, attribution

senado_obter_materiaDetalhar matéria legislativaA
Read-onlyIdempotent
Inspect

Obtém dados de uma matéria pelo codigoMateria, conforme secao (padrão detalhe): detalhe → objeto com identificacao, apelido, ementa, autor, situacao, localAtual, dataApresentacao, indexacao, classificacoes[], tramitando, relator (nome/partido/uf/comissão), deliberacao e normaGerada. tramitacao → histórico de tramitação cronológico em tramitacoes[] (data, local, descricao), com count/total (mantém os mais recentes ao truncar). textos → documentos da matéria em textos[] (tipo, formato, identificacao, data, autoria, url), do mais recente ao mais antigo. limite aplica-se a tramitacao/textos (padrão 100 e 50; ao truncar inclui aviso). Obtenha o codigoMateria via senado_buscar_materias.

Inputs: codigoMateria (required), secao, limite. Returns: provenance, attribution

senado_obter_processoDetalhar processoA
Read-onlyIdempotent
Inspect

Obtém detalhes completos de um processo legislativo específico pelo seu id. Retorna um objeto com id, codigoMateria, identificacao, sigla, numero, ano, objetivo, ementa, tipoConteudo, dataApresentacao, autoria, indexacao, urlDocumento, tramitando (boolean) e o estado atual do processo: situacaoAtual (+siglaSituacaoAtual/dataSituacaoAtual), deliberacao (data, tipo, destino) e normaGerada (quando o processo virou norma). Obtenha o idProcesso antes via senado_search_processos ou senado_buscar_materias; para emendas, relatorias ou prazos use senado_processo_detalhe (parâmetro secao).

Inputs: idProcesso (required). Returns: provenance, attribution

senado_obter_senadorDetalhar senadorA
Read-onlyIdempotent
Inspect

Obtém o detalhe biográfico de um senador específico. Retorna um objeto com codigo, nome, nomeCompleto, nomeCivil, sexo, dataNascimento, naturalidade/ufNaturalidade, partido, uf, foto, email, emExercicio e a lista mandatos (legislatura, uf, participacao, dataInicio, dataFim). emExercicio é derivado dos exercícios do mandato (aberto = em exercício) e vem null — nunca afirmado — quando os mandatos não puderam ser lidos. Código inexistente retorna erro ("Senador com código N não encontrado"), nunca um registro vazio. Requer codigoSenador — obtenha-o via senado_listar_senadores (filtro nome). Para filiações, profissões, licenças, comissões ou cargos use senado_senador_historico (parâmetro tipo).

Inputs: codigoSenador (required). Returns: provenance, attribution

senado_obter_votacaoDetalhar votaçãoA
Read-onlyIdempotent
Inspect

Obtém detalhes de uma votação de plenário, incluindo votos nominais. codigoVotacao aceita OS DOIS códigos que a fonte publica para a mesma votação: o codigoVotacao de 4 dígitos (ex.: 7101 — o que senado_search_votacoes e senado_votacoes_senador devolvem nesse campo) ou o codigoSessao de 6 dígitos da sessão plenária (ex.: 581816). Com o código da votação retorna aquela votação; com o da sessão retorna { codigoSessao, count, votacoes } com todas as votações da sessão. Cada votação traz placar, resultado legível + resultadoCodigo bruto, secreta e votos[] (codigoSenador, nomeSenador, partido, uf, voto). Resolver o código de 4 dígitos exige varrer uma janela temporal: por padrão a janela recente da fonte (~12 meses); para votação mais antiga informe ano. Código que não existe em nenhum dos dois espaços retorna erro — nunca lista vazia. Atenção: códigos de senado_votacao_comissao e o codigoVotacao de senado_orientacao_bancada pertencem a OUTROS espaços de numeração e não são válidos aqui.

Inputs: codigoVotacao (required), ano. Returns: provenance, attribution

senado_orcamento_parlamentarOrçamento parlamentar (emendas)A
Read-onlyIdempotent
Inspect

Emendas parlamentares ao orçamento da União, conforme tipo (padrão emendas). tipo: emendas (proposição) → { tipo, count, emendas }, cada item (lote de emendas de um autor) com autor, codigoAutor, quantidadeEmendas, anoExecucao, materia (peça orçamentária, p.ex. LOA 29/2023), tipoPl, dataOperacao e ativo. tipo: oficios (execução — indicação de destino de emendas já aprovadas) → { tipo, ano, count, total, aviso?, oficios }, cada ofício com id, autor, protocolo, dataInclusao e quantidadeEmendas; filtre pelo ano do orçamento da emenda (recomendado — a base cobre vários anos), pagine com limite/pagina, e use incluirEmendas: true para o detalhe de cada emenda (favorecido, CNPJ, órgão, nota de empenho). Nota: no modo oficios, o ofício é o documento de execução que indica o destino do recurso de uma emenda já aprovada (posterior à proposição); a data do ofício difere do ano do orçamento. Para a execução do orçamento interno do próprio Senado (despesas/receitas) use senado_execucao_orcamentaria.

Inputs: ano, tipo, limite, pagina, +1 more. Returns: provenance, attribution

senado_orientacao_bancadaOrientação de bancadaA
Read-onlyIdempotent
Inspect

Orientação de bancada nas votações de plenário: como cada liderança partidária orientou o voto, com placar — essencial para análise de disciplina partidária. Retorna { count, votacoes }, com cada votação trazendo codigoVotacaoSve, descricao, materia, dataInicio, dataTermino, sessao, totais (totalSim, totalNao, totalAbstencao, obstrucoes), quorumInicial/quorumFinal e orientacoes (partido, voto). Informe data (um dia) ou o período dataInicio/dataFim. O codigoVotacaoSve é o identificador interno do sistema de votação eletrônica e pertence a um espaço de numeração próprio: NÃO serve como entrada de senado_obter_votacao (use a data com senado_search_votacoes para chegar ao código da votação). Para o resultado das sessões use senado_resultado_plenario.

Inputs: data, dataFim, dataInicio. Returns: provenance, attribution

senado_pessoal_tabelasTabelas de gestão de pessoasA
Read-onlyIdempotent
Inspect

Tabelas de pessoal do Senado conforme o parâmetro tabela. Quantitativos agregados: pessoal (força de trabalho por classe/escolaridade), cargos-funcoes (cargos em comissão e funções de confiança), previsao-aposentadoria, senadores. Listas nominais: estagiarios (ativos), pensionistas, lotacoes (setores), cargos (nomes de cargos). Retorna { tabela, count, total, aviso?, registros[] } — registros agregados (nos quantitativos) ou nominais (nas listas), conforme a tabela, limitados por limite (padrão 100, máx 2000); count 0 e lista vazia quando a tabela não tem registros. O filtro textual opcional casa contra qualquer campo do registro. Para o cadastro nominal de servidores efetivos/comissionados use senado_servidores.

Inputs: tabela (required), filtro, limite. Returns: provenance, attribution

senado_processo_detalheDetalhes do processoA
Read-onlyIdempotent
Inspect

Detalha um aspecto de processos legislativos conforme o parâmetro secao: emendas → emendas apresentadas (id, identificacao, numero, tipo, autoria, data, colegiado, descricao, decisoes (objetos com casa/data/tipo/comissao/nomeComissao), url; aceita filtro codigoParlamentarAutor); relatorias → relatorias designadas (idProcesso, processo, relator, partido, uf, tipoRelator, comissao, dataDesignacao, dataDestituicao, motivoEncerramento; aceita codigoParlamentar/codigoColegiado/dataReferencia); prazos → prazos regimentais/constitucionais (registros brutos da API; aceita dataReferencia). Todos aceitam idProcesso e/ou codigoMateria e período dataInicio/dataFim (YYYYMMDD ou ISO) — informe pelo menos um filtro. Retorna { secao, count, total, aviso?, itens }, limitado a limite (padrão 100, máx. 500). Obtenha o idProcesso via senado_search_processos; tipos de prazo via senado_tabelas_processo. Ex.: { secao: 'emendas', codigoMateria: 137999 } ou { secao: 'relatorias', codigoParlamentar: 4994, dataReferencia: '2025-06-01' }.

Inputs: secao (required), limite, dataFim, dataInicio, +6 more. Returns: provenance, attribution

senado_remuneracoes_servidoresRemuneração de servidoresA
Read-onlyIdempotent
Inspect

Remunerações dos servidores do Senado em ano/mes de referência (a partir de 2013). Para perguntas de maior/menor/média/mediana/ranking ('quem ganhou mais em junho/2026', 'remuneração média') use estatisticas=true: computa min/máx/média/mediana/desvio/percentis sobre a folha INTEIRA e devolve top/bottom (padrão 10) identificados por nome (com idInternoFolha só para desambiguar homônimos, não para citar) — o modo resumo/detalhe só vê uma fatia e não acha o extremo real. Cada percentil vem com um rotulo legível e a coluna analisada tem rótulo legível em campoAnalisado. campo escolhe a verba analisada (padrão: remuneração bruta); consolidarPorServidor (padrão true) soma as linhas Normal+Suplementar da mesma pessoa antes das estatísticas; agruparPor='tipoFolha' devolve estatísticas por grupo (implica não-consolidado). Sem estatisticas: modo=resumo (padrão) retorna { ano, mes, totalRegistros, resumo[] } agregado por tipoFolha; modo=detalhe retorna { count, total, remuneracoes[] } com a composição individual, limitada por limite (padrão 50, máx 500). Filtros nome/tipoFolha aplicam antes de tudo. Para o cadastro de servidores use senado_servidores.

Inputs: ano (required), mes (required), modo, nome, +7 more. Returns: provenance, attribution

senado_requerimentos_cpiRequerimentos de CPIA
Read-onlyIdempotent
Inspect

Lista requerimentos de uma CPI (Comissão Parlamentar de Inquérito) em atividade, pela siglaCpi, com paginação por pagina (índice baseado em 0, definido pelo upstream). Retorna { siglaCpi, pagina, count, requerimentos }, onde requerimentos é a lista de registros brutos da página (campos conforme a API: tipicamente número, data, ementa, autor e situação do requerimento). count é o tamanho da página; uma página além do total retorna count 0 — use isso para saber que as páginas acabaram. Descubra as siglas via senado_listar_comissoes com tipo=cpi. Limitação conhecida: o endpoint upstream costuma responder vazio mesmo para CPIs em atividade, e não há fonte alternativa limpa na API; nesses casos o retorno traz count 0 e um campo aviso explicando — não interprete lista vazia como certeza de que a CPI não possui requerimentos.

Inputs: siglaCpi (required), pagina. Returns: provenance, attribution

senado_resultado_plenarioResultados do plenárioA
Read-onlyIdempotent
Inspect

Resultado das sessões plenárias numa data: itens de pauta apreciados, pareceres e resultados. Retorna { data, escopo, count, sessoes } (todas as sessões da data, sem paginação), com cada sessão trazendo codigoSessao, numeroSessao, data, hora, tipo, casa e itens (codigoMateria, identificacao, ementa, resultado, parecer — resultado/parecer podem vir null em itens ainda não deliberados). Sem sessão na data, count é 0 e sessoes vem vazio. escopo: sf (Senado), cn (Congresso) ou mes (resumo do mês). Para a pauta prévia use senado_agenda_plenario; orientação de bancada via senado_orientacao_bancada.

Inputs: data (required), escopo. Returns: provenance, attribution

senado_resultado_vetoResultado de vetoA
Read-onlyIdempotent
Inspect

Obtém o resultado da apreciação de um veto presidencial. Retorna { codigo, tipo, resultado }, onde resultado é o objeto bruto da API (sem wrappers), com campos variáveis — tipicamente identificação do veto, situação por dispositivo (ex.: "Rejeitado"/"Mantido") e link do PDF do resultado nominal (PdfsResultadoVotacao). A API não fornece placar numérico (sim/não) aqui — o detalhamento nominal está no PDF; vem objeto vazio quando o veto ainda não foi votado e retorna erro se o codigo não existir. tipo define o que codigo representa: veto (código do veto, padrão), materia (código do projeto vetado) ou dispositivo (dispositivo de veto parcial) — as três chaves apontam para o mesmo veto. Obtenha o código via senado_vetos. Para listar vetos (não o resultado de um) use senado_vetos.

Inputs: codigo (required), tipo. Returns: provenance, attribution

senado_reuniao_comissaoDetalhar reunião de comissãoA
Read-onlyIdempotent
Inspect

Detalha uma reunião de comissão. Aceita DOIS caminhos: o codigoReuniao direto, ou sigla da comissão mais data (YYYYMMDD) — neste segundo caso a ferramenta resolve o código sozinha, e devolve as candidatas quando o dia tem mais de uma reunião. Retorna um objeto com codigo, titulo, comissao, data, hora, local, situacao, realizada, secreta, tipoPresenca (presencial/semipresencial), presidente, links urlPauta/urlResultado/urlAta e partes (cada parte com evento e itens apreciados: identificacao, ementa, autoria, relatoria, resultado, codigoMateria). A API NÃO publica lista de presença da reunião (só presidente e eventuais convidados): reconstrua a presença pelos votos nominais (senado_votacao_comissao), por quem falou na transcrição (senado_notas_taquigraficas com tipo=reuniao) ou pela ata oficial (urlAta, quando publicada). Sem código à mão, prefira sigla + data; o codigoReuniao também sai de senado_agenda_comissoes ou senado_reunioes_comissao.

Inputs: data, sigla, codigoReuniao. Returns: provenance, attribution

senado_reunioes_comissaoReuniões de comissãoA
Read-onlyIdempotent
Inspect

Lista reuniões de uma comissão (pela sigla) num intervalo dataInicio/dataFim (YYYYMMDD) de até 30 dias; sem datas, usa os últimos 14 dias. A fonte só entrega 30 dias por pedido (e cortava o resto calada), então janelas maiores são recusadas: divida períodos longos em chamadas de até 30 dias. A agenda é lida um dia por vez; um dia que a fonte não entregar aparece em diasNaoLidos, com aviso. Retorna { sigla, periodo, count, reunioes, agendaPrevista?, diasNaoLidos?, aviso? }, cada reunião com codigo, descricao, data, hora, local, tipo e situacao. reunioes traz só as de até hoje; quando o período chega ao futuro, as marcadas para depois de hoje vêm à parte em agendaPrevista (count, reunioes, aviso) — são previsão e podem mudar. Descubra a sigla via senado_listar_comissoes; use o codigo retornado em senado_reuniao_comissao para os detalhes da pauta.

Inputs: sigla (required), dataFim, dataInicio. Returns: provenance, attribution

senado_search_processosPesquisar processosA
Read-onlyIdempotent
Inspect

Busca processos legislativos no endpoint v3 /processo (parâmetros complementares ao senado_buscar_materias). Retorna { count, total, aviso?, processos }, cada item com id, codigoMateria, identificacao, ementa, tipoDocumento, dataApresentacao, autoria (compactada: primeiros autores + total), totalAutores, tramitando (boolean) e normaGerada. É obrigatório ao menos um filtro (sigla, número, ano, autor ou período). Limitado a limite (padrão 20, máx. 200), com aviso ao truncar. Use o id retornado em senado_obter_processo para detalhes. Ex.: { sigla: 'PL', ano: 2025, dataInicioApresentacao: '2025-03-01' } (datas em YYYYMMDD ou ISO).

Inputs: ano, autor, sigla, limite, +5 more. Returns: provenance, attribution

senado_search_votacoesPesquisar votaçõesA
Read-onlyIdempotent
Inspect

Busca e lista votações do plenário combinando critérios opcionais. Janela temporal: informe dias (últimos N dias, 1-365) para atividade recente, OU dataInicio/dataFim (YYYYMMDD) para um período arbitrário — para um ano inteiro use dataInicio: "AAAA0101" e dataFim: "AAAA1231". Demais filtros: idProcesso, codigoMateria, sigla/numero/ano da matéria, codigoParlamentar e siglaVotoParlamentar. Retorna { count, votacoes } ordenadas da mais recente para a mais antiga; cada item traz codigoSessao, data, materia, codigoMateria, resultado e placar (totalSim/totalNao/totalAbstencao), sem votos nominais. Use senado_obter_votacao com o codigoSessao para os votos de cada senador.

Inputs: ano, dias, sigla, numero, +6 more. Returns: provenance, attribution

senado_senadores_adminSenadores (dados administrativos)A
Read-onlyIdempotent
Inspect

Dados administrativos dos senadores conforme o parâmetro tipo: auxilio-moradia → { tipo, count, senadores } (nome, uf, partido, auxilioMoradia, imovelFuncional; legislatura atual). escritorios-apoio → { tipo, count, escritorios } (senador, uf, partido, setor, endereco, telefone). aposentados → { tipo, count, aposentados } ex-senadores aposentados pelos planos de previdência do Congresso (IPC e PSSC), com nome, tipo do plano, dataInicial, remuneracao. Filtros opcionais uf e nome (busca parcial) aplicam-se a auxilio-moradia e escritorios-apoio; nome também filtra aposentados. Cada tipo retorna count 0 e lista vazia quando não há registros. Para gastos de cota parlamentar use senado_ceaps. Ex.: { tipo: 'auxilio-moradia', uf: 'SP' } ou { tipo: 'aposentados' }.

Inputs: tipo (required), uf, nome. Returns: provenance, attribution

senado_senadores_afastadosSenadores afastadosA
Read-onlyIdempotent
Inspect

Lista os senadores atualmente afastados (fora de exercício). Retorna { count, senadores }, cada item com codigo, nome, nomeCompleto, partido, uf, foto e emExercicio (sempre false). Não requer parâmetros. Atenção: é a lista BRUTA do upstream, sem recorte de legislatura — pode conter registros históricos (ex.: senadores falecidos) e inconsistências pontuais com o detalhe do parlamentar; também não traz o vínculo titular↔suplente (para saber quem assumiu a vaga, consulte os mandatos em senado_obter_senador). Use codigo em senado_obter_senador para o detalhe; para os senadores em exercício (e busca por nome) use senado_listar_senadores.

Inputs: no named parameters. Returns: provenance, attribution

senado_senador_historicoHistórico do senadorA
Read-onlyIdempotent
Inspect

Histórico funcional de um senador conforme o parâmetro tipo. Valores: licencas (itens com dataInicio/dataFim/descricao), comissoes (sigla/nome/casa/participacao/datas), cargos (comissao/cargo/datas), historico-academico (cursos, registros brutos da API), filiacoes (partido/nomePartido/dataFiliacao/dataDesfiliacao) e profissoes (nome). Retorna { codigoSenador, tipo, count, itens }, com a forma de cada item dependente do tipo; tipos sem registros para o senador retornam count 0 e itens vazio. Requer codigoSenador (obtenha via senado_listar_senadores). Para dados biográficos e mandatos use senado_obter_senador. Ex.: { codigoSenador: 4994, tipo: 'filiacoes' } → histórico de partidos do senador.

Inputs: tipo (required), codigoSenador (required). Returns: provenance, attribution

senado_servidoresServidores do SenadoA
Read-onlyIdempotent
Inspect

Lista servidores do Senado por situacao (ativos, efetivos, comissionados ou inativos), com filtros opcionais por nome, lotacao e cargo. Retorna { situacao, count, total, servidores[] }, cada item com nome, vinculo, situacao, cargo, funcao, lotacao, anoAdmissao etc. Aplica limite (padrão 50, máx 500) e inclui aviso quando há truncamento — refine os filtros. Também conta e lista TODOS os servidores de TODA a estrutura subordinada a uma diretoria/secretaria (não só a lotação direta), cruzando a lotação de cada servidor com o organograma até o nível de serviço: informe a unidade (sigla ou nome, ex.: 'DGER') em subordinadasA — use isso para 'quantas pessoas estão sob a Diretoria-Geral', pois filtrar lotacao pela sigla-mãe retorna 0 (os servidores ficam em serviços/núcleos subordinados). Nesse modo o retorno traz a unidade resolvida, o total (um piso), os servidores, as unidades não reconhecidas no organograma (naoClassificados, com nota explicativa) e os afastados/em trânsito (afastadosOuEmTransito); ao responder, verbalize esses conceitos em português corrente — não cite nomes de parâmetros ou campos. Para o organograma em si use senado_estrutura_organizacional; para remuneração use senado_remuneracoes_servidores.

Inputs: nome, cargo, limite, lotacao, +2 more. Returns: provenance, attribution

senado_suprimento_fundosSuprimento de fundosA
Read-onlyIdempotent
Inspect

Suprimento de fundos do Senado (adiantamentos a supridos): relação anual de supridos, atos de concessão, empenhos, movimentações ou transações de cartão corporativo, conforme tipo. Retorna { ano, tipo, count, total, registros } (snake_case da API administrativa), filtrável por filtro textual e limitado por limite (padrão 100, máx 500); ao truncar, inclui aviso. Para maior/menor/média/mediana/distribuição/ranking ('quem mais recebeu', 'fornecedor com maior gasto', 'valor mediano') use estatisticas=true (só nos tipos transacoes, empenhos, atos-concessao — os demais não têm coluna de valor): SEM agruparPor = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM agruparPor = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o tipo; o resultado já traz o rótulo legível dela em campoAnalisado. Registros sem valor são excluídos das estatísticas. Em atos de concessão, cada beneficiário é identificado pelo NOME (cruzado com o cadastro de supridos) e pode-se usar agruparPor='suprido' para ranquear por beneficiário. Informe o ano (a fonte publica de 2013 em diante); use os mesmos códigos administrativos vistos em senado_contratacoes_lista ou senado_execucao_orcamentaria para cruzar gastos.

Inputs: ano (required), tipo, topN, campo, +4 more. Returns: provenance, attribution

senado_tabelas_plenarioTabelas de referência do plenárioA
Read-onlyIdempotent
Inspect

Consulta tabelas de referência do plenário para resolver códigos/domínios, conforme tabela: tipos-sessao (espécies de sessão plenária), tipos-comparecimento (situações de presença) ou legislaturas (períodos legislativos com datas). Retorna { tabela, count, total, linhas } — count é o nº após o corte por limite e total o disponível; count < total indica truncagem (aumente limite); count 0 quando o filtro não casa. Cada linha traz o código/sigla e a descrição do domínio (campos conforme a API). Use para interpretar campos como tipo de senado_agenda_plenario/senado_resultado_plenario. Para tabelas do processo legislativo (assuntos, classes, situações) use senado_tabelas_processo. Ex.: { tabela: 'legislaturas' } ou { tabela: 'tipos-sessao', filtro: 'deliberativa' }.

Inputs: tabela (required), filtro, limite. Returns: provenance, attribution

senado_tabelas_processoTabelas de referência de processosA
Read-onlyIdempotent
Inspect

Consulta tabelas de referência do processo legislativo para resolver códigos/siglas, conforme tabela. Domínios de entidade: siglas (siglas de proposição), assuntos, classes, destinos, entes. Domínios de tipo (código→descrição): tipos-situacao, tipos-decisao, tipos-autor, tipos-atualizacao, tipos-documento, tipos-conteudo-documento, tipos-prazo. Retorna { tabela, count, total, linhas } — count é o nº após o corte por limite e total o disponível; count < total indica truncagem (aumente limite); count 0 quando o filtro não casa. Cada linha traz código/sigla e descrição (campos conforme a API). Use antes de filtrar em senado_search_processos/senado_processo_detalhe. Para as tabelas do plenário (tipos de sessão, legislaturas) use senado_tabelas_plenario. Ex.: { tabela: 'tipos-prazo' } ou { tabela: 'siglas', filtro: 'PEC' }.

Inputs: tabela (required), filtro, limite. Returns: provenance, attribution

senado_tabelas_referenciaTabelas de referênciaA
Read-onlyIdempotent
Inspect

Consulta tabelas de referência do Senado pelo parâmetro tabela. Valores: tipos-materia → { count, tipos } (sigla/nome/descricao dos tipos de proposição, p.ex. PEC, PL, MPV) — catálogo curado mantido neste servidor (12 tipos mais comuns, não é a lista viva do upstream processo/siglas, que tem ~184 siglas); use para achar a sigla correta antes de senado_buscar_materias/senado_search_processos; partidos → { count, totalSenadores, partidos } (partidos com bancada atual, ordenados por nº de senadores); ufs → { count, totalSenadores, ufs } (as 27 UFs com a contagem de senadores em exercício); legislatura-atual → { numero, periodo, dataInicio, dataFim } da legislatura vigente; tipos-norma → { count, tipos } (sigla/descricao dos tipos de norma para senado_buscar_legislacao); tipos-uso-palavra → { count, tipos } (codigo/descricao para interpretar tipoUsoPalavra em senado_discursos_senador). Toda resposta inclui o campo tabela. Para a relação nominal de parlamentares use senado_listar_senadores.

Inputs: tabela (required). Returns: provenance, attribution

senado_terceirizadosTerceirizadosA
Read-onlyIdempotent
Inspect

Lista colaboradores terceirizados do Senado, filtráveis (busca parcial, sem acento) por nome, empresa contratada ou lotação. Retorna { count, total, terceirizados }, cada item com nome, cpf, situacao, empresa, lotacao e numeroContrato. A lista completa é baixada e filtrada no Worker; resultados limitados a limite (padrão 50, máx 500), com aviso ao truncar. Para a empresa contratante e seus contratos, use senado_empresas_contratadas.

Inputs: nome, limite, empresa, lotacao. Returns: provenance, attribution

senado_vetosVetos presidenciaisA
Read-onlyIdempotent
Inspect

Lista vetos presidenciais em apreciação pelo Congresso Nacional, por ano ou por status de tramitação. Retorna { count, total, aviso?, vetos }, com cada veto trazendo codigo, identificacao, ementa, emTramitacao, materiaVetada, tipo (total/parcial), assunto e dataLimiteVotacao (prazo de sobrestamento de pauta). limite controla o corte (padrão 100; aviso indica truncagem). Informe ano OU status (tramitando/antes-rcn/encerrados). Para o resultado da votação de um veto use senado_resultado_veto.

Inputs: ano, limite, status. Returns: provenance, attribution

senado_videos_taquigrafiaVídeos da taquigrafiaA
Read-onlyIdempotent
Inspect

Lista os vídeos e áudios (unidades descritivas) de uma sessão plenária ou reunião de comissão. Retorna { id, tipo, count, total, aviso?, videos } (sessão sem mídia no acervo → count/total 0 com aviso; ao passar de limite inclui aviso). A cobertura de mídia é mais ampla que a das notas: sessões conjuntas do Congresso costumam ter vídeos mesmo sem transcrição, cada item com codigo, data, descricao, orador, duracaoSegundos e os links urlVideo, urlAudio, urlThumbnail. Obtenha o id via senado_agenda_plenario/senado_resultado_plenario (sessão) ou senado_reuniao_comissao (reunião). Para a transcrição textual correspondente use senado_notas_taquigraficas, não esta.

Inputs: id (required), tipo, limite, orador. Returns: provenance, attribution

senado_votacao_comissaoVotações em comissãoA
Read-onlyIdempotent
Inspect

Lista votações em comissões. O parâmetro por (padrão comissao) define o eixo da consulta: por: comissao → exige siglaComissao; lista as votações daquela comissão. por: senador → exige codigoSenador; lista os votos do senador em comissões (filtro opcional comissao). por: materia → exige sigla, numero e ano (ex.: PL 2630/2020); lista as votações da proposição em comissões (filtro opcional comissao). Em todos os casos aceita período opcional dataInicio/dataFim (YYYYMMDD, filtrado pela data da reunião) e retorna { por, ...contexto, count, votacoes }, cada votação com codigo, data, comissao, reuniao, materia, descricao, totais publicados pela fonte (totalSim/totalNao/totalAbstencao; contados dos votos, com placarComputado: true, só quando a fonte não os traz) e votos (senador, partido, voto). Sem paginação. Períodos amplos podem estourar o tempo-limite da consulta (erro de timeout): prefira janelas de até 3 meses e divida períodos maiores em chamadas sucessivas. Obtenha siglas via senado_listar_comissoes, codigoSenador via senado_listar_senadores; para votações no plenário use senado_votos_materia. Atenção: o codigo de cada votação de comissão pertence a um espaço de numeração próprio e NÃO é válido em senado_obter_votacao (que é exclusivo de plenário) — podem coincidir numericamente, mas apontam para votações diferentes.

Inputs: ano, por, sigla, numero, +5 more. Returns: provenance, attribution

senado_votacoes_senadorVotações de um senadorA
Read-onlyIdempotent
Inspect

Lista as votações nominais de um senador, mostrando como votou em cada matéria. Retorna { periodo, count, votos }, cada voto com codigoSessao, codigoVotacao, data, materia, descricao, voto e resultado, ordenados da mais recente para a mais antiga. Sem período usa o ano corrente; informe ano ou o par dataInicio/dataFim (YYYYMMDD). Requer codigoSenador (obtenha via senado_listar_senadores); para detalhes de uma votação específica (votos de todos os senadores) use senado_obter_votacao — os dois códigos são aceitos, e codigoSessao resolve direto.

Inputs: codigoSenador (required), ano, dataFim, dataInicio. Returns: provenance, attribution

senado_votos_materiaVotos de uma matériaA
Read-onlyIdempotent
Inspect

Obtém as votações de uma matéria pelo codigoMateria. Retorna { codigoMateria, count, votacoes }, cada item com data, descricao, resultado e placar (totalSim/totalNao/totalAbstencao); com incluirVotos: true (padrão false) acrescenta votos[] (nome, partido, uf e voto de cada senador). Obtenha o codigoMateria via senado_buscar_materias ou senado_obter_materia.

Inputs: codigoMateria (required), incluirVotos. Returns: provenance, attribution

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 69 tools

    Disambiguation3/5

    The descriptions are unusually explicit and cross-reference alternatives, which helps a lot, but several tool families overlap meaningfully: buscar_materias vs search_processos, obter_materia vs obter_processo, and the multiple voting tools (votos_materia, search_votacoes, obter_votacao, votacoes_senador, votacao_comissao) require careful reading to choose correctly. There is also redundancy such as senadores_afastados overlapping with listar_senadores(emExercicio=false). Boundaries are mostly documented, but the overlap is broader than just one or two pairs.

    Naming Consistency4/5

    Nearly all tools use a readable snake_case pattern with the senado_ prefix, often followed by a domain and an action (senado_obter_materia, senado_listar_senadores, senado_ecidadania_listar_eventos). Deviations exist: some names are noun-only (senado_mesa, senado_vetos, senado_licitacoes), two use English 'search', and the generic search/fetch tools lack the prefix, but the overall pattern remains predictable.

    Tool Count1/5

    With 69 tools, the surface is far beyond what an agent can reliably scan and select from in normal use. Even though the domain is broad and many tools cover distinct subdomains, this is the extreme end of tool-count mismatch and will impose a heavy selection burden.

    Completeness4/5

    Coverage is very broad across legislative matters, processes, voting, committees, plenary, e-Cidadania, legislation, budget, personnel, contracts, and administrative data. Minor gaps remain, such as individual detail endpoints for some administrative entities (e.g. servidores, terceirizados, empresas), but the overall read-only lifecycle is well covered.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      Not graded
      maintenance
      Enables interaction with the Brazilian Chamber of Deputies Open Data API, providing access to information about legislators, legislative proposals, voting records, events, committees, and parliamentary activities through 57 typed and validated tools.
      63
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides access to the Brazilian Chamber of Deputies open data API. It enables users to search for deputies, track their expenses, and query legislative information such as bills and API endpoints.
      6
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query Brazilian Senate data including senators, bills, voting records, committees, and plenary sessions through natural language.
      26 npm
      7
      MIT