senado-br-mcp-cloudflare

# Senado Brasil MCP Server

![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-1f6feb)
![Tools](https://img.shields.io/badge/tools-67-2ea44f)
[![CI](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
[![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-senado-br-mcp-cloudflare)](https://lobehub.com/mcp/sidneybissoli-senado-br-mcp-cloudflare)
[![smithery badge](https://smithery.ai/badge/sidneybissoli/senado-br-mcp-cloudflare)](https://smithery.ai/servers/sidneybissoli/senado-br-mcp-cloudflare)
[![senado-br-mcp-cloudflare MCP server](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare/badges/score.svg)](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare)
[![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/senado-br-mcp-cloudflare?style=flat&logo=github)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
[![License: MIT](https://img.shields.io/github/license/SidneyBissoli/senado-br-mcp-cloudflare)](LICENSE)
[![Status](https://img.shields.io/website?url=https%3A%2F%2Fsenado.sidneybissoli.com%2Fhealth&up_message=online&down_message=offline&label=status)](https://senado.sidneybissoli.com/status)

🇧🇷 [Leia em Português](README.pt-BR.md)

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 **67 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](https://legis.senado.leg.br/dadosabertos/), the [administrative open-data API](https://adm.senado.gov.br/adm-dadosabertos/swagger-ui/index.html), and the e-Cidadania portal. All tool responses are in Portuguese (pt-BR). See [CHANGELOG.md](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.

## 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`

### Install (any client)

For clients that launch MCP servers as a command — and for one-command setup — use the
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. **No build, no config, no key:**

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

- **One-click (LobeHub):** open the [server page](https://lobehub.com/mcp/sidneybissoli-senado-br-mcp-cloudflare) and click **Install**.
- **Native remote URL** (Claude Desktop/Code and other Streamable-HTTP clients): see [Connecting MCP Clients](#connecting-mcp-clients).

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
67 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published
as [`senado-br-mcp`](https://www.npmjs.com/package/senado-br-mcp).

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

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

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

```bash
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](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/overview)
at [`.claude/skills/senado-br/`](.claude/skills/senado-br/SKILL.md) that teaches Claude **when** to reach for
this server and **how** to use its 67 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/sdk` 1.26.0+ (per-request McpServer instances)
- **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](#e-cidadania-d1-backed-cron-refreshed))
- **Rate limiting:** Token bucket — global (8 req/s) + per-client (2 req/s)
- **Upstream throttle:** Max 6 concurrent requests, 10s timeout, retry with exponential backoff
- **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