README.md•6.97 kB
# MCP DivulgaCandContas Server
Um servidor MCP (Model Context Protocol) que implementa todos os serviços da API DivulgaCandContas do TSE (Tribunal Superior Eleitoral), permitindo consultas sobre candidaturas e prestação de contas eleitorais.
## Funcionalidades
Este servidor implementa as seguintes ferramentas (tools) baseadas na API oficial do TSE:
### 🏛️ Candidaturas
- **listar_candidatos_municipio**: Lista todos os candidatos em um município específico
- **consultar_candidato**: Consulta informações detalhadas de um candidato
### 🗳️ Eleições
- **listar_anos_eleitorais**: Lista anos eleitorais disponíveis
- **listar_eleicoes_ordinarias**: Lista eleições ordinárias disponíveis
- **listar_eleicoes_suplementares**: Lista eleições suplementares por estado/ano
- **listar_cargos_municipio**: Lista cargos em disputa em um município
### 💰 Prestação de Contas
- **consultar_prestador_contas**: Consulta informações de prestação de contas de candidatos
## Instalação e Uso
### Script de Gerenciamento (Recomendado)
Este projeto inclui um script de gerenciamento que facilita todas as operações:
```bash
# Tornar o script executável (apenas uma vez)
chmod +x mcp-server.sh
# Ver todas as opções disponíveis
./mcp-server.sh help
# Construir o projeto
./mcp-server.sh build
# Executar localmente
./mcp-server.sh run
# Construir e executar com Docker
./mcp-server.sh build-docker
./mcp-server.sh run-docker
# Executar testes
./mcp-server.sh test
# Ver configuração para Claude Desktop
./mcp-server.sh config
# Limpar arquivos gerados
./mcp-server.sh clean
```
## 📦 Imagem Docker
A imagem Docker está disponível no Docker Hub:
**🔗 Docker Hub:** [`karnagge/mcp-divulgacandcontas`](https://hub.docker.com/r/karnagge/mcp-divulgacandcontas)
**📋 Tags disponíveis:**
- `latest` - Versão mais recente
- `v1.0.0` - Versão estável 1.0.0
**💾 Tamanho:** ~227MB (otimizada com Alpine Linux)
**🔧 Uso rápido:**
```bash
docker run -it --rm karnagge/mcp-divulgacandcontas:latest
```
### Via Docker
#### Opção 1: Usar imagem pré-construída (Recomendado)
```bash
# Baixar e executar diretamente do Docker Hub
docker run -it --rm karnagge/mcp-divulgacandcontas:latest
# Ou executar como daemon
docker run -d --name mcp-server -p 3000:3000 karnagge/mcp-divulgacandcontas:latest
```
#### Opção 2: Build local
1. **Clone o repositório:**
```bash
git clone https://github.com/karnagge/mcpcand.git
cd mcpcand
```
2. **Build da imagem:**
```bash
docker build -t mcp-divulgacandcontas .
```
3. **Execute o container:**
```bash
docker run -p 3000:3000 mcp-divulgacandcontas
```
### Instalação Local
1. **Instalar dependências:**
```bash
npm install
# OU usando o script
./mcp-server.sh build
```
2. **Compilar TypeScript:**
```bash
npm run build
```
3. **Executar servidor:**
```bash
npm start
# OU usando o script
./mcp-server.sh run
```
### Modo Desenvolvimento
```bash
npm run dev
# OU usando o script para desenvolvimento contínuo
npm run watch # Em um terminal
./mcp-server.sh run # Em outro terminal
```
## Configuração com Claude Desktop
Para usar este servidor com Claude Desktop, adicione a seguinte configuração ao seu `claude_desktop_config.json`:
### Usando Docker
```json
{
"mcpServers": {
"divulgacandcontas": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"mcp-divulgacandcontas-server:latest"
]
}
}
}
```
### Usando Node.js Local
```json
{
"mcpServers": {
"divulgacandcontas": {
"command": "node",
"args": ["/caminho/absoluto/para/build/index.js"]
}
}
}
```
### Usando NPX (se publicado)
```json
{
"mcpServers": {
"divulgacandcontas": {
"command": "npx",
"args": ["-y", "mcp-divulgacandcontas-server"]
}
}
}
```
## Uso das Ferramentas
### Exemplo: Listar candidatos de São Paulo em 2020
```typescript
// Parâmetros necessários
{
"ano": 2020,
"municipio": 35157, // Código de São Paulo
"eleicao": 2030402020, // Eleições municipais 2020
"cargo": 11 // Prefeito
}
```
### Exemplo: Consultar informações de um candidato
```typescript
{
"ano": 2020,
"municipio": 35157,
"eleicao": 2030402020,
"candidato": 123456 // Código do candidato
}
```
### Exemplo: Listar eleições suplementares em São Paulo
```typescript
{
"ano": 2020,
"uf": "SP"
}
```
## API Base
Este servidor consulta a API oficial do TSE:
- **Base URL**: `https://divulgacandcontas.tse.jus.br/divulga/rest/v1`
- **Documentação**: [Swagger da API](https://raw.githubusercontent.com/augusto-herrmann/divulgacandcontas-doc/refs/heads/main/divulgacandcontas-swagger.yaml)
## Estrutura do Projeto
```
mcp-divulgacandcontas-server/
├── src/
│ └── index.ts # Servidor MCP principal
├── build/ # Código compilado (gerado)
├── Dockerfile # Configuração Docker
├── docker-compose.yml # Configuração Docker Compose
├── package.json # Dependências e scripts
├── tsconfig.json # Configuração TypeScript
└── README.md # Esta documentação
```
## Desenvolvimento
### Scripts Disponíveis
- `npm run build` - Compila TypeScript
- `npm run start` - Executa servidor compilado
- `npm run dev` - Compila e executa em modo desenvolvimento
- `npm run watch` - Monitora mudanças e recompila automaticamente
- `npm run clean` - Remove arquivos compilados
### Dependências Principais
- **@modelcontextprotocol/sdk**: SDK oficial do MCP
- **zod**: Validação de schemas
- **axios**: Cliente HTTP para chamadas à API do TSE
## Segurança e Limitações
- ✅ Dados públicos oficiais do TSE
- ✅ Timeout configurado (30s) para requisições
- ✅ Validação rigorosa de parâmetros com Zod
- ✅ Tratamento de erros da API
- ⚠️ Sujeito a limitações de rate limit da API do TSE
- ⚠️ Dados disponíveis conforme cronograma do TSE
## Códigos Úteis
### Códigos de Eleição Comuns
- `2030402020`: Eleições Municipais 2020
- `2030402024`: Eleições Municipais 2024
- `2030602022`: Eleições Gerais 2022
### Códigos de Cargo Comuns
- `11`: Prefeito
- `13`: Vice-prefeito
- `51`: Vereador
- `1`: Presidente
- `3`: Governador
- `5`: Senador
- `6`: Deputado Federal
- `7`: Deputado Estadual
### Estados (UF)
Use a sigla de 2 letras: `SP`, `RJ`, `MG`, `RS`, etc.
## Suporte
Este servidor implementa todos os endpoints documentados na API DivulgaCandContas do TSE. Para problemas ou dúvidas:
1. Verifique se os parâmetros estão corretos (ano, códigos de município, etc.)
2. Consulte a documentação oficial da API do TSE
3. Verifique se o serviço do TSE está disponível
## Licença
MIT License - veja o arquivo LICENSE para detalhes.
---
**Nota**: Este é um projeto independente que utiliza a API pública do TSE. Não possui afiliação oficial com o Tribunal Superior Eleitoral.