MCP DivulgaCandContas Server

# 🏛️ Servidor MCP DivulgaCandContas - Resumo do Projeto ## ✅ Projeto Concluído com Sucesso! Este projeto implementa um **servidor MCP (Model Context Protocol)** completo que roda em Docker e expõe todas as funcionalidades da API DivulgaCandContas do TSE (Tribunal Superior Eleitoral). ## 🚀 O que foi implementado ### 🔧 Servidor MCP TypeScript - **Linguagem**: TypeScript com Node.js 20+ - **Framework**: SDK oficial do MCP (@modelcontextprotocol/sdk) - **Validação**: Schemas rigorosos com Zod - **HTTP Client**: Axios com timeout e tratamento de erros - **Transporte**: STDIO para integração com clientes MCP ### 🛠️ Ferramentas (Tools) Implementadas #### 🏛️ **Candidaturas** 1. `listar_candidatos_municipio` - Lista candidatos por município 2. `consultar_candidato` - Consulta detalhes de um candidato específico #### 🗳️ **Eleições** 3. `listar_anos_eleitorais` - Lista anos disponíveis no sistema 4. `listar_eleicoes_ordinarias` - Lista eleições ordinárias 5. `listar_eleicoes_suplementares` - Lista eleições suplementares por UF/ano 6. `listar_cargos_municipio` - Lista cargos em disputa por município #### 💰 **Prestação de Contas** 7. `consultar_prestador_contas` - Consulta prestação de contas de candidatos ### 🐳 Containerização Docker - **Dockerfile** otimizado com Node.js 20 Alpine - **Docker Compose** para orquestração - **Multi-stage build** para imagens menores - **Usuário não-root** para segurança - **Health checks** configurados ### 📜 Script de Gerenciamento - **mcp-server.sh** - Script bash completo para: - Build local e Docker - Execução em diferentes modos - Testes automatizados - Configuração para Claude Desktop - Limpeza de arquivos - Ajuda contextual ### 📚 Documentação Completa - **README.md** detalhado com exemplos - **Instruções de instalação** múltiplas opções - **Configuração Claude Desktop** - **Códigos úteis** (eleições, cargos, UFs) - **Estrutura do projeto** ## 🎯 Como usar ### Opção 1: Docker (Recomendado) ```bash # Build e execução ./mcp-server.sh build-docker ./mcp-server.sh run-docker # OU com Docker Compose docker-compose up --build ``` ### Opção 2: Node.js Local ```bash # Build e execução ./mcp-server.sh build ./mcp-server.sh run ``` ### Opção 3: Claude Desktop ```json { "mcpServers": { "divulgacandcontas": { "command": "docker", "args": ["run", "-i", "--rm", "mcp-divulgacandcontas-server:latest"] } } } ``` ## 📊 API TSE Coberta ✅ **100% dos endpoints** da API DivulgaCandContas implementados: - `/candidatura/listar/{ano}/{municipio}/{eleicao}/{cargo}/candidatos` - `/candidatura/buscar/{ano}/{municipio}/{eleicao}/candidato/{candidato}` - `/eleicao/anos-eleitorais` - `/eleicao/ordinarias` - `/eleicao/suplementares/{ano}/{uf}` - `/eleicao/listar/municipios/{eleicao}/{municipio}/cargos` - `/prestador/consulta/{eleicao}/{ano}/{municipio}/{cargo}/90/90/{candidato}` ## 🔒 Segurança e Qualidade ✅ **Validação rigorosa** com Zod schemas ✅ **Tratamento de erros** da API TSE ✅ **Timeout configurado** (30s) ✅ **Container seguro** (usuário não-root) ✅ **Logs estruturados** ✅ **Testes automatizados** ## 🏗️ Estrutura do Projeto ``` mcp-divulgacandcontas-server/ ├── src/index.ts # Servidor MCP principal ├── build/ # Código compilado ├── Dockerfile # Container Docker ├── docker-compose.yml # Orquestração ├── mcp-server.sh # Script de gerenciamento ├── package.json # Dependências e scripts ├── tsconfig.json # Config TypeScript ├── .vscode/mcp.json # Config VS Code MCP └── README.md # Documentação ``` ## 📈 Próximos Passos O servidor está **100% funcional** e pronto para uso. Possíveis melhorias futuras: 1. **Cache Redis** para otimizar consultas frequentes 2. **Rate limiting** para respeitar limites da API TSE 3. **Autenticação** para ambientes enterprise 4. **Métricas** e monitoramento 5. **Publicação** no npm/Docker Hub ## 🎉 Resultado Final ✅ **Servidor MCP completo e funcional** ✅ **Docker funcionando** perfeitamente ✅ **Todas as APIs TSE** implementadas ✅ **Script de gerenciamento** robusto ✅ **Documentação** completa ✅ **Pronto para produção** --- **🏆 Projeto concluído com sucesso!** O servidor MCP DivulgaCandContas está pronto para ser usado com Claude Desktop ou qualquer outro cliente MCP compatível.