MCP Tools Reference: mapstools.googleapis.com

Tài liệu tham khảo về công cụ MCP:

Tài liệu này mô tả các điểm cuối REST API hướng ra bên ngoài được dùng để gọi Công cụ Giao thức ngữ cảnh mô hình (MCP) từ xa của Google. API này đóng vai trò là một proxy bảo mật giữa một ứng dụng HTTP bên ngoài (chẳng hạn như curl hoặc một dịch vụ web) và Máy chủ MCP nội bộ.

Nhận thông số kỹ thuật của công cụ MCP

Để lấy thông số kỹ thuật của công cụ MCP cho tất cả các công cụ trong máy chủ MCP, hãy sử dụng phương thức `tools/list`. Ví dụ sau đây minh hoạ cách sử dụng curl để liệt kê tất cả các công cụ và thông số kỹ thuật hiện có trong máy chủ 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/list",
    "jsonrpc": "2.0",
    "id": 1
}'

Công cụ: search_places

Gọi công cụ này khi người dùng yêu cầu tìm địa điểm, doanh nghiệp, địa chỉ, vị trí, địa điểm yêu thích hoặc bất kỳ nội dung tìm kiếm nào khác liên quan đến Google Maps.

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

  1. text_query (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm chính. Bạn phải xác định rõ những gì người dùng đang tìm kiếm.

    • Ví dụ: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • Đối với thông tin chi tiết về một địa điểm cụ thể: Thêm thuộc tính được yêu cầu (ví dụ: 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  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: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Cách sử dụng:
      • Để thiên về bán kính 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Để thiên về điểm trung tâm: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (bỏ qua radius_meters).

  3. language_code (chuỗi – KHÔNG BẮT BUỘC): Ngôn ngữ để hiển thị nội dung tóm tắt kết quả tìm kiếm.

    • Định dạng: Mã ngôn ngữ gồm hai chữ cái (ISO 639-1), có thể theo sau là dấu gạch dưới và mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ: en, ja, en_US, zh_CN, es_MX. Nếu bạn không cung cấp mã ngôn ngữ, kết quả sẽ bằng tiếng Anh.

  4. region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode của người dùng. Tham số này được dùng để hiển thị thông tin chi tiết về địa điểm, chẳng hạn như tên địa điểm theo khu vực (nếu có). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

    • Định dạng: Mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ: US, CA.

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

  • Thông tin vị trí (QUAN TRỌNG): Cụm từ tìm kiếm phải có đủ thông tin vị trí. Nếu vị trí không rõ ràng (ví dụ: chỉ là "nơi bán pizza"), bạn phải chỉ định vị trí đó trong text_query (ví dụ: "pizza places in New York") hoặc sử dụng tham số location_bias. Thêm tên thành phố, tiểu bang/tỉnh và khu vực/quốc gia nếu cần để phân biệt.

  • Luôn cung cấp text_query cụ thể nhất và giàu ngữ cảnh nhất có thể.

  • Chỉ sử dụng location_bias nếu bạn cung cấp rõ ràng toạ độ hoặc nếu việc suy luận vị trí từ bối cảnh đã biết của người dùng là phù hợp và cần thiết để có kết quả tốt hơn.

Các mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ MCP search_places.

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": search_places,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Công cụ: lookup_weather

Cung cấp thông tin về điều kiện thời tiết hiện tại, dự báo theo giờ và theo ngày cho mọi địa điểm. Hãy sử dụng công cụ này cho mọi thắc mắc liên quan đến thời tiết.

Dữ liệu cụ thể có sẵn: Nhiệt độ (Hiện tại, Cảm giác như, Tối đa/Tối thiểu, Chỉ số nhiệt), Gió (Tốc độ, Gió giật, Hướng), Sự kiện thiên văn (Mặt trời mọc/Mặt trời lặn, Pha mặt trăng), Lượng mưa (Loại, Xác suất, Số lượng/QPF), Điều kiện khí quyển (Chỉ số UV, Độ ẩm, Lượng mây che phủ, Xác suất có giông bão) và Địa chỉ vị trí được mã hoá địa lý.

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

  • Điều kiện hiện tại: Chỉ yêu cầu một vị trí (ví dụ: thành phố hoặc địa chỉ). Đừng chỉ định ngày hoặc giờ.

  • Dự báo hằng giờ: Yêu cầu có vị trí và giờ (0-23). Sử dụng nếu người dùng hỏi về thời tiết tại một thời điểm cụ thể hoặc sử dụng các cụm từ như "vài giờ tới" hoặc "hôm nay muộn hơn".

  • Dự báo hằng ngày: Yêu cầu có vị trí và ngày đầy đủ.

Xử lý ngày (QUAN TRỌNG): Bạn PHẢI cung cấp ngày và giờ do người dùng cung cấp theo múi giờ địa phương của vị trí được yêu cầu. Ngày PHẢI được chia thành các tham số riêng biệt là số nguyên: năm, tháng và ngày. Định dạng bắt buộc cho các tham số này là: {"year": , "month": , "day": }

Các mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ MCP lookup_weather.

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": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Công cụ: compute_routes

Tính toán tuyến đường di chuyển giữa một điểm khởi hành và điểm đến cụ thể. Các chế độ di chuyển được hỗ trợ: LÁI XE (mặc định), ĐI BỘ.

Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG): Yêu cầu cả điểm khởi hành và điểm đến. Bạn phải cung cấp từng thông tin bằng một trong các phương thức sau, được lồng trong trường tương ứng:

  • address: (chuỗi, ví dụ: "Tháp Eiffel, Paris"). Lưu ý: Địa chỉ đầu vào càng chi tiết hoặc cụ thể thì kết quả sẽ càng tốt.

  • lat_lng: (đối tượng, {"latitude": number, "longitude": number})

  • place_id: (chuỗi, ví dụ: 'ChIJOwE_Id1w5EAR4Q27FkL6T_0') Lưu ý: Bạn có thể lấy mã nhận dạng này từ công cụ search_places. Bạn có thể kết hợp các loại dữ liệu đầu vào (ví dụ: điểm xuất phát theo địa chỉ, điểm đến theo lat_lng). Nếu thiếu điểm xuất phát hoặc điểm đến, bạn PHẢI hỏi người dùng để làm rõ trước khi tìm cách gọi công cụ.

Ví dụ về lệnh gọi công cụ: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

Các mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ MCP compute_routes.

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": compute_routes,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'