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 索引一一对应。失败的查询将在 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”或“Eiffel Tower, 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 索引一一对应。索引 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 引用上写入 scheme，以免客户端尝试与其联系。

前缀是任意的，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，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

破坏性提示：❌ | 幂等性提示：❌ | 只读提示：✅ | 开放世界提示：❌