MCP Docker Orchestrator

MCP Docker Orchestrator

Um daemon gerenciado por systemd que orquestra servidores MCP (Model Context Protocol) como contêineres Docker e configura roteamento baseado em caminho no AWS ALB.

Recursos

• Integração com Docker Compose: Gerencie servidores MCP usando o formato padrão do Docker Compose
• Integração com AWS ALB: Configure roteamento baseado em caminho no Application Load Balancer da AWS
• Painel Web: Monitore e controle serviços MCP através de uma interface web
• Autocorreção: Reconcilie automaticamente a configuração e o estado real
• Seguro: Sem persistência de segredos, compatível com LiteLLM Proxy

Arquitetura

O MCP Docker Orchestrator consiste em vários componentes principais:

• Gerenciador de Configuração: Lida com carregamento e análise da configuração do Docker Compose
• Gerenciador de Compose: Gerencia o ciclo de vida dos serviços Docker Compose
• Gerenciador ALB: Configura regras de roteamento no AWS ALB
• Painel: Interface web para monitoramento e gerenciamento
• Serviço Orquestrador: Processo principal que coordena todos os componentes

Pré-requisitos

• Python 3.8 ou superior
• Docker e Docker Compose
• Conta AWS com permissões apropriadas
• Host Linux (para o serviço systemd)

Instalação

Instalação Automática

A maneira mais fácil de instalar é usando o script de configuração fornecido:

sudo ./setup.sh

Isso irá:

1. Instalar dependências Python
2. Criar arquivos de configuração padrão
3. Configurar o serviço systemd
4. Configurar permissões

Instalação Manual

1. Instale as dependências Python:

   pip install -r requirements.txt
   

2. Configure as definições em settings.conf

3. Configure os servidores MCP em mcp-compose.yaml

4. Instale o serviço systemd:

   sudo cp service.template /etc/systemd/system/mcp-orchestrator.service
   # Edit the service file to configure paths
   sudo systemctl daemon-reload
   sudo systemctl enable mcp-orchestrator.service
   

Configuração

Configurações (settings.conf)

[aws]
region = us-west-2      # AWS region
alb_arn =               # ARN of your Application Load Balancer
listener_arn =          # ARN of your ALB listener
vpc_id =                # ID of your VPC

[service]
reconciliation_interval_seconds = 60  # How often to check and reconcile state
port_range_start = 8000               # Start of port range for container mapping
port_range_end = 9000                 # End of port range for container mapping

[dashboard]
username = admin        # Dashboard login username
password = changeme     # Dashboard login password (change this!)
path = /monitor         # URL path for dashboard

[logging]
level = INFO            # Logging level (DEBUG, INFO, WARNING, ERROR)

Configuração do Servidor MCP (mcp-compose.yaml)

version: '3'

services:
  example-mcp-server:
    image: mcp/example:latest
    restart: always
    environment:
      FASTMCP_LOG_LEVEL: "ERROR"
      ADDITIONAL_ENV_VAR: "value"
    labels:
      mcp.path: "/mcp/example"
      mcp.disabled: "false"
      mcp.managed_by: "mcp-orchestrator"

Cada configuração de servidor MCP consiste em:

• image: Imagem Docker a ser executada
• restart: Política de reinicialização (recomendado: always)
• environment: Variáveis de ambiente
• labels:
  • mcp.path: Padrão de caminho para roteamento no ALB
  • mcp.disabled: Se este servidor está desabilitado
  • mcp.managed_by: Deve ser sempre "mcp-orchestrator"

Uso

Iniciando o Serviço

sudo systemctl start mcp-orchestrator

Verificando o Status

sudo systemctl status mcp-orchestrator

Visualizando Logs

sudo journalctl -u mcp-orchestrator -f

Execução Manual

Para teste ou depuração:

# Run once and exit
python orchestrator/main.py --one-shot

# Run without dashboard
python orchestrator/main.py --no-dashboard

# Specify custom config files
python orchestrator/main.py --compose /path/to/mcp-compose.yaml --settings /path/to/settings.conf

# Migrate from old config format
python orchestrator/main.py --migrate /path/to/old/mcp.config.json

Painel

O painel web está disponível em:

http://your-server:5000/monitor

Login padrão: admin / changeme

Recursos:

• Visão geral dos servidores MCP
• Monitoramento de status dos contêineres
• Configuração de roteamento ALB
• Ações (iniciar/parar/reiniciar serviços)
• Controles de sincronização

Roteamento

Cada servidor MCP é mapeado para um caminho com base em seu ID ou no label mcp.path:

/mcp/{server-id}/*

Esses padrões de caminho são configurados nas regras do listener do ALB.

Migrando de mcp.config.json

Se você estiver atualizando de uma versão antiga que usava mcp.config.json, você pode usar a ferramenta de migração integrada:

python orchestrator/main.py --migrate /path/to/mcp.config.json

Isso irá:

1. Ler seu mcp.config.json existente
2. Convertê-lo para o novo formato Docker Compose
3. Salvá-lo como mcp-compose.yaml

Solução de Problemas

Problemas com Contêineres

• Verifique o status do Docker Compose: docker compose ps
• Verifique os logs do contêiner: docker compose logs {service-id}
• Verifique se há conflitos de porta
• Se você vir erros "Permission denied":
  • O usuário do serviço precisa de acesso ao socket do Docker
  • Certifique-se de que o usuário está no grupo docker
  • Talvez seja necessário fazer logout e login novamente para que as alterações de grupo tenham efeito

Problemas com AWS ALB

• Verifique as credenciais AWS
• Verifique o ARN do listener e as regras do ALB
• Certifique-se de que os target groups estejam configurados corretamente
• Verifique se a instância EC2 está registrada nos target groups

Problemas com o Serviço

• Verifique o status do systemd: systemctl status mcp-orchestrator
• Veja os logs: journalctl -u mcp-orchestrator -f
• Verifique se os arquivos de configuração estão formatados corretamente

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.