MCP Server Automation CLI

Uma ferramenta de linha de comando para automatizar o empacotamento de servidores MCP como imagens Docker e implantá-los no AWS ECS.

GitHub
4
Experimente este MCPPatrocinado

Documentação

MCP Server Automation CLI

Uma ferramenta CLI poderosa que automatiza o processo de transformar servidores stdio do Model Context Protocol (MCP) em imagens Docker implantadas no AWS ECS usando mcp-proxy. Esta ferramenta preenche a lacuna entre servidores MCP locais e implantações remotas baseadas em HTTP.

🚀 Recursos

  • ⚡ Modo de Comando Direto: Construa servidores MCP instantaneamente sem arquivos de configuração usando a sintaxe de separador --
  • 🔄 Build Automático: Busque servidores MCP do GitHub, construa imagens Docker e envie para o ECR
  • ☁️ Implantação com Um Clique: Gere modelos CloudFormation e implante infraestrutura ECS completa
  • 🔍 Detecção Inteligente: Detecte automaticamente comandos de servidor MCP a partir de arquivos README
  • 🐳 Multi-idioma: Suporte para servidores MCP Python e Node.js/TypeScript com detecção automática de idioma
  • 🏷️ Nomenclatura Inteligente: Extração automática do nome do pacote para nomeação de imagens Docker
  • 🔧 Suporte a Depuração: Logging de depuração integrado para solução de problemas
  • 📝 Geração de Configuração: Gere configurações de cliente MCP para Claude Desktop, Cline, etc.

📋 Pré-requisitos

  • Python 3.8+
  • Docker (com daemon em execução)
  • AWS CLI configurado com as permissões apropriadas
  • Repositório AWS ECR (criado se usar push ECR)
  • Cluster AWS ECS (criado se implantar)

Instalar uv

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

📖 Início Rápido

Modo de Comando Direto (Sem Arquivo de Configuração)

A maneira mais rápida de construir imagens de servidor MCP é usando o modo de comando direto:

# Build MCP server image directly (no config file needed)
uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation -- npx -y @modelcontextprotocol/server-everything

# Build and push to ECR
uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --push-to-ecr -- uvx mcp-server-automation

# Build for specific architecture
uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything

Arquivos de Configuração

Use arquivos de configuração baseados em YAML para implantações complexas:

# Install from a Git repository
uvx --from git+https://github.com/aws-samples/sample-mcp-server-automation mcp-server-automation --config your-config.yaml

Configuração de Desenvolvimento Local (MacOS ou Linux)

# Clone and setup
git clone https://github.com/aws-samples/sample-mcp-server-automation
cd mcp-convert-automate
uv sync
source .venv/bin/activate

# Run with config file
uv run mcp-server-automation --config your-config.yaml

# Run with direct command mode
uv run mcp-server-automation -- npx -y @modelcontextprotocol/server-everything

# Run with specific architecture
uv run mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything

⚙️ Configuração

A ferramenta suporta dois modos:

  1. Modo de Comando Direto: Nenhum arquivo de configuração necessário - especifique o comando diretamente com o separador --
  2. Modo de Arquivo de Configuração: Use arquivos de configuração YAML para builds e implantações complexas

Modo de Comando Direto

Use o separador -- para especificar comandos diretamente:

# Basic usage
mcp-server-automation -- npx -y @modelcontextprotocol/server-everything

# With ECR push (requires ECR repository to be configured separately)
mcp-server-automation --push-to-ecr -- python -m my_server

# With specific architecture for cross-platform builds
mcp-server-automation --arch linux/arm64 -- npx -y @modelcontextprotocol/server-everything

# Package name extraction for image naming
# @modelcontextprotocol/server-everything → mcp-server-everything
# mcp-server-automation → mcp-mcp-server-automation

Recursos:

  • Nenhum arquivo de configuração necessário
  • Extração automática do nome do pacote para nomeação de imagens Docker
  • Suporte a múltiplas arquiteturas com o parâmetro --arch (linux/amd64, linux/arm64, etc.)
  • Modo somente build (a implantação requer arquivos de configuração)
  • Suporte simples à flag --push-to-ecr

Modo de Arquivo de Configuração

Para cenários complexos, use arquivos de configuração YAML com as seções build e deploy:

build:
  # Method 1: Use command and package manager
  entrypoint:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-everything"

  # Method 2: Fetch MCP server from GitHub
  # github:
    # Required: GitHub repository URL for MCP server
    # github_url: "https://github.com/awslabs/mcp"

    # Optional: Subfolder path if MCP server is not in root
    # subfolder: "src/aws-documentation-mcp-server"

    # Optional: Git branch to build from (default: main)
    # branch: "develop"

  # Required for deployment: Must be true to enable ECR push and deployment
  push_to_ecr: true

  # Optional: Custom Docker image configuration
  # If not specified, auto-generated when push_to_ecr=true
  # image:
  #   repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/mcp-servers/my-mcp-server"
  #   tag: "v1.0"  # Optional, defaults to dynamic git-based tag

  # Optional: AWS region (default: from AWS profile, fallback to us-east-1)
  # aws_region: "us-west-2"

  # Optional: Custom Dockerfile path
  # dockerfile_path: "./custom.Dockerfile"

  # Optional: Override auto-detected MCP server command
  # Required when README only contains Docker commands or no suitable command is found
  # command_override:
  #   - "python"
  #   - "-m"
  #   - "my_server_module"
  #   - "--verbose"

  # Optional: Set environment variables in the container
  # environment_variables:
  #   LOG_LEVEL: "debug"
  #   AWS_REGION: "us-east-1"
  #   MCP_SERVER_NAME: "custom-server"

  # Optional: Target architecture for Docker build
  # architecture: "linux/arm64"  # Options: linux/amd64, linux/arm64

deploy:
  # Required: Enable deployment (only works when push_to_ecr=true)
  enabled: true

  # Required: ECS service name
  service_name: "my-mcp-service"

  # Required: ECS cluster name
  cluster_name: "my-ecs-cluster"

  # Required: VPC ID where resources will be created
  vpc_id: "vpc-12345678"

  # Required: Subnet configuration
  alb_subnet_ids:    # Public subnets for ALB (minimum 2 in different AZs)
    - "subnet-public-1"
    - "subnet-public-2"
  ecs_subnet_ids:    # Private subnets for ECS tasks (minimum 1, should resides in AZ of alb_subnet_ids)
    - "subnet-private-1"
    - "subnet-private-2"

  # Optional: Container port (default: 8000)
  port: 8000

  # Optional: Task CPU units (default: 256)
  cpu: 256

  # Optional: Task memory in MB (default: 512)
  memory: 512

  # Optional: SSL certificate ARN for HTTPS
  certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"

  # Optional: Save MCP client configuration to file
  save_config: "./mcp-config.json"

🔧 Uso Avançado

Dockerfile Personalizado

build:
  github_url: "https://github.com/my-org/custom-mcp-server"
  dockerfile_path: "./custom/Dockerfile"
  push_to_ecr: true
deploy:
  enabled: true
  # ... deployment configuration

Variáveis de Ambiente no Contêiner

Defina variáveis de ambiente personalizadas que estarão disponíveis para o servidor MCP em tempo de execução:

build:
  github_url: "https://github.com/my-org/custom-mcp-server"
  environment_variables:
    LOG_LEVEL: "debug"
    AWS_REGION: "us-east-1"
    MCP_SERVER_NAME: "custom-server"
    PYTHONPATH: "/app/mcp-server:/custom/path"
  push_to_ecr: true

Variáveis de Ambiente do Sistema

Defina variáveis de ambiente para substituir as configurações padrão da AWS:

export AWS_REGION=us-west-2
export ECS_CLUSTER_NAME=my-production-cluster

🏗️ Arquitetura

Fluxo do Processo de Build

A ferramenta suporta dois modos de build:

Modo de Comando Direto

  1. Análise de Comando: Analisa comando e argumentos da CLI usando o separador -- (ex.: -- npx -y @modelcontextprotocol/server-everything)
  2. Extração do Nome do Pacote: Extrai automaticamente nomes de pacotes para nomeação de imagens Docker (ex.: @modelcontextprotocol/server-everything → mcp-server-everything)
  3. Detecção de Linguagem: Detecta o runtime (Node.js/Python) a partir do comando
  4. Geração de Dockerfile: Cria contêineres otimizados com pacotes pré-instalados
  5. Construção de Imagem: Constrói contêiner pronto para executar o comando especificado

Modo de Arquivo de Configuração (GitHub/Entrypoint)

  1. Análise de Repositório: Baixa repositórios GitHub e detecta a configuração do servidor MCP a partir de arquivos README (modo GitHub)
  2. Detecção de Linguagem: Detecta automaticamente Python ou Node.js/TypeScript com base nos arquivos do projeto (package.json, pyproject.toml, etc.)
  3. Detecção de Comando: Analisa blocos JSON em arquivos README para extrair comandos de inicialização do servidor MCP dos formatos de configuração do Claude Desktop (mcpServers) e VS Code (mcp.servers)
  4. Geração de Dockerfile: Usa modelos Jinja2 específicos de linguagem (Dockerfile-python.j2, Dockerfile-nodejs.j2) para criar builds otimizados com integração CLI do mcp-proxy
  5. Construção de Imagem: Cria contêineres específicos de linguagem com gerenciamento adequado de dependências e builds em múltiplos estágios

Arquitetura de Implantação

GitHub Repo → Docker Build → ECR → ECS Fargate ← ALB ← Internet
     ↓              ↓           ↓         ↓        ↓
MCP Server → mcp-proxy + MCP → Image → Service → HTTP/SSE Endpoints

Suporte e Detecção de Linguagem

A ferramenta suporta servidores MCP Python e Node.js/TypeScript com detecção automática de linguagem:

Projetos Python

  • Detectados por: arquivos pyproject.toml, requirements.txt, setup.py ou .py
  • Gerenciadores de pacotes: pip, uv, poetry (detectados automaticamente)
  • Imagem base: python:3.12-slim-bookworm
  • Extração de comando de: scripts de console em pyproject.toml, entry points em setup.py

Projetos Node.js/TypeScript

  • Detectados por: arquivos package.json, tsconfig.json ou .ts/.js
  • Gerenciador de pacotes: npm (com imagem base Node.js 24-bullseye)
  • Imagem base: node:24-bullseye
  • Extração de comando de: configurações JSON do README

Detecção e Substituição de Comando

A ferramenta detecta automaticamente comandos de inicialização do servidor MCP a partir de:

  1. Arquivos README - Blocos de configuração JSON que suportam ambos os formatos:
    • Claude Desktop: {"mcpServers": {...}}
    • VS Code: {"mcp": {"servers": {...}}}
  2. Projetos Python - Scripts de console pyproject.toml, entry points setup.py
  3. Projetos Node.js - Configurações do README (scripts do package.json não são analisados)

Substituição de Comando Necessária Quando:

  • O README contém apenas comandos Docker (não adequados para conteinerização)
  • Nenhum comando de inicialização adequado pode ser detectado
  • Você deseja especificar parâmetros exatos de inicialização

Exemplo:

build:
  github:
    github_url: "https://github.com/my-org/custom-mcp-server"
  command_override:
    - "python"
    - "-m"
    - "my_server_module"
    - "--verbose"
    - "--port"
    - "3000"
  push_to_ecr: true

Exemplos de Configurações README Suportadas:

Formato Claude Desktop:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

Formato VS Code:

{
  "mcp": {
    "servers": {
      "everything": {
        "command": "python",
        "args": ["-m", "server"]
      }
    }
  }
}

Exemplo de Erro:

Se o README do seu servidor MCP mostrar apenas comandos Docker:

{
  "mcpServers": {
    "myserver": {
      "command": "docker",
      "args": ["run", "myserver:latest"]
    }
  }
}

Você receberá um erro exigindo command_override para especificar o comando de inicialização direto.

🐛 Solução de Problemas

Problemas de Build Docker

  • Certifique-se de que o daemon do Docker está em execução
  • Verifique se o servidor MCP possui arquivos de dependência adequados (requirements.txt, pyproject.toml, etc.)
  • Confirme se a URL do repositório GitHub está acessível

Problemas de Build Multi-Arquitetura

Ao usar o parâmetro --arch ou architecture em arquivos de configuração, você pode encontrar:

Erro: "No builder available for architecture"

Isso significa que o Docker Buildx não está configurado corretamente. Para corrigir:

# Create and use a new multi-platform builder
docker buildx create --name multiarch --use

# Or use an existing builder
docker buildx use <builder-name>

# List available builders
docker buildx ls

Arquiteturas suportadas:

  • linux/amd64 - x86-64 padrão (Intel/AMD)
  • linux/arm64 - ARM 64 bits (Apple Silicon, AWS Graviton)

Para mais informações, visite: https://docs.docker.com/build/building/multi-platform/

Problemas de Push ECR

  • Certifique-se de que as credenciais AWS tenham permissões ECR
  • Verifique se o repositório ECR existe e está acessível
  • Confirme que o Docker está autenticado com o ECR

Problemas de Implantação CloudFormation

  • Certifique-se de que as credenciais AWS tenham permissões suficientes
  • Verifique se o cluster ECS existe
  • Confirme se a região AWS está correta
  • Revise os eventos do CloudFormation no Console AWS para mensagens de erro detalhadas

Problemas de Conexão do Servidor MCP

  • Verifique os logs do contêiner na configuração local: docker logs <container-id>
  • Verifique o endpoint de health check: curl http://<alb-url>/mcp (espera HTTP 400)
  • Teste a conexão direta: curl http://<alb-url>/mcp
  • Use o modo de depuração para logging detalhado

🔐 Permissões AWS Necessárias

As credenciais AWS usadas devem ter as seguintes permissões:

Permissões ECR

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:GetAuthorizationToken",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload"
      ],
      "Resource": "*"
    }
  ]
}

Permissões ECS e CloudFormation

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:*",
        "cloudformation:*",
        "ec2:*",
        "elasticloadbalancing:*",
        "iam:CreateRole",
        "iam:AttachRolePolicy",
        "iam:PassRole",
        "logs:CreateLogGroup",
        "logs:DescribeLogGroups"
      ],
      "Resource": "*"
    }
  ]
}

📝 Configuração do Cliente MCP

Após a implantação, a ferramenta gera configuração para clientes MCP:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "sse",
      "url": "http://<ALB address>/sse"
    }
  }
}

Testando a Conexão MCP

# Install mcp-proxy client
npm install -g mcp-proxy

# Test connection
mcp-proxy https://your-alb-url.amazonaws.com/mcp

Segurança

Consulte CONTRIBUTING para mais informações.

Licença

Esta biblioteca é licenciada sob a Licença MIT-0. Consulte o arquivo LICENSE.

🆘 Suporte

  • Consulte a seção de solução de problemas para problemas comuns
  • Revise os eventos do CloudFormation no Console AWS para problemas de implantação
  • Use o modo de depuração para logging detalhado
  • Abra uma issue para bugs ou solicitações de recursos