MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_maps_urls

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

Thời điểm 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 hàng loạt duy nhất.

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

  • urls (mảng chuỗi – BẮT BUỘC): Danh sách các URL trên 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ả 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 (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. 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ố URL phân giải thành công trong khi những URL khác không phân giải được).
  • 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, bạn sẽ nhận được thông báo Entity 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 failed_requests map 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 biểu thị chỉ mục dựa trên 0 của URL 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_maps_urls 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_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ể đã phân giải từ URL Google Maps. Đảm bảo ánh xạ 1:1 với các chỉ mục urls của yêu cầu. Một 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. Bản đồ truyền đạt các 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ị 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.

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 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 cố gắng liên hệ với các URL thuộc 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.

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ở: ❌