cristianoaredes/mcp-senado

MCP Senado Federal 🇧🇷 | Brazilian Senate Open Data API for AI Assistants

Official MCP Server for querying Brazilian Federal Senate (Senado Federal) legislative data via Claude, Cursor, Windsurf, and Continue.dev Access senator voting records, legislative proposals, committee activities, and congress sessions. 56 tools for legislative transparency, political research, and data journalism.

| Português | Documentação Completa |

📋 Índice

• Visão Geral
• Recursos Principais
• Instalação
• Início Rápido
• Ferramentas Disponíveis
• Modos de Implantação
• Configuração
• Exemplos de Uso
• Documentação
• Contribuindo
• Licença

🎯 Visão Geral

MCP Senado Federal é um servidor MCP (Model Context Protocol) de código aberto que conecta assistentes de inteligência artificial à API de Dados Abertos do Senado Federal do Brasil. Desenvolvido com TypeScript, oferece acesso programático a dados legislativos completos, incluindo informações sobre senadores, propostas legislativas, votações, comissões, partidos e sessões plenárias.

Por que usar?

• 🤖 Integração com IA: Use ChatGPT, Claude, Cursor, Windsurf para consultar dados do Senado
• 📊 Dados Oficiais: Acesso direto à fonte oficial de dados abertos do Senado Federal
• 🚀 Pronto para Produção: Circuit breaker, rate limiting, cache e monitoramento incluídos
• 🔒 Seguro e Confiável: Validação de entrada, conformidade com LGPD, tratamento robusto de erros
• 🌍 Deploy Global: Suporte para Docker, Cloudflare Workers (edge computing) e HTTP/REST
• 📚 Bem Documentado: Documentação completa em português e inglês

Casos de Uso

• Jornalismo de Dados: Análise automatizada de votações e propostas legislativas
• Pesquisa Acadêmica: Estudos sobre comportamento parlamentar e produção legislativa
• Transparência Pública: Ferramentas de acompanhamento da atividade legislativa
• Aplicações Cívicas: Chatbots e assistentes virtuais para educação política
• Análise Política: Dashboards e relatórios sobre o Congresso Nacional

✨ Recursos Principais

🛠️ 56 Ferramentas em 7 Categorias

🚀 Características Técnicas

• ⚡ Alto Desempenho: Cache em memória com LRU, otimização de requisições
• 🛡️ Resiliência: Circuit breaker para proteção contra falhas da API
• 📊 Monitoramento: Logs estruturados, métricas, health checks
• 🔄 Rate Limiting: Token bucket para controle de taxa de requisições
• 🎯 TypeScript Strict: Type-safe com inferência de tipos completa
• ✅ Testado: 211 testes (73% de cobertura), incluindo E2E
• 🐳 Containerizado: Imagem Docker otimizada multi-stage (~150MB)
• ⚡ Edge Computing: Deploy em Cloudflare Workers (300+ data centers)

🔐 Segurança e Conformidade

• ✅ Validação rigorosa de entrada com Zod schemas
• ✅ Sanitização automática de dados
• ✅ Mascaramento de PII (Personally Identifiable Information)
• ✅ Conformidade com LGPD (Lei Geral de Proteção de Dados)
• ✅ Autenticação opcional por token
• ✅ CORS configurável
• ✅ Rate limiting para prevenir abuso

📦 Instalação

Via NPM (Recomendado)

# Instalação global
npm install -g @aredes.me/mcp-senado

# Ou executar diretamente
npx @aredes.me/mcp-senado

Via Git (Desenvolvimento)

git clone https://github.com/cristianoaredes/mcp-senado.git
cd mcp-senado
npm install
npm run build

Requisitos

• Node.js 18.x ou superior
• npm 9.x ou superior
• Memória: Mínimo 512MB RAM
• Sistema Operacional: Linux, macOS, Windows (WSL2)

🚀 Início Rápido

Claude Desktop

Adicione ao arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "senado-federal": {
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Localização do arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor / Windsurf

Adicione às configurações MCP do editor:

{
  "mcpServers": {
    "senado-federal": {
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"]
    }
  }
}

Continue.dev

Adicione ao config.json:

{
  "mcpServers": [
    {
      "name": "senado-federal",
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"]
    }
  ]
}

Testando a Integração

Após configurar, pergunte ao seu assistente de IA:

"Liste os senadores do estado de São Paulo"
"Quais foram as últimas votações no Senado?"
"Mostre propostas sobre educação tramitando no Senado"

🛠️ Ferramentas Disponíveis

📚 Dados de Referência (10 ferramentas)

Acesso a dados fundamentais do sistema legislativo:

• ufs_listar - Lista todos os estados brasileiros (UFs)
• legislaturas_listar - Lista legislaturas do Senado Federal
• tipos_materia_listar - Lista tipos de proposições legislativas
• situacoes_materia_listar - Lista situações de tramitação
• tipos_comissao_listar - Lista tipos de comissões
• tipos_autor_listar - Lista tipos de autores
• tipos_sessao_listar - Lista tipos de sessões
• tipos_votacao_listar - Lista tipos de votações
• tipos_documento_listar - Lista tipos de documentos
• assuntos_listar - Lista classificações temáticas

👥 Senadores (13 ferramentas)

Informações completas sobre parlamentares:

• senadores_listar - Busca senadores com filtros (nome, partido, UF, legislatura)
• senador_detalhes - Detalhes completos de um senador específico
• senador_historico - Histórico parlamentar e mandatos anteriores
• senador_votacoes - Votações de um senador com filtros
• senador_materias - Propostas de autoria do senador
• senador_discursos - Discursos proferidos pelo senador
• senador_licencas - Licenças e afastamentos
• senador_comissoes - Participação em comissões
• senador_liderancas - Cargos de liderança ocupados
• senador_filiacao - Histórico de filiação partidária
• senador_profissoes - Profissões declaradas
• senador_apartes - Apartes realizados
• senador_relatorias - Relatorias de proposições

📜 Propostas Legislativas (12 ferramentas)

Acesso completo ao processo legislativo:

• materias_pesquisar - Busca avançada de proposições
• materia_detalhes - Informações detalhadas da proposição
• materia_texto - Texto integral da proposição
• materia_votacoes - Votações relacionadas
• materia_tramitacao - Histórico de tramitação
• materia_autores - Autores e coautores
• materia_relacionadas - Proposições relacionadas
• materia_emendas - Emendas apresentadas
• materia_pareceres - Pareceres emitidos
• materia_notas_tecnicas - Notas técnicas
• materia_audiencias - Audiências públicas relacionadas
• materia_documentos - Documentos anexos

🗳️ Votações (5 ferramentas)

Resultados de votações nominais e simbólicas:

• votacoes_listar - Lista votações com filtros
• votacao_detalhes - Detalhes de votação específica
• votacao_votos - Votos individuais dos senadores
• votacao_orientacoes - Orientações de bancadas
• votacao_resumo - Resumo estatístico da votação

🏛️ Comissões (5 ferramentas)

Informações sobre comissões parlamentares:

• comissoes_listar - Lista todas as comissões (permanentes e temporárias)
• comissao_detalhes - Detalhes de comissão específica
• comissao_membros - Composição da comissão
• comissao_reunioes - Calendário de reuniões
• comissao_materias - Propostas em análise

🎭 Partidos (5 ferramentas)

Dados sobre partidos e blocos parlamentares:

• partidos_listar - Lista partidos e blocos
• partido_detalhes - Informações do partido
• partido_membros - Senadores filiados
• partido_liderancas - Lideranças partidárias
• blocos_listar - Blocos parlamentares e coligações

📅 Sessões Plenárias (6 ferramentas)

Acompanhamento de sessões do plenário:

• sessoes_listar - Calendário de sessões
• sessao_detalhes - Detalhes de sessão específica
• sessao_votacoes - Votações da sessão
• sessao_discursos - Discursos proferidos
• sessao_ordem_dia - Ordem do dia
• sessao_expediente - Expediente da sessão

🌐 Modos de Implantação

1️⃣ Modo stdio (Padrão MCP)

Protocolo nativo para assistentes de IA:

# Via npx
npx @aredes.me/mcp-senado

# Via instalação global
mcp-senado

# Via código fonte
npm run dev

Uso: Integração direta com Claude Desktop, Cursor, Windsurf, Continue.dev

2️⃣ Modo HTTP/REST API

Servidor HTTP standalone para aplicações web:

# Desenvolvimento
npm run dev:http

# Produção
npm run start:http

# Porta personalizada
HTTP_PORT=8080 npm run start:http

Endpoints disponíveis:

GET  /health                    # Health check
POST /mcp                       # Protocolo MCP via JSON-RPC
GET  /sse                       # Streaming (Server-Sent Events)
GET  /info                      # Informações do servidor
GET  /api/tools                 # Lista todas as ferramentas
GET  /api/tools/:name           # Detalhes de ferramenta
POST /api/tools/:name           # Executa ferramenta
GET  /api/categories            # Lista categorias
GET  /api/tools/category/:cat   # Ferramentas por categoria

Exemplo de uso:

# Listar senadores de SP
curl -X POST http://localhost:3000/api/tools/senadores_listar \
  -H "Content-Type: application/json" \
  -d '{"uf": "SP"}'

# Health check
curl http://localhost:3000/health

# JSON-RPC (tools/list)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"demo","method":"tools/list"}'

# SSE streaming (somente leitura)
curl -N -H "Accept: text/event-stream" http://localhost:3000/sse

Autenticação (opcional):

HTTP_AUTH_ENABLED=true \
HTTP_AUTH_TOKEN=seu-token-secreto \
npm run start:http

# Requisição autenticada
curl -H "Authorization: Bearer seu-token-secreto" \
  http://localhost:3000/api/tools

3️⃣ Modo Docker

Deploy containerizado com isolamento completo:

Docker Compose (Recomendado):

# Iniciar
docker-compose up -d

# Ver logs
docker-compose logs -f

# Parar
docker-compose down

Docker manual:

# Build
docker build -t mcp-senado .

# Run
docker run -d \
  --name mcp-senado \
  -p 3000:3000 \
  -e HTTP_PORT=3000 \
  -e MCP_LOG_LEVEL=info \
  mcp-senado:latest

# Logs
docker logs -f mcp-senado

Características:

• 🐳 Imagem Alpine Linux (~150MB)
• 🔒 Execução como usuário não-root
• 🏥 Health check integrado
• 📊 Multi-stage build otimizado

4️⃣ Cloudflare Workers (Edge Computing)

Deploy global em 300+ data centers com Durable Objects para estado persistente:

🎯 Arquitetura com Durable Objects

O MCP Senado utiliza 4 Durable Objects para gerenciar estado distribuído:

Por que Durable Objects?

• 🔄 Estado persistente entre todas as requisições Workers
• 🌍 Consistência global através de todos os 300+ data centers
• ⚡ Performance com cache compartilhado e circuit breaker distribuído
• 📊 Métricas precisas agregadas de todas as instâncias Workers

📋 Pré-requisitos

1. Conta Cloudflare com acesso a Durable Objects (plano Workers Paid - $5/mês)
2. Wrangler CLI instalado

npm install -g wrangler
wrangler login

🚀 Deploy Passo a Passo

1. Build do projeto:

npm run build

Isso compila TypeScript para JavaScript e gera:

• build/workers/index.js - Entry point do Worker
• build/durable-objects/*.js - Código dos Durable Objects

2. Deploy inicial (development):

npm run deploy:workers
# ou manualmente:
wrangler deploy --env development

3. Deploy para produção:

npm run deploy:workers:production
# ou manualmente:
wrangler deploy --env production

4. Verificar deployment:

# Ver status dos Durable Objects
wrangler deployments list

# Logs em tempo real
wrangler tail

🔧 Configuração (wrangler.toml)

name = "mcp-senado"
main = "build/workers/index.js"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]

# Durable Objects Bindings
[[durable_objects.bindings]]
name = "CACHE"
class_name = "CacheDurableObject"
script_name = "mcp-senado"

[[durable_objects.bindings]]
name = "RATE_LIMITER"
class_name = "RateLimiterDurableObject"
script_name = "mcp-senado"

[[durable_objects.bindings]]
name = "CIRCUIT_BREAKER"
class_name = "CircuitBreakerDurableObject"
script_name = "mcp-senado"

[[durable_objects.bindings]]
name = "METRICS"
class_name = "MetricsDurableObject"
script_name = "mcp-senado"

# Migrations (necessário para criar DOs)
[[migrations]]
tag = "v1"
new_classes = ["CacheDurableObject", "RateLimiterDurableObject", "CircuitBreakerDurableObject", "MetricsDurableObject"]

# Variáveis de ambiente
[vars]
MCP_SERVER_NAME = "mcp-senado"
MCP_SERVER_VERSION = "1.0.0"
SENADO_API_BASE_URL = "https://legis.senado.leg.br/dadosabertos"
SENADO_API_TIMEOUT = "30000"

# Cache
MCP_CACHE_ENABLED = "true"
MCP_CACHE_TTL = "300000"  # 5 minutos

# Rate Limiting
MCP_RATE_LIMIT_ENABLED = "true"
MCP_RATE_LIMIT_MAX_TOKENS = "30"
MCP_RATE_LIMIT_REFILL_RATE = "0.5"  # 0.5 tokens/segundo

# Circuit Breaker
MCP_CIRCUIT_BREAKER_ENABLED = "true"
MCP_CIRCUIT_BREAKER_THRESHOLD = "5"   # Falhas para abrir
MCP_CIRCUIT_BREAKER_TIMEOUT = "60000" # 1 minuto

# Logging
MCP_LOG_LEVEL = "INFO"

# Ambientes
[env.development]
name = "mcp-senado-dev"
vars = { ENVIRONMENT = "development" }

[env.production]
name = "mcp-senado-prod"
vars = { ENVIRONMENT = "production" }
# Descomentar e configurar sua rota:
# route = "mcp-senado.seudominio.com/*"

🧪 Desenvolvimento Local

# Iniciar servidor de desenvolvimento com Durable Objects
npm run dev:workers

# Servidor estará disponível em:
# http://localhost:8787

Testando endpoints:

# Health check
curl http://localhost:8787/health

# Listar ferramentas MCP
curl http://localhost:8787/v1/tools/list

# Invocar ferramenta
curl -X POST http://localhost:8787/v1/tools/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_senator",
    "arguments": {"codigo": "5012"}
  }'

# Métricas (do MetricsDurableObject)
curl http://localhost:8787/v1/metrics/global

📊 Monitoramento de Durable Objects

1. Métricas globais:

curl https://mcp-senado-prod.seu-worker.workers.dev/v1/metrics/global

2. Estatísticas de cache:

curl https://mcp-senado-prod.seu-worker.workers.dev/v1/cache/stats

3. Status do circuit breaker:

curl https://mcp-senado-prod.seu-worker.workers.dev/v1/circuit-breaker/stats

4. Rate limiter status:

curl https://mcp-senado-prod.seu-worker.workers.dev/v1/rate-limiter/stats

🎯 Boas Práticas

1. Sempre faça build antes de deploy:

   npm run build && npm run deploy:workers
   

2. Teste localmente antes de produção:

   npm run dev:workers
   # Testar thoroughly
   npm run deploy:workers  # Deploy em dev primeiro
   

3. Monitor logs em produção:

   wrangler tail --env production
   

4. Use variáveis de ambiente corretas para cada ambiente:

   • Development: mais logs, cache TTL menor
   • Production: logs INFO/WARN, cache TTL otimizado

💰 Custos

Cloudflare Workers + Durable Objects:

Estimativa de custos para 1M requisições/mês:

• Workers: ~$0-5 (dependendo do uso)
• Durable Objects: ~$0-5 (storage + requests)
• Total: ~$5-10/mês para tráfego moderado

🔐 Segurança

Secrets (valores sensíveis):

# Definir API key (opcional)
wrangler secret put MCP_API_KEY --env production

# Definir tokens de autenticação
wrangler secret put WORKERS_AUTH_TOKEN --env production

Habilitar autenticação no Worker:

[env.production.vars]
WORKERS_AUTH_ENABLED = "true"

Então use o header Authorization nas requisições:

curl -H "Authorization: Bearer seu-token-aqui" \
  https://mcp-senado-prod.seu-worker.workers.dev/v1/tools/list

✨ Benefícios do Deploy com Durable Objects

• ⚡ Zero cold starts - Workers sempre quentes
• 🌍 Latência ultra-baixa - 300+ data centers globalmente
• 🔄 Cache persistente - Compartilhado entre todas as requisições
• 🛡️ Circuit breaker distribuído - Proteção contra falhas da API do Senado
• 📊 Métricas precisas - Analytics em tempo real agregadas
• 📈 Escalabilidade automática - De 0 a milhões de requisições
• 💰 Custo otimizado - Pague apenas pelo que usar
• 🔐 DDoS protection - Incluído automaticamente
• 🚀 Deploy em segundos - CI/CD integrado
• 🧪 Desenvolvimento local fácil - Emulador completo de DOs

5️⃣ Dokploy em VPS Hostinger

Implantação orquestrada pelo Dokploy em um VPS Hostinger aproveitando o mesmo Dockerfile e variáveis de ambiente do projeto.

• ✅ Ideal para fluxos de CI/CD self-hosted com pipelines Git
• 🔒 Mantém suporte a autenticação HTTP (HTTP_AUTH_TOKEN) e CORS customizado
• ⚙️ Compatível com tempo de execução Docker ou Node dentro do Dokploy
• 📘 Guia completo em

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# API do Senado Federal
SENADO_API_BASE_URL=https://legis.senado.leg.br/dadosabertos
SENADO_API_TIMEOUT=30000
SENADO_API_MAX_RETRIES=3
SENADO_API_RETRY_DELAY=1000

# Servidor HTTP (opcional)
HTTP_PORT=3000
HTTP_HOST=0.0.0.0
HTTP_CORS_ORIGIN=*
HTTP_AUTH_ENABLED=false
HTTP_AUTH_TOKEN=
HTTP_REQUEST_TIMEOUT=30000

# Transporte (stdio | http)
MCP_TRANSPORT=http

# Cache
MCP_CACHE_ENABLED=true
MCP_CACHE_TTL=300000
MCP_CACHE_MAX_SIZE=1000
MCP_CACHE_CLEANUP_INTERVAL=60000

# Rate Limiting
MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_TOKENS=30
MCP_RATE_LIMIT_INTERVAL=60000
MCP_RATE_LIMIT_REFILL_RATE=2000

# Circuit Breaker
MCP_CIRCUIT_BREAKER_ENABLED=true
MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
MCP_CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2
MCP_CIRCUIT_BREAKER_TIMEOUT=60000

# Logging
MCP_LOG_LEVEL=info  # debug | info | warn | error
MCP_LOG_FORMAT=json  # json | text
MCP_LOG_MASK_PII=true

# Ambiente
NODE_ENV=production  # development | production | test

Configuração Avançada

Performance:

# Cache agressivo (ideal para dados que mudam pouco)
MCP_CACHE_TTL=3600000       # 1 hora em ms
MCP_CACHE_MAX_SIZE=5000     # Mais entradas

# Rate limiting relaxado (para uso interno)
MCP_RATE_LIMIT_TOKENS=100
MCP_RATE_LIMIT_INTERVAL=60000

Segurança:

# Produção segura
HTTP_AUTH_ENABLED=true
HTTP_AUTH_TOKEN=token-forte-aqui
HTTP_CORS_ORIGIN=https://meu-dominio.com
MCP_LOG_MASK_PII=true

Debug:

# Modo de desenvolvimento
NODE_ENV=development
MCP_LOG_LEVEL=debug
MCP_LOG_FORMAT=text
MCP_CACHE_ENABLED=false  # Facilita debug

💡 Exemplos de Uso

Exemplo 1: Consultar Senadores

Prompt para IA:

"Liste todos os senadores do estado de São Paulo na legislatura atual"

Resposta esperada:

• Nome completo de cada senador
• Partido político
• Telefones e emails de contato
• Período do mandato

Exemplo 2: Pesquisar Propostas

Prompt para IA:

"Busque propostas legislativas sobre educação que estão tramitando"

Resultado:

• Lista de PLs (Projetos de Lei)
• Ementa e descrição
• Status de tramitação
• Autores

Exemplo 3: Acompanhar Votações

Prompt para IA:

"Mostre as votações do Senado nos últimos 7 dias e como cada senador votou"

Informações retornadas:

• Data e hora da votação
• Matéria votada
• Resultado (aprovado/rejeitado)
• Votos individuais por senador
• Orientação das bancadas

Exemplo 4: Análise de Comissões

Prompt para IA:

"Quais comissões permanentes estão ativas e quem são os presidentes?"

Dados fornecidos:

• Nome da comissão
• Sigla
• Presidente atual
• Vice-presidente
• Número de membros

Exemplo 5: Uso via API HTTP

# Consultar votações recentes
curl -X POST http://localhost:3000/api/tools/votacoes_listar \
  -H "Content-Type: application/json" \
  -d '{
    "dataInicio": "2024-01-01",
    "dataFim": "2024-12-31",
    "pagina": 1,
    "itensPorPagina": 10
  }'

# Detalhes de um senador
curl -X POST http://localhost:3000/api/tools/senador_detalhes \
  -H "Content-Type: application/json" \
  -d '{"codigo": 5012}'

# Propostas por tipo
curl -X POST http://localhost:3000/api/tools/materias_pesquisar \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "PL",
    "ano": "2024",
    "tramitando": true
  }'

📚 Documentação

Documentação Oficial

• - Documentação em inglês
• - Como contribuir com o projeto
• - Normas da comunidade
• - Política de segurança
• - Histórico de versões
• - Planejamento futuro

Recursos Externos

• API Dados Abertos do Senado - Documentação oficial da API
• Model Context Protocol - Especificação MCP
• TypeScript - Documentação TypeScript
• Vitest - Framework de testes

Suporte e Comunidade

• 🐛 Issues: GitHub Issues
• 💬 Discussões: GitHub Discussions
• 📧 Email: Contato com mantenedores
• 🌟 Star no GitHub: Mostre seu apoio!

🤝 Contribuindo

Contribuições são muito bem-vindas! Este é um projeto open-source mantido pela comunidade.

Como Contribuir

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/minha-feature)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
4. Push para a branch (git push origin feature/minha-feature)
5. Abra um Pull Request

Diretrizes

• ✅ Escreva testes para novas funcionalidades
• ✅ Mantenha cobertura de testes > 70%
• ✅ Siga o style guide TypeScript
• ✅ Documente alterações no código
• ✅ Use commits semânticos (conventional commits)
• ✅ Atualize documentação quando necessário

Áreas que Precisam de Ajuda

• 📝 Documentação de ferramentas específicas
• 🧪 Testes adicionais (E2E, integração)
• 🌍 Traduções (inglês, espanhol)
• 🎨 Exemplos de uso
• 🐛 Correção de bugs
• ⚡ Otimizações de performance

Veja para guia completo e o manual resumido em para agentes MCP ou contribuintes que precisam de uma visão rápida das diretrizes.

🏗️ Arquitetura

Estrutura do Projeto

mcp-senado/
├── lib/                      # Código fonte
│   ├── adapters/            # Adaptadores de transporte
│   │   ├── http.ts          # Adaptador HTTP/REST
│   │   └── workers.ts       # Adaptador Cloudflare Workers
│   ├── bin/                 # Entry points CLI
│   │   ├── mcp-senado.ts        # stdio (MCP)
│   │   └── mcp-senado-http.ts   # HTTP server
│   ├── config/              # Configuração
│   ├── core/                # Lógica core MCP
│   │   ├── mcp-server.ts    # Servidor MCP principal
│   │   ├── tools.ts         # Registry de ferramentas
│   │   ├── validation.ts    # Validação com Zod
│   │   └── errors.ts        # Tratamento de erros
│   ├── infrastructure/      # Infraestrutura
│   │   ├── cache.ts         # Cache LRU
│   │   ├── circuit-breaker.ts
│   │   ├── http-client.ts   # Cliente HTTP
│   │   ├── logger.ts        # Logging estruturado
│   │   └── rate-limiter.ts  # Rate limiting
│   ├── tools/               # Implementação das ferramentas
│   │   ├── reference-tools.ts
│   │   ├── senator-tools.ts
│   │   ├── proposal-tools.ts
│   │   ├── voting-tools.ts
│   │   ├── committee-tools.ts
│   │   ├── party-tools.ts
│   │   └── session-tools.ts
│   ├── types/               # Definições TypeScript
│   └── workers/             # Cloudflare Workers
├── test/                     # Testes
│   ├── core/                # Testes unitários core
│   ├── e2e/                 # Testes E2E
│   ├── infrastructure/      # Testes infra
│   └── integration/         # Testes integração
├── .github/workflows/       # CI/CD
└── docker/                   # Docker configs

Stack Tecnológica

• Runtime: Node.js 18+
• Linguagem: TypeScript 5.7+ (strict mode)
• Framework MCP: @modelcontextprotocol/sdk
• HTTP Server: Express 5.x
• Validação: Zod
• Testes: Vitest (211 testes, 73% coverage)
• Build: TypeScript Compiler
• Deploy: Docker, Cloudflare Workers
• CI/CD: GitHub Actions

📈 Status do Projeto

Métricas

• ✅ 211 testes passando (2 skipped)
• ✅ 73% cobertura de código
• ✅ 56 ferramentas implementadas
• ✅ 7 categorias de dados
• ✅ 4 modos de deployment
• ✅ 0 vulnerabilidades de segurança

Versão Atual

v0.1.0 - Primeira versão pública

• Core MCP server completo
• 56 ferramentas funcionais
• 4 adaptadores de transporte
• Documentação completa
• CI/CD configurado

Próximos Passos

• Publicação no NPM oficial
• Suporte a webhooks do Senado
• Interface web de demonstração
• Expansão para Câmara dos Deputados
• SDK JavaScript/TypeScript
• Integração com mais assistentes de IA

Veja para planejamento completo.

❓ Perguntas Frequentes (FAQ)

O que é MCP Senado Federal?

MCP Senado é um servidor oficial do Model Context Protocol que conecta assistentes de IA à API de Dados Abertos do Senado Federal Brasileiro, permitindo consultas sobre senadores, propostas legislativas, votações e atividades do Congresso.

Como integrar com Claude Desktop?

Adicione a seguinte configuração ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "senado-federal": {
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"]
    }
  }
}

Localização do arquivo:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Posso usar para pesquisa política?

Sim! O MCP Senado oferece 56 ferramentas perfeitas para pesquisa política, jornalismo de dados e estudos acadêmicos sobre comportamento legislativo brasileiro.

Os dados são oficiais e atualizados?

Todos os dados vêm diretamente da API oficial de Dados Abertos do Senado Federal (https://legis.senado.leg.br/dadosabertos), mantida pelo governo brasileiro.

Quais idiomas são suportados?

O servidor suporta português (PT-BR) e inglês. Os nomes das ferramentas estão em português, mas a documentação é totalmente bilíngue.

Posso fazer deploy em produção?

Sim! Faça deploy via Docker, Cloudflare Workers (com Durable Objects) ou como servidor HTTP/REST standalone. Veja a documentação de deployment.

É gratuito?

Sim! O projeto é open-source (licença MIT) e a API do Senado é pública e gratuita. Se você usar Cloudflare Workers, há um plano gratuito disponível (com limitações).

Como contribuir com o projeto?

Contribuições são muito bem-vindas! Veja o guia completo em e o resumo em .

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo para detalhes.

Termos

• ✅ Uso comercial permitido
• ✅ Modificação permitida
• ✅ Distribuição permitida
• ✅ Uso privado permitido
• ⚠️ Sem garantias
• ⚠️ Limitação de responsabilidade

🙏 Agradecimentos

• Senado Federal - Pela API de Dados Abertos
• Anthropic - Pelo Model Context Protocol
• Comunidade Open Source - Por tornar isso possível
• Contribuidores - Obrigado por cada PR e issue!

📞 Contato

• GitHub: @cristianoaredes
• Issues: Reportar bug ou sugerir feature
• Discussions: Fórum da comunidade

Feito com ❤️ para a transparência e democracia brasileira
_{Dados abertos • Código aberto • Democracia aberta}

⬆️ Voltar ao topo