MCP Reference: mapstools.googleapis.com

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

הגדרת השרת

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

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

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

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

לשרת ה-MCP ‏mapstools.googleapis.com יש את נקודת הקצה הבאה של ה-MCP:

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

כלי MCP

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

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

כלי MCP
search_places

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

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

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

    • דוגמאות: '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 אם הקואורדינטות מסופקות באופן מפורש או אם מתאים ונדרש להסיק מיקום מההקשר הידוע של המשתמש כדי לשפר את התוצאות.
lookup_weather

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

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

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

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

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

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

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

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

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

    • מחרוזת חופשית שנדרשת ספציפיות לגיאו-קידוד.
    • עיר ואזור: תמיד צריך לכלול אזור או מדינה (לדוגמה, London, UK ולא London).
    • כתובת: מציינים את הכתובת המלאה (לדוגמה, "בן גוריון 35, רמת גן, ישראל").
    • מיקודים: חובה לציין את שם המדינה (לדוגמה: '90210, USA', ולא '90210').

מצבי שימוש:

  1. מזג אוויר נוכחי: צריך לספק רק את location. אל תציינו את date ואת hour.

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

  3. תחזית יומית: מספקים את location ואת date. אל תציינו את הערך hour. השימוש הוא לבקשות כלליות לגבי היום (למשל, "weather for tomorrow" [מזג האוויר מחר], "weather on Friday" [מזג האוויר ביום שישי], "weather on 12/25" [מזג האוויר ב-25 בדצמבר]). אם התאריך של היום לא מופיע בהקשר, צריך לברר אותו עם המשתמש. תחזית יומית מעבר ל-10 ימים, כולל היום, לא אפשרית. אין תמיכה בנתוני מזג אוויר היסטוריים.

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

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

קבלת מפרטים של כלי ה-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
}'