# 🏛️ 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

```bash
npm install
```

### 2. Compilar

```bash
npm run build
```

### 3. Configurar no Claude Desktop

Edite o arquivo de configuração:

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```

Adicione a configuração:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "camara-br": {
      "command": "node",
      "args": ["/caminho/completo/para/AgenteCidadaoMCP/dist/server.js"]
    }
  }
}
```

**Windows (use barras duplas `\\`):**
```json
{
  "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](./GUIA_INSTALACAO_WINDOWS.md) 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](./GUIA_INSTALACAO_WINDOWS.md)
- **macOS/Linux**: Continue com as instruções abaixo ou veja o [Guia de Instalação Completo](./docs/guides/GUIA_INSTALACAO_USO.md)
- **Início Rápido**: Para desenvolvedores experientes, veja [Início Rápido](./docs/guides/INICIO_RAPIDO.md)

## Instalação Completa

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

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

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

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

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

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

```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):

```json
{
  "tool": "despesas_deputado",
  "arguments": {
    "id": 220000,
    "ano": 2024,
    "mes": 1
  }
}
```

## Monitoramento

### Métricas

O servidor expõe métricas no formato Prometheus:

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

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

```bash
# 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](./docs/guides/INICIO_RAPIDO.md) - Comece em 5 minutos
- [Guia de Instalação e Uso](./docs/guides/GUIA_INSTALACAO_USO.md) - Instalação e configuração completas

### Exemplos e Testes
- [Exemplos Práticos](./docs/examples/EXEMPLOS_PRATICOS.md) - Casos de uso com LLMs
- [Exemplos de Testes](./docs/examples/EXEMPLOS_TESTES.md) - Validação e testes

### Especificações
- [Especificação Técnica Completa](./docs/specs/mcp-camara-br-especificacao-completa.md) - Documentação técnica detalhada

### Integrações
- [Sistema Multi-Agentes n8n](./docs/n8n/SISTEMA_MULTI_AGENTES.md) - Arquitetura de orquestração de agentes especialistas

### Para Desenvolvedores
- [Guia de Contribuição](./CONTRIBUTING.md) - Como contribuir com o projeto
- [Guia para IA (CLAUDE.md)](./CLAUDE.md) - Instruções para assistentes de IA

### Índice Completo
- [Documentação Organizada](./docs/README.md) - Í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](./CONTRIBUTING.md) - Guia completo de contribuição com padrões de código, workflow e boas práticas

**Resumo rápido:**

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
3. Siga os padrões de código (TypeScript strict, ESLint, Prettier)
4. Escreva testes para novas funcionalidades
5. Commit usando [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, etc.)
6. Push para a branch (`git push origin feature/MinhaFeature`)
7. Abra um Pull Request com descrição detalhada

**Scripts úteis para desenvolvimento:**
```bash
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](LICENSE) para detalhes.

## 🔗 Links

- [API Dados Abertos da Câmara](https://dadosabertos.camara.leg.br/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Documentação da API](https://dadosabertos.camara.leg.br/swagger/api.html)

## Suporte

Para reportar bugs ou solicitar features, abra uma [issue](https://github.com/gvc2000/AgenteCidadaoMCP/issues).

---

Desenvolvido com ❤️ para democratização de dados públicos