MCP Reference: cloudcli.googleapis.com

שרת MCP של Cloud CLI מספק כלים להפעלת פקודות Cloud CLI בסביבת ארגז חול מרוחקת.

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

הגדרת השרת

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

נקודות קצה של שרתים

נקודת קצה של שירות MCP היא כתובת הרשת וממשק התקשורת (בדרך כלל כתובת URL) של שרת ה-MCP, שמשמשת אפליקציית AI (המארח של לקוח ה-MCP) כדי ליצור חיבור מאובטח וסטנדרטי. הוא משמש כנקודת קשר למודל ה-LLM כדי לבקש הקשר, להפעיל כלי או לגשת למשאב. נקודות הקצה של Google MCP יכולות להיות גלובליות או אזוריות.

לשרת ה-MCP של Cloud CLI Execution API יש את נקודת הקצה הגלובלית הבאה של MCP:

  • https://cloudcli.googleapis.com/mcp

כלי MCP

כלי MCP הוא פונקציה או יכולת הפעלה ששרת MCP חושף למודל שפה גדול (LLM) או לאפליקציית AI כדי לבצע פעולה בעולם האמיתי.

כלים

בשרת ה-MCP cloudcli.googleapis.com יש את הכלים הבאים:

כלי MCP
run_gcloud_command

הפעלת פקודה אחת של gcloud CLI בפרויקט Google Cloud של המשתמש. אזהרת בטיחות קריטית (עלולה לגרום נזק): הכלי הזה יכול ליצור, לעדכן או למחוק משאבי GCP (לדוגמה, gcloud compute instances delete). היא לא מוגבלת לפקודות לקריאה בלבד. חשוב לנהוג בזהירות רבה. פקודות אסורות: סוכן לא יכול להריץ את פקודות gcloud הבאות (כולל גרסאות אלפא/בטא שלהן): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey. כללי ביצוע מחמירים:

  1. כשמשתמשים בכלי הזה, חובה לציין את הפרמטר project (כלומר project="projects/PROJECT_ID") (הוא משמש לבדיקת ההפעלה של Cloud CLI Execution API, לחיוב, למכסה וכו'). הדגל הזה שונה מהדגל ‎--project בפקודות gcloud שמשמש לציון הפרויקט ש-gcloud פועל בו.
  2. פורמט הדגל: תמיד צריך להשתמש בסימן '=' כדי להפריד בין מפתחות הדגל לבין הערכים שלהם בכל האפשרויות הארוכות. נכון: --zone=us-central1-a או --project=my-project. שגוי: --zone us-central1-a או --project my-project.
  3. פרויקט לחיוב: אי אפשר להניח שקיימות הגדרות פרויקט או הגדרות חיוב שהוגדרו מראש בסביבת ההפעלה. לפקודות שלא מוגבלות לפרויקט (לדוגמה, ברמת התיקייה או הארגון) או לתרחישים ספציפיים כמו Cloud Storage Requester Pays, חובה להעביר את הדגל --billing-project=PROJECT. לפקודות בהיקף הפרויקט, אפשר גם לציין את --billing-project=PROJECT כדי לבטל את פרויקט המכסה. הפעולה הזו תשפיע על ממשקי GCP API שלא תומכים בביטול פרויקט המשאבים.
  4. היקף הפרויקט: תמיד צריך להעביר את הדגל --project=PROJECT_ID לפקודות בהיקף הפרויקט. אל תשתמשו בו לפקודות ברמת הארגון או התיקייה. אם לא מספקים את האפשרות ‎--project לפקודה בהיקף הפרויקט, פרויקט המשאב יהיה כברירת מחדל הפרויקט שמוגדר באפשרות ‎--billing-project.
  5. אם מציינים את הדגל ‎--billing-project בפקודת gcloud, צריך לוודא שהערך הוא מזהה פרויקט או מספר פרויקט. הערך לא יכול להיות ערך מיוחד (למשל LEGACY, ‏ CURRENT_PROJECT, ‏ CURRENT_PROJECT_WITH_FALLBACK).
  6. צריך לציין לפחות אחת מהאפשרויות ‎--project או ‎--billing-project במחרוזת הפקודה.
  7. פעולות אסינכרוניות: לפעולות סינכרוניות ארוכות (למשל, יצירת מכונה וירטואלית או מסד נתונים), תמיד צריך להעביר את הדגל --async כדי למנוע מצבים של פסק זמן של הסוכן.
  8. הגבלת קצב יצירת יומנים: כשמשתמשים ב-gcloud logging read, חובה תמיד לכלול דגל --limit (למשל, --limit=100) כדי למנוע פסק זמן של אישורים וחיבורים.
  9. תיקון עצמי: אם פקודה מחזירה שגיאה, המודל ינתח את stderr, יתקן את התחביר או את האפשרויות וינסה שוב באיטרציה הבאה.
  10. ‫input_files: (אופציונלי) רשימה של קבצים שייווצרו בסביבה לפני הפעלת הפקודה. לכל קובץ צריך להיות 'path' (יחסי לספרייה הנוכחית) ו-'contents'. התוכן צריך להיות טקסט פשוט שמייצג את התוכן של הקובץ. האפשרות הזו שימושית לפקודות שקוראות מקבצים (למשל gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

דוגמאות לפקודות או לתבניות של gcloud:

  1. קריאת יומנים של מופעי GCE עם חומרה ברמה ERROR ומעלה: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • שימו לב לשימוש במירכאות בביטוי הסינון.
  2. הצגת רשימה של כל נקודות הקצה של PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. תיאור של נקודת קצה של PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • שימו לב לשימוש בסימן '=' בדגל ‎--region.
  4. הצגת כל האשכולות: gcloud container clusters list --project=PROJECT_ID
  5. תיאור של אשכול: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. מציגים את מכונות המחשוב: gcloud compute instances list --project=PROJECT_ID
  7. קבלת מדיניות IAM לפרויקט: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

כברירת מחדל, מחרוזות התגובה מעוצבות לפלט של מסוף (stdout או stderr). כדי לשנות את הפורמט, משתמשים בדגל ‎--format.
run_bq_command

מריץ פקודה אחת של BigQuery CLI‏ (bq). הכלי הזה מאפשר להריץ כל פקודת bq בפרויקט של המשתמש, כולל פקודות שיוצרות, מעדכנות או מוחקות משאבי GCP (כלומר, מוטציות). אזהרת בטיחות קריטית (עלול לגרום נזק): הכלי הזה יכול ליצור, לעדכן או למחוק משאבים של BigQuery (למשל, bq rm,‏ bq cancel,‏ bq query). היא לא מוגבלת לפקודות לקריאה בלבד. חשוב לנהוג בזהירות רבה. פקודות אסורות: סוכן לא יכול להריץ את פקודות bq הבאות: bq init, ‏ bq load, ‏ bq pyshell, ‏ bq shell. כללי ביצוע מחמירים:

  1. צריך לציין לפחות אחת מהאפשרויות --project_id או --quota_project_id במחרוזת הפקודה.
  2. מזהה פרויקט לעומת פרויקט מכסת משאבים: הדגל ‎--project_id מציין את פרויקט המשאבים שהפקודה פועלת עליו (משקף את הדגל ‎--project של gcloud). הדגל ‎--quota_project_id מציין את הפרויקט שמחויב על החיוב או המכסה של קריאת BigQuery API במורד הזרם (משקף את הדגל ‎--billing-project של gcloud). אם מציינים את ‎--project_id בפקודה, הוא ישמש כפרויקט לחיוב או כפרויקט של מכסת השימוש. אם לא מציינים את ‎--project_id או אם מציינים בנוסף את ‎--quota_project_id, הפרויקט לחיוב או למכסת נפח יהיה הפרויקט שמוגדר בדגל ‎--quota_project_id.
  3. פורמט הדגל: תמיד צריך להשתמש בסימן '=' כדי להפריד בין מפתחות הדגל לבין הערכים שלהם בכל האפשרויות הארוכות. נכון: ‎'--project_id=my-project'‎ או ‎ '--location=us'‎. לא נכון: ‎'--project_id my-project'‎ או ‎ '--location us'‎. אל תוסיפו רווחים בין הדגלים לבין הערכים שלהם.
  4. אין הגדרות ברירת מחדל: הפקודה bq מופעלת בלי שמירת מצב. היא לא טוענת קובצי תצורה מקומיים כמו ‎.bigqueryrc. לכן, בכל הפעולות האזוריות (למשל, יצירת מערך נתונים או שאילתה של מערך נתונים אזורי), חובה לציין באופן מפורש את האפשרות ‎--location (למשל, ‎--location=us או ‎--location=EU).
  5. פעולות אסינכרוניות: פקודות מסוימות מפעילות פעולות סינכרוניות ממושכות (למשל, הפעלת משימות של שאילתות). תמיד צריך להעביר את הדגל ‎--nosync לפקודות האלה כדי למנוע פסק זמן של הסוכן.
  6. הגבלות על פקודות: אסור להשתמש בפקודות bq הבאות: bq init, ‏ bq pyshell, ‏ bq shell. אין תמיכה בצינורות או בשרשור של פקודות.
  7. תיקון עצמי: אם פקודה מחזירה שגיאה, המודל ינתח את stderr, יתקן את התחביר או את האפשרויות וינסה שוב באיטרציה הבאה.

דוגמאות לפקודות bq שמשנות את הנתונים: bq mk,‏ bq rm,‏ bq update,‏ bq insert,‏ bq query (בלי ‎--dry_run) וכו'. שימוש: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) חובה לציין את פקודת bq המלאה כמחרוזת אחת בפרמטר 'command'. חובה לציין את הפרמטר project (בפורמט: projects/PROJECT_ID) כפרויקט ההפעלה של ה-API לצורכי חיוב, הפעלת ה-API ובדיקות של ניצול המכסה.

דוגמאות לפקודות או לתבניות של פקודות bq:

  1. מריצים שאילתה: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROM project.dataset.table LIMIT 10'
  2. יצירת מערך נתונים: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. יוצרים טבלה: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. הסרת מערך נתונים: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. כדי להסיר טבלה: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. עדכון תיאור הטבלה: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. הצגת רשימה של מערכי נתונים בפרויקט: bq ls --datasets=true --project_id=PROJECT_ID

קבלת מפרטים של כלי ה-MCP

כדי לקבל את המפרטים של כלי ה-MCP לכל הכלים בשרת MCP, משתמשים בשיטה tools/list. בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להציג רשימה של כל הכלים והמפרטים שלהם שזמינים כרגע בשרת ה-MCP.

בקשת Curl 
                      
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'