Apps Script: Gemini CLI और MCP सर्वर की मदद से, Gmail ऐड-ऑन को वाइब-कोड करना

1. खास जानकारी

इस लैब में, आपको एआई की मदद से काम करने वाले आधुनिक वर्कफ़्लो के बारे में बताया गया है. इसकी मदद से, Gmail के डाइनैमिक ऐड-ऑन को शुरू से बनाया जा सकता है. gcloud और clasp जैसे टूल को इंटिग्रेट करने के लिए, MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) सर्वर और Gemini CLI एक्सटेंशन का इस्तेमाल करके, एक बेहतरीन लोकल डेवलपमेंट एनवायरमेंट को व्यवस्थित करने के लिए, Gemini CLI का इस्तेमाल किया जाएगा.

आपके बनाए गए ऐड-ऑन में, Google Cloud के Vertex AI प्लैटफ़ॉर्म पर मौजूद इमेज मॉडल को कॉल करके, मांग के हिसाब से बिल्ली की यूनीक इमेज जनरेट की जाएगी और उसे दिखाया जाएगा.

आखिर तक, आपके पास पूरी तरह से काम करने वाला Gmail ऐड-ऑन होगा. यह ऐड-ऑन, Vertex AI API को कॉल करके Gmail इंटरफ़ेस में सीधे तौर पर यूनीक इमेज जनरेट करता है. इन सभी को आपकी लोकल कमांड लाइन से मैनेज किया जाता है.

2. आपको क्या सीखने को मिलेगा

इस लैब को पूरा करने के बाद, आपको इनके बारे में जानकारी मिलेगी:

• एक्सटेंशन के साथ Gemini CLI को सेट अप करना और उसका इस्तेमाल करना
• ऐसा Gmail ऐड-ऑन बनाना जो किसी बाहरी एपीआई को कॉल करता हो
• इमेज जनरेट करने के लिए, Vertex AI API को कॉल करने के लिए ऐड-ऑन में बदलाव करना
• Apps Script के यूज़र इंटरफ़ेस से, Google Workspace ऐड-ऑन का टेस्ट वर्शन डिप्लॉय करना

3. सेटअप और ज़रूरी शर्तें

लैब शुरू करने से पहले

1. अगर आपके पास पहले से कोई Google खाता नहीं है, तो आपको एक Google खाता बनाना होगा. ऑफ़िस या स्कूल वाले खाते के बजाय, निजी खाते का इस्तेमाल करें. ऑफ़िस और स्कूल वाले खातों पर कुछ पाबंदियां हो सकती हैं. इनकी वजह से, इस लैब के लिए ज़रूरी एपीआई चालू नहीं किए जा सकते.
2. Google Cloud Console में साइन इन करें.
3. Cloud Console में बिलिंग चालू करें.

⚠️अहम जानकारी: इस लैब में, बिल किए जाने वाले Cloud संसाधनों का इस्तेमाल किया जाता है. लगातार शुल्क से बचने के लिए, लैब के आखिर में दिए गए निर्देशों का पालन करके, संसाधनों को हटाएं. नए उपयोगकर्ता, 300 डॉलर की बिना किसी शुल्क आज़माने की सुविधा का फ़ायदा पा सकते हैं.

4. नया प्रोजेक्ट बनाएं या किसी मौजूदा प्रोजेक्ट का फिर से इस्तेमाल करें.

लैब की ज़रूरी शर्तें

इस लैब का ज़्यादा से ज़्यादा फ़ायदा पाने के लिए, आपको इनकी ज़रूरत होगी:

• वेब ब्राउज़र: Chrome जैसा कोई स्टैंडर्ड वेब ब्राउज़र (सुझाया गया).
• तय किया गया समय: लैब की गतिविधियों पर ध्यान देने के लिए, पर्याप्त समय निकालें.

4. Google Cloud एनवायरमेंट सेट अप करना

1. 'Cloud Shell चालू करें' आइकॉन पर क्लिक करें: कंसोल के हेडर में सबसे ऊपर दाएं कोने में मौजूद, टर्मिनल आइकॉन पर क्लिक करें. इस आइकॉन पर कर्सर घुमाने पर, "Cloud Shell चालू करें" लिखा होता है.
2. अनुमति दें पर क्लिक करें.
3. Wait for Initialization: Cloud Shell सेशन, आपकी कंसोल विंडो में सबसे नीचे एक नए फ़्रेम में खुलेगा. सेशन को शुरू होने में कुछ समय लगेगा, क्योंकि यह आपके लिए Debian पर आधारित एक अस्थायी वर्चुअल मशीन (वीएम) उपलब्ध कराता है.
4. सेशन शुरू होने के बाद, आपको कमांड-लाइन प्रॉम्प्ट (user@cloudshell:~ $) दिखेगा.
5. विंडो का साइज़ बढ़ाने के लिए, बड़ा करें बटन पर क्लिक करके Cloud Shell विंडो को बड़ा किया जा सकता है.
6. अपने प्रोजेक्ट की पुष्टि करें: यह निर्देश चलाएं:

gcloud config list project

7. अगर ज़रूरी हो, तो अपना प्रोजेक्ट बदलें:

gcloud config set project [YOUR_PROJECT_ID]

अब आप लैब की गतिविधियां शुरू कर सकते हैं!

5. अपना लोकल डेवलपमेंट एनवायरमेंट कॉन्फ़िगर करना

इस टास्क में, आपको Gemini CLI और इसके एक्सटेंशन सेट अप करने होंगे. इससे, अपने टर्मिनल से क्लाउड और Apps Script प्रोजेक्ट मैनेज किए जा सकेंगे.

1. Gemini CLI, Cloud Shell एनवायरमेंट के हिस्से के तौर पर पहले से ही इंस्टॉल है. इसलिए, इसे इंस्टॉल करने की ज़रूरत नहीं है.
2. clasp, Cloud Shell एनवायरमेंट के हिस्से के तौर पर पहले से ही इंस्टॉल है. हालांकि, हम यह पक्का करेंगे कि इस लैब में, हम सबसे नए वर्शन का इस्तेमाल कर रहे हों.

npm install -g @google/clasp@latest

3. clasp को अपने खाते का ऐक्सेस देने के लिए, यहां दिया गया निर्देश डालें और नीचे दिए गए निर्देशों का पालन करें:

clasp login --no-localhost

clasp को अनुमति देने के लिए, टर्मिनल में जनरेट किए गए यूआरएल पर क्लिक करें. लॉगिन करने के लिए, छात्र-छात्राओं के लिए बने लैब खाते का इस्तेमाल करें. जब अनुमतियों के लिए कहा जाए, तो सभी चुनें को चुनें और जारी रखें पर क्लिक करें. इसके बाद, आपको गड़बड़ी का यह मैसेज दिखेगा.

अपनी ब्राउज़र विंडो से यूआरएल कॉपी करें (जो 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 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. Deploy के बगल में मौजूद ऐरो पर क्लिक करें और Test deployments चुनें.
4. इसके बाद, "टेस्ट डिप्लॉयमेंट" डायलॉग बॉक्स दिखेगा. इसमें आपको ऐसा ऐड-ऑन इंस्टॉल करने का विकल्प दिखेगा जिसे पब्लिश नहीं किया गया है.
5. इंस्टॉल करें बटन पर क्लिक करें.
6. आपको पुष्टि का एक मैसेज दिखेगा. डप्लॉयमेंट डायलॉग बॉक्स को बंद करने के लिए, सबसे नीचे मौजूद हो गया पर क्लिक करें.
7. Gmail का होम पेज खोलें और रीफ़्रेश करें.
8. अब ऐड-ऑन उपलब्ध होना चाहिए. ऐड-ऑन, दाईं ओर मौजूद पैनल में दिखता है.
9. पहली बार ऐड-ऑन का इस्तेमाल करने पर, आपको ज़रूरी डेटा या अनुमतियों को ऐक्सेस करने की अनुमति देने के लिए कहा जाएगा. अनुमतियां देने के लिए, स्क्रीन पर दिए गए निर्देशों का पालन करें.
10. आपको बिल्ली की एक इमेज दिखनी चाहिए. अगर आपको इमेज नहीं दिखती है, तो गड़बड़ी का मैसेज शेयर करके Gemini CLI की मदद से समस्या हल करें.

9. एआई की मदद से इमेज जनरेट करने की सुविधा लागू करना

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. अब आपको एआई से जनरेट की गई बिल्ली की इमेज दिखेगी. अगर कोई इमेज नहीं दिख रही है, तो गड़बड़ी का मैसेज शेयर करके और 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. ऐड-ऑन को रीफ़्रेश करें. इसके लिए, तीन वर्टिकल बिंदुओं पर क्लिक करके रीफ़्रेश करें या Gmail के होम पेज को रीफ़्रेश करके, ऐड-ऑन को फिर से खोलें.
3. किसी दूसरे जानवर की तस्वीर चुनकर, नई सुविधा को आज़माएं. अगर कोई गड़बड़ी होती है, जैसे कि यूज़र इंटरफ़ेस (यूआई) रीफ़्रेश नहीं हो रहा है या कोई गड़बड़ी दिख रही है, तो गड़बड़ी का मैसेज शेयर करके और उसके निर्देशों का पालन करके, Gemini CLI की मदद से समस्या हल करें.

11. व्यवस्थित करें

Gemini CLI से बाहर निकलना

Gemini CLI से बाहर निकलें और इस कमांड का इस्तेमाल करके, अपने इस्तेमाल के आंकड़े देखें:

/quit

Google Cloud प्रोजेक्ट मिटाना

⚠️चेतावनी: इस Google Cloud प्रोजेक्ट को मिटाने से, इसके सभी संसाधन हमेशा के लिए मिट जाएंगे. इनमें इस कोडलैब से जुड़ा काम भी शामिल है. इसके अलावा, आने वाले समय में इस कस्टम प्रोजेक्ट आईडी का दोबारा इस्तेमाल नहीं किया जा सकेगा. आईडी को बनाए रखने के लिए, पूरे प्रोजेक्ट के बजाय सिर्फ़ इस लैब के दौरान बनाए गए संसाधनों को मिटाएं.

इस कोडलैब में इस्तेमाल किए गए संसाधनों के लिए, अपने Google Cloud खाते से शुल्क लिए जाने से बचने के लिए, हमारा सुझाव है कि आप Google Cloud प्रोजेक्ट को मिटा दें.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Apps Script प्रोजेक्ट मिटाना

⚠️चेतावनी: इस Apps Script प्रोजेक्ट को मिटाने पर, इसमें मौजूद सभी फ़ाइलें हमेशा के लिए मिट जाएंगी. साथ ही, सभी चालू डिप्लॉयमेंट बंद हो जाएंगे. अगर आपने इस कोडलैब के लिए किसी मौजूदा प्रोजेक्ट का फिर से इस्तेमाल किया है, तो इस कार्रवाई से आपका पिछला काम भी मिट जाएगा. हमारा सुझाव है कि प्रोजेक्ट को पूरी तरह से मिटाने के बजाय, प्रोजेक्ट में मौजूद हर संसाधन को मैन्युअल तरीके से हटाएं. इससे, आने वाले समय में आपके डिप्लॉयमेंट का इस्तेमाल किया जा सकेगा.

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. बधाई हो!

आपने लैब को पूरा कर लिया है. साथ ही, Gmail ऐड-ऑन को वाइब-कोड करने के लिए Gemini CLI का इस्तेमाल किया है.

इस लैब में, आपने ये सीखा:

• Gemini CLI का इस्तेमाल करें.
• एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) सर्वर का इस्तेमाल करके, टूल इंस्टॉल करें और Gemini CLI को एक्सटेंड करें.
• Gmail ऐड-ऑन बनाना, उसे डिप्लॉय करना, और इंस्टॉल करना.

अब आप अगले लैब पर जा सकते हैं.