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:

# 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

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

docker run -it --rm karnagge/mcp-divulgacandcontas:latest

Via Docker

Opção 1: Usar imagem pré-construída (Recomendado)

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

   git clone https://github.com/karnagge/mcpcand.git
   cd mcpcand

2. Build da imagem:

   docker build -t mcp-divulgacandcontas .

3. Execute o container:

   docker run -p 3000:3000 mcp-divulgacandcontas

Instalação Local

1. Instalar dependências:

npm install
# OU usando o script
./mcp-server.sh build

2. Compilar TypeScript:

npm run build

3. Executar servidor:

npm start
# OU usando o script
./mcp-server.sh run

Modo Desenvolvimento

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

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "mcp-divulgacandcontas-server:latest"
      ]
    }
  }
}

Usando Node.js Local

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "node",
      "args": ["/caminho/absoluto/para/build/index.js"]
    }
  }
}

Usando NPX (se publicado)

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "npx",
      "args": ["-y", "mcp-divulgacandcontas-server"]
    }
  }
}

Uso das Ferramentas

Exemplo: Listar candidatos de São Paulo em 2020

// 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

{
  "ano": 2020,
  "municipio": 35157,
  "eleicao": 2030402020, 
  "candidato": 123456  // Código do candidato
}

Exemplo: Listar eleições suplementares em São Paulo

{
  "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

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.