🏛️ MCP Câmara BR
Servidor MCP (Model Context Protocol) completo para a API de Dados Abertos da Câmara dos Deputados do Brasil.
Visão Geral
O mcp-camara-br é um servidor MCP que expõe todas as funcionalidades da API de Dados Abertos da Câmara dos Deputados através de tools tipadas, validadas e otimizadas para uso com Large Language Models (LLMs).
Características
- ✅ Cobertura Completa - Mapeia os principais endpoints da API da Câmara
- ✅ Validação Rigorosa - Inputs validados com Zod
- ✅ Cache Inteligente - Sistema de cache em camadas com TTL diferenciado
- ✅ Rate Limiting - Proteção contra sobrecarga da API
- ✅ Circuit Breaker - Resiliência a falhas
- ✅ Métricas - Observabilidade completa (Prometheus-ready)
- ✅ Type-Safe - 100% TypeScript
- ✅ Docker Ready - Containerizado e pronto para deploy
🚀 Início Rápido (5 minutos)
1. Instalar dependências
npm install
2. Compilar
npm run build
3. Configurar no Claude Desktop
Edite o 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
Adicione a configuração:
macOS/Linux:
{
"mcpServers": {
"camara-br": {
"command": "node",
"args": ["/caminho/completo/para/AgenteCidadaoMCP/dist/server.js"]
}
}
}
Windows (use barras duplas \\):
{
"mcpServers": {
"camara-br": {
"command": "node",
"args": ["C:\\Users\\SeuUsuario\\AgenteCidadaoMCP\\dist\\server.js"]
}
}
}
⚠️ Importante para Windows: Use barras duplas (
\\) nos caminhos. Veja o Guia Windows para mais detalhes.
4. Reiniciar Claude Desktop
Feche e abra o Claude Desktop novamente.
Requisitos
- Node.js >= 20.0.0
- npm ou yarn
📖 Guias de Instalação Detalhados
Escolha o guia apropriado para seu sistema operacional:
- Windows 11/10: Veja o Guia de Instalação para Windows
- macOS/Linux: Continue com as instruções abaixo ou veja o Guia de Instalação Completo
- Início Rápido: Para desenvolvedores experientes, veja Início Rápido
Instalação Completa
# Clonar o repositório
git clone https://github.com/gvc2000/AgenteCidadaoMCP.git
cd AgenteCidadaoMCP
# Instalar dependências
npm install
# Copiar arquivo de configuração
cp .env.example .env
# Build
npm run build
# Executar
npm start
Uso com Docker
# Build da imagem
docker-compose build
# Executar
docker-compose up -d
# Ver logs
docker-compose logs -f
# Parar
docker-compose down
Uso via HTTP (API REST)
O servidor também pode ser executado em modo HTTP, expondo uma API REST:
# Executar servidor HTTP
npm run start:http
# Ou em desenvolvimento com hot-reload
npm run dev:http
Endpoints HTTP
GET /- Informações da APIGET /api/tools- Lista todas as ferramentas disponíveisPOST /api/tools/:toolName- Executa uma ferramentaGET /health- Health checkGET /metrics- Métricas PrometheusGET /metrics/json- Métricas em JSON
Exemplo de Uso HTTP
# Buscar deputados
curl -X POST http://localhost:9090/api/tools/buscar_deputados \
-H "Content-Type: application/json" \
-d '{"uf":"SP","pagina":1,"itens":10}'
Configuração
Edite o arquivo .env para personalizar as configurações:
# API Configuration
API_BASE_URL=https://dadosabertos.camara.leg.br/api/v2
# Cache
CACHE_ENABLED=true
CACHE_TTL_SECONDS=600
# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=100
# Metrics
METRICS_ENABLED=true
METRICS_PORT=9090
🛠️ Tools Disponíveis (57 tools)
Tools de Ajuda
sugerir_ferramentas- Sugere quais tools usar para uma consultadiagnosticar_consulta- Analisa objetivo e sugere fluxo completo de tools
Deputados (9)
buscar_deputados- Busca deputados por nome, UF, partido, etc.detalhar_deputado- Informações detalhadas de um deputadodespesas_deputado- Despesas da cota parlamentardiscursos_deputado- Discursos proferidoseventos_deputado- Eventos que participoufrentes_deputado- Frentes parlamentares das quais é membroocupacoes_deputado- Histórico de ocupações na Câmaraorgaos_deputado- Órgãos dos quais é membroprofissoes_deputado- Profissões declaradas
Proposições (7)
buscar_proposicoes- Busca proposições legislativas (PLs, PECs, MPs, etc.)detalhar_proposicao- Informações detalhadas de uma proposiçãoautores_proposicao- Lista os autores de uma proposiçãotramitacoes_proposicao- Histórico de tramitaçãovotacoes_proposicao- Votações da proposiçãorelacionadas_proposicao- Proposições relacionadastemas_proposicao- Temas/assuntos da proposição
Votações (5)
buscar_votacoes- Busca votações por período ou proposiçãodetalhar_votacao- Resultado geral de uma votaçãovotos_votacao- Voto individual de cada deputadoorientacoes_votacao- Orientação dos partidosultimas_votacoes- Votações mais recentes
Eventos (6)
buscar_eventos- Busca reuniões e sessões por períododetalhar_evento- Informações de um eventodeputados_evento- Deputados presentespauta_evento- Pauta do eventovotacoes_evento- Votações realizadasorgaos_evento- Órgãos participantes
Órgãos (5)
buscar_orgaos- Busca comissões e órgãosdetalhar_orgao- Informações de um órgãomembros_orgao- Composição atualeventos_orgao- Eventos do órgãovotacoes_orgao- Votações do órgão
Partidos (4)
buscar_partidos- Lista partidosdetalhar_partido- Informações de um partidomembros_partido- Deputados do partidolideres_partido- Liderança do partido
Frentes Parlamentares (3)
buscar_frentes- Busca frentes parlamentaresdetalhar_frente- Informações de uma frentemembros_frente- Membros da frente
Blocos (2)
buscar_blocos- Busca blocos partidáriosdetalhar_bloco- Informações de um bloco
Legislaturas (3)
buscar_legislaturas- Lista legislaturasdetalhar_legislatura- Informações de uma legislaturamesa_legislatura- Mesa Diretora
Referências (5)
situacoes_proposicao- Situações possíveis de proposiçõestipos_proposicao- Tipos de proposições (PL, PEC, etc.)tipos_orgao- Tipos de órgãos da Câmaratipos_evento- Tipos de eventosufs- Unidades Federativas
Análises (6)
analise_presenca- Taxa de presença de deputadosranking_proposicoes- Ranking de proposiçõesanalise_despesas_partido- Despesas agregadas por partidocomparativo_votacoes- Compara votaçõestimeline_tramitacao- Timeline de tramitaçãoexportar_dados- Exporta dados para CSV/JSON
💬 Exemplos de Uso
Buscar Deputados de SP do PT
Liste deputados do estado de São Paulo no partido PT
Ou via JSON:
{
"tool": "buscar_deputados",
"arguments": {
"uf": "SP",
"partido": "PT",
"pagina": 1,
"itens": 10
}
}
Buscar Proposições sobre Educação
Busque projetos de lei sobre educação apresentados em 2024
Ou via JSON:
{
"tool": "buscar_proposicoes",
"arguments": {
"keywords": "educação",
"ano": 2024,
"pagina": 1,
"itens": 20
}
}
Frentes Parlamentares de um Deputado
Quais frentes parlamentares o deputado Guilherme Boulos participa?
Análise Completa de um Deputado
Me conte sobre a deputada Tabata Amaral:
- Suas frentes parlamentares
- Despesas de janeiro de 2024
- Discursos recentes sobre educação
Despesas de um Deputado
Mostre as despesas do deputado Guilherme Boulos em janeiro de 2024
Ou via JSON (usando ID):
{
"tool": "despesas_deputado",
"arguments": {
"id": 220000,
"ano": 2024,
"mes": 1
}
}
Monitoramento
Métricas
O servidor expõe métricas no formato Prometheus:
# Métricas Prometheus
curl http://localhost:9090/metrics
# Métricas JSON
curl http://localhost:9090/metrics/json
# Health check
curl http://localhost:9090/health
Logs
Os logs são estruturados em JSON (padrão) ou formato pretty para desenvolvimento:
# Ativar logs pretty
LOG_FORMAT=pretty npm start
📁 Estrutura do Projeto
AgenteCidadaoMCP/
├── src/ # Código-fonte do MCP Server
│ ├── server.ts # Entry point
│ ├── mcp.ts # MCP server setup
│ ├── config.ts # Configurações
│ │
│ ├── api/ # Cliente HTTP e comunicação
│ │ ├── client.ts # Cliente HTTP com retry
│ │ └── normalizers.ts # Normalização de dados
│ │
│ ├── core/ # Sistemas core
│ │ ├── cache.ts # Sistema de cache LRU
│ │ ├── errors.ts # Classes de erro customizadas
│ │ ├── logging.ts # Logs estruturados (Pino)
│ │ ├── metrics.ts # Métricas Prometheus
│ │ ├── rate-limiter.ts # Rate limiting (token bucket)
│ │ ├── circuit-breaker.ts # Circuit breaker pattern
│ │ ├── queue.ts # Fila de requisições
│ │ └── schemas.ts # Schemas Zod compartilhados
│ │
│ ├── tools/ # MCP Tools organizados por categoria
│ │ ├── deputados/ # 10 tools sobre deputados
│ │ ├── proposicoes/ # 8 tools sobre proposições
│ │ ├── votacoes/ # 5 tools sobre votações
│ │ ├── orgaos/ # 6 tools sobre órgãos
│ │ ├── eventos/ # 7 tools sobre eventos
│ │ ├── partidos/ # 5 tools sobre partidos
│ │ ├── legislaturas/ # 4 tools sobre legislaturas
│ │ ├── frentes/ # 4 tools sobre frentes
│ │ ├── blocos/ # 3 tools sobre blocos
│ │ ├── referencias/ # 6 tools de referência
│ │ └── analises/ # 7 tools de análise e export
│ │
│ └── utils/ # Utilitários
│ ├── aggregators.ts # Agregação de dados
│ ├── currency.ts # Formatação de moeda
│ ├── date.ts # Utilitários de data
│ └── sanitizers.ts # Sanitização de inputs
│
├── frontend/ # Interface Web
│ ├── current/ # Versão atual (v4)
│ │ ├── index.html # Interface principal
│ │ ├── admin-agente-cidadao.html
│ │ ├── demo-agente-cidadao.html
│ │ └── login-agente-cidadao.html
│ ├── archive/ # Versões anteriores
│ └── README.md # Documentação do frontend
│
├── docs/ # Documentação organizada
│ ├── guides/ # Guias de instalação e uso
│ │ ├── GUIA_INSTALACAO_USO.md
│ │ └── INICIO_RAPIDO.md
│ ├── examples/ # Exemplos práticos
│ │ ├── EXEMPLOS_PRATICOS.md
│ │ └── EXEMPLOS_TESTES.md
│ ├── testing/ # Planos e relatórios de testes
│ ├── process/ # Artefatos de processo
│ ├── specs/ # Especificações técnicas
│ │ └── mcp-camara-br-especificacao-completa.md
│ └── README.md # Índice da documentação
│
├── scripts/ # Scripts utilitários
│ └── healthcheck.sh # Health check para deploy
│
├── .github/ # GitHub Actions
│ └── workflows/
│ ├── ci.yml # CI/CD pipeline
│ └── release.yml # Release automation
│
├── dist/ # Código compilado (gerado)
│
├── .env.example # Template de variáveis de ambiente
├── .dockerignore # Arquivos ignorados no Docker build
├── .npmignore # Arquivos ignorados no npm publish
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Docker Compose config
├── package.json # Configuração npm
├── tsconfig.json # Configuração TypeScript
│
├── README.md # Este arquivo
├── CONTRIBUTING.md # Guia de contribuição
├── CLAUDE.md # Guia para assistentes de IA
└── LICENSE # Licença MIT
Desenvolvimento
# Modo desenvolvimento com watch
npm run dev
# Testes
npm test
# Cobertura de testes
npm run test:coverage
# Linting
npm run lint
# Formatação
npm run format
# Type checking
npm run type-check
⚡ Performance
O servidor implementa várias otimizações:
- Cache em Camadas: Diferentes TTLs por tipo de dado
- Rate Limiting: Token bucket algorithm
- Circuit Breaker: Previne cascata de falhas
- Request Queue: Controla concorrência
- Retry Logic: Exponential backoff com jitter
🔄 CI/CD
O projeto possui workflows automatizados do GitHub Actions:
CI (Integração Contínua)
- ✅ Type checking (TypeScript)
- ✅ Linting (ESLint)
- ✅ Formatação (Prettier)
- ✅ Testes automatizados
- ✅ Build em Node.js 20.x e 21.x
- ✅ Build Docker
Release (Publicação)
- 🚀 Criação automática de releases no GitHub
- 🚀 Build de imagens Docker em tags
- 📦 Preparado para publicação no npm (requer configuração)
Configuração:
Os workflows estão em .github/workflows/:
ci.yml- Executado em push/PR para main/developrelease.yml- Executado ao criar tags (v*)
📚 Documentação Completa
Guias
- Início Rápido - Comece em 5 minutos
- Guia de Instalação e Uso - Instalação e configuração completas
Exemplos e Testes
- Exemplos Práticos - Casos de uso com LLMs
- Exemplos de Testes - Validação e testes
Especificações
- Especificação Técnica Completa - Documentação técnica detalhada
Integrações
- Sistema Multi-Agentes n8n - Arquitetura de orquestração de agentes especialistas
Para Desenvolvedores
- Guia de Contribuição - Como contribuir com o projeto
- Guia para IA (CLAUDE.md) - Instruções para assistentes de IA
Índice Completo
- Documentação Organizada - Índice completo de toda documentação
🤝 Contribuindo
Contribuições são muito bem-vindas! Este projeto segue boas práticas de desenvolvimento e possui diretrizes claras para contribuidores.
Antes de contribuir, leia:
- CONTRIBUTING.md - Guia completo de contribuição com padrões de código, workflow e boas práticas
Resumo rápido:
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/MinhaFeature) - Siga os padrões de código (TypeScript strict, ESLint, Prettier)
- Escreva testes para novas funcionalidades
- Commit usando Conventional Commits (
feat:,fix:, etc.) - Push para a branch (
git push origin feature/MinhaFeature) - Abra um Pull Request com descrição detalhada
Scripts úteis para desenvolvimento:
npm run validate # Executa type-check + lint + format-check + tests
npm run lint:fix # Corrige problemas de lint automaticamente
npm run format # Formata o código com Prettier
Licença
MIT License - veja o arquivo LICENSE para detalhes.
🔗 Links
Suporte
Para reportar bugs ou solicitar features, abra uma issue.
Desenvolvido com ❤️ para democratização de dados públicos