MCP Tools Reference: mapstools.googleapis.com

כלי: resolve_maps_urls

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

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

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

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

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

שמירה במפות Google:

  • התשובה כוללת את השדה save_to_maps_url: קישור יחיד למפות Google שמכיל את כל המקומות שזוהו בהצלחה.
  • כשמשתמש רוצה לשמור, לשתף או לפתוח את המקומות שזוהו כרשימה ב-Google Maps (למשל, איסוף מקומות ששותפו בשיחה), צריך להציג לו את הקישור הזה. אל תיצרו את הקישור הזה בעצמכם.

טיפול בשגיאות (קריטי):

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

בדוגמת הקוד הבאה מוצג שימוש בפקודה curl כדי להפעיל את הכלי resolve_maps_urls MCP.

בקשת 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": "resolve_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

הודעת בקשה ל-ResolveMapsUrls.

ResolveMapsUrlsRequest

ייצוג ב-JSON 
{
  "urls": [
    string
  ]
}
שדות
urls[]

string

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

סכימת הפלט

הודעת התגובה ל-ResolveMapsUrls.

ResolveMapsUrlsResponse

ייצוג ב-JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
שדות
entities[]

object (Entity)

פלט בלבד. רשימת הישויות שנפתרו מכתובות ה-URL של מפות Google. מובטח מיפוי של 1:1 עם האינדקסים של הבקשה urls. הודעה ריקה באינדקס i (שבו לא מוגדר entity) מציינת שהפענוח של כתובת ה-URL הזו נכשל. אם הפענוח נכשל, צריך לבדוק את השדה failed_requests כדי לראות את סטטוס השגיאה.
failedRequests

map (key: integer, value: object (Status))

פלט בלבד. מפה שמציגה כשלים חלקיים בכתובות ה-URL של מפות Google. המפתח הוא האינדקס של הבקשה שנכשלה בשדה urls. הערך הוא סטטוס השגיאה שמפרט למה הפענוח נכשל.

אובייקט שמכיל רשימה של "key": value זוגות. לדוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

פלט בלבד. קישור לשמירת כל הישויות שנפתרו בהצלחה במפות Google.

ישות

ייצוג ב-JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
שדות
שדה איחוד entity. סוג הישות שנפתר. הערך entity יכול להיות רק אחד מהבאים:
place

string

שם המשאב של המקום שנמצא.

FailedRequestsEntry

ייצוג ב-JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
שדות
key

integer
value

object (Status)

סטטוס

ייצוג ב-JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

integer

קוד הסטטוס, שצריך להיות ערך enum של google.rpc.Code.
message

string

הודעת שגיאה שמוצגת למפתח, שצריכה להיות באנגלית. כל הודעת שגיאה שמוצגת למשתמש צריכה להיות מותאמת לשפה המקומית ולהישלח בשדה google.rpc.Status.details, או להיות מותאמת לשפה המקומית על ידי הלקוח.
details[]

object

רשימה של הודעות שכוללות את פרטי השגיאה. יש קבוצה משותפת של סוגי הודעות לשימוש בממשקי API.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

הכול

ייצוג ב-JSON 
{
  "typeUrl": string,
  "value": string
}
שדות
typeUrl

string

מזהה את הסוג של הודעת Protobuf שעברה סריאליזציה באמצעות הפניה ל-URI שכוללת קידומת שמסתיימת בקו נטוי ושם סוג מלא.

דוגמה: type.googleapis.com/google.protobuf.StringValue

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

הקידומת היא שרירותית, וההטמעות של Protobuf אמורות פשוט להסיר את כל מה שמופיע עד הסימן / האחרון, כולל הסימן עצמו, כדי לזהות את הסוג. ‫type.googleapis.com/ היא תחילית ברירת מחדל נפוצה שנדרשת בחלק מההטמעות מדור קודם. הקידומת הזו לא מציינת את המקור של הסוג, ולא צפוי שמזהי URI שמכילים אותה יגיבו לבקשות כלשהן.

כל מחרוזות כתובות ה-URL של הסוג חייבות להיות הפניות URI חוקיות, עם הגבלה נוספת (בפורמט הטקסט) שלפיה התוכן של ההפניה חייב לכלול רק תווים אלפאנומריים, תווים מוברחים בקידוד אחוזים ותווים בערכה הבאה (לא כולל הגרשיים החיצוניים): /-.~_!$&()*+,;=. למרות שאנחנו מאפשרים קידודים באחוזים, ההטמעות לא צריכות לבטל את הקידוד שלהם כדי למנוע בלבול עם מנתחי נתונים קיימים. לדוגמה, צריך לדחות את type.googleapis.com%2FFoo.

בתכנון המקורי של Any נשקלה האפשרות להפעיל שירות לפתרון סוגים בכתובות ה-URL האלה של הסוגים, אבל ב-Protobuf אף פעם לא בוצעה הטמעה של שירות כזה, והפנייה לכתובות ה-URL האלה נחשבת לבעייתית ועלולה לגרום לבעיות אבטחה. אל תנסו ליצור קשר עם כתובות URL מהסוג הזה.
value

string (bytes format)

מחזיק סריאליזציה של Protobuf של הסוג שמתואר על ידי type_url.

מחרוזת בקידוד Base64.

הערות בכלי

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

בנוסף למחרוזת הכותרת, מוגדרים הרמזים הבוליאניים הבאים:

  • ‫readOnlyHint: אם הערך הוא true, הכלי לא משנה את הסביבה שלו. ברירת מחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא false, הכלי יכול לבצע רק פעולות של הוספה. ברירת מחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת מחדל: false.
  • ‫openWorldHint: אם הערך הוא true, הכלי יכול ליצור אינטראקציה עם 'עולם פתוח' של ישויות חיצוניות. אם הערך הוא false, הכלי יכול ליצור אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי לחיפוש באינטרנט יהיה עולם פתוח, אבל כלי לזיכרון לא יהיה עולם פתוח.

רמז הרסני: ❌ | רמז אידמפוטנטי: ❌ | רמז לקריאה בלבד: ✅ | רמז לעולם פתוח: ❌