Apps Script: Gemini CLI 및 MCP 서버로 Gmail 부가기능 바이브 코드 작성

1. 개요

이 실습에서는 최신 AI 기반 워크플로를 통해 처음부터 동적 Gmail 부가기능을 빌드하는 방법을 안내합니다. Gemini CLI를 사용하여 강력한 로컬 개발 환경을 오케스트레이션하고, MCP (모델 컨텍스트 프로토콜) 서버와 Gemini CLI 확장 프로그램을 활용하여 gcloud 및 clasp와 같은 도구를 통합합니다.

생성하는 부가기능은 Google Cloud의 Vertex AI 플랫폼에서 이미지 모델을 호출하여 요청 시 고유한 고양이 이미지를 생성하고 표시합니다.

이 과정을 마치면 Gmail 인터페이스 내에서 직접 Vertex AI API를 호출하여 고유한 이미지를 생성하는 완전한 기능을 갖춘 Gmail 부가기능을 만들 수 있으며, 이 모든 작업은 로컬 명령줄에서 관리됩니다.

2. 학습할 내용

이 실습을 완료하면 다음 작업을 수행하는 방법을 배우게 됩니다.

• 확장 프로그램과 함께 Gemini CLI 설정 및 사용
• 외부 API를 호출하는 Gmail 부가기능 빌드
• Vertex AI API를 호출하여 이미지를 생성하도록 부가기능 수정
• Apps Script 사용자 인터페이스에서 Google Workspace 부가기능의 테스트 버전 배포

3. 설정 및 요건

실습을 시작하기 전에

1. 아직 Google 계정이 없다면 Google 계정을 만들어야 합니다. 직장 또는 학교 계정 대신 개인 계정을 사용합니다. 직장 및 학교 계정에는 이 실습에 필요한 API를 사용 설정하지 못하도록 하는 제한이 있을 수 있습니다.
2. Google Cloud 콘솔에 로그인합니다.
3. Cloud 콘솔에서 결제를 사용 설정합니다.

⚠️주의: 이 실습에서는 청구 가능한 Cloud 리소스를 사용합니다. 지속적인 요금이 청구되지 않도록 실습이 끝날 때 정리 단계를 따르세요. 신규 사용자는 300달러(USD) 상당의 무료 체험판을 사용할 수 있습니다.

4. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다.

실습 요구사항

이 실습을 최대한 활용하려면 다음이 필요합니다.

• 웹브라우저: Chrome과 같은 표준 웹브라우저 (권장)
• 전용 시간: 실습 활동에 집중할 수 있는 충분한 시간을 확보하세요.

4. Google Cloud 환경 설정

1. Cloud Shell 활성화 아이콘 클릭: 콘솔 헤더의 오른쪽 상단에서 마우스를 가져가면 'Cloud Shell 활성화'라고 표시되는 터미널 아이콘을 클릭합니다.
2. 승인을 클릭합니다.
3. 초기화 대기: 콘솔 창 하단의 새 프레임에서 Cloud Shell 세션이 열립니다. 세션에서 임시 Debian 기반 가상 머신 (VM)을 프로비저닝하므로 초기화하는 데 몇 분 정도 걸립니다.
4. 세션이 초기화되면 명령줄 프롬프트 (user@cloudshell:~ $)가 표시됩니다.
5. 확장 버튼을 클릭하여 Cloud Shell 창을 확장하여 창 크기를 늘릴 수 있습니다.
6. 프로젝트 확인: 다음 명령어를 실행합니다.

gcloud config list project

7. 필요한 경우 프로젝트를 변경합니다.

gcloud config set project [YOUR_PROJECT_ID]

이제 실습 활동을 시작할 수 있습니다.

5. 로컬 개발 환경 구성

이 작업에서는 터미널에서 클라우드 및 Apps Script 프로젝트를 관리할 수 있도록 Gemini CLI와 확장 프로그램을 설정합니다.

1. Gemini CLI는 Cloud Shell 환경의 일부로 이미 설치되어 있으므로 설치할 필요가 없습니다.
2. clasp도 Cloud Shell 환경의 일부로 이미 설치되어 있지만 이 실습에서는 최신 버전을 사용하도록 하겠습니다.

npm install -g @google/clasp@latest

3. 다음 명령어를 입력하고 아래 안내를 따라 clasp가 계정에 액세스하도록 승인합니다.

clasp login --no-localhost

터미널에서 생성된 URL을 클릭하여 clasp를 승인합니다. 학생 실습 계정으로 로그인하고 권한을 묻는 메시지가 표시되면 모두 선택을 선택하고 계속을 클릭합니다. 그러면 아래와 같은 오류 메시지가 표시됩니다.

브라우저 창에서 URL (http://localhost:8888/?code=xxx로 시작)을 복사하여 열려 있는 Cloud Shell 세션에 붙여넣고 Enter 키를 누릅니다. clasp에서 승인 흐름을 계속 진행하고 로그인이 성공하면 You are logged in as [e-mail]과 비슷한 확인 메시지가 표시됩니다.

4. clasp Gemini CLI 확장 프로그램을 설치합니다.

gemini extensions install https://github.com/google/clasp --consent

5. gcloud Gemini CLI 확장 프로그램을 설치합니다.

gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent

6. Google Workspace 개발자 Gemini CLI 확장 프로그램을 설치합니다.

gemini extensions install https://github.com/googleworkspace/developer-tools --consent

7. 빈 프로젝트 디렉터리를 만듭니다.

mkdir genai-cat-add-on

8. 새로 만든 프로젝트 디렉터리로 변경합니다.

cd genai-cat-add-on

9. 이 프로젝트의 Gemini CLI 컨텍스트 파일을 구성합니다.

cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE

10. 학생 실습 계정에서 Google Apps Script API를 사용 설정하고 Google Apps Script API를 클릭한 다음 사용 안함에서 사용으로 전환합니다.

6. Gemini CLI 설정 시작 및 확인

1. 프로젝트 디렉터리에서 Gemini를 시작합니다.

gemini

⭐ 도움말: Gemini CLI를 사용하는 중에 문제가 발생하면 문제 해결 도움말로 이동하여 특정 버전의 Gemini CLI를 실행할 수 있습니다.

2. 기본적으로 Gemini CLI는 파일 변경사항을 검토하고 수락하라는 메시지를 표시합니다. 이 실습에서는 Shift + Tab을 눌러 수정사항을 자동으로 수락하여 실습을 제시간에 완료하는 것이 좋습니다. 이제 화면에 이 옵션이 빨간색으로 강조 표시되어야 합니다.

3. GEMINI.md 파일이 로드되었는지 확인하고 Gemini CLI의 컨텍스트에 로드된 내용을 표시합니다.

/memory show

4. MCP 서버가 올바르게 구성되었는지 확인합니다. gcloud MCP 서버가 초기화되는 데 시간이 걸릴 수 있으므로 연결이 끊긴 것으로 표시되더라도 놀라지 마세요. 잠시 후 다시 시도해 보세요.

/mcp list

ℹ️참고: 다음 단계를 따르는 동안 Gemini CLI에서 실습에 필요한 특정 도구를 사용할 수 있도록 허용하라는 메시지가 표시됩니다. 모든 도구를 실행할 수 있는 권한을 부여해야 합니다.

7. Gmail 부가기능 만들기

5. Gemini에게 Gmail 부가기능의 첫 번째 버전을 만들어 달라고 요청합니다.

Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.

❗중요: Gemini CLI에서 MCP 도구 또는 확장 프로그램의 실행을 허용하라는 메시지가 표시되면 메시지에 표시된 서버 / 확장 프로그램의 도구를 항상 허용하여 처리할 수 있습니다.

6. Gemini가 프롬프트에 대한 대답을 완료하면 제공된 링크를 클릭하거나 Apps Script 홈페이지로 이동하여 genai-cat-add-on 프로젝트를 클릭합니다.
7. 페이지 왼쪽의 프로젝트 설정 아이콘 (톱니바퀴 아이콘) 을 클릭합니다.

8. '편집기에 'appsscript.json' 매니페스트 파일 표시' 옵션을 선택합니다.

9. 편집기 화면으로 전환하여 Code.gs에 생성된 코드와 appsscript.json에 프로젝트를 구성하는 매니페스트 파일을 확인합니다.

8. 부가기능 설치 및 테스트

1. Apps Script 프로젝트 페이지로 돌아갑니다.
2. 상단에서 배포 버튼을 찾습니다.
3. 배포 옆에 있는 화살표를 클릭하고 테스트 배포를 선택합니다.
4. 표시되는 '배포 테스트' 대화상자에서 게시되지 않은 부가기능을 설치하는 옵션을 확인할 수 있습니다.
5. Install 버튼을 클릭합니다.
6. 확인 메시지가 표시됩니다. 하단의 완료를 클릭하여 배포 대화상자를 닫습니다.
7. Gmail 홈페이지를 열고 새로고침합니다.
8. 이제 부가기능을 사용할 수 있습니다. 부가기능이 오른쪽 패널에 표시됩니다.
9. 부가기능과 처음 상호작용할 때 필요한 데이터 또는 권한에 액세스하도록 승인하라는 메시지가 표시됩니다. 화면에 표시되는 메시지에 따라 권한을 부여합니다.
10. 고양이 이미지가 표시됩니다. 표시되지 않으면 오류 메시지를 공유하여 Gemini CLI로 문제를 해결하세요.

9. AI 이미지 생성 로직 구현

1. 이제 Gemini에게 이미지를 생성하는 로직을 추가해 달라고 요청합니다.

Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.

2. Gmail 홈페이지를 새로고침하고 부가기능을 다시 엽니다. 메시지가 표시되면 새 권한을 수락합니다.
3. 이제 AI 생성 고양이 이미지가 표시됩니다. 이미지가 표시되지 않으면 오류 메시지를 공유하고 안내를 따라 Gemini CLI로 문제를 해결하세요.
4. 이메일을 열면 이미지가 발신자 이름이 포함된 말풍선으로 변경됩니다. 이전 단계와 마찬가지로 Gemini CLI 문제를 해결합니다.

10. [선택사항] 동물 유형 드롭다운 추가

1. Gemini에게 고양이 이미지 외에 다른 동물을 생성하는 옵션을 추가해 달라고 요청합니다.

Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.

2. 세로 점 3개를 클릭하고 새로고침을 클릭하거나 Gmail 홈페이지를 새로고침하고 부가기능을 다시 열어 부가기능을 새로고침합니다.
3. 다른 동물 사진을 선택하여 새 기능을 테스트합니다. UI가 새로고침되지 않거나 오류가 표시되는 등의 오류가 있는 경우 오류 메시지를 공유하고 안내를 따라 Gemini CLI로 문제를 해결합니다.

11. 삭제

Gemini CLI 종료

Gemini CLI를 종료하고 다음 명령어를 실행하여 사용 통계를 확인합니다.

/quit

Google Cloud 프로젝트 삭제

⚠️주의: 이 Google Cloud 프로젝트를 삭제하면 이 Codelab과 관련이 없는 작업을 포함하여 프로젝트 내의 모든 리소스가 영구적으로 삭제됩니다. 또한 나중에 이 맞춤 프로젝트 ID를 재사용할 수 없습니다. ID를 유지하려면 전체 프로젝트가 아닌 이 실습에서 만든 특정 리소스만 삭제합니다.

이 Codelab에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 Google Cloud 프로젝트를 삭제하는 것이 좋습니다.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Apps Script 프로젝트 삭제

⚠️주의: 이 Apps Script 프로젝트를 삭제하면 포함된 모든 파일이 영구적으로 삭제되고 활성 배포가 모두 삭제됩니다. 이 Codelab에서 기존 프로젝트를 재사용한 경우 이 작업으로 이전 작업도 삭제됩니다. 나중에 사용할 배포를 유지하려면 프로젝트를 완전히 삭제하는 대신 프로젝트 내에서 개별 리소스를 수동으로 삭제하는 것이 좋습니다.

왼쪽 탐색 패널에서 정보 아이콘을 클릭한 다음 화면 오른쪽에 있는 휴지통 아이콘을 클릭하여 Apps Script 프로젝트를 삭제합니다.

12. 문제 해결 도움말

• Gemini CLI 및 확장 프로그램에 문제가 있는 경우 다음 명령어를 사용하여 특정 작동 버전의 Gemini CLI를 실행할 수 있습니다.

npx https://github.com/google-gemini/gemini-cli#v0.12.0

• 오류가 발생하면 Gemini에게 오류를 수정해 달라고 요청하고 오류와 컨텍스트 (오류가 발생하는 위치)를 공유합니다.
• Gemini가 오류 로깅을 구현하고 오류를 공유해 달라고 요청하는 경우 오류를 일으킨 단계를 다시 실행한 다음 결과를 Gemini와 공유하세요.
• 다음과 같은 프롬프트를 사용해 보세요.

You have my permission to fix any errors. Please go ahead and make it work.

• 막혀서 Gemini를 돕고 싶다면 다음 프롬프트를 사용하세요.

Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

13. 축하합니다.

실습을 완료하고 Gemini CLI를 사용하여 Gmail 부가기능을 바이브 코딩했습니다.

이 실습에서는 다음을 수행하는 방법을 배웠습니다.

• Gemini CLI를 사용합니다.
• MCP (모델 컨텍스트 프로토콜) 서버를 사용하여 도구를 설치하고 Gemini CLI를 확장합니다.
• Gmail 부가기능을 빌드, 배포, 설치합니다.

이제 다음 실습으로 넘어갈 준비가 되었습니다.