Sample MCP Server Automation

MCP服务器自动化CLI

一个强大的CLI工具，可以使用以下工具自动将模型上下文协议（MCP）stdio服务器转换为部署在AWS ECS上的Docker映像 mcp代理此工具弥合了本地MCP服务器和远程基于HTTP的部署之间的差距。

🚀 特性

• ⚡ 直接命令模式：使用以下命令立即构建MCP服务器，无需配置文件 -- 分隔符语法
• 🔄 自动构建：从GitHub获取MCP服务器，构建Docker镜像，并推送到ECR
• ☁️ 一键部署：生成CloudFormation模板并部署完整的ECS基础架构
• 🔍 智能检测：自动检测README文件中的MCP服务器命令
• 🐳 多语言：支持Python和Node.js/TypeScript MCP服务器，具有自动语言检测功能
• 🏷️ 智能命名：Docker镜像命名的自动包名提取
• 🔧 调试支持：内置调试日志用于故障排除
• 📝 配置生成：为Claude Desktop、Cline等生成MCP客户端配置。

📋 先决条件

• Python 3.8+
• 码头工人 （守护进程正在运行）
• AWS-CLI 配置了适当的权限
• AWS ECR存储库 （如果使用ECR推送创建）
• AWS云服务器集群 （部署时创建）

安装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"

📖 快速开始

直接命令模式（无配置文件）

构建MCP服务器映像的最快方法是使用直接命令模式：

# 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

配置文件

将基于yaml的配置文件与配置文件一起用于复杂的部署：

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

本地开发设置（MacOS或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

⚙️ 配置

该工具支持两种模式：

1. 直接命令模式：不需要配置文件-直接使用指定命令 -- 分隔符
2. 配置文件模式：使用YAML配置文件进行复杂的构建和部署

直接命令模式

使用 -- 分隔符直接指定命令：

# 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

特征：

• 不需要配置文件
• Docker镜像命名的包名自动提取
• 多架构支持 --arch 参数（linux/amd64、linux/arm64等）
• 仅构建模式（部署需要配置文件）
• 简单 --push-to-ecr 旗帜支持

配置文件模式

对于复杂的场景，使用YAML配置文件 build 和 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"

🔧 高级用法

自定义 Docker 文件

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

容器中的环境变量

设置MCP服务器在运行时可用的自定义环境变量：

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

系统环境变量

设置环境变量以覆盖默认AWS设置：

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

🏗️ 建筑

构建流程

该工具支持两种构建模式：

直接命令模式

1. 指令分析：使用以下命令从CLI解析命令和参数 -- 分离器（例如。， -- npx -y @modelcontextprotocol/server-everything)
2. 包名称提取：自动提取Docker镜像命名的包名（例如。， @modelcontextprotocol/server-everything → mcp-server-everything)
3. 语言检测：从命令中检测运行时（Node.js/Python）
4. Dockerfile生成：使用预安装的包创建优化的容器
5. 建立形象：构建容器，准备执行指定的命令

配置文件模式（GitHub/入口点）

1. 存储库分析：下载GitHub存储库并从README文件中检测MCP服务器配置（GitHub模式）
2. 语言检测：根据项目文件（package.json、pyproject.toml等）自动检测Python或Node.js/TypeScript
3. 命令检测：解析README文件中的JSON块，以从两个Claude Desktop中提取MCP服务器启动命令(mcpServers)和VS代码(mcp.servers)配置格式
4. Dockerfile生成：使用特定语言的Jinja2模板（Dockerfile-python.j2、Dockerfile-nodejs.j2）创建具有mcp-proxy CLI集成的优化构建
5. 建立形象：创建具有适当依赖关系管理和多阶段构建的特定语言容器

部署架构

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

语言支持和检测

该工具支持两者 python 和 Node.js/TypeScript 具有自动语言检测功能的MCP服务器：

Python项目

• 检测者： pyproject.toml, requirements.txt, setup.py，或 .py 文件
• 包管理器：pip、uv、诗意（自动检测）
• 基础图像： python:3.12-slim-bookworm
• 从以下位置提取命令：pyproject.toml中的控制台脚本、setup.py入口点

Node.js/TypeScript项目

• 检测者： package.json, tsconfig.json，或 .ts/.js 文件
• 包管理器：npm（带Node.js 24靶心基础镜像）
• 基础图像： node:24-bullseye
• 命令提取来源：README JSON配置

命令检测和超控

该工具自动检测来自以下来源的MCP服务器启动命令：

1. 自述文件 -支持两种格式的JSON配置块：

- 克劳德桌面： {"mcpServers": {...}} - VS代码： {"mcp": {"servers": {...}}}

1. Python项目 - pyproject.toml 控制台脚本， setup.py 入口点
2. Node.js项目 -README配置（未解析package.json脚本）

在以下情况下需要命令覆盖：

• README只包含Docker命令（不适合容器化）
• 未检测到合适的启动命令
• 您想指定精确的启动参数

例子：

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

支持的README配置示例：

克劳德桌面格式：

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

VS代码格式：

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

错误示例：

如果您的MCP服务器README只显示Docker命令：

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

您将收到一个错误，要求 command_override 指定直接启动命令。

🐛 故障排除

Docker构建问题

• 确保Docker守护进程正在运行
• 检查MCP服务器是否具有正确的依赖文件（requirements.txt、pyproject.toml等）
• 验证GitHub存储库URL是否可访问

多架构构建问题

使用时 --arch 参数或 architecture 在配置文件中，您可能会遇到：

错误：“没有可用于架构的构建器”

这意味着Docker Buildx配置不正确。要修复：

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

# Or use an existing builder
docker buildx use 

# List available builders
docker buildx ls

支持的架构：

• linux/amd64 -标准x86-64（英特尔/AMD）
• linux/arm64 -ARM 64位（苹果硅、AWS Graviton）

有关更多信息，请访问：https://docs.docker.com/build/building/multi-platform/

ECR推送问题

• 确保AWS凭据具有ECR权限
• 验证ECR存储库是否存在并且可以访问
• 检查Docker是否已通过ECR身份验证

CloudFormation部署问题

• 确保AWS凭据具有足够的权限
• 检查ECS集群是否存在
• 验证AWS区域是否正确
• 查看AWS控制台中的CloudFormation事件以了解详细的错误消息

MCP服务器连接问题

• 检查本地设置中的容器日志： docker logs
• 验证健康检查端点： curl http:///mcp （需要HTTP 400）
• 测试直接连接： curl http:///mcp
• 使用调试模式进行详细日志记录

🔐 需要AWS权限

使用的AWS凭据必须具有以下权限：

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

ECS和CloudFormation权限

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

📝 MCP客户端配置

部署后，该工具为MCP客户端生成配置：

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "sse",
      "url": "http:///sse"
    }
  }
}

测试MCP连接

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

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

安全

看 贡献 了解更多信息。

许可证

此库根据MIT-0许可证获得许可。请参阅LICENSE文件。

🆘 支持

• 检查 故障排除部分 常见问题
• 查看AWS控制台中的CloudFormation事件以了解部署问题
• 使用调试模式进行详细日志记录
• 为bug或功能请求打开问题