MCP Reference: mapstools.googleapis.com

Máy chủ Giao thức ngữ cảnh mô hình (MCP) đóng vai trò là một proxy giữa dịch vụ bên ngoài cung cấp ngữ cảnh, dữ liệu hoặc các chức năng cho Mô hình ngôn ngữ lớn (LLM) hoặc ứng dụng AI. Các máy chủ MCP kết nối các ứng dụng AI với các hệ thống bên ngoài như cơ sở dữ liệu và dịch vụ web, chuyển đổi các phản hồi của chúng sang định dạng mà ứng dụng AI có thể hiểu được.

Thiết lập máy chủ

Bạn phải bật máy chủ MCP và thiết lập quy trình xác thực trước khi sử dụng. Để biết thêm thông tin về cách sử dụng máy chủ MCP từ xa của Google và Google Cloud, hãy xem bài viết Tổng quan về máy chủ MCP của Google Cloud.

Đây là một máy chủ MCP do Maps Grounding Lite API cung cấp. Máy chủ này cung cấp các công cụ để nhà phát triển xây dựng ứng dụng LLM trên Google Maps Platform.

Điểm cuối của máy chủ

Điểm cuối dịch vụ MCP là địa chỉ mạng và giao diện giao tiếp (thường là một URL) của máy chủ MCP mà một ứng dụng AI (Máy chủ lưu trữ cho ứng dụng MCP) sử dụng để thiết lập một kết nối an toàn, tiêu chuẩn. Đây là điểm tiếp xúc để LLM yêu cầu ngữ cảnh, gọi một công cụ hoặc truy cập vào một tài nguyên. Các điểm cuối MCP của Google có thể là toàn cầu hoặc theo khu vực.

Máy chủ MCP mapstools.googleapis.com có điểm cuối MCP sau đây:

  • https://mapstools.googleapis.com/mcp

Công cụ MCP

Công cụ MCP là một chức năng hoặc khả năng thực thi mà máy chủ MCP cung cấp cho một LLM hoặc ứng dụng AI để thực hiện một hành động trong thế giới thực.

Máy chủ MCP mapstools.googleapis.com có các công cụ sau:

Công cụ MCP
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ề thông tin đầ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'.
    • Để biết 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:
      • Để ưu tiên bán kính 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Để thiên về điểm giữa: {"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 2 chữ cái (ISO 639-1), có thể theo sau là dấu gạch dưới và mã quốc gia gồm 2 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ỉ "nơi bán pizza"), bạn phải chỉ định vị trí đó trong text_query (ví dụ: "nơi bán pizza ở 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.
lookup_weather

Truy xuất dữ liệu thời tiết toàn diện, bao gồm cả tình hình thời tiết hiện tại, dự báo theo giờ và dự báo hằng ngày.

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ý.

Vị trí và Quy tắc về vị trí (QUAN TRỌNG):

Vị trí mà bạn yêu cầu dữ liệu thời tiết được chỉ định bằng trường "location". Trường này là một cấu trúc "oneof", nghĩa là bạn PHẢI cung cấp giá trị cho CHỈ MỘT trong 3 trường phụ vị trí bên dưới để đảm bảo tra cứu dữ liệu thời tiết chính xác.

  1. Toạ độ địa lý (lat_lng)

    • Sử dụng khi bạn được cung cấp toạ độ vĩ độ/kinh độ chính xác.
    • Ví dụ: "lat_lng": { "latitude": 34.0522, "longitude": -118.2437 } // Los Angeles

  2. Mã địa điểm (place_id)

    • Một giá trị nhận dạng duy nhất ở dạng chuỗi (Mã địa điểm trên Google Maps).
    • Bạn có thể tìm nạp place_id bằng công cụ search_places.
    • Ví dụ: "place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0" // Eiffel Tower

  3. Chuỗi địa chỉ (address)

    • Một chuỗi tuỳ ý cần có tính cụ thể để mã hoá địa lý.
    • Thành phố và khu vực: Luôn thêm khu vực/quốc gia (ví dụ: "London, Vương quốc Anh" chứ không phải "London").
    • Địa chỉ đường phố: Cung cấp địa chỉ đầy đủ (ví dụ: "1600 Pennsylvania Ave NW, Washington, DC").
    • Mã bưu chính: PHẢI đi kèm với tên quốc gia (ví dụ: "90210, Hoa Kỳ", KHÔNG phải "90210").

Các chế độ sử dụng:

  1. Thời tiết hiện tại: Chỉ cung cấp location. Không chỉ định date và hour.

  2. Dự báo hằng giờ: Cung cấp location, date và hour (0-23). Sử dụng cho các thời điểm cụ thể (ví dụ: "lúc 5 giờ chiều") hoặc các cụm từ như "vài giờ tới" hoặc "hôm nay muộn hơn". Nếu người dùng chỉ định phút, hãy làm tròn xuống giờ gần nhất. Chúng tôi không hỗ trợ dự báo hằng giờ cho khoảng thời gian quá 120 giờ kể từ thời điểm hiện tại. Thông tin thời tiết theo giờ trong quá khứ được hỗ trợ tối đa 24 giờ.

  3. Dự báo hằng ngày: Cung cấp location và date. Không chỉ định hour. Dùng cho các yêu cầu chung về ngày (ví dụ: "thời tiết ngày mai", "thời tiết vào thứ Sáu", "thời tiết vào ngày 25/12"). Nếu ngày hôm nay không có trong ngữ cảnh, bạn nên làm rõ với người dùng. Chúng tôi không hỗ trợ dự báo hằng ngày cho hơn 10 ngày, kể cả hôm nay. Không hỗ trợ thông tin thời tiết trong quá khứ.

Các ràng buộc về tham số:

  • Múi giờ: Tất cả các giá trị đầu vào date và hour phải tương ứng với múi giờ địa phương của vị trí, chứ không phải múi giờ của người dùng.
  • Định dạng ngày: Bạn phải tách các giá trị đầu vào thành {year, month, day} số nguyên.
  • Đơn vị: Mặc định là METRIC. Đặt units_system thành IMPERIAL cho độ Fahrenheit/dặm nếu người dùng ngụ ý sử dụng tiêu chuẩn của Hoa Kỳ hoặc yêu cầu rõ ràng.
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ề thông tin đầ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 ý: Thông tin đầu vào địa chỉ 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ã địa điểm 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 yêu cầu 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"}

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

Để nhận thông số kỹ thuật của công cụ MCP cho tất 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
}'