MCP Reference: cloud-sql

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

הגדרת השרת

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

‫Cloud SQL Admin API ל-MCP

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

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

לשרת ה-MCP של Cloud SQL יש את נקודת הקצה הבאה של MCP:

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

כלי MCP

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

לשרת ה-MCP של Cloud SQL יש את הכלים הבאים:

כלי MCP
list_instances הצגת רשימה של כל המכונות של Cloud SQL בפרויקט.
get_instance קבלת הפרטים של מכונת Cloud SQL.
create_instance

הפעולה יוצרת מכונה של Cloud SQL.

  • הכלי מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.
  • יצירת המכונה עשויה להימשך כמה דקות. משתמשים בכלי של שורת פקודה כדי להשהות את הבדיקה למשך 30 שניות לפני שבודקים שוב את הסטטוס.
  • אחרי שמשתמשים בכלי create_instance כדי ליצור מופע, אפשר להשתמש בכלי create_user כדי ליצור חשבון משתמש IAM למשתמש שמחובר כרגע לפרויקט.

  • כברירת מחדל, הערך של data_api_access מוגדר כ-ALLOW_DATA_API. ההגדרה הזו מאפשרת לכם להריץ הצהרות SQL באמצעות הכלי execute_sql ו-executeSql API.

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

ההגדרה הבאה היא הגדרת ברירת המחדל למופע בסביבת פיתוח:

{
  "tier": "db-perf-optimized-N-2",
  "data_disk_size_gb": 100,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "ZONAL",
  "tags": [{"environment": "dev"}]
}

ההגדרה הבאה מומלצת למופע בסביבת ייצור:

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}

מומלץ להשתמש בהגדרת המכונה הבאה ל-SQL Server:

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "SQLSERVER_2022_STANDARD",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}
execute_sql

להריץ כל הצהרת SQL תקינה, כולל הצהרות של שפת הגדרת נתונים (DDL), שפת בקרת נתונים (DCL), שפת שאילתות נתונים (DQL) או שפת טיפול בנתונים (DML), במופע Cloud SQL.

כדי לתמוך בכלי execute_sql, מכונה ב-Cloud SQL צריכה לעמוד בדרישות הבאות:

  • הערך של data_api_access חייב להיות ALLOW_DATA_API.
  • במופע MySQL, צריך להגדיר את הדגל של מסד הנתונים cloudsql_iam_authentication לערך on. במכונת PostgreSQL, צריך להגדיר את האפשרות cloudsql.iam_authentication במסד הנתונים לערך on.
  • כדי להפעיל את הכלי execute_sql, צריך חשבון משתמש ב-IAM או חשבון שירות ב-IAM (CLOUD_IAM_USER או CLOUD_IAM_SERVICE_ACCOUNT). הכלי מריץ את הצהרות ה-SQL באמצעות ההרשאות של משתמש מסד הנתונים שנכנס באמצעות אימות מסד נתונים של IAM.

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

אלו המגבלות של הכלי execute_sql:

  • אם הצהרת SQL מחזירה תשובה גדולה מ-10 MB, התשובה תיחתך.
  • בכלי execute_sql, ברירת המחדל של הזמן הקצוב לתפוגה היא 30 שניות. אם שאילתה פועלת יותר מ-30 שניות, הכלי מחזיר שגיאה DEADLINE_EXCEEDED.
  • הכלי execute_sql לא נתמך ב-SQL Server.

אם מופיעות שגיאות כמו "אימות IAM לא מופעל עבור המופע", אפשר להשתמש בכלי get_instance כדי לבדוק את הערך של דגל אימות מסד הנתונים של IAM עבור המופע.

אם מופיעות שגיאות כמו "המופע לא מאפשר שימוש ב-executeSql כדי לגשת למופע הזה", אפשר להשתמש בכלי get_instance כדי לבדוק את ההגדרה data_api_access.

אם מתקבלות שגיאות אימות:

  1. בודקים אם חשבון המשתמש שמחובר כרגע קיים כמשתמש IAM במופע באמצעות הכלי list_users.
  2. אם חשבון המשתמש ב-IAM לא קיים, צריך להשתמש בכלי create_user כדי ליצור את חשבון המשתמש ב-IAM עבור המשתמש המחובר.
  3. אם למשתמש שמחובר כרגע אין את תפקידי המשתמש המתאימים במסד הנתונים, אפשר להשתמש בכלי update_user כדי להעניק למשתמש תפקידים במסד הנתונים. לדוגמה, תפקיד cloudsqlsuperuser יכול לספק למשתמש IAM הרבה הרשאות נדרשות.

  4. בודקים אם למשתמש שמחובר כרגע יש את הרשאות ה-IAM הנכונות שהוקצו לפרויקט. אפשר להשתמש בפקודה gcloud projects get-iam-policy [PROJECT_ID] כדי לבדוק אם למשתמש הוקצו התפקידים או ההרשאות המתאימים ב-IAM לפרויקט.

    • למשתמש צריכה להיות הרשאה cloudsql.instance.login לבצע אימות אוטומטי של מסד נתונים ב-IAM.
    • למשתמש צריכה להיות הרשאה cloudsql.instances.executeSql להפעיל הצהרות SQL באמצעות הכלי execute_sql או executeSql API.
    • תפקידי IAM נפוצים שמכילים את ההרשאות הנדרשות: Cloud SQL Instance User (roles/cloudsql.instanceUser) או Cloud SQL Admin (roles/cloudsql.admin)

כשמקבלים ExecuteSqlResponse, צריך תמיד לבדוק את השדות message ו-status בגוף התגובה. קוד סטטוס של HTTP שמציין הצלחה לא מבטיח שכל הצהרות ה-SQL יצליחו. בשדות message ו-status יצוין אם היו שגיאות או אזהרות חלקיות במהלך הביצוע של הצהרת ה-SQL.
get_operation אחזור הסטטוס של פעולה ממושכת. פעולה ממושכת יכולה להימשך כמה דקות. אם פעולה מסוימת נמשכת זמן רב, כדאי להשתמש בכלי של שורת הפקודה כדי להשהות אותה למשך 30 שניות לפני שבודקים שוב את הסטטוס שלה.
create_user

יוצרים משתמש של מסד נתונים במכונה של Cloud SQL.

  • הכלי הזה מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.
  • כשמשתמשים בכלי create_user, מציינים את סוג המשתמש: CLOUD_IAM_USER או CLOUD_IAM_SERVICE_ACCOUNT.
  • כברירת מחדל, למשתמש החדש שנוצר מוקצה התפקיד cloudsqlsuperuser, אלא אם מציינים במפורש תפקידים אחרים במסד הנתונים בבקשה.
  • אפשר להשתמש במשתמש שנוצר לאחרונה באמצעות הכלי execute_sql אם המשתמש הוא משתמש IAM שמחובר כרגע. הכלי execute_sql מריץ את הצהרות ה-SQL באמצעות ההרשאות של משתמש מסד הנתונים שמחובר באמצעות אימות מסד נתונים של IAM.

אלו המגבלות של הכלי create_user:

  • אי אפשר ליצור משתמש מובנה עם סיסמה.
  • הכלי create_user לא תומך ביצירת משתמש ל-SQL Server.

כדי ליצור משתמש IAM ב-PostgreSQL:

  • שם המשתמש במסד הנתונים חייב להיות כתובת האימייל של משתמש IAM, וכולו באותיות קטנות. לדוגמה, כדי ליצור משתמש עבור משתמש PostgreSQL IAM‏ example-user@example.com, אפשר להשתמש בבקשה הבאה:
{
  "name": "example-user@example.com",
  "type": "CLOUD_IAM_USER",
  "instance":"test-instance",
  "project": "test-project"
}

שם המשתמש במסד הנתונים שנוצר למשתמש IAM הוא example-user@example.com.

כדי ליצור חשבון שירות של IAM ב-PostgreSQL:

  • צריך ליצור את שם המשתמש במסד הנתונים בלי הסיומת .gserviceaccount.com, למרות שכתובת האימייל המלאה של החשבון היא service-account-name@project-id.iam.gserviceaccount.com. לדוגמה, כדי ליצור חשבון שירות IAM עבור PostgreSQL, אפשר להשתמש בפורמט הבקשה הבא:
{
   "name": "test@test-project.iam",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

שם המשתמש במסד הנתונים שנוצר עבור חשבון השירות ב-IAM הוא test@test-project.iam.

כדי ליצור משתמש IAM או חשבון שירות IAM ב-MySQL:

  • כש-Cloud SQL ל-MySQL מאחסן שם משתמש, הוא חותך את התו @ ואת שם הדומיין מכתובת האימייל של המשתמש או של חשבון השירות. לדוגמה, example-user@example.com הופך ל-example-user.
  • לכן, אי אפשר להוסיף לאותה מכונת Cloud SQL שני משתמשי IAM או שני חשבונות שירות עם אותו שם משתמש אבל שמות דומיין שונים.
  • לדוגמה, כדי ליצור משתמש עבור משתמש IAM ב-MySQL‏ example-user@example.com, משתמשים בבקשה הבאה:
{
   "name": "example-user@example.com",
   "type": "CLOUD_IAM_USER",
   "instance": "test-instance",
   "project": "test-project"
}

שם המשתמש במסד הנתונים שנוצר למשתמש IAM הוא example-user.

  • לדוגמה, כדי ליצור את חשבון השירות של MySQL IAM‏ service-account-name@project-id.iam.gserviceaccount.com, משתמשים בבקשה הבאה:
{
   "name": "service-account-name@project-id.iam.gserviceaccount.com",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

שם המשתמש במסד הנתונים שנוצר עבור חשבון השירות ב-IAM הוא service-account-name.
update_user

עדכון משתמש של מסד נתונים במכונה של Cloud SQL. תרחיש נפוץ לשימוש ב-update_user הוא הענקת התפקיד cloudsqlsuperuser למשתמש, שיכול לספק למשתמש הרשאות רבות שנדרשות לו.

הכלי הזה תומך רק בעדכון משתמשים כדי להקצות להם תפקידים במסד הנתונים.

  • הכלי הזה מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.
  • לפני שמפעילים את הכלי update_user, תמיד כדאי לבדוק את ההגדרות הקיימות של המשתמש, כמו סוג המשתמש, באמצעות הכלי list_users.
  • במקרה מיוחד של MySQL, אם הכלי list_users מחזיר כתובת אימייל מלאה בשדה iamEmail, לדוגמה {name=test-account, iamEmail=test-account@project-id.iam.gserviceaccount.com}, צריך להשתמש בכתובת האימייל המלאה בשדה iamEmail בבקשת update_user בשדה name של הכלי. לדוגמה, name=test-account@project-id.iam.gserviceaccount.com.

פרמטרים חשובים לעדכון תפקידי משתמשים:

  • ‫database_roles: רשימה של תפקידים במסד הנתונים שיוקצו למשתמש.
  • ‫revokeExistingRoles: שדה בוליאני (ברירת מחדל: false) שקובע איך המערכת מטפלת בתפקידים קיימים.

איך מתבצעים עדכוני תפקידים:

  1. אם revokeExistingRoles נכון:

    • כל התפקידים הקיימים שהוענקו למשתמש אבל לא מופיעים ברשימה database_roles שסופקה יבוטלו.
    • ביטול הרשאה רלוונטי רק לתפקידים שאינם תפקידי מערכת. תפקידי מערכת כמו cloudsqliamuser וכו' לא יבוטלו.
    • כל התפקידים ברשימה database_roles שהמשתמש עדיין לא קיבל יוקצו לו.
    • אם database_roles ריק, כל התפקידים הקיימים שאינם תפקידי מערכת מבוטלים.

  2. אם הערך של revokeExistingRoles הוא False (ברירת מחדל):

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

דוגמאות:

  • תפקידים קיימים: [roleA, roleB]

    • בקשה: database_roles: [roleB, roleC], revokeExistingRoles: true
    • תוצאה: ביטול roleA, הענקה roleC. תפקידי המשתמשים הופכים ל[roleB, roleC].
    • בקשה: database_roles: [roleB, roleC], revokeExistingRoles: false
    • תוצאה: מענקים roleC. תפקידי המשתמשים הופכים ל[roleA, roleB, roleC].
    • בקשה: database_roles: [], revokeExistingRoles: true
    • תוצאה: ביטול roleA, ביטול roleB. תפקידי המשתמשים הופכים ל[].
    • בקשה: database_roles: [], revokeExistingRoles: false
    • תוצאה: ללא שינוי. תפקידי המשתמשים נשארים [roleA, roleB].
clone_instance

יצירת מכונה של Cloud SQL כשיבוט של מכונת מקור.

  • הכלי הזה מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.
  • פעולת השיבוט יכולה להימשך כמה דקות. משתמשים בכלי של שורת פקודה כדי להשהות למשך 30 שניות לפני שבודקים שוב את הסטטוס.
update_instance

עדכון חלקי של הגדרות התצורה של מופע Cloud SQL.

  • הכלי הזה מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.
list_users הצגת רשימה של כל משתמשי מסד הנתונים במכונה של Cloud SQL.
import_data

ייבוא נתונים למכונה של Cloud SQL.

אם הקובץ לא מתחיל ב-gs://, ההנחה היא שהקובץ מאוחסן באופן מקומי. אם הקובץ מקומי, צריך להעלות אותו ל-Cloud Storage לפני שאפשר לבצע את הקריאה בפועל של import_data. כדי להעלות את הקובץ ל-Cloud Storage, אפשר להשתמש בפקודות gcloud או gsutil.

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

אחרי שהקובץ מועלה ל-Cloud Storage, לחשבון השירות של המופע צריכות להיות הרשאות מספיקות כדי לקרוא את הקובץ שהועלה מהקטגוריה של Cloud Storage.

כדי לעשות זאת:

  1. משתמשים בכלי get_instance כדי לקבל את כתובת האימייל של חשבון השירות של המופע. מפלט הכלי, מקבלים את הערך של השדה serviceAccountEmailAddress.
  2. מקצים לחשבון השירות של המכונה את התפקיד storage.objectAdmin בקטגוריה של Cloud Storage שצוינה. משתמשים בפקודה כמו gcloud storage buckets add-iam-policy-binding או בבקשה ל-Cloud Storage API. יכול להיות שיעברו שתיים עד שבע דקות או יותר עד שהתפקיד יינתן וההרשאות יועברו לחשבון השירות ב-Cloud Storage. אם נתקלתם בשגיאת הרשאות אחרי עדכון מדיניות IAM, כדאי להמתין כמה דקות ולנסות שוב.

אחרי שתקבלו הרשאות, תוכלו לייבא את הנתונים. מומלץ להשאיר את הפרמטרים האופציונליים ריקים ולהשתמש בברירות המחדל של המערכת. בדרך כלל אפשר לזהות את סוג הקובץ לפי הסיומת שלו. לדוגמה, אם הקובץ הוא קובץ SQL, .sql או .csv לקובץ CSV.

הדוגמה הבאה היא של SQL importContext ל-MySQL.

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL"
}

לא קיים פרמטר database עבור MySQL, כי שם מסד הנתונים אמור להופיע בקובץ ה-SQL. צריך לציין רק URI אחד. אין שדות חובה אחרים מלבד importContext.

ב-PostgreSQL, השדה database הוא חובה. הדוגמה הבאה היא של קובץ PostgreSQL importContext עם השדה database שצוין.

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL",
  "database": "sample-db"
}

הכלי import_data מחזיר פעולה ממושכת. משתמשים בכלי get_operation כדי לבצע דגימה של הסטטוס שלה עד שהפעולה מסתיימת.

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

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

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