MCP Server Automation CLI

Una herramienta de línea de comandos para automatizar el despliegue de servidores MCP en AWS ECS.

GitHubPrueba este MCPPatrocinado

Documentación

Aviso de Migración

Este repositorio ha sido migrado a aws-samples. La nueva ruta del repositorio es https://github.com/aws-samples/sample-mcp-server-automation. Este repositorio está archivado.

MCP Server Automation CLI

Una potente herramienta CLI que automatiza el proceso de transformar servidores MCP (Model Context Protocol) stdio en imágenes Docker desplegadas en AWS ECS usando mcp-proxy. Esta herramienta cierra la brecha entre servidores MCP locales y despliegues remotos basados en HTTP.

🚀 Características

  • 🔄 Compilación Automática: Obtiene servidores MCP desde GitHub, compila imágenes Docker y las envía a ECR
  • ☁️ Despliegue con Un Clic: Genera plantillas CloudFormation y despliega infraestructura ECS completa
  • 🔍 Detección Inteligente: Detecta automáticamente los comandos del servidor MCP desde archivos README
  • 🐳 Multi-Arquitectura: Soporte para servidores MCP de Python, Node.js e híbridos
  • 🔧 Soporte de Depuración: Registro de depuración integrado para solucionar problemas
  • 📝 Generación de Configuración: Genera configuraciones de cliente MCP para Claude Desktop, Cline, etc.

📋 Requisitos Previos

  • Python 3.8+
  • Docker (con el daemon en ejecución)
  • AWS CLI configurado con los permisos apropiados
  • Repositorio AWS ECR (creado si se usa el envío a ECR)
  • Clúster AWS ECS (creado si se despliega)

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"

📖 Inicio Rápido

Usando uvx (Recomendado)

La forma más fácil de usar esta herramienta es con uvx, que maneja las dependencias automáticamente:

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

Configuración de Desarrollo Local

# Clone and setup
git clone <repository-url>
cd mcp-convert-automate

# Create virtual environment and install dependencies
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Install in development mode (optional - for local CLI usage)
pip install -e .

⚙️ Configuración

La herramienta utiliza un archivo de configuración YAML unificado con las secciones build y deploy.

Configuración Unificada

build:
  # Required: GitHub repository URL
  github_url: "https://github.com/awslabs/mcp"

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

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

  # 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"

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"

🏗️ Arquitectura

Flujo del Proceso de Compilación

  1. Análisis del Repositorio: Descarga repositorios de GitHub y detecta la configuración del servidor MCP desde archivos README
  2. Detección de Comandos: Analiza bloques JSON en archivos README para extraer comandos de inicio del servidor MCP, priorizando comandos NPX/uvx sobre comandos Docker
  3. Generación de Dockerfile: Utiliza plantillas Jinja2 para crear compilaciones Docker de múltiples etapas con integración CLI de mcp-proxy
  4. Compilación de Imágenes: Crea contenedores híbridos Node.js + Python con gestión de dependencias adecuada

Arquitectura de Despliegue

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

Detalles Técnicos Clave

  • Integración mcp-proxy: Utiliza la herramienta CLI de TypeScript/Node.js para transporte HTTP con registro de depuración habilitado
  • Arquitectura de Contenedores: Compilaciones de múltiples etapas con imagen base node:24-bullseye, incluye netcat para verificaciones de salud
  • Formato de Comando: mcp-proxy --debug --port 8000 --shell <command> [-- <args>] para un orden adecuado de argumentos
  • Protocolo de Transporte: Convierte MCP stdio a HTTP con el endpoint /mcp para transporte HTTP Streamable
  • Etiquetado Dinámico: Las imágenes se etiquetan con el hash del commit de git y la marca de tiempo (por ejemplo, a1b2c3d4-develop-20231222-143055)
  • Soporte de Ramas: Puede compilar desde ramas específicas de git, por defecto usa 'main'
  • Verificaciones de Salud: El contenedor utiliza verificación de puertos con netcat, verificaciones de salud del ALB en el endpoint /mcp esperando HTTP 400
  • Generación de Configuración MCP: Genera e imprime automáticamente la configuración del cliente MCP después del despliegue
  • Infraestructura: Pila CloudFormation completa con VPC, ALB, ECS Fargate, grupos de seguridad y roles IAM

🔧 Uso Avanzado

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

Detección y Anulación de Comandos

La herramienta detecta automáticamente los comandos de inicio del servidor MCP desde:

  1. Archivos README - Bloques de configuración JSON con mcpServers
  2. pyproject.toml - Scripts de consola o módulos principales
  3. setup.py - Puntos de entrada y scripts

Se Requiere Anulación de Comandos Cuando:

  • El README solo contiene comandos Docker (no adecuados para contenerización)
  • No se puede detectar un comando de inicio adecuado
  • Desea especificar parámetros de inicio exactos

Ejemplo:

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

Ejemplo de Error: Si el README de su servidor MCP solo muestra:

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

Recibirá un error que requiere command_override para especificar el comando de inicio directo.

Variables de Entorno en el Contenedor

Establezca variables de entorno personalizadas que estarán disponibles para el servidor MCP en tiempo de ejecución:

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

Variables de Entorno del Sistema

Establezca variables de entorno para anular la configuración predeterminada de AWS:

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

🐛 Solución de Problemas

Problemas de Compilación Docker

  • Asegúrese de que el daemon de Docker esté en ejecución
  • Verifique que el servidor MCP tenga los archivos de dependencias adecuados (requirements.txt, pyproject.toml, etc.)
  • Confirme que la URL del repositorio de GitHub sea accesible

Problemas de Envío a ECR

  • Asegúrese de que las credenciales de AWS tengan permisos de ECR
  • Verifique que el repositorio ECR exista y sea accesible
  • Compruebe que Docker esté autenticado con ECR

Problemas de Despliegue con CloudFormation

  • Asegúrese de que las credenciales de AWS tengan permisos suficientes
  • Verifique que el clúster ECS exista
  • Confirme que la región de AWS sea correcta
  • Revise los eventos de CloudFormation en la Consola de AWS para ver mensajes de error detallados

Problemas de Conexión del Servidor MCP

  • Revise los registros del contenedor: docker logs <container-id>
  • Verifique el endpoint de verificación de salud: curl http://<alb-url>/mcp (espera HTTP 400)
  • Pruebe la conexión directa: curl http://<alb-url>/mcp
  • Use el modo de depuración para un registro detallado

🔐 Permisos de AWS Requeridos

Las credenciales de AWS utilizadas deben tener los siguientes permisos:

Permisos de 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": "*"
    }
  ]
}

Permisos de ECS y CloudFormation

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

📝 Configuración del Cliente MCP

Después del despliegue, la herramienta genera configuración para clientes MCP:

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

Prueba de la Conexión MCP

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

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

Seguridad

Consulte CONTRIBUTING para obtener más información.

Licencia

Esta biblioteca está licenciada bajo la Licencia MIT-0. Consulte el archivo LICENSE.

🆘 Soporte

  • Consulte la sección de solución de problemas para problemas comunes
  • Revise los eventos de CloudFormation en la Consola de AWS para problemas de despliegue
  • Use el modo de depuración para un registro detallado
  • Abra un issue para errores o solicitudes de funciones