MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_names

Phân giải một danh sách hàng loạt các truy vấn vị trí cụ thể (tên địa danh hoặc địa chỉ chính xác) thành mã địa điểm chuẩn của Google Maps.

Yêu cầu về thông tin đầu vào (QUAN TRỌNG):

  1. queries (mảng đối tượng – BẮT BUỘC): Danh sách các truy vấn vị trí cần phân giải. Bạn có thể chỉ định tối đa 20 cụm từ tìm kiếm.

    • Mỗi đối tượng truy vấn phải có:
      • text (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm bằng văn bản đại diện cho một tên địa điểm hoặc địa chỉ cụ thể cần phân giải.
        • Ví dụ: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (đối tượng – KHÔNG BẮT BUỘC): Sử dụng tham số này để ưu tiên kết quả ở gần một khu vực địa lý cụ thể.

    • Định dạng: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode (mã quốc gia gồm 2 chữ cái, ví dụ: US, CA) của người dùng để điều chỉnh kết quả.

Hướng dẫn về lệnh gọi công cụ:

  • Tính cụ thể (RẤT QUAN TRỌNG): Cụm từ tìm kiếm phải thể hiện một tên địa điểm hoặc địa chỉ cụ thể. Chúng tôi không hỗ trợ các cụm từ tìm kiếm chung chung như 'restaurants' hoặc tên chuỗi như 'Starbucks'.
  • KHÔNG gọi công cụ này nếu các công cụ hạ nguồn mà bạn dự định gọi đã chấp nhận trực tiếp các chuỗi địa chỉ hoặc tên địa điểm thô.

Lưu vào Google Maps:

  • Phản hồi bao gồm một trường save_to_maps_url: một đường liên kết duy nhất đến Google Maps chứa tất cả những địa điểm đã được phân giải thành công.
  • Khi người dùng muốn lưu, chia sẻ hoặc mở các địa điểm đã phân giải dưới dạng danh sách trong Google Maps, hãy cung cấp đường liên kết này cho người dùng. KHÔNG tự tạo đường liên kết này.

Xử lý lỗi (NGHIÊM TRỌNG):

  • Đây là một công cụ xử lý hàng loạt. Một yêu cầu có thể trả về "kết quả hỗn hợp" (ví dụ: một số truy vấn phân giải thành công trong khi những truy vấn khác không thành công).
  • Danh sách đầu ra của results được đảm bảo ánh xạ 1:1 với các chỉ mục queries đầu vào. Một truy vấn không thành công sẽ dẫn đến thông báo Result trống (không có entity nào được đặt) tại chỉ mục tương ứng trong danh sách results.
  • Bạn PHẢI kiểm tra trường failed_requests bản đồ trong phản hồi để xác định chỉ mục truy vấn cụ thể nào không thành công. Khoá của failed_requests biểu thị chỉ mục dựa trên 0 của truy vấn không thành công trong yêu cầu. Đừng giả định rằng toàn bộ lệnh gọi hàng loạt đều không thành công do một phần không thành công.

Mã mẫu sau đây cho biết cách sử dụng curl để gọi công cụ resolve_names MCP.

Yêu cầu 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
}'

Giản đồ đầu vào

Thông báo yêu cầu cho ResolveNames.

ResolveNamesRequest

Biểu diễn dưới dạng JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Trường
queries[]

object (LocationQuery)

Bắt buộc. Danh sách các truy vấn về vị trí cần được phân giải. Bạn có thể chỉ định tối đa 20 cụm từ tìm kiếm.
locationBias

object (LocationBias)

Không bắt buộc. Một khu vực không bắt buộc để thiên vị kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về những thực thể gần khu vực này hơn. Việc thêm location_bias hoặc region_code thường mang lại kết quả tốt hơn bằng cách thu hẹp không gian tìm kiếm.

Nếu bạn chỉ định cả location_bias và region_code, thì location_bias sẽ được ưu tiên hơn region_code.
regionCode

string

Không bắt buộc. Mã khu vực không bắt buộc để thiên vị kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về những thực thể ở trong hoặc gần khu vực được chỉ định. Đây phải là mã vùng CLDR. Ví dụ: "US" hoặc "CA". Việc thêm location_bias hoặc region_code thường mang lại kết quả tốt hơn bằng cách thu hẹp không gian tìm kiếm.

Nếu bạn chỉ định cả location_bias và region_code, thì location_bias sẽ được ưu tiên hơn region_code.

LocationQuery

Biểu diễn dưới dạng JSON 
{
  "text": string
}
Trường
text

string

Bắt buộc. Cụm từ tìm kiếm dạng văn bản để phân giải thành một thực thể không gian địa lý cụ thể trên Google Maps, chẳng hạn như một địa điểm hoặc địa chỉ. Câu hỏi càng cụ thể thì giải pháp càng chính xác. Ví dụ: "San Francisco", "Googleplex, Mountain View, California", "1600 Amphitheatre Parkway, Mountain View, California" hoặc "Tháp Eiffel, Paris". Cụm từ tìm kiếm phải là một địa chỉ hoặc tên địa điểm cụ thể. Chúng tôi không hỗ trợ các vị trí chung chung như tên chuỗi cửa hàng (ví dụ: Starbucks) hoặc cụm từ tìm kiếm như "nhà hàng".

LocationBias

Biểu diễn dưới dạng JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Trường
Trường nhóm type. Loại thiên kiến về vị trí. type chỉ có thể là một trong những trạng thái sau:
viewport

object (Viewport)

Khung nhìn được xác định bằng một hộp bao quanh.

Khung nhìn

Biểu diễn dưới dạng JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Trường
low

object (LatLng)

Bắt buộc. Điểm thấp nhất của khung nhìn.
high

object (LatLng)

Bắt buộc. Điểm cao nhất của khung nhìn.

LatLng

Biểu diễn dưới dạng JSON 
{
  "latitude": number,
  "longitude": number
}
Trường
latitude

number

Vĩ độ tính bằng độ. Giá trị này phải nằm trong khoảng [-90.0, +90.0].
longitude

number

Kinh độ tính bằng độ. Giá trị này phải nằm trong khoảng [-180.0, +180.0].

Giản đồ đầu ra

Thông báo phản hồi cho ResolveNames.

ResolveNamesResponse

Biểu diễn dưới dạng JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Trường
results[]

object (Result)

Chỉ có đầu ra. Danh sách các thực thể được phân giải từ các truy vấn vị trí. Đảm bảo ánh xạ 1:1 với các chỉ mục queries của yêu cầu. Một chuỗi trống tại chỉ mục i cho biết quá trình phân giải không thành công cho truy vấn đó. Nếu quá trình phân giải không thành công, vui lòng kiểm tra trường failed_requests để biết trạng thái lỗi.
failedRequests

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

Chỉ có đầu ra. Một bản đồ cho biết một số lỗi. Khoá là chỉ mục của yêu cầu không thành công trong trường queries. Giá trị này là trạng thái lỗi nêu chi tiết lý do khiến quá trình phân giải không thành công.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Chỉ có đầu ra. Đường liên kết để lưu tất cả các thực thể đã được phân giải thành công trong Google Maps.

Kết quả

Biểu diễn dưới dạng JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Trường
entity

object (Entity)

Chỉ có đầu ra. Thực thể được phân giải từ truy vấn vị trí.
confidence

enum (Confidence)

Chỉ có đầu ra. Mức độ tin cậy của độ phân giải.

Thực thể

Biểu diễn dưới dạng JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Trường
Trường nhóm entity. Loại thực thể đã phân giải. entity chỉ có thể là một trong những trạng thái sau:
place

string

Tên tài nguyên của địa điểm đã phân giải.

FailedRequestsEntry

Biểu diễn dưới dạng JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Trường
key

integer
value

object (Status)

Trạng thái

Biểu diễn dưới dạng JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Trường
code

integer

Mã trạng thái, phải là giá trị enum của google.rpc.Code.
message

string

Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi mà người dùng thấy đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc được ứng dụng khách bản địa hoá.
details[]

object

Danh sách các thông báo chứa thông tin cụ thể về lỗi. Có một nhóm gồm nhiều loại thông báo chung để API sử dụng.

Một đối tượng chứa các trường thuộc một loại tuỳ ý. Một trường bổ sung "@type" chứa một URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" }.

Bất kỳ

Biểu diễn dưới dạng JSON 
{
  "typeUrl": string,
  "value": string
}
Trường
typeUrl

string

Xác định loại thông báo Protobuf được chuyển đổi tuần tự bằng một tham chiếu URI bao gồm tiền tố kết thúc bằng dấu gạch chéo và tên loại đủ điều kiện.

Ví dụ: type.googleapis.com/google.protobuf.StringValue

Chuỗi này phải chứa ít nhất một ký tự / và nội dung sau ký tự / cuối cùng phải là tên đủ điều kiện của loại ở dạng chính tắc, không có dấu chấm ở đầu. Đừng viết một lược đồ trên các tham chiếu URI này để máy khách không cố gắng liên hệ với chúng.

Tiền tố này là tuỳ ý và các phương thức triển khai Protobuf chỉ cần loại bỏ mọi thứ cho đến và bao gồm cả / cuối cùng để xác định loại. type.googleapis.com/ là một tiền tố mặc định phổ biến mà một số chế độ triển khai cũ yêu cầu. Tiền tố này không cho biết nguồn gốc của loại và các URI chứa tiền tố này không được mong đợi phản hồi bất kỳ yêu cầu nào.

Tất cả các chuỗi URL loại đều phải là các tham chiếu URI hợp lệ với hạn chế bổ sung (đối với định dạng văn bản) là nội dung của tham chiếu chỉ được bao gồm các ký tự chữ và số, các ký tự thoát được mã hoá theo tỷ lệ phần trăm và các ký tự trong tập hợp sau (không bao gồm dấu nháy ngược bên ngoài): /-.~_!$&()*+,;=. Mặc dù chúng tôi cho phép mã hoá phần trăm, nhưng các phương thức triển khai không được phép huỷ bỏ việc thoát các mã này để tránh gây nhầm lẫn với các trình phân tích cú pháp hiện có. Ví dụ: type.googleapis.com%2FFoo sẽ bị từ chối.

Trong thiết kế ban đầu của Any, khả năng chạy một dịch vụ phân giải loại tại các URL loại này đã được cân nhắc nhưng Protobuf chưa bao giờ triển khai dịch vụ nào và coi việc liên hệ với các URL này là có vấn đề và có thể gây ra vấn đề bảo mật. Không được tìm cách liên hệ với các URL loại này.
value

string (bytes format)

Lưu giữ một quy trình chuyển đổi tuần tự Protobuf của loại được mô tả bằng type_url.

Một chuỗi được mã hoá base64.

Độ tin cậy

Mức độ tin cậy của độ phân giải.

Enum
CONFIDENCE_UNSPECIFIED Giá trị mặc định. Giá trị này không được dùng.
MEDIUM Độ tin cậy trung bình cho biết giải pháp có khả năng chính xác nhưng có thể có những giải pháp khác.
HIGH Độ tin cậy cao cho biết độ phân giải chính xác và thể hiện một thực thể không gian địa lý cụ thể (ví dụ: một địa điểm cụ thể).

Chú thích bằng công cụ

Chú thích công cụ được gửi đến các ứng dụng MCP để mô tả rủi ro cơ bản của một công cụ nhất định. Hầu hết các ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng chúng có thể được dùng để quyết định thời điểm gửi lời nhắc xác nhận cho người dùng.

Cùng với chuỗi tiêu đề, các gợi ý boolean sau đây được xác định như sau:

  • readOnlyHint: Nếu đúng, công cụ sẽ không sửa đổi môi trường của công cụ. Mặc định: false.
  • destructiveHint: Nếu đúng, công cụ có thể thực hiện các hành động phá huỷ. Nếu là false, thì công cụ chỉ có thể thực hiện các thao tác bổ sung. Mặc định: true.
  • idempotentHint: Nếu đúng, thì việc gọi công cụ nhiều lần với cùng một đối số sẽ không ảnh hưởng gì thêm đến môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, công cụ này có thể tương tác với "thế giới mở" của các thực thể bên ngoài. Nếu là false, thì công cụ chỉ có thể tương tác với các thực thể nội bộ. Ví dụ: một công cụ tìm kiếm trên web sẽ là thế giới mở, trong khi một công cụ bộ nhớ sẽ không phải là thế giới mở.

Gợi ý mang tính huỷ diệt: ❌ | Gợi ý không thay đổi giá trị: ❌ | Gợi ý chỉ đọc: ✅ | Gợi ý thế giới mở: ❌