איך בונים שרת MCP באמצעות Gemini CLI ו-Go

1. מבוא

ב-codelab הזה תלמדו איך ליצור ולפרוס שרת Model Context Protocol‏ (MCP) כדי להרחיב את היכולות של Gemini CLI. תבנו את godoctor, שרת מבוסס-Go שמספק כלים מותאמים אישית לפיתוח ב-Go, וכך תהפכו את Gemini CLI מעוזר תכנות למטרות כלליות למומחה לפיתוח ב-Go.

ב-codelab הזה נעשה שימוש בגישה מבוססת-הנחיות. אתה תפעל כראש צוות טכני ותספק הנחיות לעוזר ה-AI שלך (Gemini CLI). המטרה שלכם היא ללמוד איך לתרגם דרישות של פרויקט להנחיות יעילות, ולאפשר ל-AI לטפל בפרטי ההטמעה.

בבסיס הפרויקט הזה נמצא Model Context Protocol‏ (MCP). ‫MCP הוא פרוטוקול קוד פתוח שקובע תקנים לאופן שבו מודלים גדולים של שפה (LLM) כמו Gemini מתקשרים עם כלים ושירותים חיצוניים. הוא משמש כגשר שמאפשר ל-AI לגשת למידע מהעולם האמיתי ולבצע פעולות מעבר לידע המובנה שלו. כשבונים שרת MCP, יוצרים תוסף בהתאמה אישית ש-Gemini CLI יכול לגלות ולהשתמש בו, וכך ללמד אותו מיומנויות חדשות.

מה תלמדו

איך מתקינים ומגדירים את Gemini CLI
איך לנסח הנחיות יעילות כדי להנחות עוזר AI בפיתוח תוכנה
איך מספקים הקשר והנחיות לעוזר דיגיטלי מבוסס-AI
איך ליצור ולהגדיר שרת MCP כדי לשפר את היכולות של Gemini CLI
איך יוצרים קונטיינר לאפליקציית Go ופורסים אותה ב-Google Cloud Run

הדרישות

אפשר להשתתף בסדנה הזו באופן מלא ב-Google Cloud Shell, שכולל את כל התלויות הנדרשות (ה-CLI של gcloud, ‏ Go, ‏ Docker, ‏ Gemini CLI) שמותקנות מראש.

לחלופין, אם אתם מעדיפים לעבוד על המחשב שלכם, תצטרכו את הדברים הבאים:

‫Node.js 20 ואילך
ה-SDK של Google Cloud‏ (ה-CLI של gcloud) מותקן ומופעל
גרסה 1.24 ואילך של Go מותקנת במערכת
‫Docker מותקן במערכת

טכנולוגיות מרכזיות

כאן אפשר למצוא מידע נוסף על הטכנולוגיות שבהן נשתמש:

‫Gemini CLI: ממשק שורת הפקודה מבוסס-AI שאנחנו נרחיב
‫Model Context Protocol (MCP): פרוטוקול קוד פתוח שמאפשר ל-Gemini CLI לתקשר עם הכלי המותאם אישית שלנו
‫Go SDK for MCP: ספריית Go שבה נשתמש כדי להטמיע את שרת ה-MCP שלנו

טיפים ליצירת Codelab מוצלח

עבודה עם עוזר דיגיטלי מבוסס-AI היא דרך חדשה לפתח תוכנה. הנה כמה טיפים שיעזרו לכם ליהנות מחוויה חלקה ומוצלחת:

אל תחששו להקיש על ESC. לפעמים ה-AI יציע פעולות או קוד שלא תסכימו איתם. אפשר להשתמש במקש ESC כדי לבטל את הפעולה המוצעת ולתת הנחיה חדשה שתכוון אותו לכיוון הנכון. אתם משתתפים בפיילוט.
מעודדים את השימוש בכלים. אם נראה שה-AI לא מבין את ההקשר או שהוא ממציא מידע, כדאי לעודד אותו להשתמש בכלים הזמינים שלו. הנחיות כמו "תשתמש בחיפוש Google כדי לאמת את זה" או "תשתמש בכלי read_file כדי להבין את הקוד הנוכחי לפני שתבצע שינויים" יכולות להיות יעילות מאוד.
לא לבצע שינויים ידניים. כדאי לנסות שה-AI יבצע את כל העבודה. זו המיומנות העיקרית שאתם מתרגלים. עם זאת, אם אתם חייבים לבצע שינוי ידני, חשוב לספר על כך ל-AI אחר כך. הנחיה כמו "עדכנתי ידנית את הקובץ README.md. כדי לוודא שה-AI יישאר מסונכרן עם הפרויקט, אפשר להשתמש בהנחיה 'כדאי לקרוא את זה שוב כדי לרענן את הידע שלך'.
ניסית לכבות את המחשב ולהדליק אותו מחדש? במקרים נדירים, יכול להיות שה-AI מנסה לכפות נתיב מסוים בניגוד לפקודה שלכם. זה יכול לקרות בגלל ירידה באיכות ההקשר (לפעמים נקראת גם 'התדרדרות ההקשר'). במקרה כזה, אפשר להשתמש בפקודה ‎/compress ב-Gemini CLI כדי לצמצם את הרעש בהקשר, או במקרים קיצוניים, להשתמש בפקודה ‎/clear כדי לנקות את כל היסטוריית השיחות.

2. הגדרת הסביבה

בוחרים באחת מהאפשרויות הבאות: הגדרה של סביבה בקצב אישי אם רוצים להריץ את ה-codelab הזה במחשב שלכם, או הפעלה של Cloud Shell אם רוצים להריץ את ה-codelab הזה כולו בענן.

הגדרת סביבה בקצב אישי

נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו אחרי שהוא מוגדר. מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית, ובדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא תישאר לאורך הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

מפעילים את Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-מסוף Google Cloud, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הפעלת Cloud Shell

יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:

צילום מסך של טרמינל Google Cloud Shell שבו מוצג שהסביבה מחוברת

המכונה הווירטואלית הזו כוללת את כל הכלים שדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.

3. איך מתחילים להשתמש ב-Gemini CLI

בקטע הזה מוסבר על Gemini CLI, כולל איך להתקין אותו ולהגדיר אותו לסביבה שלכם.

מה זה Gemini CLI?

‫Gemini CLI הוא ממשק שורת פקודה מבוסס-AI שיכול לעזור לכם במגוון רחב של משימות פיתוח. הוא יכול להבין את ההקשר של הפרויקט, לענות על שאלות, ליצור קוד ולהשתמש בכלים חיצוניים כדי להרחיב את היכולות שלו.

התקנה

מתקינים את Gemini CLI באופן גלובלי באמצעות npm.

npm install -g @google/gemini-cli

כדי לוודא שה-CLI מותקן, מריצים את הפקודה:

gemini --version

הגדרות אישיות

ההתנהגות של Gemini CLI נקבעת על ידי קובצי הגדרה ומשתני סביבה. יש שני קובצי מפתח:

‫GEMINI.md: הקובץ הזה מספק הנחיות והקשר ל-AI. ממשק ה-CLI קורא את הקובץ הזה כדי להבין את הסטנדרטים והמוסכמות של הקידוד בפרויקט.
‫.gemini/settings.json: הקובץ הזה שולט בהגדרות של ה-CLI, כולל איך להתחבר לכלים חיצוניים. נשתמש בקובץ הזה בהמשך כדי להגדיר את ה-CLI כך שישתמש בשרת ה-MCP שאנחנו בונים במעבדה הזו.

קודם נגדיר את הסביבה ואז ניצור את הקובץ GEMINI.md. הגדרת הקובץ settings.json תתבצע בשלב מאוחר יותר.

יוצרים ומפעילים ספריית פרויקט:

mkdir godoctor && cd godoctor
go mod init godoctor

אימות באמצעות Application Default Credentials של Google Cloud:

צריך להתחבר לחשבון שיש לו גישה לפרויקט Google Cloud Platform שבו תשתמשו ב-Codelab הזה:

מוודאים שהתקנתם ואתחלתם את ה-SDK של Google Cloud.
מריצים את הפקודה הבאה כדי להגדיר Application Default Credentials:

gcloud auth application-default login

4. קובץ ההקשר (GEMINI.md)

קבצים של הקשר, שמשתמשים בשם ברירת המחדל GEMINI.md, משמשים כדי לספק הקשר הדרכתי למודל Gemini. אתם יכולים להשתמש בקבצים האלה כדי לתת הוראות ספציפיות לפרויקט, להגדיר פרסונה או לספק הנחיות לגבי סגנון כתיבת קוד, כדי שהתשובות של ה-AI יהיו מדויקות יותר ומותאמות לצרכים שלכם.

כדי לוודא שעוזר ה-AI יוצר קוד Go איכותי ואידיומטי, נכתוב קובץ GEMINI.md עם כמה שיטות מומלצות נפוצות למפתחי Go.

יעד: ליצור קובץ GEMINI.md שישמש כקבוצת הכללים של העוזר הדיגיטלי מבוסס-AI במהלך הפרויקט הזה.

פותחים את סביבת הפיתוח המשולבת (IDE) כדי ליצור את הקובץ GEMINI.md עם התוכן שבהמשך. אם משתמשים ב-Cloud Shell, אפשר לפתוח עורך באמצעות הפקודה הבאה:

cloudshell edit .

משימה: יוצרים קובץ בשם GEMINI.md בתיקיית השורש של godoctor ומדביקים בו את התוכן הבא.

# Go Development Guidelines
All code contributed to this project must adhere to the following principles.

## 1. Formatting
All Go code **must** be formatted with `gofmt` before being submitted.

## 2. Naming Conventions
- **Packages:** Use short, concise, all-lowercase names.
- **Variables, Functions, and Methods:** Use `camelCase` for unexported identifiers and `PascalCase` for exported identifiers.
- **Interfaces:** Name interfaces for what they do (e.g., `io.Reader`), not with a prefix like `I`.

## 3. Error Handling
- Errors are values. Do not discard them.
- Handle errors explicitly using the `if err != nil` pattern.
- Provide context to errors using `fmt.Errorf("context: %w", err)`.

## 4. Simplicity and Clarity
- "Clear is better than clever." Write code that is easy to understand.
- Avoid unnecessary complexity and abstractions.
- Prefer returning concrete types, not interfaces.

## 5. Documentation
- All exported identifiers (`PascalCase`) **must** have a doc comment.
- Comments should explain the *why*, not the *what*.

## 6. Project structure
- cmd/ contains source code for target binaries (e.g. server, client)
- internal/ contains source code for packages not meant to be exported (e.g. internal/tools/hello)
- bin/ contains the compiled binaries
- At the root place README.md, go.mod and go.sum

עכשיו סביבת הפיתוח מוגדרת באופן מלא.

5. הגרסה הראשונית: שרת תיעוד

היעד הראשון הוא ליצור את הגרסה הראשונית של godoctor השרת. הגרסה הזו צריכה להיות אפליקציה מינימלית שמספקת כלי יחיד בשם read_docs, שמאפשר לחפש תיעוד של Go.

המטרה: ליצור שרת MCP שמוכן לייצור וחושף את הפקודה go doc, כדי לאפשר ל-LLM לשלוח שאילתות למסמכי Go.

מריצים את הפקודה של Gemini CLI ב-Shell:

gemini

כשמריצים את ה-CLI בפעם הראשונה, תתבקשו לבחור מצב אימות ועיצוב.

אם אתם מריצים את ה-codelab הזה ב-Cloud Shell, בוחרים באפשרות Use Cloud Shell user credentials (שימוש בפרטי הכניסה של המשתמש ב-Cloud Shell). אם לא, אפשר להשתמש בכניסה באמצעות Google כדי להיכנס עם חשבון Google אישי וליהנות מהתוכנית הנדיבה לשימוש חופשי של Gemini CLI. מסך הבחירה של האימות ייראה בערך כך:

אם תרצו לשנות את הבחירה, תוכלו להקליד /auth ולהקיש על Enter כדי לפתוח שוב את התפריט הזה.

בשלב הבא תתבקשו לבחור עיצוב:

בדומה ל-/auth, אפשר גם לשנות את העיצוב מאוחר יותר באמצעות הפקודה /theme.

אחרי שבוחרים את שיטת האימות ואת העיצוב המועדף, מגיעים לשורת הפקודה. כאן אפשר להקליד את הפקודות, למשל:

Write a hello world application in Go

ממשק ה-CLI משתמש בשילוב של חשיבה רציונלית משלו (באמצעות מודל Gemini כמו Gemini Flash או Gemini Pro) וכלים כדי לבצע את המשימות. הוא משתמש בכלים כשהוא צריך ליצור אינטראקציה עם מערכת הקבצים או עם שירותים חיצוניים, כמו ממשקי API, מסדי נתונים וכו'. דוגמאות לכלים שזמינים מראש, או 'כלים פנימיים', הם read_file,‏ write_file,‏ web_fetch ו-google_search. שרת ה-MCP שאנחנו בונים יהפוך גם לכלי שיהיה זמין ב-CLI.

בפעם הראשונה שבה הוא יפעיל כלי, הוא יבקש את ההרשאה שלכם. אתם יכולים לתת לה הרשאה חד-פעמית (אישור חד-פעמי), אישור גורף לשאר הסשן (אישור תמיד) או לדחות את הבקשה שלה. אם מדובר בפעולת עריכה של קובץ, תופיע גם האפשרות לערוך את הקובץ באמצעות עורך חיצוני, למקרה שתרצו לבצע שינויים. לדוגמה, זה הפלט של הפרומפט שלמעלה, ליצירת תוכנית Hello World:

בנוסף להנחיות, אפשר גם להשתמש בפקודות עם לוכסן. אם מקלידים '/', ה-CLI יציג אוטומטית את אפשרויות ההשלמה האוטומטית. אפשר להמשיך להקליד את הפקודה המלאה או לבחור אחת מהאפשרויות. הפקודות /auth ו-/theme שצוינו למעלה הן דוגמאות לפקודות כאלה.

אחרי שתכירו את הממשק, תוכלו להתחיל במשימה העיקרית של הקטע הזה, שהיא לבקש מ-CLI לכתוב את שרת ה-MCP בשבילכם.

יצירת שרת MCP של Hello World

אחת הדרכים הטובות ביותר לוודא שהמודל יבנה דברים בצורה עקבית יותר היא לחלק משימות מורכבות לשלבים מצטברים. יכול להיות שהמודל יוכל להבין משימה מורכבת בעצמו, אבל בלי ההגדרה הנכונה ייקח לו הרבה זמן לגלות את ההטמעה הנכונה.

כדי להשיג גישה עקבית יותר, נורה אותו קודם ליצור שרת MCP של Hello World לפני שנחיל את הפונקציונליות הרצויה (קריאת תיעוד של Go).

דוגמה להנחיה:

Create a Model Context Protocol (MCP) server that exposes a "hello_world" tool. This tool, when called, should return the message "Hello, MCP world!"

For the MCP implementation, you should use the official Go SDK for MCP (github.com/modelcontextprotocol/go-sdk/mcp) and use the stdio transport.

TODO:
- Download the dependency: `go get github.com/modelcontextprotocol/go-sdk/mcp`
- Inspect the documentation of the SDK: `go doc github.com/modelcontextprotocol/go-sdk/mcp`
- Build a `server` command that supports stdio transport only
- Build a `client` command that connects to the server over command transport to test the server

Acceptance Criteria:
- `./bin/client --list-tools` returns the list of server tools including "hello_world"
- `./bin/client --call-tool` "hello_world" returns the output "Hello, MCP world!"

שימו לב שההנחיה שלמעלה מורכבת משלושה פלחים עיקריים:

פירוט הבעיה, כולל מה אנחנו רוצים לבנות והאילוצים (לדוגמה, שימוש ב-SDK הרשמי במקום בכל SDK, העברת נתונים ב-stdio במקום ב-http)
פירוט של המשימות לביצוע (TODOs)
קריטריונים לקבלת המשימה, שמשמשים כהליך בדיקה כדי שהסוכן יידע מתי המשימה הושלמה

שלושת הרכיבים האלה יעזרו למודל להשיג את התוצאות הרצויות בצורה עקבית יותר.

הטמעה של הכלי `read_docs`

אחרי שתהיה לכם הטמעה תקינה, נוכל להמשיך להטמעה של הכלי האמיתי read_docs:

Add a new tool to our MCP server called "read_docs" that invokes the "go doc" shell command. The tool will take a mandatory "package" argument and an optional "symbol" argument.

TODO:
- create a package `./internal/tools/docs`
- register the tool with the MCP server
- update the client to support the "read_docs" tool by providing arguments to the tool call

Acceptance Criteria:
- `./bin/client --tools-list` show both hello_world and read_docs
- `./bin/client --tool-call read_docs fmt` returns the documentation for the `fmt` package
- `./bin/client --tool-call read_docs fmt.Println` returns the documentation for the `fmt.Println` function
- `./bin/client --tool-call read_docs github.com/modelcontextprotocol/go-sdk/mcp` returns documentation for the `mcp` package

הערה: אתם יכולים להתנסות בהנחיה הזו או לנסות ליצור הנחיה משלכם.

טיפים שימושיים

בהתחשב בכך ש-MCP הוא עדיין מושג חדש ושה-SDK של Go ל-MCP הוא ספרייה חדשה, בשלב הזה יכול להיות שיעבור זמן רב עד ש-Gemini ימצא את ההטמעה הנכונה בעצמו. כדי לעזור למודל להגיע לפתרון הנכון, אפשר לנסות את הפעולות הבאות:

אם המודל דילג על קריאת התיעוד בשלב כלשהו, מקישים על מקש ESC ומזכירים לו לעשות זאת. אם אתם לא מכירים את go, הפעלת הפקודה go doc בתוספת שם החבילה go doc github.com/modelcontextprotocol/go-sdk/mcp תחזיר את התיעוד הנכון.
למודול ברמה העליונה github.com/modelcontextprotocol/go-sdk אין תיעוד (כי הוא לא כולל קוד Go). צריך להנחות את המודל לחפש את הנתיב המלא
לעומת זאת, אם המודל יפיק הזיה של חבילה שלא קיימת, למשל: "go doc github.com/modelcontextprotocol/go-sdk/mcp/server", פשוט צריך להפנות אותו לחבילה ברמה העליונה.

6. הגדרת godoctor כשרת MCP ל-Gemini CLI

אחרי שעוזר ה-AI יצר את הקוד גם ללקוח וגם לשרת, אפשר להנחות אותו להריץ כמה בדיקות ידניות. לדוגמה:

retrieve the documentation for the package net/http

חשוב לבדוק את זה גם עם תלות חיצונית (לא בספרייה הרגילה):

retrieve the documentation for the github.com/modelcontextprotocol/go-sdk/mcp package

אחרי שמרוצים מהתוצאות, מבקשים ממנו לכתוב קובץ README.md עם הוראות לשימוש בפרויקט הזה ולפיתוח שלו.

Now write a detailed README.md file explaining both from a user and a developer perspective how to use and to build this project.

עכשיו נגדיר את השרת כך ש-Gemini CLI יוכל להשתמש בו במהלך השלב הבא של הפיתוח.

מבקשים מ-CLI לעדכן את GEMINI.md כדי להשתמש ב-read_docs כשיטה המועדפת לקריאת מאמרי עזרה:

update the GEMINI.md file to include instructions to always use the read_docs tool to retrieve documentation about Go packages or symbols. This should be done whenever seeing an import for the first time in a session or after a new dependency is installed to the project (e.g. via `go get`)

עכשיו צריך להפעיל מחדש את Gemini CLI כדי להגדיר את שרת ה-MCP. קודם כל, נשמור את שיחת הצ'אט כדי שתוכלו להמשיך מהמקום שבו הפסקתם אחרי ההפעלה מחדש.

/chat save godoctor-workshop

כדי לצאת מ-CLI, לוחצים פעמיים על Ctrl+D או מקלידים את הפקודה /quit.
בשלבים הקודמים, הסוכן אמור היה לקמפל עבורכם קובץ בינארי של השרת, אבל אנחנו מקמפלים את השרת שוב עם שם אחר כדי שלא יושפע כשנשנה את קוד המקור שלו:

mkdir -p bin && go build -o ./bin/godoctor ./cmd/server

מגדירים את Gemini CLI עבור הכלי המקומי: יוצרים קובץ .gemini/settings.json בשורש הפרויקט ומוסיפים קטע mcpServers כדי להגדיר ל-Gemini CLI איך להריץ את השרת המקומפל.

mkdir -p .gemini && touch .gemini/settings.json

עכשיו, מוסיפים את התוכן הבא לקובץ החדש באמצעות העורך של Cloud Shell או סביבת הפיתוח המשולבת (IDE) המועדפת.

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor"
    }
  }
}

הפעלת Gemini CLI באמצעות הפקודה gemini
כדי לראות שהכלי נטען, מקלידים את הפקודה /mcp. אפשר גם להציג את התיאור המלא של הכלים באמצעות /mcp desc:

בודקים את השילוב על ידי בקשה מ-Gemini CLI להשתמש בכלי עם הנחיה כמו 'הצגת התיעוד של החבילה net/http'

אתם אמורים לראות משהו כזה:

אם הכלי פועל בצורה תקינה, אמורה להופיע תיעוד שאוחזר באמצעות קריאה לכלי:

יצרת כלי MCP אבל זה לא הסוף, עדיין אפשר לשפר את השרת הזה.

7. הוספת כלי מבוסס-AI לבדיקת קוד

בואו נוסיף תכונה מתוחכמת יותר שמבוססת על AI: בודק קוד שמשתמש ב-Gemini API.

עכשיו אפשר לשחזר את שיחת הצ'אט הקודמת באמצעות הפקודה /chat resume godoctor-workshop.. כך יטען ההקשר של הסשן עד לנקודה שבה סיימנו לפתח את read_docs, ולכן למודל יהיה הידע הנדרש לבניית הכלי החדש.

הכלי הזה יצטרך גישה ל-Vertex AI, לכן צריך להפעיל קודם את ה-API. אתם יכולים להריץ פקודות של מעטפת בלי לצאת מ-Gemini CLI. לשם כך, מקלידים סימן קריאה (!) בהנחיה ריקה. ממשק Gemini CLI יעבור למצב מעטפת.

מריצים את הפקודה הבאה במצב מעטפת כדי להפעיל את Vertex AI API:

gcloud services enable aiplatform.googleapis.com

אחרי שהפקודה מסתיימת, אפשר להקיש על מקש Esc כדי לחזור למצב הנחיה.

מטרה: הוספת כלי חדש בשם code_review לפרויקט הקיים. הכלי הזה ישתמש ב-Gemini API כדי לנתח קוד Go ולספק משוב.

הנחיה לדוגמה:

Add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with model id gemini-2.5-pro) to analyze Go code and provide a list of improvements according to the best practices accepted by the Go community.

The tool should take the Go code content and an optional hint as input. The hint will be used to provide additional guidance for the AI reviewer, like "focus on security" or "help me simplify this code".

The tool output should be text in Markdown format.

TODO:
- add the genai SDK dependency with `go get import google.golang.org/genai`
- create the tool code in ./internal/tools/code/review.go
- create a code review prompt to be used by the tool
- use go-genai with Vertex AI authentication to call gemini-2.5-pro
- register the tool with the server
- add a flag to the server to set the Google Cloud Project ID: --project
- add a flag to the server to set the Google Cloud Location: --location
- add support to the review tool in the client CLI

NOT TO DO:
- DO NOT use the package github.com/google/generative-ai-go/genai as it is DEPRECATED
- DO NOT use the package cloud.google.com/go/vertexai/genai as it has been superseded by google.golang.org/genai

Acceptance Criteria:
- `./bin/client --tools-list` show all tools including `code_review`
- `./bin/client --tool-call code_review internal/tools/code/review.go` returns the code review for the "review.go" file

טיפים שימושיים

אחרי שהמודל יתחיל לעבוד על זה, יכול להיות שתראו באופן אוטומטי בקשה להפעיל את הכלי read_docs כדי לעיין במסמכי התיעוד של חבילת genai. אם זה לא קורה, תמיד אפשר להפסיק את התהליך באמצעות מקש Escape ולהזכיר לו שעכשיו יש לו את הכלי read_docs.
אם אתם רואים שה-AI הגנרטיבי מנסה להשתמש ב-SDK הלא נכון (גם אם יש רשימה ברורה של SDK שאסור להשתמש בהם בהנחיה), צריך להנחות אותו לחזור ל-SDK הנכון.

בדיקת בודק הקוד

שומרים את שיחת הצ'אט עם /chat save godoctor-workshop ואז יוצאים מ-CLI על ידי הקשה על Ctrl+D פעמיים.
קומפילציה מחדש של השרת עם הגדרת הכלי החדשה:.

go build -o ./bin/godoctor ./cmd/server

בסביבת הפיתוח המשולבת (IDE), מעדכנים את הקובץ .gemini/settings.json כך שיכלול את הגדרות הסביבה של Vertex AI:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor",
      "env": {
        "GOOGLE_CLOUD_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "<your-project-id>",
        "GOOGLE_CLOUD_LOCATION": "<your-preferred-region>"
      }
    }
  }
}

מפעילים שוב את Gemini CLI. שחזור שיחת הצ'אט עם /chat resume godoctor-workshop
כדי לוודא שהכלי מופעל, מקלידים את הפקודה /mcp. אתם אמורים לראות משהו כזה:

עכשיו נבדוק את הכלי code_review על ידי בדיקת אחד מקובצי המקור של הכלי:

Use the code_review tool to review cmd/server/main.go

    You should see something like this:

אחרי שהכלי לבדיקת קוד פועל, אפשר להציע למודל ליישם חלק מהשיפורים שהוא מצא, כדי ליצור תהליך עבודה מלא של 'שיפור עצמי'.

עכשיו אפשר לוודא שהכלי code-review פועל. בקטע הבא תעבדו על פריסת האפליקציה בענן. שמירת הסשן הנוכחי באמצעות /chat save godoctor-workshop ויציאה מ-CLI.

8. הכנת השרת לענן

שרת ה-MCP שפיתחנו עד עכשיו פועל רק במחשב המקומי, וזה בסדר אם אתם מפתחים כלים לשימוש עצמי. אבל לעיתים קרובות בסביבות ארגוניות אנחנו צריכים לפרוס כלים לשימוש נרחב של מאות או אפילו אלפי מפתחים.

כדי להרחיב את שרת ה-MCP שלנו, אנחנו צריכים להמיר אותו משרת שמדבר רק סטנדרט I/O לשרת שיכול לדבר HTTP, ולפרוס אותו במקום שבו מפתחים שונים יוכלו לגשת אליו. כדי להשיג את המטרה הזו, נשתמש במצב העברה שמוגדר במפרט MCP כ-HTTP שניתן להזרמה, ונשתמש ב-Cloud Run כיעד הפריסה שלנו.

המטרה: לבצע רפקטורינג בשרת godoctor כדי להשתמש ב-HTTP transport שניתן להזרמה.

הנחיה לדוגמה:

The godoctor server is currently using the stdio transport. I want to prepare it to be deployed to Cloud Run, so we need to add support to use the Streamable HTTP transport.

TODO:
- Update server to enable Streamable HTTP via the -http flag.
- An optional -listen flag can be specified to set the port to listen
- If no -http flag is specified, the server defaults to stdio transport and -listen is ignored
- Update client to use Streamable HTTP via the -addr flag
- If no flag is specified, the client defaults to command transport
- Create a shell script test_server.sh to support testing

NOT TO DO:
- DO NOT use the HTTP+SSE protocol as it has been deprecated by the MCP specification

Acceptance Criteria
- Create a shell script that:
  - Runs the server in the background;
  - Runs the client connecting over HTTP and call list tools
  - Kills the background process
- The shell script should run without failures

טיפים שימושיים

יכול להיות שהמודל ינסה להשתמש ב-HTTP+SSE במקום זאת, אבל הפרוטוקול הזה הוצא משימוש. אם אתם רואים שהבקשה עוברת בנתיב הזה, נסו להפנות אותה חזרה ל-HTTP שניתן להזרמה.
הגרסה הנוכחית של Gemini CLI‏ (0.26.0) לא תומכת בהרצת תהליכים ברקע (כל תהליך שמופעל באמצעות run_shell_command נסגר ברגע שהקריאה לכלי מסתיימת), ולכן אנחנו מבקשים מ-Gemini להפוך את תהליך הבדיקה לאוטומטי באמצעות סקריפט. התכונה הזו מתוכננת ותתווסף בעתיד הקרוב, כדי לפשט את תהליך הבדיקה.

אופציונלי: בדיקת שרת ה-MCP באמצעות HTTP

אם רוצים להגדיר את Gemini CLI כך שישתמש בשרת באמצעות HTTP:

שמירת הסשן ויציאה מה-CLI
עורכים את קובץ .gemini/settings.json ומשנים את ההגדרות כך שיצביעו על השרת המקומי הפעיל.

"mcpServers": {
  "godoctor": {
    "httpUrl": "http://localhost:8080"
  }
}

בטרמינל השני, מריצים את השרת עם HTTP באופן מקומי:

go build -o ./bin/godoctor ./cmd/server && ./bin/godoctor -listen=:8080

מפעילים מחדש את Gemini CLI ומזינים הנחיה כדי לבדוק את החיבור, למשל: "Use the godoctor tool to get the documentation for fmt.Println."
בסיום הבדיקה, מקישים על Ctrl+C כדי לעצור את השרת.

9. יצירת קונטיינר לאפליקציה באמצעות Docker

עכשיו, כשהשרת שלנו משתמש בפרוטוקול התעבורה הנכון, אנחנו יכולים להכניס אותו למאגר לצורך פריסה.

המטרה: ליצור קובץ Docker כדי לארוז את שרת godoctor לתוך אימג' קונטיינר נייד שמוכן לייצור.

הנחיה לדוגמה:

Please create a multi-stage Dockerfile that compiles the Go binary and copies it into a minimal golang image like golang:1.25.6-alpine. The image should support the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI
- GOOGLE_CLOUD_PROJECT
- GOOGLE_CLOUD_LOCATION

Acceptance Criteria:
- The image builds successfully
- Create a script test_docker.sh to launch the docker image in background and test the connectivity with the client:
    - Call list_tools on the client pointing to the server running on Docker
    - Call read_docs for fmt.Println
    - Stop the server
- The script should run without failures

אופציונלי: בדיקה ידנית של תמונת Docker

אחרי שיוצרים את Dockerfile, בונים את התמונה ומפעילים פתרונות חכמים כדי לוודא שהיא פועלת בצורה תקינה.

בונים את מאגר התגים:

docker build -t godoctor:latest .

מריצים את הקונטיינר באופן מקומי:

docker run -p 8080:8080 -e PORT=8080 godoctor:latest

בדיקת קונטיינר פועל: במסוף אחר, מפעילים את Gemini CLI ומבקשים ממנו לאחזר תיעוד.
בסיום הבדיקה, מקישים על Ctrl+C כדי לעצור את השרת.

10. פריסה ב-Cloud Run

עכשיו הגיע הזמן לפרוס את הקונטיינר שלנו בענן.

המטרה: פריסת שרת godoctor בקונטיינר ב-Google Cloud Run.

הנחיה לדוגמה:

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Configure Cloud Run to use the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI: true,
- GOOGLE_CLOUD_PROJECT: <your-project-id>
- GOOGLE_CLOUD_LOCATION: <your-preferred-region>

TODO:
- Run `docker build -t gcr.io/daniela-genai-sandbox/godoctor .`
- Run `gcloud run deploy godoctor --image` with the image created above

Acceptance Criteria:
- Call list-tools with the client pointing to the CloudRun endpoint

אחרי שהפריסה תסתיים, נגדיר את Gemini CLI כך שישתמש בכלי שפרסתם.

מעדכנים את קובץ .gemini/settings.json כדי לשנות את ההגדרה של כלי ה-MCP כך שיצביע על השירות שנפרס, או מבקשים מ-Gemini CLI לעשות זאת בשבילכם:

now update the .gemini/settings.json file to use this URL for the godoctor server

הקטע הסופי mcpServers צריך להיראות כך (חשוב להחליף את ה-פלייסהולדר בכתובת ה-URL של האפליקציה בפועל של Cloud Run):

"mcpServers": {
  "godoctor": {
    "httpUrl": "https://<your-cloud-run-id>.us-central1.run.app"
  }
}

בדיקת הפריסה של Cloud Run

עכשיו אפשר לבצע את הבדיקה הסופית מקצה לקצה.

מפעילים מחדש את Gemini CLI בפעם האחרונה (באמצעות /chat save ו-/chat resume אם רוצים לשמור את ההקשר). עכשיו ה-CLI אמור להיות מסוגל להתקשר לשרת ה-MCP המרוחק. אפשר לנסות לבקש תיעוד של חבילות.

אפשר גם לבדוק את כלי בקרת הקוד:

Use the godoctor tool to review the cmd/godoctor/main.go file

ניקוי

אחרי שמסיימים את הבדיקה, חשוב לנקות את הסביבה. אתם יכולים להנחות את Gemini למחוק את הפרויקט או רק להסיר את הפריסה של CloudRun. הנחיה לדוגמה:

I'm done with my tests on the CloudRun server, please delete this deployment for me and revert my .gemini/settings.json to use the local version.

‫11. מעולה!

הצלחתם להנחות עוזר אישי מבוסס-AI לבנות, להכניס לקונטיינר ולפרוס כלי מתוחכם שמבוסס על AI. חשוב מכך, תרגלתם את המיומנות החיונית של פיתוח תוכנה מודרני: תרגום דרישות להנחיות יעילות. הצלחתם להרחיב את Gemini CLI באמצעות כלי MCP בהתאמה אישית, וכך הפכתם אותו לעוזר פיתוח Go יעיל וייעודי יותר.

איך בונים שרת MCP באמצעות Gemini CLI ו-Go

1. מבוא

מה תלמדו

הדרישות

טכנולוגיות מרכזיות

טיפים ליצירת Codelab מוצלח

2. הגדרת הסביבה

הגדרת סביבה בקצב אישי

מפעילים את Cloud Shell

3. איך מתחילים להשתמש ב-Gemini CLI

מה זה Gemini CLI?

התקנה

הגדרות אישיות

4. קובץ ההקשר (GEMINI.md)

5. הגרסה הראשונית: שרת תיעוד

יצירת שרת MCP של Hello World

הטמעה של הכלי read_docs

טיפים שימושיים

6. הגדרת godoctor כשרת MCP ל-Gemini CLI

7. הוספת כלי מבוסס-AI לבדיקת קוד

טיפים שימושיים

בדיקת בודק הקוד

8. הכנת השרת לענן

טיפים שימושיים

אופציונלי: בדיקת שרת ה-MCP באמצעות HTTP

9. יצירת קונטיינר לאפליקציה באמצעות Docker

אופציונלי: בדיקה ידנית של תמונת Docker

10. פריסה ב-Cloud Run

בדיקת הפריסה של Cloud Run

ניקוי

‫11. מעולה!

מסמכי עזר

הטמעה של הכלי `read_docs`