MCP Tools Reference: mapstools.googleapis.com

工具：resolve_maps_urls

將 Google 地圖網址清單解析為標準 Google 地圖地點 ID。

呼叫這項工具的時機 (重要)：

  • 當使用者提供一或多個 Google 地圖分享連結或網址 (例如「https://maps.app.goo.gl/...」「https://www.google.com/maps/place/...」或「https://maps.google.com/...」)，且需要擷取基礎標準地點 ID。
  • 在單一批次要求中，最多可以指定 20 個網址。

輸入內容規定 (重要)：

  • urls (字串陣列 - 必填)：要解析的 Google 地圖網址清單。每個網址都必須是有效的單一地點 Google 地圖網址。

儲存至 Google 地圖：

  • 回應包含 save_to_maps_url 欄位：單一 Google 地圖連結，內含所有成功解析的地點。
  • 如果使用者想將解析的地點儲存、分享或在 Google 地圖中以清單形式開啟 (例如收集對話中分享的地點)，請向使用者顯示這個連結。請勿自行建構這個連結。

錯誤處理 (重要)：

  • 這項工具可批次處理資料，要求可能會傳回「混合結果」(例如部分網址成功解析，其他網址則失敗)。
  • entities 的輸出清單保證會與輸入 urls 索引 1:1 對應。如果網址解析失敗，entities 清單中對應索引的 Entity 訊息會是空白 (未設定任何欄位)。
  • 您必須檢查回應中的 failed_requests 對應欄位，找出失敗的網址索引。failed_requests 的鍵代表要求中失敗網址的索引 (從 0 開始)。請勿假設整個批次呼叫因部分失敗而失敗。

下列程式碼範例說明如何使用 curl 呼叫 resolve_maps_urls 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_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

ResolveMapsUrls 的要求訊息。

ResolveMapsUrlsRequest

JSON 表示法 
{
  "urls": [
    string
  ]
}
欄位
urls[]

string

必填。要解析的 Google 地圖網址。每個網址都必須是有效的 Google 地圖網址，例如 https://maps.app.goo.gl/...、https://www.google.com/maps/place/... 或 https://maps.google.com/...。目前僅支援指向單一地點的網址。最多可指定 20 個網址。

輸出內容的結構定義

ResolveMapsUrls 的回應訊息。

ResolveMapsUrlsResponse

JSON 表示法 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
欄位
entities[]

object (Entity)

僅供輸出。從 Google 地圖網址解析出的實體清單。保證與要求 urls 索引 1:1 對應。如果索引 i 處的訊息空白 (未設定 entity)，表示該網址解析失敗。如果解析失敗，請查看 failed_requests 欄位，瞭解錯誤狀態。
failedRequests

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

僅供輸出。這份對應表會指出 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

狀態碼，應為 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 編碼字串。

工具註解

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

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

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

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