MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_maps_urls

Phân giải danh sách URL trên Google Maps thành Mã địa điểm chính tắc trên Google Maps.

Trường hợp nên gọi công cụ này (QUAN TRỌNG):

  • Sử dụng công cụ này khi người dùng cung cấp một hoặc nhiều đường liên kết hoặc URL chia sẻ trên Google Maps (ví dụ: "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." hoặc "https://maps.google.com/...") và bạn cần trích xuất Mã địa điểm chính tắc cơ bản.
  • Bạn có thể chỉ định tối đa 20 URL để phân giải trong một yêu cầu theo lô.

Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):

  • urls (mảng chuỗi – BẮT BUỘC): Danh sách URL của Google Maps cần phân giải. Mỗi URL phải là một URL hợp lệ, chỉ đến một địa điểm duy nhất trên Google Maps.

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ả đị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 (ví dụ: thu thập các địa điểm được chia sẻ trong một cuộc trò chuyện), hãy cung cấp đường liên kết này cho người dùng. ĐỪNG tự tạo đường liên kết này.

Xử lý lỗi (QUAN TRỌNG):

  • Đây là 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ố URL phân giải thành công trong khi một số khác không thành công).
  • Danh sách đầu ra của entities được đảm bảo ánh xạ 1:1 với các chỉ mục urls đầu vào. Nếu không phân giải được URL, thì thông báo Entity sẽ trống (không có trường nào được đặt) tại chỉ mục tương ứng trong danh sách entities.
  • Bạn PHẢI kiểm tra trường bản đồ failed_requests trong phản hồi để xác định chỉ mục URL cụ thể nào không thành công. Khoá của failed_requests đại diện cho chỉ mục dựa trên 0 của URL không thành công trong yêu cầu. Đừng cho rằng toàn bộ lệnh gọi theo lô đều không thành công vì 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ụ MCP resolve_maps_urls.

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_maps_urls",
    "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 ResolveMapsUrls.

ResolveMapsUrlsRequest

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

string

Bắt buộc. URL trên Google Maps cần được phân giải. Mỗi URL phải là một URL hợp lệ của Google Maps, ví dụ: https://maps.app.goo.gl/..., https://www.google.com/maps/place/... hoặc https://maps.google.com/.... Hiện tại, chúng tôi chỉ hỗ trợ những URL trỏ đến một địa điểm duy nhất. Bạn có thể chỉ định tối đa 20 URL.

Giản đồ đầu ra

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

ResolveMapsUrlsResponse

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

object (Entity)

Chỉ có đầu ra. Danh sách các thực thể đã được phân giải từ URL của Google Maps. Đảm bảo liên kết 1:1 với các chỉ mục urls của yêu cầu. Thông báo trống tại chỉ mục i (nơi không đặt entity) cho biết quá trình phân giải không thành công cho URL đó. 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 đồ thông báo lỗi một phần cho URL của Google Maps. Khoá là chỉ mục của yêu cầu không thành công trong trường urls. Giá trị 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. Một đườ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.

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 một 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 chuẩn, không có dấu chấm ở đầu. Đừng viết lược đồ trên các tham chiếu URI này để ứng dụng không cố gắng liên hệ với chúng.

Tiền tố là tuỳ ý và các phương thức triển khai Protobuf dự kiến sẽ 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à tiền tố mặc định phổ biến mà một số cá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 dự kiến sẽ phản hồi bất kỳ yêu cầu nào.

Tất cả chuỗi URL loại phải là tham chiếu URI hợp lệ với quy định hạn chế bổ sung (đối với định dạng văn bản) rằng nội dung của tham chiếu chỉ được bao gồm các ký tự chữ và số, ký tự thoát được mã hoá theo phần trăm và các ký tự trong tập hợp sau (không bao gồm dấu phẩ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 bỏ ký tự thoát để tránh 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 khởi chạy dịch vụ phân giải loại tại các URL loại này đã được xem xét, nhưng Protobuf chưa bao giờ triển khai dịch vụ này 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. Đừng cố gắng liên hệ với các URL loại.
value

string (bytes format)

Chứa một 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.

Chú thích về công cụ

Chú thích về công cụ được gửi đến ứ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 ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng có thể dùng chú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 nó. Mặc định: false.
  • destructiveHint: Nếu đúng, thì công cụ có thể thực hiện các hành động có tính huỷ diệt. Nếu là false, thì công cụ chỉ có thể thực hiện các hành động 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 có thêm hiệu ứng nào đối với môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, thì công cụ 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ụ: công cụ tìm kiếm trên web sẽ là công cụ thế giới mở, còn công cụ ghi nhớ sẽ không phải là công cụ thế giới mở.

Gợi ý về hành động huỷ diệt: ❌ | Gợi ý về hành động luỹ đẳng: ❌ | Gợi ý về hành động chỉ đọc: ✅ | Gợi ý về hành động trong thế giới mở: ❌