MCP Tools Reference: mapstools.googleapis.com

הפניה לכלי MCP:

במסמך הזה מתוארים נקודות הקצה של ה-API בארכיטקטורת REST שפונות אל הציבור הרחב, ומשמשות להפעלת כלי פרוטוקול הקשר של מודלים מרוחקים (MCP) של Google. ממשק ה-API הזה פועל כפרוקסי מאובטח בין לקוח HTTP חיצוני (כמו curl או שירות אינטרנט) לבין שרת MCP פנימי.

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

כלי: search_places

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

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

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

בדוגמאות הבאות מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP search_places.

בקשת Curl 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": search_places,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

כלי: lookup_weather

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

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

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

  • תנאים נוכחיים: נדרש רק מיקום (למשל עיר או כתובת). אל תציינו תאריך או שעה.

  • תחזיות לפי שעה: צריך לציין מיקום ושעה (0-23). משתמשים בפונקציה הזו אם המשתמש שואל על מזג האוויר בשעה מסוימת או משתמש במונחים כמו 'בשעות הקרובות' או 'בהמשך היום'.

  • תחזיות יומיות: נדרשים מיקום ותאריך מלא.

טיפול בתאריכים (קריטי): תאריכים ושעות שהמשתמשים סיפקו חייבים להיות באזור הזמן המקומי של המיקום המבוקש. חובה לפרק את התאריכים לפרמטרים נפרדים של מספרים שלמים: שנה, חודש ויום. הפורמט הנדרש לפרמטרים האלה הוא: {"year": , "month": , "day": }

בדוגמאות הבאות מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP lookup_weather.

בקשת Curl 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

כלי: compute_routes

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

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

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

  • 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"}

בדוגמאות הבאות מוצגות דרכים להשתמש ב-curl כדי להפעיל את כלי MCP ‏compute_routes.

בקשת Curl 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": compute_routes,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'