MCP Tools Reference: mapstools.googleapis.com

工具：resolve_names

將特定地點查詢 (地標名稱或確切地址) 的批次清單解析為標準的 Google 地圖地點 ID。

輸入規定 (重要)：

  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 地圖中儲存、分享或開啟已解析的地點清單，請向使用者顯示這個連結。請勿自行建構這個連結。

錯誤處理 (重大)：

  • 這項工具可進行批次處理。要求可能會傳回「混合結果」(例如，部分查詢成功解析，其他查詢則失敗)。
  • 輸出 results 清單保證會與輸入 queries 索引建立 1:1 的對應關係。如果查詢失敗，results 清單中對應的索引會產生空白的 Result 訊息 (未設定 entity)。
  • 您必須檢查回應中的 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」或「巴黎鐵塔, Paris」。查詢內容必須是特定地址或地點名稱。不支援一般地點，例如連鎖店名稱 (如星巴克) 或「餐廳」等搜尋查詢。

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)

僅供輸出。位置查詢中已解析的實體清單。保證與要求 queries 索引 1:1 對應。索引 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

狀態碼，應為 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

使用 URI 參照識別序列化 Protobuf 訊息的類型，該參照包含以斜線結尾的前置字串和完整類型名稱。

例如：type.googleapis.com/google.protobuf.StringValue

這個字串必須包含至少一個 / 字元，且最後一個 / 後的內容必須是正規形式的類型完整名稱，且不得有開頭點。請勿在這些 URI 參照中寫入配置，以免用戶端嘗試與其聯絡。

前置字元是任意的，Protobuf 實作項目應會直接去除最後一個 / 之前的所有內容 (包括該字元)，以識別類型。type.googleapis.com/ 是常見的預設前置字串，部分舊版實作方式需要使用這個前置字串。這個前置字元不會指出型別的來源，且含有這個前置字元的 URI 不會回應任何要求。

所有型別網址字串都必須是合法的 URI 參照，且參照內容只能包含英數字元、百分比編碼逸出字元，以及下列字元集中的字元 (不含外側的反引號)：/-.~_!$&()*+,;=。雖然我們允許百分比編碼，但實作時不應取消逸脫，以免與現有剖析器混淆。舉例來說，type.googleapis.com%2FFoo 應遭到拒絕。

在 Any 的原始設計中，我們曾考慮在這些型別網址啟動型別解析服務，但 Protobuf 從未實作這項服務，且認為聯絡這些網址有問題，可能造成安全性問題。請勿嘗試輸入類型網址。
value

string (bytes format)

保存 type_url 所述類型的 Protobuf 序列化。

Base64 編碼字串。

可信度

解決方案的信賴水準。

列舉
CONFIDENCE_UNSPECIFIED 預設值。這個值不會使用。
MEDIUM 中等信賴度表示解析結果可能正確，但可能還有其他候選項目。
HIGH 高信賴度表示解析結果正確，且代表特定地理空間實體 (例如特定地點)。

工具註解

工具註解會傳送至 MCP 用戶端，說明特定工具的基本風險。大多數用戶端會將這些提示視為不受信任，但可用於決定何時可能向使用者傳送確認提示。

除了標題字串，以下布林值提示的定義如下：

  • readOnlyHint：如果為 true，工具不會修改環境。預設值為 false。
  • destructiveHint：如果為 true，工具可以執行破壞性動作。如果為 false，工具只能執行加法動作。預設值為 true。
  • idempotentHint：如果為 true，以相同引數重複呼叫工具時，不會對環境產生額外影響。預設值為 false。
  • openWorldHint：設為 true 時，工具可與外部實體的「開放世界」互動。如果為 false，工具只能與內部實體互動。舉例來說，網路搜尋工具屬於開放世界，記憶體工具則不屬於開放世界。

破壞性提示：❌ | 等冪提示：❌ | 唯讀提示：✅ | 開放世界提示：❌