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 (למשל, לאסוף מקומות ששותפו בשיחה), צריך להציג למשתמש את הקישור הזה. אל תיצרו את הקישור הזה בעצמכם.

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

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

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

בקשת 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, לדוגמה, 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, עם הגבלה נוספת (לפורמט הטקסט) שלפיה התוכן של ההפניה חייב לכלול רק תווים אלפאנומריים, תווי בריחה (escape) בקידוד אחוזים ותווים בקבוצה הבאה (לא כולל הגרשים ההפוכים החיצוניים): /-.~_!$&()*+,;=. למרות שאנחנו מאפשרים קידוד באחוזים, בהטמעות לא צריך לבטל את תווי המילוט כדי למנוע בלבול עם מנתחים קיימים. לדוגמה, צריך לדחות את 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, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌