mcp-server-govbox

MCP Server Govbox

Um servidor MCP (Model Context Protocol) desenvolvido para facilitar a integração entre Large Language Models (LLMs) e tarefas do Rakefile do projeto Govbox.

📋 Sobre o Projeto

Este servidor atua como uma ponte entre LLMs e comandos Rake, permitindo que modelos de linguagem executem tarefas automatizadas de forma segura e controlada. O projeto foi desenvolvido para simplificar a execução de comandos Rake, tornando-os acessíveis, sem necessidade de conhecimento prévio dos comandos específicos.

🎯 Objetivo

O principal objetivo é permitir que LLMs possam:

• Executar tarefas do Rakefile de forma programática
• Automatizar processos comuns
• Reduzir a necessidade de conhecimento específico dos comandos Rake
• Prover uma interface padronizada para execução de tarefas

🚀 Funcionalidades

• Execução segura e controlada de tarefas
• Suporte a múltiplos projetos
• Retorno padronizado de resultados
• Tratamento de erros robusto

🛠️ Tecnologias Utilizadas

• Go (Golang) para o servidor MCP
• Ruby/Rake para execução das tarefas
• Docker para containerização

⚙️ Instalação e Configuração

📦 Passo 1: Obtenção do Código

• Clone o repositório

git clone https://github.com/giovanoh/mcp-server-govbox.git
cd mcp-server-govbox

🔨 Passo 2: Build

• Usando Docker

docker build -t mcp-server-govbox .

• Executando localmente

go build cmd/app/main.go

🔧 Passo 3: Configuração do Server

O servidor utiliza variáveis de ambiente para sua configuração. Todas as variáveis de ambiente devem ser configuradas para o funcionamento adequado do servidor. Para começar:

cp .env.example .env
# Edite o arquivo .env com suas configurações

As seguintes variáveis de ambiente são necessárias:

• MCP_GOVBOX_PROJECT_PATH: Caminho para o diretório do projeto Govbox
• MCP_SHELL_PATH: Shell a ser usado para execução dos comandos (ex: /bin/zsh)
• MCP_SHELL_OPTIONS: Argumentos adicionais para o shell (ex: -c)

Nota importante: O arquivo .env deve estar localizado na pasta raiz do projeto client que está chamando o servidor. Por exemplo:

• Se estiver utilizando com o Claude Desktop no Windows, o arquivo deve ficar em: C:\Users\<Usuário>\AppData\Local\AnthropicClaude\app-<Versão>\.env
• Se estiver utilizando com um client próprio, coloque o .env na pasta raiz do client

Certifique-se de que todas as variáveis estejam devidamente configuradas no arquivo .env antes de iniciar o servidor.

🔧 Passo 4: Configuração do Client

Para utilizar este servidor com o aplicativo Claude Desktop como client, ajuste a configuração do seu arquivo claude_desktop_config.json de acordo com os exemplos:

Para uso com Docker

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

Para uso do executável diretamente

{
    "mcpServers": {
        "mcp-server-govbox": {
            "command": "/path/to/executable"
        }
    }
}

Para outros clients, copie a configuração desejada e configure de acordo com o modelo utilizado pelo seu client de LLM.

# Usando Docker
cp config_docker_example.json config.json
# OU para executável
cp config_executable_example.json config.json

❌ Possíveis Erros

Durante a execução do servidor, alguns erros podem ocorrer e serão retornados para o client. Abaixo estão os possíveis erros e suas causas:

Erros de Inicialização

• "Error loading .env file":

  • Ocorre quando o arquivo .env não é encontrado
  • Ou quando há problemas de permissão para ler o arquivo
  • Ou quando o arquivo está mal formatado

• "Invalid shell configuration":

  • Ocorre quando as variáveis de ambiente do shell estão incorretas ou ausentes
  • Possíveis causas:
    • MCP_GOVBOX_PROJECT_PATH não foi definido ou está vazio
    • MCP_SHELL_PATH não foi definido ou está vazio
    • Shell especificado não existe no sistema

Erros de Validação

• "Param 'projects' must be a string":
  • Ocorre quando o parâmetro 'projects' não foi fornecido na requisição
  • Ou quando o valor fornecido não é uma string válida

Erros de Execução

• "Error during command execution (start)":

  • Ocorre quando há problemas ao iniciar o comando
  • Possíveis causas: permissões insuficientes, shell não encontrado, variáveis de ambiente mal configuradas

• "Error during command execution (wait)":

  • Ocorre quando há problemas durante a execução do comando
  • Possíveis causas: comando interrompido abruptamente, problemas de recursos do sistema

• "Error creating stdout/stderr pipe":

  • Ocorre quando o servidor não consegue criar os pipes para capturar a saída do comando
  • Possíveis causas: problemas de permissão, limites do sistema operacional atingidos

Como Resolver

1. Verifique se todas as variáveis de ambiente estão configuradas corretamente no arquivo .env
2. Certifique-se de que o arquivo .env está no local correto
3. Verifique se o usuário tem permissões adequadas para:
   • Ler o arquivo .env
   • Executar o shell configurado
   • Acessar o diretório do projeto Govbox
4. Confirme se o shell configurado existe e está acessível
5. Verifique se o caminho do projeto Govbox está correto
6. Verifique os logs do servidor para mais detalhes sobre o erro

📝 Licença

Este projeto está licenciado sob a .