AWS 모델 컨텍스트 프로토콜(MCP) 서버

AI 어시스턴트가 MCP(Model Context Protocol)를 통해 AWS CLI 명령을 실행할 수 있도록 하는 가벼운 서비스입니다.

개요

AWS MCP 서버는 MCP 지원 AI 어시스턴트(예: Claude Desktop, Cursor, Windsurf)와 AWS CLI를 연결하는 다리 역할을 합니다. 이러한 어시스턴트는 다음과 같은 작업을 수행할 수 있습니다.

AWS CLI 설명서 검색 ( aws_cli_help ) - AWS 서비스 및 명령에 대한 자세한 도움말을 받으세요.
AWS CLI 명령 실행 ( aws_cli_pipeline ) - Unix 파이프로 명령을 실행하고 AI 사용에 최적화된 포맷된 결과를 받습니다.

지엑스피1

데모

이 비디오에서는 AWS MCP 서버와 함께 Claude Desktop을 사용하여 AWS SSM 에이전트가 설치된 새로운 AWS EC2 인스턴스를 만드는 방법을 보여줍니다.

특징

명령 문서 - AWS CLI 명령에 대한 자세한 도움말 정보
명령 실행 - AWS CLI 명령을 실행하고 사람이 읽을 수 있는 결과를 반환합니다.
Unix 파이프 지원 - 표준 Unix 파이프 및 유틸리티를 사용하여 AWS CLI 출력 필터링 및 변환
AWS 리소스 컨텍스트 - MCP 리소스를 통해 AWS 프로필, 리전, 계정 정보 및 환경 세부 정보에 액세스
프롬프트 템플릿 - 모범 사례를 따르는 일반적인 AWS 작업을 위한 미리 정의된 프롬프트 템플릿
Docker 통합 - 다중 아키텍처 지원(AMD64/x86_64 및 ARM64)을 통한 컨테이너화를 통한 간편한 배포
AWS 인증 - 호스트 머신의 기존 AWS 자격 증명을 활용합니다.

요구 사항

Docker(기본값) 또는 Python 3.13+(및 로컬에 설치된 AWS CLI)
AWS 자격 증명이 구성됨

시작하기

참고: 보안 및 안정성을 위해 Docker 컨테이너 내에서 서버를 실행하는 것이 강력히 권장됩니다 . 중요한 고려 사항은 보안 고려 사항 섹션을 참조하세요.

서버 실행 옵션 1: Docker 사용(권장)

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Build and run Docker container
docker compose -f deploy/docker/docker-compose.yml up -d

Docker 이미지는 AMD64/x86_64(Intel/AMD) 및 ARM64(Apple Silicon M1-M4, AWS Graviton) 아키텍처를 모두 지원합니다.

참고 : GitHub 패키지의 공식 이미지는 다중 아키텍처를 지원하므로 시스템에 적합한 버전을 자동으로 사용합니다.
# Use the latest stable version docker pull ghcr.io/alexei-led/aws-mcp-server:latest # Or pin to a specific version (recommended for production) docker pull ghcr.io/alexei-led/aws-mcp-server:1.0.0
Docker 이미지 태그 :
latest : 최신 안정 릴리스
xyz (예: 1.0.0 ): 특정 버전
sha-<commit-sha> : Git 커밋 SHA로 태그된 개발 빌드(예: sha-gb697684 )

서버 실행 옵션 2: Python 사용

주의해서 사용하세요: 네이티브로 실행하려면 신중한 환경 설정이 필요하며 권장 Docker 배포보다 보안 위험이 더 높습니다. 보안 고려 사항 섹션에 설명된 내용을 반드시 이해해야 합니다.

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Set up virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Run the server
python -m aws_mcp_server

구성

AWS MCP 서버는 환경 변수를 사용하여 구성할 수 있습니다.

환경 변수	설명	기본
`AWS_MCP_TIMEOUT`	명령 실행 시간 초과(초)	300
`AWS_MCP_MAX_OUTPUT`	최대 출력 크기(문자)	100000
`AWS_MCP_TRANSPORT`	사용할 전송 프로토콜("stdio" 또는 "sse")	stdio
`AWS_PROFILE`	사용할 AWS 프로필	기본
`AWS_REGION`	사용할 AWS 지역	미국 동부 1
`AWS_MCP_SECURITY_MODE`	보안 모드("엄격" 또는 "허용")	엄격한
`AWS_MCP_SECURITY_CONFIG`	사용자 정의 보안 구성 파일 경로	""

중요: 마운트된 ~/.aws 파일이나 환경 변수를 통해 서버에 제공된 AWS 자격 증명을 안전하게 관리하십시오. 자격 증명이 보안 고려 사항 섹션에 설명된 최소 권한 원칙을 준수하는지 확인하십시오. Docker를 통해 실행하는 경우 이러한 변수가 컨테이너 환경에 올바르게 전달되는지 확인하십시오(예: docker run -e VAR=value ... ).

보안 고려 사항

AWS 환경에서 명령을 실행할 때는 보안이 무엇보다 중요합니다. AWS MCP 서버가 기능을 제공하지만, 이를 안전하게 구성하고 실행하는 것은 사용자의 책임입니다 . 다음 사항을 엄격히 준수하십시오.

1. 권장 배포: Docker 컨테이너

격리: Docker 컨테이너 내에서 서버를 실행하는 것은 강력히 권장되는 기본 배포 방법입니다. 컨테이너화는 파일 시스템과 프로세스를 매우 안전하게 격리합니다. 파이프를 통해 실행되는 잠재적으로 파괴적인 Unix 명령(예: rm , mv )은 잘못 사용하더라도 임시 Docker 환경에 저장되므로 호스트 머신의 파일 시스템에 영향을 미치지 않습니다 . 컨테이너는 쉽게 중지하고 다시 생성할 수 있습니다.
제어된 환경: Docker는 필요한 종속성을 갖춘 일관된 환경을 보장하여 예상치 못한 동작을 줄입니다.

2. AWS 자격 증명 및 IAM 최소 권한(중요)

사용자 책임: 사용자는 AWS 자격 증명을 서버에 제공합니다(마운트된 ~/.aws 또는 환경 변수를 통해).
최소 권한이 필수입니다. 서버는 사용자가 제공한 자격 증명을 사용하여 AWS CLI 명령을 실행합니다. 이러한 자격 증명은 이 도구를 통해 수행하려는 AWS 작업 에만 필요한 최소 권한 (최소 권한)으로 구성된 IAM 보안 주체(사용자 또는 역할)에 속해야 합니다.
- 루트 자격 증명을 사용하지 마세요. AWS 계정 루트 사용자 자격 증명을 절대 사용하지 마세요.
- 정기적으로 권한을 검토하세요. 자격 증명과 관련된 IAM 권한을 주기적으로 감사합니다.
영향 제한: 적절하게 구성된 IAM 권한은 서버를 통해 실행되는 모든 명령의 잠재적 영향을 제한하는 주요 메커니즘 입니다. 의도적이든 의도치 않든 명령이 조작된 경우에도 해당 명령은 특정 IAM 정책에서 허용하는 작업만 수행할 수 있습니다.

3. 신뢰할 수 있는 사용자 모델

서버는 MCP 클라이언트(예: Claude Desktop, Cursor)와 상호 작용하는 최종 사용자가 서버를 구성하고 최소 권한 AWS 자격 증명을 제공한 신뢰할 수 있는 사용자와 동일 하다고 가정합니다. 신뢰할 수 없는 사용자에게 서버 또는 연결된 클라이언트를 노출하지 마십시오.

4. 실행 위험 이해(현재 구현)

명령 실행: 현재 구현에서는 셸 기능(하위 프로세스 호출에서 shell=True )을 사용하여 AWS 명령을 실행하고 Unix 파이프를 처리합니다. 이 방식은 편리하지만, 입력 명령 문자열이 조작될 경우(명령 삽입) 고유한 위험을 수반합니다.
운영 제어를 통한 완화: 신뢰할 수 있는 사용자 모델 과 Docker 배포 의 맥락에서 이러한 위험은 운영상 완화됩니다.
- 신뢰할 수 있는 사용자는 자신의 환경에 대해 의도적으로 악의적인 명령을 제공하지 않는다고 가정합니다.
- Docker에는 파일 시스템의 부작용이 있습니다.
- 중요한 점은 IAM의 최소 권한이 실행될 수 있는 모든 AWS 작업의 범위를 제한한다는 것입니다.
자격 증명 유출 위험: 컨테이너화 및 IAM에도 불구하고, 정교한 명령 주입은 컨테이너 내에 마운트된 자격 증명( ~/.aws ) 또는 환경 변수를 읽고 유출(예: curl 사용)을 시도할 수 있습니다. 엄격한 IAM 정책은 잠재적으로 유출될 수 있는 자격 증명의 가치를 제한하는 가장 중요한 방어 수단입니다 .

5. 네트워크 노출(SSE 전송)

sse 전송(네트워크 리스너를 의미)을 사용하는 경우, 서버를 신뢰할 수 있는 네트워크 인터페이스(예: localhost )에만 연결하거나, 서버를 더 광범위하게 노출하는 경우 적절한 네트워크 보안 제어(방화벽, 인증 프록시)를 구현해야 합니다. 기본 stdio 전송은 네트워크 포트를 열지 않습니다.

6. 공동 책임 요약

AWS MCP 서버가 도구를 제공합니다.
사용자는 다음에 대한 책임을 집니다.
- 권장하는 안전한 Docker 환경에서 실행합니다.
- 최소 권한 AWS 자격 증명을 제공하고 안전하게 관리합니다.
- 신뢰할 수 있는 사용자만 서버/클라이언트와 상호 작용하도록 보장합니다.
- 해당되는 경우 네트워크 환경을 보호합니다.

Docker 배포와 세심한 IAM 최소 권한 구성을 엄격히 준수하면 현재 구현을 통해 AWS MCP 서버를 안전하게 사용하는 데 필요한 운영 제어를 확립할 수 있습니다.

Claude Desktop과 통합

구성

AWS MCP 서버를 Claude Desktop과 수동으로 통합하려면 다음을 수행합니다.

Claude Desktop 구성 파일을 찾으세요 :
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
AWS MCP 서버를 포함하도록 구성 파일을 편집합니다 .
{ "mcpServers": { "aws-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro", "ghcr.io/alexei-led/aws-mcp-server:latest" ] } } }
변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.
- 재시작 후 입력 상자의 오른쪽 하단에 망치 🔨 아이콘이 표시됩니다.
- 이는 AWS MCP 서버를 사용할 수 있음을 나타냅니다.

예시 상호작용

AWS CLI 문서 가져오기 :

User: What are the available options for the AWS S3 cp command?

Claude: Let me get that information for you.

The AWS S3 cp command has the following options:

NAME
    cp - Copies a local file or S3 object to another location locally or in S3.

SYNOPSIS
    cp <LocalPath> <S3Uri> or <S3Uri> <LocalPath> or <S3Uri> <S3Uri> [--acl <value>] [--cache-control <value>] ...

AWS CLI 명령 실행 :

User: List my S3 buckets

Claude: I'll list your S3 buckets for you.

2023-10-15 14:30:45 my-bucket-1
2023-11-20 09:15:32 my-bucket-2
2024-01-05 11:22:18 my-backup-bucket

명령 파이프 사용하기 :

User: List my S3 buckets that have "backup" in their name and show them in alphabetical order

Claude: Let me find that for you.

2024-01-05 11:22:18 my-backup-bucket
2024-03-01 09:44:12 weekly-backup-bucket
2024-03-15 13:10:57 database-backup-bucket

AWS 리소스에 액세스하기 :

User: What AWS regions are available for me to use?

Claude: Let me check what AWS regions are available for you.

Available regions:
- us-east-1 (US East, N. Virginia) - Currently selected
- us-east-2 (US East, Ohio)
- us-west-1 (US West, N. California)
- us-west-2 (US West, Oregon)
- eu-west-1 (EU West, Ireland)
- eu-central-1 (EU Central, Frankfurt)
- ap-northeast-1 (Asia Pacific, Tokyo)
- ap-southeast-1 (Asia Pacific, Singapore)
- ap-southeast-2 (Asia Pacific, Sydney)

You're currently using the us-east-1 region.

프롬프트 템플릿 사용하기 :

User: I need to perform a security audit of my S3 buckets

Claude: I'll help you audit the security of your S3 buckets.

Here are AWS CLI commands to perform a comprehensive security audit:

# List all buckets with public access settings
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-public-access-block --bucket {}

# Check bucket policies for public access
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-policy --bucket {} 2>/dev/null

# Identify buckets without encryption
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-encryption --bucket {} 2>/dev/null

# Check for buckets without logging enabled
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-logging --bucket {} 2>/dev/null

# Verify bucket versioning status
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-versioning --bucket {}

사용 가능한 프롬프트 템플릿

AWS MCP 서버에는 다음과 같은 미리 정의된 프롬프트 템플릿이 포함되어 있습니다.

핵심 운영

즉각적인	설명	매개변수
`create_resource`	모범 사례를 사용하여 AWS 리소스를 생성하는 명령 생성	`resource_type` , `resource_name`
`resource_inventory`	리소스의 포괄적인 인벤토리를 만듭니다.	`service` , `region` (선택 사항)
`troubleshoot_service`	서비스 문제를 해결하기 위한 명령 생성	`service` , `resource_id`
`resource_cleanup`	자원을 식별하고 안전하게 정리합니다	`service` , `criteria` (선택 사항)

보안 및 규정 준수

즉각적인	설명	매개변수
`security_audit`	특정 AWS 서비스에 대한 감사 보안 설정	`service`
`security_posture_assessment`	AWS 환경 전반에 걸친 포괄적인 보안 평가	없음
`iam_policy_generator`	최소 권한 IAM 정책 만들기	`service` , `actions` , `resource_pattern` (선택 사항)
`compliance_check`	표준 준수 여부 확인	`compliance_standard` , `service` (선택 사항)

비용 및 성능

즉각적인	설명	매개변수
`cost_optimization`	서비스에 대한 비용 최적화 기회 찾기	`service`
`performance_tuning`	AWS 리소스의 성능 최적화 및 조정	`service` , `resource_id`

인프라 및 건축

즉각적인	설명	매개변수
`serverless_deployment`	모범 사례를 통해 서버리스 애플리케이션 배포	`application_name` , `runtime` (선택 사항)
`container_orchestration`	컨테이너 환경 설정(ECS/EKS)	`cluster_name` , `service_type` (선택 사항)
`vpc_network_design`	보안 VPC 네트워킹 설계 및 구현	`vpc_name` , `cidr_block` (선택 사항)
`infrastructure_automation`	인프라 관리 자동화	`resource_type` , `automation_scope` (선택 사항)
`multi_account_governance`	안전한 다중 계정 전략 구현	`account_type` (선택 사항)

신뢰성 및 모니터링

즉각적인	설명	매개변수
`service_monitoring`	종합적인 모니터링 설정	`service` , `metric_type` (선택 사항)
`disaster_recovery`	엔터프라이즈급 DR 솔루션 구현	`service` , `recovery_point_objective` (선택 사항)

보안

AWS MCP 서버는 명령 검증 및 보안에 대한 포괄적인 다층적 접근 방식을 구현합니다.

명령 검증 시스템

서버는 3계층 시스템을 통해 모든 AWS CLI 명령을 검증합니다.

기본 명령 구조 :
- 명령이 'aws' 접두사로 시작하고 유효한 서비스를 포함하는지 확인합니다.
- 적절한 명령 구문을 보장합니다
보안 중심 명령 필터링 :
- 위험한 명령 : 보안을 손상시킬 수 있는 명령을 차단합니다.
- 안전 패턴 : 일반적인 사용에 필요한 읽기 전용 작업을 명시적으로 허용합니다.
- 정규식 패턴 매칭 : 패턴 매칭을 통해 복잡한 보안 위험을 방지합니다.
파이프 커맨드 보안 :
- 파이프에서 사용되는 Unix 명령을 검증합니다.
- 명령을 안전한 허용 목록으로 제한합니다.
- 파일 시스템 조작 및 임의 명령 실행을 방지합니다.

기본 보안 구성

기본 보안 구성은 다음과 같은 공격 벡터를 방지하는 데 중점을 둡니다.

1. ID 및 액세스 관리(IAM) 위험

차단된 명령	보안 위험
`aws iam create-user`	지속적인 액세스로 잠재적인 백도어 계정을 생성합니다.
`aws iam create-access-key`	도난당하거나 오용될 수 있는 장기 자격 증명을 생성합니다.
`aws iam attach-*-policy`	정책 첨부를 통한 잠재적 권한 확대
`aws iam put-user-policy`	인라인 정책은 과도한 권한을 부여할 수 있습니다.
`aws iam create-policy`	잠재적으로 위험한 권한으로 새로운 정책 만들기
`aws iam create-login-profile`	기존 사용자에 대한 콘솔 암호를 생성합니다.
`aws iam deactivate-mfa-device`	다중 인증 요소를 비활성화하여 보안을 약화시킵니다.
`aws iam update-assume-role-policy`	신뢰 관계를 수정하여 권한 확대를 활성화합니다.

2. 감사 및 로깅 변조

차단된 명령	보안 위험
`aws cloudtrail delete-trail`	AWS 활동의 감사 추적을 제거합니다.
`aws cloudtrail stop-logging`	활동 로그 수집을 중단하고 사각지대를 만듭니다.
`aws cloudtrail update-trail`	로깅 구성을 리디렉션하거나 수정할 수 있습니다.
`aws config delete-configuration-recorder`	AWS Config에서 리소스 변경 사항을 기록하는 것을 비활성화합니다.
`aws guardduty delete-detector`	위협 탐지 기능을 비활성화합니다.

3. 민감한 데이터 접근 및 보호

차단된 명령	보안 위험
`aws secretsmanager put-secret-value`	민감한 자격 증명을 수정합니다
`aws secretsmanager delete-secret`	민감한 자격 증명을 제거합니다
`aws kms schedule-key-deletion`	암호화 키 삭제 일정으로 인해 데이터 손실 위험이 있습니다.
`aws kms disable-key`	암호화 키를 비활성화하여 잠재적으로 데이터를 노출합니다.
`aws s3api put-bucket-policy`	공개 S3 버킷을 생성하여 데이터를 노출할 수 있습니다.
`aws s3api delete-bucket-policy`	버킷에서 보호 정책을 제거합니다.

4. 네트워크 보안 위험

차단된 명령	보안 위험
`aws ec2 authorize-security-group-ingress`	인바운드 네트워크 접속을 열어 잠재적 노출을 방지합니다.
`aws ec2 authorize-security-group-egress`	아웃바운드 네트워크 접근을 허용하여 잠재적인 데이터 유출을 방지합니다.
`aws ec2 modify-instance-attribute`	인스턴스의 보안 속성을 변경할 수 있습니다.

이러한 패턴과 일치하는 많은 읽기 전용 작업은 안전 패턴을 통해 명시적으로 허용됩니다.

모든 get- , list- 및 describe- 명령
모든 도움말 명령( --help , help )
시뮬레이션 및 테스트 명령(예: aws iam simulate-custom-policy )

구성 옵션

보안 모드 :
- strict (기본값): 모든 보안 검증을 시행합니다.
- permissive : 경고를 기록하지만 실행을 허용합니다(신중하게 사용하세요)
사용자 정의 구성 :
- YAML 구성 파일을 통해 기본 보안 규칙 재정의
- 서비스별 위험 명령 구성
- 사용자 정의 안전 패턴 및 정규식 규칙 정의
- 환경 변수: AWS_MCP_SECURITY_CONFIG
실행 제어 :
- 시간 초과는 장시간 실행되는 명령을 방지합니다(기본값: 300초)
- 출력 크기 제한으로 메모리 문제 방지
- 환경 변수: AWS_MCP_TIMEOUT , AWS_MCP_MAX_OUTPUT

사용자 정의 보안 규칙 예

YAML 구성 파일을 정의하여 사용자 정의 보안 규칙을 만들 수 있습니다.

# Example custom security configuration
# Save to a file and set AWS_MCP_SECURITY_CONFIG environment variable

# Dangerous commands to block
dangerous_commands:
  iam:
    # Only block specific IAM operations for your environment
    - "aws iam create-user"
    - "aws iam attach-user-policy"
  
  # Custom service restrictions for your organization
  lambda:
    - "aws lambda delete-function"
    - "aws lambda remove-permission"
  
  # Prevent accidental DynamoDB table deletion
  dynamodb:
    - "aws dynamodb delete-table"

# Safe patterns to explicitly allow
safe_patterns:
  # Global safe patterns
  general:
    - "--help"
    - "--dry-run"
  
  # Allow read operations on IAM
  iam:
    - "aws iam get-"
    - "aws iam list-"
  
  # Allow specific Lambda operations
  lambda:
    - "aws lambda list-functions"
    - "aws lambda get-function"

# Complex regex rules for security validation
regex_rules:
  general:
    # Prevent use of root credentials
    - pattern: "aws .* --profile\\s+root"
      description: "Prevent use of root profile"
      error_message: "Using the root profile is not allowed for security reasons"
  
  iam:
    # Block creation of admin users
    - pattern: "aws iam create-user.*--user-name\\s+.*admin.*"
      description: "Prevent creation of admin users"
      error_message: "Creating users with 'admin' in the name is restricted"
    
    # Prevent wildcards in IAM policies
    - pattern: "aws iam create-policy.*\"Effect\":\\s*\"Allow\".*\"Action\":\\s*\"\\*\".*\"Resource\":\\s*\"\\*\""
      description: "Prevent wildcards in policies"
      error_message: "Creating policies with '*' wildcards for both Action and Resource is not allowed"
  
  s3:
    # Prevent public bucket policies
    - pattern: "aws s3api put-bucket-policy.*\"Effect\":\\s*\"Allow\".*\"Principal\":\\s*\"\\*\""
      description: "Prevent public bucket policies"
      error_message: "Creating bucket policies with public access is restricted"

보안 사례

이 시스템은 권한 상승을 방지하는 데 중점을 두고 IAM 모범 사례를 따릅니다.

# This command would be blocked (creates user)
aws iam create-user --user-name new-user
> Error: This command (aws iam create-user) is restricted for security reasons.

# This command would be blocked (attaches admin policy)
aws iam attach-user-policy --user-name any-user --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
> Error: Attaching Administrator policies is restricted for security reasons.

# This command would be blocked (opens SSH port globally)
aws ec2 authorize-security-group-ingress --group-id sg-12345 --protocol tcp --port 22 --cidr 0.0.0.0/0
> Error: Opening non-web ports to the entire internet (0.0.0.0/0) is restricted.

# These commands are allowed (read-only operations)
aws iam list-users
aws s3 ls
aws ec2 describe-instances

보안 모범 사례

프로덕션에서는 항상 기본 strict 보안 모드를 사용하십시오.
보안 고려사항 의 배포 권장 사항을 따르세요.
최소 권한 AWS 자격 증명으로 실행
사용자 정의 구성의 경우 보안 요구 사항에 중점을 두십시오.

개발

개발 환경 설정

# Install only runtime dependencies using pip
pip install -e .

# Install all development dependencies using pip
pip install -e ".[dev]"

# Or use uv for faster dependency management
make uv-install       # Install runtime dependencies
make uv-dev-install   # Install development dependencies

Makefile 명령어

이 프로젝트에는 일반적인 작업을 위한 다양한 대상이 포함된 Makefile이 포함되어 있습니다.

# Test commands
make test             # Run tests excluding integration tests
make test-unit        # Run unit tests only (all tests except integration tests)
make test-integration # Run integration tests only (requires AWS credentials)
make test-all         # Run all tests including integration tests

# Test coverage commands
make test-coverage    # Run tests with coverage report (excluding integration tests)
make test-coverage-all # Run all tests with coverage report (including integration tests)

# Linting and formatting
make lint             # Run linters (ruff check and format --check)
make lint-fix         # Run linters and auto-fix issues where possible
make format           # Format code with ruff

사용 가능한 명령어의 전체 목록을 보려면 make help 실행하세요.

코드 커버리지

이 프로젝트에는 Codecov 가 코드 커버리지 지표를 추적하는 구성이 포함되어 있습니다. 구성은 codecov.yml 파일에 있으며, 다음과 같은 기능을 합니다.

80%의 목표 적용 범위 임계값을 설정합니다.
테스트 파일, 설정 파일 및 문서를 적용 범위 보고서에서 제외합니다.
PR 주석 및 상태 확인을 구성합니다.

CI/CD 실행 중에 커버리지 보고서가 자동으로 생성되어 Codecov에 업로드됩니다.

통합 테스트

통합 테스트는 AWS MCP 서버가 실제 AWS 리소스와 정상적으로 작동하는지 확인합니다. 실행 방법은 다음과 같습니다.

AWS 리소스 설정 :
- 테스트를 위해 S3 버킷을 생성합니다.
- 환경 변수를 설정합니다: export AWS_TEST_BUCKET=your-test-bucket-name
- AWS 자격 증명이 구성되었는지 확인하세요.
통합 테스트 실행 :
# Run all tests including integration tests make test-all # Run only integration tests make test-integration

또는 pytest 명령을 직접 실행할 수 있습니다.

# Run all tests including integration tests
pytest --run-integration

# Run only integration tests
pytest --run-integration -m integration

문제 해결

인증 문제 : AWS 자격 증명이 올바르게 구성되었는지 확인하세요.
연결 오류 : 서버가 실행 중인지, AI 어시스턴트 연결 설정이 올바른지 확인하세요.
권한 오류 : AWS 자격 증명에 필요한 권한이 있는지 확인하세요.
시간 초과 오류 : 장시간 실행되는 명령의 경우 AWS_MCP_TIMEOUT 환경 변수를 늘리세요.

Docker로 배포하는 이유

Docker를 통해 AWS MCP 서버를 배포하는 것이 권장되는 접근 방식이며, 이를 통해 도구의 안전한 사용 패턴의 핵심을 형성하는 상당한 보안 및 안정성 이점을 얻을 수 있습니다.

보안 혜택

격리(주요 완화책): Docker 컨테이너는 필수적인 파일 시스템 및 프로세스 격리 기능을 제공합니다. AWS CLI 명령과 파이프로 연결된 Unix 유틸리티는 격리된 환경에서 실행됩니다. 파일 시스템에 영향을 미치는 우발적이거나 오용된 명령은 컨테이너로 제한되어 호스트 머신을 보호합니다 .
제어된 자격 증명 액세스: 자격 증명을 마운트할 때 :ro (읽기 전용) 플래그를 사용하면 컨테이너가 AWS 구성 파일을 수정하는 기능이 제한됩니다.
로컬 설치 없음: AWS CLI와 종속성을 호스트 시스템에 직접 설치하지 않아도 됩니다.
깨끗한 환경: 각 컨테이너 실행은 알려진 깨끗한 상태에서 시작됩니다.

신뢰성의 장점

일관된 구성 : 모든 필수 도구(AWS CLI, SSM 플러그인, jq)가 사전 설치되어 올바르게 구성되었습니다.
종속성 관리 : 도구와 종속성 간의 버전 충돌을 방지합니다.
크로스 플랫폼 일관성 : 다양한 운영 체제에서 동일한 방식으로 작동합니다.
완벽한 환경 : 명령 파이프, 필터링 및 포맷팅에 필요한 모든 도구가 포함되어 있습니다.

기타 혜택

다중 아키텍처 지원 : Intel/AMD(x86_64) 및 ARM(Apple Silicon, AWS Graviton) 프로세서 모두에서 실행됩니다.
간단한 업데이트 : 단일 풀 명령으로 새 버전으로 업데이트
Python 환경 충돌 없음 : 시스템의 다른 Python 애플리케이션과의 잠재적 충돌을 방지합니다.
버전 고정 : 프로덕션 환경에서 안정성을 위해 특정 버전에 쉽게 고정

버전 관리

이 프로젝트에서는 setuptools_scm을 사용하여 Git 태그에 따라 버전을 자동으로 결정합니다.

릴리스 버전 : Git 태그가 있는 경우(예: 1.2.3 ) 버전은 해당 태그와 정확히 일치합니다.
개발 버전 : 태그가 없는 커밋의 경우 개발 버전은 <last-tag>.post<commits-since-tag>+g<commit-hash>.d<date> 형식으로 생성됩니다(예: 1.2.3.post10+gb697684.d20250406 ).

다음 버전은 자동으로 포함됩니다.

패키지 버전 정보
Docker 이미지 레이블
지속적인 통합 빌드

릴리스 만들기

새로운 릴리스 버전을 만들려면:

# Create and push a new tag
git tag -a 1.2.3 -m "Release version 1.2.3"
git push origin 1.2.3

CI/CD 파이프라인은 적절한 버전 태그로 Docker 이미지를 자동으로 빌드하고 게시합니다.

버전 관리 시스템에 대한 자세한 내용은 VERSION.md를 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Integrations