MCP Tools Reference: mapstools.googleapis.com

כלי: resolve_names

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

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

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

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

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

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

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

הוראות לקריאה לפונקציה:

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

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

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

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

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

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

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

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

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