MCP Tools Reference: mapstools.googleapis.com

כלי: resolve_names

הפונקציה פותרת רשימה של שאילתות לגבי מיקומים ספציפיים (שמות של ציוני דרך או כתובות מדויקות) למזהים קנוניים של מקומות במפות Google.

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

  1. queries (מערך של אובייקטים – חובה): רשימה של שאילתות למיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.

    • כל אובייקט שאילתה צריך לכלול:
      • ‫text (string - חובה): שאילתת הטקסט שמייצגת שם של מקום ספציפי או כתובת שרוצים לפתור.
        • דוגמאות: 'Googleplex, Mountain View, CA', ‏ '1600 Amphitheatre Pkwy, Mountain View, CA', ‏ 'Eiffel Tower, Paris'.

  2. ‫location_bias (object – אופציונלי): משתמשים בפרמטר הזה כדי לתת עדיפות לתוצאות שקרובות לאזור גיאוגרפי ספציפי.

    • פורמט: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (מחרוזת – אופציונלי): קוד האזור של CLDR ב-Unicode (קוד מדינה בן שתי אותיות, למשל US, CA) של המשתמש, כדי להטות את התוצאות.

הוראות לשימוש בכלי:

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

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

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

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

  • זהו כלי לעיבוד קבוצתי. יכול להיות שבקשה תחזיר "תוצאות מעורבות" (למשל, חלק מהשאילתות יפעלו בהצלחה וחלק ייכשלו).
  • מובטח שרשימת הפלט של results תמופה 1:1 עם האינדקסים של הקלט queries. אם שאילתה נכשלת, תופיע הודעה ריקה Result (לא מוגדר entity) באינדקס המתאים ברשימה results.
  • חובה לבדוק את שדה המיפוי failed_requests בתגובה כדי לזהות את האינדקס הספציפי של השאילתה שנכשל. המפתח של failed_requests מייצג את האינדקס מבוסס-0 של השאילתה שנכשלה בבקשה. אל תניחו שכל הקריאות באצווה נכשלו בגלל כשל חלקי.

בדוגמת הקוד הבאה מוצג שימוש בפקודה curl כדי להפעיל את הכלי resolve_names 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_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

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

ResolveNamesRequest

ייצוג ב-JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
שדות
queries[]

object (LocationQuery)

חובה. רשימה של שאילתות מיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.
locationBias

object (LocationBias)

אופציונלי. אזור אופציונלי להטיית תוצאות ההחלטה. אם מציינים אזור, תוצאות ההחלטה יושפעו יותר מהישויות שקרובות לאזור הזה. אם כוללים את התווים location_bias או region_code, לרוב מקבלים תוצאות טובות יותר כי מרחב החיפוש מצטמצם.

אם מציינים גם את location_bias וגם את region_code, ל-location_bias יש עדיפות על פני region_code.
regionCode

string

אופציונלי. קוד אזור אופציונלי להטיית תוצאות ההמרה. אם מציינים אזור, התוצאות של ההחלטה יתמקדו בישויות שנמצאות באזור שצוין או בקרבתו. הערך צריך להיות קוד אזור ממאגר ה-CLDR. לדוגמה, 'US' או 'CA'. אם כוללים את התווים location_bias או region_code, לרוב מקבלים תוצאות טובות יותר כי מרחב החיפוש מצטמצם.

אם מציינים גם את location_bias וגם את region_code, ל-location_bias יש עדיפות על פני region_code.

LocationQuery

ייצוג ב-JSON 
{
  "text": string
}
שדות
text

string

חובה. שאילתת הטקסט שצריך לפתור כדי להגיע לישות גיאוספציפית ספציפית במפות Google, כמו מקום או כתובת. ככל שהשאילתה תהיה ספציפית יותר, כך הפתרון יהיה מדויק יותר. לדוגמה, 'סן פרנסיסקו', 'Googleplex, Mountain View, CA',‏ '1600 Amphitheatre Parkway, Mountain View, CA' או 'מגדל אייפל, פריז'. השאילתות צריכות להיות כתובת ספציפית או שם של מקום. אין תמיכה במיקומים כלליים כמו שם של רשת (למשל, Starbucks) או שאילתת חיפוש כמו 'מסעדות'.

LocationBias

ייצוג ב-JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
שדות
שדה איחוד type. סוג ההטיה לפי מיקום. הערך type יכול להיות רק אחד מהבאים:
viewport

object (Viewport)

אזור תצוגה שמוגדר על ידי תיבה תוחמת.

אזור התצוגה

ייצוג ב-JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
שדות
low

object (LatLng)

חובה. הנקודה הנמוכה של אזור התצוגה.
high

object (LatLng)

חובה. הנקודה הגבוהה ביותר באזור התצוגה.

LatLng

ייצוג ב-JSON 
{
  "latitude": number,
  "longitude": number
}
שדות
latitude

number

קו הרוחב במעלות. הערך חייב להיות בטווח [‎-90.0, ‎+90.0].
longitude

number

קו האורך במעלות. הערך חייב להיות בטווח [‎-180.0, ‎+180.0].

סכימת הפלט

הודעת התגובה של ResolveNames.

ResolveNamesResponse

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

object (Result)

פלט בלבד. רשימת הישויות שנפתרו משאילתות המיקום. מובטח שהמיפוי יהיה 1:1 עם האינדקסים של בקשת queries. מחרוזת ריקה באינדקס i מציינת שהפענוח נכשל עבור השאילתה הזו. אם הפענוח נכשל, צריך לבדוק את השדה failed_requests כדי לראות את סטטוס השגיאה.
failedRequests

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

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

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

string

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

תוצאה

ייצוג ב-JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
שדות
entity

object (Entity)

פלט בלבד. הישות שזוהתה מתוך שאילתת המיקום.
confidence

enum (Confidence)

פלט בלבד. רמת המהימנות של הפתרון.

ישות

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

רמת מהימנות

רמת המהימנות של הפתרון.

טיפוסים בני מנייה (enum)
CONFIDENCE_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
MEDIUM רמת מהימנות בינונית מציינת שהפתרון כנראה נכון, אבל יכול להיות שיש מועמדים אחרים.
HIGH רמת מהימנות גבוהה מציינת שהרזולוציה נכונה ומייצגת ישות גיאוספציפית ספציפית (למשל, מקום ספציפי).

הערות בכלי

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

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

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

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