Introdução

Como entusiasta e treinador de IA, acredito que dados abertos de alta qualidade são essenciais para construir modelos de linguagem e agentes úteis. Este projeto - o "Africa Energy Data MCP" - envolve uma API pública de Dados de Energia da África e a expõe como ferramentas MCP para que LLMs (Claude, Cursor, etc.) possam chamá-las diretamente.

Neste breve guia, você encontrará um passo a passo claro para:

• Configurar o projeto localmente
• Compreender a arquitetura
• Conectar um cliente MCP (Claude / Cursor)
• Executar e testar as ferramentas
• Opções de publicação (breve)

Agradecimentos especiais ao meu amigo Denzel (dkkinyua) que desenvolveu a API subjacente que alimenta este projeto - confira o trabalho dele aqui: https://github.com/dkkinyua/AfricaEnergyDataAPI/tree/main

Por que isso é importante

LLMs se tornam muito mais úteis quando podem chamar ferramentas que buscam dados reais. Este projeto torna indicadores históricos de eletricidade, energia e economia para 54 países africanos (2000–2022) trivialmente disponíveis para agentes, com cache, tentativas e validação integrados.

Destaques rápidos

• Ferramentas: get_electricity_data, get_energy_data, get_economic_data, check_api_health, list_countries
• Tecnologia: Python 3.11, httpx, servidor mcp, cache em memória simples, logging estruturado
• Containerização: Dockerfile + exemplo de GitHub Actions incluído

Passo 1 - Obter o código

Clone o repositório e entre no diretório do projeto:

git clone https://github.com/Navashub/africa_energy_mcp.git
cd africa_energy_mcp

Passo 2 - Instalar dependências

Crie um virtualenv e instale os requisitos:

python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt

Passo 3 - Adicione sua chave API

Copie o arquivo de exemplo .env e cole sua chave RapidAPI do provedor de API (API do Denzel ou a listagem do RapidAPI):

cp .env.example .env
# edite .env e substitua AFRICA_ENERGY_API_KEY pela sua chave

Importante: nunca comite .env ou sua chave API no GitHub. O repositório já inclui um .gitignore.

Passo 4 - Execute o servidor MCP

Inicie o servidor localmente:

py server.py

Você deve ver logs estruturados no stderr indicando que o servidor MCP foi inicializado e as ferramentas registradas. Deixe isso rodando — ele escuta no stdio para clientes MCP.

Passo 5 - Conectar um cliente MCP (Claude / Cursor)

Para testes locais, aponte seu cliente compatível com MCP para o processo server.py. Exemplos:

• Claude Desktop (Windows) — edite %APPDATA%\Claude\claude_desktop_config.json e adicione:

{
  "mcpServers": {
    "africa-energy": {
      "command": "py",
      "args": ["D:\\mcp_projects\\africa_energy_mcp\\server.py"]
    }
  }
}

• Cursor — adicione a entrada equivalente mcp.servers nas configurações do Cursor apontando para seu local server.py.

Passo 6 - Testar consultas úteis

Comece com comandos de descoberta para confirmar a conectividade:

• "Quais países são suportados pela ferramenta de Dados de Energia da África?" — deve retornar a lista de 54 países (ferramenta list_countries).
• "A API de Dados de Energia da África está online?" — a ferramenta check_api_health deve retornar um JSON de saúde.
• Exemplo: "Obter dados de eletricidade para o Quênia em 2022." — chamará get_electricity_data e retornará resultados em JSON.

Se um endpoint retornar um 500, isso indica que o backend da API remota falhou — o erro está do lado do provedor da API. O servidor MCP exibirá uma mensagem de erro clara nesse caso.

Arquitetura (breve)

1. server.py - servidor MCP que declara ferramentas e roteia chamadas
2. handlers.py - Validação de entrada e mapeamento de argumentos de ferramentas para chamadas de API
3. api_client.py - wrapper httpx.AsyncClient com tentativas, timeout de 30s e um cache em memória de 10 minutos
4. tools.py - Esquemas para cada ferramenta MCP
5. config.py - Ambiente e constantes (incluindo a lista codificada de 54 países)

Containerização & CI

Se você deseja hospedagem remota, o repositório inclui um Dockerfile e um exemplo de fluxo de trabalho do GitHub Actions que constrói e envia um contêiner para o GHCR. A publicação requer um token de registro — adicionamos um fluxo de trabalho que prefere um segredo GHCR_TOKEN ou recai sobre o GITHUB_TOKEN do repositório quando permitido.

Agradecimentos

Um enorme agradecimento a Denzel (dkkinyua) por construir a API subjacente de Dados de Energia da África — por favor, confira o repositório dele: https://github.com/dkkinyua/AfricaEnergyDataAPI/tree/main

Agradecimento: Este projeto foi adaptado e envolto em um servidor MCP por um entusiasta e treinador de IA (sou eu — Navashub) para tornar os dados acessíveis a LLMs para educação, pesquisa e uso em produção.

Melhores práticas & dicas

• Mantenha suas chaves API em segredo - use .env localmente e segredos de repositório para CI.
• Teste com list_countries e check_api_health antes de executar grandes consultas.
• Aumente REQUEST_TIMEOUT em config.py apenas se souber que o backend requer mais tempo.
• Para hospedagem em produção, use a imagem Docker e forneça segredos através do host ou do mecanismo de segredos da plataforma.

Conclusão

Disponibilizar dados de energia históricos e estruturados para LLMs desbloqueia uma melhor análise automatizada, respostas e suporte à decisão. Este projeto é uma pequena, mas prática ponte - agradecimentos a Denzel pela API e a você por explorá-la.