Amazon Q Developer CLI & MCP 워크샵(1)

Amazon Q Developer CLI & MCP란? 쉽게 정리해보기

이번 워크샵에서는 **Amazon Q Developer의 CLI(Command Line Interface)**와 **MCP(Model Context Protocol)**를 활용한 실습을 진행합니다. 실습을 본격적으로 하기 전에, 먼저 "Amazon Q Developer"가 뭔지부터 간단히 이해하고 넘어갈게요.

💡 Amazon Q Developer란?

Amazon Q Developer는 개발자를 위한 생성형 AI 어시스턴트예요. 쉽게 말해, 코딩할 때 옆에서 도와주는 똑똑한 동료 같은 존재죠. 우리가 자주 사용하는 개발 툴이나 CLI, AWS 콘솔, 슬랙 같은 협업툴까지 폭넓게 지원해서, 개발 속도와 효율을 높여줘요.

Amazon Q Developer는 어디서 쓸 수 있을까?

1. IDE(개발툴) 확장 프로그램으로
   VS Code 같은 IDE에서 실시간으로 코드를 추천해주고, 주석을 기반으로 코드를 만들어주거나, 디버깅 도우미 역할을 해줘요.
2. CLI(Command Line Interface)
   우리가 터미널에서 명령어를 입력해서 AWS 리소스를 관리할 때, Amazon Q가 도우미로 함께 작업해요.
   예: q ask 명령어로 S3 버킷을 만들거나, CloudFormation 템플릿을 자동 생성하게 할 수 있어요.
3. AWS 콘솔, 문서, 슬랙, Teams 등
   콘솔에서 직접 Amazon Q와 대화하거나, 슬랙 채널에서 AWS 리소스 상태를 바로 확인할 수 있어요.
4. GitHub, GitLab 같은 외부 툴 연동도 가능
   코드 리뷰, PR 자동화, 보안 체크 같은 반복 업무를 대신해줄 수 있어요.

---

🔧 MCP(Model Context Protocol)란?

MCP는 Amazon Q Developer가 다양한 도구나 환경에서 문맥을 이해하고 작업을 실행할 수 있게 해주는 기술 기반이에요.
쉽게 말해, Q가 "내가 지금 어떤 상황에서 어떤 파일을 보고 있는지", "무슨 프로젝트를 하고 있는지" 등을 파악해서 더 정확한 도움을 줄 수 있게 해주는 시스템

 

Q가 어떤 상황인지 "컨텍스트"를 인식하게 해주는 역할.
→ 현재 어떤 파일을 보고 있는지, 어떤 프로젝트인지, 어떤 명령을 수행했는지 등의 정보 전달

CLI에서 특정 플러그인이나 설정을 통해 더 정밀하고 유의미한 작업이 가능하게 해주는 핵심 요소라고 이해하면 될 듯.
(예: 단순히 리소스를 생성하는 게 아니라, 현재 구조를 파악하고 거기에 맞게 자동 생성 가능)

 

 

⚙️  VS Code Server + Amazon Q CLI 개발 환경 구축

 

EC2 인스턴스에 브라우저 기반 Visual Studio Code 환경을 배포하기 위해 VS Code 환경에는 필요한 모든 것이 사전 구성

• ✅ Amazon Q Developer CLI: 워크샵 전반에 걸쳐 사용할 주요 도구입니다.
• ✅ AWS CLI: AWS 서비스와 상호작용하기 위한 도구입니다.
• ✅ SAM CLI: 서버리스 애플리케이션 배포를 위한 도구입니다.
• ✅ Python: 다양한 도구와 스크립트 실행에 필요합니다.
• ✅ 코드 샘플: 실습에 필요한 모든 예제 프로젝트입니다.

✅ 요약 흐름도

1. VPC/서브넷/인터넷 구성 → EC2 생성 및 보안 설정
2. UserData를 통해 EC2에서 개발 환경 자동 설치
3. CodeServer를 CloudFront로 배포 → IP 보호 & 접근 제어
4. 결과 값으로 CloudFront URL, 인스턴스 정보, 암호 출력

Amazon EC2에 직접 수동으로 VS Code Server + Amazon Q CLI 개발 환경을 구축하는 전체 가이드를 아래와 같이 단계별로 정리했어. Code Server를 EC2에서 직접 돌리고, Amazon Q Developer CLI와 SAM CLI 등 개발 도구까지 포함하는 세팅 방식

---

✅ 1단계: EC2 인스턴스 생성

🔸 사양 추천

• AMI: Amazon Linux 2023 (x86_64)
• 인스턴스 타입: t3.large 이상
• 보안그룹
  • 인바운드: TCP 8080 (CloudFront 또는 본인 IP에서만 허용)
  • 아웃바운드: 전체 허용

---

✅ 2단계: EC2 초기 세팅 (SSH 접속 후)

# 접속
ssh -i <your-key.pem> ec2-user@<EC2-Public-IP>

 

---

✅ 3단계: 필수 패키지 설치

 

sudo dnf update -y
sudo dnf install -y unzip wget curl git

---

✅ 4단계: AWS CLI 설치

curl -fsSL https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip
unzip awscliv2.zip
sudo ./aws/install
aws --version

---

✅ 5단계: AWS SAM CLI 설치

curl -LO https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
unzip aws-sam-cli-linux-x86_64.zip -d sam-installation
sudo ./sam-installation/install
sam --version

---

✅ 6단계: VS Code Server 설치

# 최신 버전 번호를 확인하고 교체
VERSION=4.91.1

curl -fOL https://github.com/coder/code-server/releases/download/v${VERSION}/code-server-${VERSION}-amd64.rpm
sudo rpm -i code-server-${VERSION}-amd64.rpm

# 서비스 실행
sudo systemctl enable --now code-server@ec2-user

---

✅ 7단계: Code Server 설정

# 비밀번호로 AWS Account ID 사용
PASSWORD=$(aws sts get-caller-identity --query "Account" --output text)

# 설정 파일 수정
CONFIG="/home/ec2-user/.config/code-server/config.yaml"
sed -i.bak "s/password:.*/password: $PASSWORD/" $CONFIG
sed -i 's/127.0.0.1:8080/0.0.0.0:8080/' $CONFIG

# 재시작
sudo systemctl restart code-server@ec2-user

---

✅ 8단계: Amazon Q Developer CLI 설치

cd /home/ec2-user
wget https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.appimage
chmod +x amazon-q.appimage
./amazon-q.appimage --appimage-extract

echo 'export PATH=/home/ec2-user/squashfs-root/usr/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# CLI 활성화
q login
# => 여기서 "Use for Free with Builder ID" → 웹 브라우저에서 인증

---

✅ 9단계: VS Code 확장 설치 (Amazon Q, Python 등)

# 설치는 code-server로 실행
code-server --install-extension amazonwebservices.amazon-q-vscode
code-server --install-extension ms-python.python

---

✅ 10단계: S3 파일 다운로드 (옵션)

 

# 예: Q CLI 데모 패키지 다운로드
aws s3 cp s3://<your-bucket-name>/<your-prefix>/lambda-q-cli.zip .
unzip lambda-q-cli.zip

---

✅ 11단계: 웹 접속 확인

브라우저에서 아래 주소로 접속:

http://<EC2 Public IP>:8080

로그인 비밀번호는 AWS 계정 ID (예: 123456789012)

 

 

 VS Code 인터페이스 보기

1. 탐색기 (왼쪽 사이드바): 작업 공간의 파일과 폴더를 탐색합니다.
2. 터미널 (하단 패널): 명령줄 인터페이스에 액세스합니다.
3. 편집기 (메인 영역): 코드 파일을 보고 편집합니다.
4. 확장 (왼쪽 사이드바): 추가 기능을 위한 VS Code 확장입니다.

 

⚙️  설치된 도구 확인하기

1. Terminal > New Terminal을 클릭하여 새 터미널을 엽니다.

 

2. 다음 명령어를 실행하여 설치를 확인합니다:

AWS CLI 버전 확인:

aws --version

Amazon Q CLI 버전 확인:

q --version

SAM CLI 버전 확인:

sam --version

Python 설치 확인:

python3 --version

⚙️  AWS CLI 설정하기

계정의 AWS 리소스와 상호작용하려면 AWS 자격 증명을 설정해야 합니다

1. AWS 자격 증명 파일을 편집합니다:

nano ~/.aws/credentials

 

2. 파일에 자격 증명을 추가합니다:

[default]
aws_access_key_id = <your-access-key>
aws_secret_access_key = <your-secret-key>
aws_session_token = <your-session-token>

 

3. 저장하고 종료합니다 (Ctrl+O, Enter, Ctrl+X).

예시:

[default] 
aws_access_key_id = AKIAIOSFODNN7EXAMPLE 
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

4.AWS 구성 파일을 편집합니다:

nano ~/.aws/config

5. 리전 구성을 추가합니다:

[default]
region = us-east-1
output = json

6.저장하고 종료합니다 (Ctrl+O, Enter, Ctrl+X).\

7. 현재 AWS CLI 설정을 표시하여 구성을 확인합니다:

aws configure list

예상 출력:

   Name                    Value             Type    Location
   ----                    -----             ----    --------
profile                <not set>             None    None
access_key     ****************XXXX shared-credentials-file    
secret_key     ****************XXXX shared-credentials-file    
region                us-east-1      config-file    ~/.aws/config

8. 현재 AWS 자격 증명이 나타내는 IAM ID에 대한 세부 정보를 검색합니다:

aws sts get-caller-identity

예상 출력:

 {
   "UserId": "AROAXXXXXXXXXXXXXXXXX:user@example.com",
   "Account": "123456789012",
   "Arn": "arn:aws:sts::123456789012:assumed-role/TeamRole/user@example.com"
 }

출력에는 AWS 계정 ID와 인증된 IAM 역할 또는 사용자가 표시됩니다. 이는 적절한 AWS 자격 증명이 구성되었음을 확인해 줍니다. 이제 개발 환경이 설정되었으므로 Amazon Q Developer CLI 작업을 시작할 준비가 되었습니다!

 

🧪 실습 1: Amazon Q Developer CLI 시작하기

Amazon Q Developer CLI는 코드 서버 환경에 이미 설치되어 있음.
이제 해야 할 일은 AI 기능을 쓸 수 있도록 Builder ID 인증을 연결해주는 작업.
CLI 자체는 로컬에서 돌아가지만, Q의 대화형 기능은 AWS Builder ID를 통해 인증을 받아야 사용 가능하다.

---

📌 Amazon Q Developer CLI가 뭔데?

본격적인 명령어를 사용하기 전에, Amazon Q CLI가 어떻게 작동하는지 개념부터 정리해봤다.
이걸 이해해두면 명령 하나하나가 왜 그렇게 동작하는지 자연스럽게 연결된다.

✔️ 에이전트 기반 CLI

단순한 명령 실행 도구가 아님.
→ 입력한 자연어 요청을 의도 파악 → 문제 해결 → 실행의 흐름으로 이어주는 AI 에이전트처럼 동작함.

✔️ 자연어 이해 & 명령 생성

예를 들어,

nginx

복사편집

q ask "S3 버킷 하나 만들고, 퍼블릭 읽기 막아줘"

이렇게 요청하면,
→ Q가 자연어를 해석하고
→ 필요한 AWS CLI 명령어로 바꿔서
→ 리소스를 생성하고 설정까지 처리해줌.

✔️ 컨텍스트 인식

대화형으로 작업 가능.
→ 이전 명령어에서 만든 자원을 기억하고
→ 다음 명령어에서 그걸 기반으로 이어서 작업 가능함.
(대화형 에이전트 느낌이라고 보면 됨)

✔️ 도구 통합 & 확장성

• AWS CLI 기반 명령 실행
• 로컬 파일 접근
• **MCP(Model Context Protocol)**를 통해 더 전문적인 기능 확장 가능
  → CI/CD, IaC 등 다양한 워크플로우에도 연계 가능

✔️ 보안 모델

명령 실행 전 **수동 승인(confirm)**을 요구함
→ 실수로 자원 삭제 같은 일 방지
→ AI에게 맡기되, 통제권은 내가 유지

---

💡 왜 CLI 버전이 유용할까?

Amazon Q는 IDE 플러그인으로도 사용 가능하지만,
CLI는 별도 터미널에서 바로 쓸 수 있고, 더 유연한 활용이 가능하다.

• 독립형으로 쓰거나, VS Code, JetBrains 터미널에서 직접 실행 가능
• SSH 접속한 서버나 코드 컨테이너 안에서도 바로 실행 가능
  → 어떤 환경이든 명령줄만 있으면 Q를 쓸 수 있다!

---

✅ 1단계: AWS Builder ID로 로그인

Amazon Q CLI를 처음 사용할 땐, 먼저 인증을 진행해야 함.

1. 코드 서버에서 터미널 열기
   Terminal → New Terminal 클릭
2. 다음 명령어 실행
3. bash
   q login
4. 로그인 옵션 선택
   Use for Free with Builder ID 선택
   👉 무료 체험으로 Builder ID 로그인 가능
5. URL과 코드가 출력됨
   → 터미널에 나오는 인증 URL을 브라우저에 복붙해서 접속
6. 브라우저에서 인증 진행
   • Confirm and continue 클릭
   • Allow access 클릭
7. 터미널에서 인증 완료 메시지 확인

---

💡 AWS Builder ID 인증, 이게 뭔데?

Q를 쓰기 위한 사용자 인증 수단이라고 보면 된다.
중요한 포인트는 아래 네 가지.

• Amazon Q의 대화형 기능 활성화용 인증
• 일반 AWS 계정이랑은 별개
  → AWS 리소스에 접근 권한을 직접 주는 건 아님
• 실제 리소스 제어는 로컬 AWS 프로파일 자격증명을 따름
• 즉, Q는 AWS 자격이 있어야 리소스를 만들거나 수정 가능

정리하자면:
Builder ID는 Q 사용 인증용
AWS 자격은 리소스 접근 권한용
→ 둘 다 필요함