MCP Tools Reference: mapstools.googleapis.com

כלי: 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):

  • זהו כלי ל​עיבוד ברצף (batch processing). יכול להיות שבקשה תחזיר 'תוצאות מעורבות' (למשל, חלק מכתובות ה-URL נפתחות בהצלחה וחלק לא).
  • מובטח שרשימת הפלט של entities תמופה ביחס של 1:1 עם האינדקסים של הקלט urls. אם לא ניתן לפתור כתובת URL, תוצג הודעה ריקה Entity (ללא הגדרת שדות) באינדקס המתאים ברשימה entities.
  • חובה לבדוק את שדה המפה failed_requests בתגובה כדי לזהות את כתובת ה-URL הספציפית שהוספתה לאינדקס נכשלה. המפתח של failed_requests מייצג את האינדקס מבוסס-0 של כתובת ה-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 tool's MCP 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)
    },
    ...
  }
}
שדות
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" }.

ישות

ייצוג ב-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.

הערות על כלים

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