MCP Reference: mapstools.googleapis.com

זהו שרת MCP שמסופק על ידי Maps Grounding Lite API. השרת מספק למפתחים כלים ליצירת אפליקציות LLM על בסיס Google Maps Platform.

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

הגדרת השרת

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

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

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

לשרת ה-MCP של Maps Grounding Lite API יש את נקודת הקצה הגלובלית הבאה של MCP:

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

כלי MCP

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

כלים

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

כלי MCP
search_places

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

דרישות קלט (קריטיות):

  1. text_query (string - חובה): שאילתת החיפוש הראשית. ההגדרה הזו צריכה להבהיר מה המשתמש מחפש.

    • דוגמאות: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • לפרטים ספציפיים על מקום: צריך לכלול את המאפיין המבוקש (למשל, 'Google Store Mountain View opening hours', ‏ 'SF MoMa phone number', ‏ 'Shoreline Park Mountain View address').

  2. ‫location_bias (object – אופציונלי): משתמשים בפרמטר הזה כדי לתת עדיפות לתוצאות שקרובות לאזור גיאוגרפי ספציפי.

    • פורמט: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • שימוש:
      • כדי להגדיר הטיה לרדיוס של 5 ק"מ: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • כדי להטות באופן משמעותי לנקודת המרכז: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (השמטה של radius_meters).

  3. ‫language_code (מחרוזת – אופציונלי): השפה שבה יוצג סיכום תוצאות החיפוש.

    • פורמט: קוד שפה בן שתי אותיות (ISO 639-1), שאחריו יכול לבוא קו תחתון וקוד מדינה בן שתי אותיות (ISO 3166-1 alpha-2), לדוגמה, en, ja, en_US, zh_CN, es_MX. אם לא מציינים את קוד השפה, התוצאות יהיו באנגלית.

  4. ‫region_code (מחרוזת – אופציונלי): קוד האזור של המשתמש ב-Unicode CLDR. הפרמטר הזה משמש להצגת פרטי המקום, כמו שם המקום הספציפי לאזור, אם הוא זמין. הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

    • פורמט: קוד מדינה בן שתי אותיות (ISO 3166-1 alpha-2), למשל US, CA.

הוראות לשימוש בכלי:

  • נתוני מיקום (קריטי): החיפוש חייב לכלול מספיק נתוני מיקום. אם המיקום לא ברור (למשל, רק 'פיצריות'), חובה לציין אותו בפרמטר text_query (למשל, 'פיצריות בניו יורק') או להשתמש בפרמטר location_bias. אם צריך להבחין בין כמה מיקומים, צריך לכלול את שם העיר, המדינה/המחוז והאזור/המדינה.

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

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

  • אם יש מידע בשדה attribution, צריך לציין את המקור של הפלט המבוסס על הארקה באמצעות המידע הזה.
lookup_weather

שליפת נתוני מזג אוויר מקיפים, כולל התנאים הנוכחיים ותחזיות לפי שעה ויומיות.

נתונים ספציפיים שזמינים: טמפרטורה (נוכחית, מה הטמפרטורה בפועל, מקסימלית/מינימלית, אינדקס חום), רוח (מהירות, משבי רוח, כיוון), אירועים שמימיים (זריחה/שקיעה, מופע הירח), משקעים (סוג, הסתברות, כמות), תנאים אטמוספריים (מדד UV, לחות, כיסוי עננים, הסתברות לסופת רעמים) וכתובת מיקום עם קידוד גיאוגרפי.

מיקום וכללים שמתייחסים למיקום (קריטי):

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

  1. קואורדינטות גיאוגרפיות (lat_lng)

    • כדאי להשתמש בה כשמקבלים קואורדינטות מדויקות של קו רוחב/אורך.
    • דוגמה: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // לוס אנג'לס

  2. מזהה מקום (place_id)

    • מחרוזת מזהה חד-משמעית (מזהה מקום במפות Google).
    • אפשר לאחזר את מזהה המקום באמצעות הכלי search_places.
    • דוגמה: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // מגדל אייפל

  3. מחרוזת כתובת (כתובת)

    • מחרוזת חופשית שנדרשת לגיאו-קידוד.
    • עיר ואזור: תמיד צריך לכלול אזור או מדינה (למשל, 'לונדון, בריטניה', ולא רק 'לונדון').
    • כתובת: מציינים את הכתובת המלאה (לדוגמה, "בן גוריון 35, רמת גן, ישראל").
    • מיקודים: חובה לציין את שם המדינה (לדוגמה: '90210, ארה"ב', ולא '90210').
    • דוגמה: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

מצבי שימוש:

  • מזג האוויר הנוכחי: צריך לציין רק את location. אין לציין את date ואת hour.

  • תחזית שעתית: מציינים את location, date וhour (0-23). אפשר להשתמש בשעות ספציפיות (למשל, "בשעה 17:00") או במונחים כמו "בשעות הקרובות" או "בהמשך היום". אם המשתמש מציין דקה, מעגלים כלפי מטה לשעה הקרובה. אין תמיכה בתחזית לפי שעה מעבר ל-120 שעות מהרגע הזה. אפשר לראות נתוני מזג אוויר היסטוריים לפי שעה עד 24 שעות אחורה.

  • תחזית יומית: צריך לספק את location וdate. אין לציין את hour. משתמשים בה כשמבקשים תחזית ליום מסוים (לדוגמה, 'מה מזג האוויר מחר', 'מה מזג האוויר ביום שישי', 'מה מזג האוויר ב-25 בדצמבר'). אם התאריך של היום לא מופיע בהקשר, צריך לברר אותו עם המשתמש. אי אפשר לספק תחזית יומית ליותר מ-10 ימים, כולל היום. אי אפשר לספק תחזית היסטורית.

אילוצים של פרמטרים:

  • אזורי זמן: כל הערכים של date ו-hour צריכים להיות ביחס לאזור הזמן המקומי של המיקום, ולא לאזור הזמן של המשתמש.
  • פורמט התאריך: צריך להזין {year, month, day} מספרים שלמים מופרדים.
  • יחידות: ברירת המחדל היא METRIC. מגדירים את units_system לערך IMPERIAL עבור פרנהייט/מיילים אם המשתמש מרמז על תקנים אמריקאיים או מבקש זאת במפורש.

  • אם יש מידע בשדה attribution, צריך לציין את המקור של הפלט המבוסס על הארקה באמצעות המידע הזה.
compute_routes

חישוב מסלול נסיעה בין נקודת מוצא ליעד שצוינו. מצבי נסיעה נתמכים: נהיגה (ברירת מחדל), הליכה.

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

  • ‫address: (מחרוזת, למשל, 'Eiffel Tower, Paris'). הערה: ככל שהכתובת שמוזנת מפורטת או ספציפית יותר, כך התוצאות יהיו טובות יותר.

  • lat_lng: (object, {"latitude": number, "longitude": number})

  • ‫place_id: (מחרוזת, למשל 'ChIJOwE_Id1w5EAR4Q27FkL6T_0') הערה: אפשר לקבל את המזהה הזה מהכלי search_places. מותר להשתמש בכל שילוב של סוגי קלט (למשל, מקור לפי כתובת, יעד לפי lat_lng). אם חסר מקור או יעד, חובה לבקש מהמשתמש הבהרה לפני שמנסים להפעיל את הכלי.

קריאה לדוגמה לכלי: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • אם יש מידע בשדה attribution, צריך לציין את המקור של הפלט המבוסס על הארקה באמצעות המידע הזה.
resolve_names

הפונקציה פותרת רשימה של שאילתות לגבי מיקומים ספציפיים (שמות של ציוני דרך או כתובות מדויקות) למזהים קנוניים של מקומות במפות Google.

דרישות קלט (קריטיות):

  1. ‫queries (מערך של אובייקטים – חובה): רשימה של שאילתות למיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.

    • כל אובייקט שאילתה צריך לכלול:
      • ‫text (מחרוזת – חובה): שאילתת הטקסט שמייצגת שם של מקום ספציפי או כתובת שרוצים לפתור.
        • דוגמאות: 'Googleplex, Mountain View, CA', ‏ '1600 Amphitheatre Pkwy, Mountain View, CA', ‏ 'Eiffel Tower, Paris'.

  2. ‫location_bias (object – אופציונלי): משתמשים בפרמטר הזה כדי לתת עדיפות לתוצאות שקרובות לאזור גיאוגרפי ספציפי.

    • פורמט: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (מחרוזת – אופציונלי): קוד האזור של CLDR ב-Unicode (קוד מדינה בן שתי אותיות, למשל US, CA) של המשתמש, כדי להטות את התוצאות.

הוראות לשימוש בכלי:

  • ספציפיות (קריטי): השאילתות צריכות לייצג שם מקום או כתובת ספציפיים. אין תמיכה בחיפושים כלליים כמו 'restaurants' או בשמות של רשתות כמו 'Starbucks'.
  • אל תתקשרו לכלי הזה אם הכלים במורד הזרם שאתם מתכננים להפעיל כבר מקבלים ישירות מחרוזות של כתובות גולמיות או שמות מקומות.

Error Handling (CRITICAL):

  • זהו כלי לעיבוד קבוצתי. יכול להיות שבקשה תחזיר "תוצאות מעורבות" (למשל, חלק מהשאילתות יסתיימו בהצלחה וחלק ייכשלו).
  • מובטח שרשימת הפלט של results תמופה ביחס של 1:1 עם האינדקסים של הקלט queries. שאילתה שנכשלה תגרום להודעה ריקה Result (לא מוגדר entity) באינדקס המתאים ברשימה results.
  • חובה לבדוק את שדה המפה failed_requests בתגובה כדי לזהות את האינדקס הספציפי של השאילתה שנכשלה. המפתח של failed_requests מייצג את האינדקס של השאילתה שנכשלה בבקשה, החל מ-0. אל תניחו שהקריאה כולה נכשלה בגלל כשל חלקי.
resolve_maps_urls

הפונקציה הזו מחזירה רשימה של מזהים ייחודיים של מקומות במפות Google מתוך רשימה של כתובות URL קנוניות במפות Google.

מתי כדאי להפעיל את הכלי הזה (קריטי):

  • השתמש בכלי הזה כשהמשתמש מספק קישורי שיתוף או כתובות URL של Google Maps (לדוגמה, 'https://maps.app.goo.gl/...', ‏ 'https://www.google.com/maps/place/...' או 'https://maps.google.com/...') ואתה צריך לחלץ את מזהי המקום הקנוניים הבסיסיים.
  • אפשר לציין עד 20 כתובות URL לפתרון בבקשת Batch אחת.

דרישות קלט (קריטיות):

  • ‫urls (מערך של מחרוזות – חובה): רשימת כתובות ה-URL של מפות Google שצריך לפתור. כל כתובת URL צריכה להיות כתובת URL תקינה של מקום יחיד במפות Google.

Error Handling (CRITICAL):

  • זהו כלי לעיבוד קבוצתי. יכול להיות שבקשה תחזיר 'תוצאות מעורבות' (למשל, חלק מכתובות ה-URL נפתחות בהצלחה וחלק לא).
  • מובטח שרשימת הפלט של entities תמופה ביחס של 1:1 עם האינדקסים של הקלט urls. אם לא ניתן לפתור כתובת URL, תוצג הודעה ריקה Entity (ללא הגדרת שדות) באינדקס המתאים ברשימה entities.
  • חובה לבדוק את שדה המפה failed_requests בתגובה כדי לזהות את כתובת ה-URL הספציפית שהוספתה לאינדקס נכשלה. המפתח של failed_requests מייצג את האינדקס מבוסס-0 של כתובת ה-URL שנכשלה בבקשה. אל תניחו שכל השיחות באותו אצווה נכשלו בגלל כשל חלקי.

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

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

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