🏛️ 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 API
GET /api/tools - Lista todas as ferramentas disponíveis
POST /api/tools/:toolName - Executa uma ferramenta
GET /health - Health check
GET /metrics - Métricas Prometheus
GET /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 consulta
diagnosticar_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 deputado
despesas_deputado - Despesas da cota parlamentar
discursos_deputado - Discursos proferidos
eventos_deputado - Eventos que participou
frentes_deputado - Frentes parlamentares das quais é membro
ocupacoes_deputado - Histórico de ocupações na Câmara
orgaos_deputado - Órgãos dos quais é membro
profissoes_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ção
autores_proposicao - Lista os autores de uma proposição
tramitacoes_proposicao - Histórico de tramitação
votacoes_proposicao - Votações da proposição
relacionadas_proposicao - Proposições relacionadas
temas_proposicao - Temas/assuntos da proposição

Votações (5)

buscar_votacoes - Busca votações por período ou proposição
detalhar_votacao - Resultado geral de uma votação
votos_votacao - Voto individual de cada deputado
orientacoes_votacao - Orientação dos partidos
ultimas_votacoes - Votações mais recentes

Eventos (6)

buscar_eventos - Busca reuniões e sessões por período
detalhar_evento - Informações de um evento
deputados_evento - Deputados presentes
pauta_evento - Pauta do evento
votacoes_evento - Votações realizadas
orgaos_evento - Órgãos participantes

Órgãos (5)

buscar_orgaos - Busca comissões e órgãos
detalhar_orgao - Informações de um órgão
membros_orgao - Composição atual
eventos_orgao - Eventos do órgão
votacoes_orgao - Votações do órgão

Partidos (4)

buscar_partidos - Lista partidos
detalhar_partido - Informações de um partido
membros_partido - Deputados do partido
lideres_partido - Liderança do partido

Frentes Parlamentares (3)

buscar_frentes - Busca frentes parlamentares
detalhar_frente - Informações de uma frente
membros_frente - Membros da frente

Blocos (2)

buscar_blocos - Busca blocos partidários
detalhar_bloco - Informações de um bloco

Legislaturas (3)

buscar_legislaturas - Lista legislaturas
detalhar_legislatura - Informações de uma legislatura
mesa_legislatura - Mesa Diretora

Referências (5)

situacoes_proposicao - Situações possíveis de proposições
tipos_proposicao - Tipos de proposições (PL, PEC, etc.)
tipos_orgao - Tipos de órgãos da Câmara
tipos_evento - Tipos de eventos
ufs - Unidades Federativas

Análises (6)

analise_presenca - Taxa de presença de deputados
ranking_proposicoes - Ranking de proposições
analise_despesas_partido - Despesas agregadas por partido
comparativo_votacoes - Compara votações
timeline_tramitacao - Timeline de tramitação
exportar_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/develop
release.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

AgenteCidadaoMCP