MCP Reference: mapstools.googleapis.com

यह Maps Grounding Lite API का एमसीपी सर्वर है. यह सर्वर, डेवलपर को Google Maps Platform पर एलएलएम ऐप्लिकेशन बनाने के लिए टूल उपलब्ध कराता है.

एक मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर, एक बाहरी सेवा और लार्ज लैंग्वेज मॉडल (एलएलएम) या एआई ऐप्लिकेशन के बीच प्रॉक्सी के तौर पर काम करता है. बाहरी सेवा, एलएलएम या एआई ऐप्लिकेशन को कॉन्टेक्स्ट, डेटा या सुविधाएं उपलब्ध कराती है. एमसीपी सर्वर, एआई ऐप्लिकेशन को डेटाबेस और वेब सेवाओं जैसे बाहरी सिस्टम से कनेक्ट करते हैं. साथ ही, उनके जवाबों को ऐसे फ़ॉर्मैट में ट्रांसलेट करते हैं जिसे एआई ऐप्लिकेशन समझ सके.

सर्वर का सेटअप

इस्तेमाल करने से पहले, आपको एमसीपी सर्वर चालू करने होंगे और पुष्टि की प्रोसेस सेट अप करनी होगी. Google और Google Cloud के रिमोट एमसीपी सर्वर के इस्तेमाल के बारे में ज़्यादा जानने के लिए, Google Cloud के एमसीपी सर्वर की खास जानकारी देखें.

सर्वर के एंडपॉइंट

एमसीपी सेवा का एंडपॉइंट, एमसीपी सर्वर का नेटवर्क पता और कम्यूनिकेशन इंटरफ़ेस (आम तौर पर, एक यूआरएल) होता है. एआई ऐप्लिकेशन (एमसीपी क्लाइंट के लिए होस्ट) इसका इस्तेमाल, सुरक्षित और स्टैंडर्ड कनेक्शन बनाने के लिए करता है. एलएलएम, कॉन्टेक्स्ट का अनुरोध करने, किसी टूल को कॉल करने या किसी संसाधन को ऐक्सेस करने के लिए, इस एंडपॉइंट का इस्तेमाल करता है. Google के एमसीपी एंडपॉइंट, ग्लोबल या स्थानीय हो सकते हैं.

Maps Grounding Lite API के एमसीपी सर्वर का ग्लोबल एमसीपी एंडपॉइंट यह है:

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

एमसीपी टूल

एक एमसीपी टूल, एक फ़ंक्शन या एक्ज़ीक्यूटेबल सुविधा होती है. एमसीपी सर्वर, एलएलएम या एआई ऐप्लिकेशन को यह सुविधा उपलब्ध कराता है, ताकि वह असल दुनिया में कोई कार्रवाई कर सके.

टूल

mapstools.googleapis.com के एमसीपी सर्वर में ये टूल शामिल हैं:

एमसीपी टूल
search_places

जब उपयोगकर्ता, जगहें, कारोबार, पते, लोकेशन, दिलचस्पी की जगहें या Google Maps से जुड़ी कोई अन्य चीज़ खोजने का अनुरोध करता है, तब इस टूल को कॉल करें.

इनपुट की ज़रूरी शर्तें (अहम जानकारी):

  1. text_query (स्ट्रिंग - ज़रूरी है): मुख्य सर्च क्वेरी. इससे यह साफ़ तौर पर पता चलना चाहिए कि उपयोगकर्ता क्या ढूंढ रहा है.

    • उदाहरण: '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'.
    • किसी जगह की खास जानकारी पाने के लिए: अनुरोध किया गया एट्रिब्यूट शामिल करें. जैसे, 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address'.

  2. location_bias (ऑब्जेक्ट - ज़रूरी नहीं): इसका इस्तेमाल, किसी खास भौगोलिक इलाके के आस-पास के नतीजों को प्राथमिकता देने के लिए करें.

    • फ़ॉर्मैट: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • इस्तेमाल का तरीका:
      • 5 किलोमीटर के दायरे में मौजूद जगहों को प्राथमिकता देने के लिए: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • केंद्र बिंदु को प्राथमिकता देने के लिए: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (radius_meters को छोड़कर).

  3. language_code (स्ट्रिंग - ज़रूरी नहीं): खोज नतीजों की खास जानकारी दिखाने के लिए भाषा.

    • फ़ॉर्मैट: दो अक्षरों वाला भाषा कोड (ISO 639-1). इसके बाद, ज़रूरत पड़ने पर अंडरस्कोर और दो अक्षरों वाला देश कोड (ISO 3166-1 alpha-2) जोड़ा जा सकता है. जैसे, en, ja, en_US, zh_CN, es_MX. अगर भाषा कोड नहीं दिया जाता है, तो नतीजे अंग्रेज़ी में दिखेंगे.

  4. region_code (स्ट्रिंग - ज़रूरी नहीं): उपयोगकर्ता का यूनिकोड CLDR क्षेत्र कोड. इस पैरामीटर का इस्तेमाल, जगह की जानकारी दिखाने के लिए किया जाता है. जैसे, अगर उपलब्ध हो, तो क्षेत्र के हिसाब से जगह का नाम. लागू कानून के आधार पर, इस पैरामीटर से नतीजों पर असर पड़ सकता है.

    • फ़ॉर्मैट: दो अक्षरों वाला देश कोड (ISO 3166-1 alpha-2). जैसे, US, CA.

टूल को कॉल करने के निर्देश:

  • जगह की जानकारी (अहम जानकारी): खोज में, जगह की पूरी जानकारी होनी चाहिए. अगर जगह की जानकारी साफ़ नहीं है (जैसे, सिर्फ़ "पिज़्ज़ा प्लेस"), तो आपको इसकी जानकारी text_query में देनी होगी. जैसे, "पिज़्ज़ा प्लेस इन न्यूयॉर्क". इसके अलावा, location_bias पैरामीटर का इस्तेमाल भी किया जा सकता है. अगर जानकारी को साफ़ करने के लिए ज़रूरी हो, तो शहर, राज्य/प्रांत, और क्षेत्र/देश का नाम शामिल करें.

  • हमेशा सबसे सटीक और कॉन्टेक्स्ट के हिसाब से सही text_query दें.

  • location_bias का इस्तेमाल सिर्फ़ तब करें, जब निर्देशांक साफ़ तौर पर दिए गए हों. इसके अलावा, अगर उपयोगकर्ता के जाने-पहचाने कॉन्टेक्स्ट से किसी जगह का अनुमान लगाना सही और ज़रूरी हो, तब भी इसका इस्तेमाल किया जा सकता है. ऐसा करने से बेहतर नतीजे मिलते हैं.

  • जब attribution फ़ील्ड में जानकारी उपलब्ध हो, तब ग्राउंडेड आउटपुट को सोर्स के साथ एट्रिब्यूट किया जाना चाहिए.
lookup_weather

मौसम का पूरा डेटा वापस लाता है. इसमें मौजूदा मौसम की जानकारी, हर घंटे और हर दिन का पूर्वानुमान शामिल होता है.

उपलब्ध खास डेटा: तापमान (मौजूदा, महसूस होने वाला, ज़्यादा से ज़्यादा/कम से कम, हीट इंडेक्स), हवा (रफ़्तार, झोंके, दिशा), खगोलीय घटनाएं (सूर्य उगना/डूबना, चंद्रमा की कलाएं), बारिश (टाइप, संभावना, मात्रा/क्यूपीएफ़), वायुमंडलीय स्थितियां (यूवी इंडेक्स, नमी, बादल छाने का स्तर, आंधी-तूफ़ान की संभावना), और जियोकोड की गई जगह का पता.

जगह और जगह के नियम (अहम जानकारी):

location फ़ील्ड का इस्तेमाल करके, उस जगह की जानकारी दी जाती है जिसके लिए मौसम का डेटा मांगा गया है. यह फ़ील्ड 'oneof' स्ट्रक्चर है. इसका मतलब है कि मौसम का सटीक डेटा पाने के लिए, आपको जगह के इन तीन सब-फ़ील्ड में से सिर्फ़ एक के लिए वैल्यू देनी होगी.

  1. भौगोलिक निर्देशांक (lat_lng)

    • इसका इस्तेमाल तब करें, जब आपको अक्षांश/देशांतर के सटीक निर्देशांक दिए गए हों.
    • उदाहरण: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // लॉस ऐंजेलिस

  2. जगह का आईडी (place_id)

    • एक ऐसा स्ट्रिंग आइडेंटिफ़ायर (Google Maps जगह का आईडी) जो किसी जगह की साफ़ तौर पर पहचान करता है.
    • search_places टूल से place_id फ़ेच किया जा सकता है.
    • उदाहरण: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // एफ़िल टावर

  3. पते की स्ट्रिंग (address)

    • यह एक फ़्री-फ़ॉर्म स्ट्रिंग है. जियोकोडिंग के लिए, इसमें सटीक जानकारी देना ज़रूरी है.
    • शहर और क्षेत्र: हमेशा क्षेत्र/देश का नाम शामिल करें. जैसे, "London, UK", न कि "London".
    • मोहल्ले का पता: पूरा पता दें. जैसे, "1600 Pennsylvania Ave NW, Washington, DC".
    • पिन कोड/ज़िप कोड: इनके साथ देश का नाम होना ज़रूरी है. जैसे, "90210, USA", न कि "90210".
    • उदाहरण: {"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

इस्तेमाल के मोड:

  • मौजूदा मौसम की जानकारी: सिर्फ़ location की जानकारी दें. date और hour की जानकारी न दें.

  • हर घंटे मौसम की जानकारी: location, date, और hour (0-23) की जानकारी दें. इसका इस्तेमाल, खास समय (जैसे, "शाम 5 बजे") या "अगले कुछ घंटों" या "आज बाद में" जैसे शब्दों के लिए करें. अगर उपयोगकर्ता मिनट की जानकारी देता है, तो इसे सबसे नज़दीकी घंटे में राउंड डाउन करें. फ़िलहाल, 120 घंटे से ज़्यादा का हर घंटे का पूर्वानुमान उपलब्ध नहीं है. पिछले 24 घंटों का हर घंटे का मौसम का डेटा उपलब्ध है.

  • हर दिन मौसम की जानकारी: location और date की जानकारी दें. hour की जानकारी न दें. इसका इस्तेमाल, दिन के सामान्य अनुरोधों के लिए करें. जैसे, "कल का मौसम", "शुक्रवार का मौसम", "25 दिसंबर का मौसम". अगर कॉन्टेक्स्ट में आज की तारीख शामिल नहीं है, तो आपको उपयोगकर्ता को इसकी जानकारी देनी चाहिए. आज के मौसम के साथ-साथ, अगले 10 दिनों का मौसम का पूर्वानुमान उपलब्ध नहीं है. पुराना मौसम का डेटा उपलब्ध नहीं है.

पैरामीटर की सीमाएं:

  • टाइमज़ोन: सभी date और hour इनपुट, जगह के स्थानीय टाइमज़ोन के हिसाब से होने चाहिए, न कि उपयोगकर्ता के टाइमज़ोन के हिसाब से.
  • तारीख का फ़ॉर्मैट: इनपुट को {year, month, day} इंटिजर में अलग-अलग किया जाना चाहिए.
  • यूनिट: डिफ़ॉल्ट रूप से METRIC पर सेट होता है. अगर उपयोगकर्ता, अमेरिका के स्टैंडर्ड के हिसाब से फ़ारेनहाइट/मील में जानकारी चाहता है या साफ़ तौर पर इसका अनुरोध करता है, तो units_system को IMPERIAL पर सेट करें.

  • जब attribution फ़ील्ड में जानकारी उपलब्ध हो, तब ग्राउंडेड आउटपुट को सोर्स के साथ एट्रिब्यूट किया जाना चाहिए.
compute_routes

तय की गई जगह से मंज़िल तक पहुंचने के लिए, यात्रा का रूट दिखाता है. यात्रा के इन तरीकों के लिए रूट दिखाया जा सकता है: DRIVE (डिफ़ॉल्ट), WALK.

इनपुट की ज़रूरी शर्तें (अहम जानकारी): इसके लिए शुरू होने की जगह और मंज़िल, दोनों की जानकारी ज़रूरी है. इन दोनों की जानकारी, यहां दिए गए किसी एक तरीके से दी जानी चाहिए. साथ ही, इन्हें अपने-अपने फ़ील्ड में नेस्ट किया जाना चाहिए:

  • address: (स्ट्रिंग, जैसे, 'एफ़िल टावर, पेरिस'). ध्यान दें: पते की जानकारी जितनी सटीक होगी, नतीजे उतने ही बेहतर होंगे.

  • lat_lng: (ऑब्जेक्ट, {"latitude": number, "longitude": number})

  • place_id: (स्ट्रिंग, जैसे, 'ChIJOwE_Id1w5EAR4Q27FkL6T_0') ध्यान दें: यह आईडी, search_places टूल से पाया जा सकता है. इनपुट टाइप के किसी भी कॉम्बिनेशन का इस्तेमाल किया जा सकता है. जैसे, शुरू होने की जगह का पता और मंज़िल के लिए अक्षांश/देशांतर. अगर शुरू होने की जगह या मंज़िल की जानकारी नहीं दी गई है, तो टूल को कॉल करने से पहले, आपको उपयोगकर्ता से इसकी जानकारी मांगनी होगी.

टूल को कॉल करने का उदाहरण: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • जब attribution फ़ील्ड में जानकारी उपलब्ध हो, तब ग्राउंडेड आउटपुट को सोर्स के साथ एट्रिब्यूट किया जाना चाहिए.
resolve_names

जगह की खास क्वेरी (लैंडमार्क के नाम या सटीक पते) की बैच लिस्ट को, Google Maps Place ID में बदलता है.

इनपुट की ज़रूरी शर्तें (अहम जानकारी):

  1. queries (ऑब्जेक्ट का कलेक्शन - ज़रूरी है): जगह की क्वेरी की वह सूची जिसे रिज़ॉल्व करना है. ज़्यादा से ज़्यादा 20 क्वेरी दी जा सकती हैं.

    • हर क्वेरी ऑब्जेक्ट में यह जानकारी होनी चाहिए:
      • text (स्ट्रिंग - ज़रूरी है): वह टेक्स्ट क्वेरी जिसे रिज़ॉल्व करना है. यह किसी जगह के नाम या पते की जानकारी देती है.
        • उदाहरण: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (ऑब्जेक्ट - ज़रूरी नहीं): इसका इस्तेमाल, किसी खास भौगोलिक इलाके के आस-पास के नतीजों को प्राथमिकता देने के लिए करें.

    • फ़ॉर्मैट: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (स्ट्रिंग - ज़रूरी नहीं): उपयोगकर्ता का यूनिकोड CLDR क्षेत्र कोड (दो अक्षरों वाला देश कोड, जैसे, US, CA). इसका इस्तेमाल, नतीजों को प्राथमिकता देने के लिए किया जाता है.

टूल को कॉल करने के निर्देश:

  • सटीक जानकारी (अहम जानकारी): क्वेरी में, किसी जगह के नाम या पते की सटीक जानकारी होनी चाहिए. सामान्य खोजें, जैसे कि 'restaurants' या चेन के नाम, जैसे कि 'Starbucks' काम नहीं करते.
  • अगर डाउनस्ट्रीम टूल, रॉ पते या जगह के नाम की स्ट्रिंग को सीधे तौर पर स्वीकार करते हैं, तो इस टूल को कॉल न करें.

गड़बड़ी को ठीक करना (अहम जानकारी):

  • यह बैच प्रोसेसिंग टूल है. किसी अनुरोध के लिए "मिले-जुले नतीजे" मिल सकते हैं. जैसे, कुछ क्वेरी रिज़ॉल्व हो जाती हैं, जबकि कुछ नहीं हो पाती हैं.
  • results की आउटपुट सूची, इनपुट queries के इंडेक्स के साथ 1:1 मैप होती है. अगर कोई क्वेरी रिज़ॉल्व नहीं होती है, तो results सूची में उसके इंडेक्स पर, Result मैसेज खाली होगा. इसका मतलब है कि entity सेट नहीं है.
  • आपको यह पता लगाने के लिए, रिस्पॉन्स में failed_requests मैप फ़ील्ड की जांच ज़रूर करनी चाहिए कि किस क्वेरी का इंडेक्स रिज़ॉल्व नहीं हुआ. failed_requests की कुंजी, अनुरोध में रिज़ॉल्व न हुई क्वेरी का 0-आधारित इंडेक्स दिखाती है. यह न मान लें कि आंशिक गड़बड़ी की वजह से, बैच कॉल पूरी तरह से रिज़ॉल्व नहीं हुआ.
resolve_maps_urls

Google Maps के यूआरएल की सूची को, Google Maps Place ID में बदलता है.

इस टूल को कब कॉल करना चाहिए (अहम जानकारी):

  • इस टूल का इस्तेमाल तब करें, जब उपयोगकर्ता Google Maps के एक या उससे ज़्यादा शेयरिंग लिंक या यूआरएल देता है. जैसे, 'https://maps.app.goo.gl/...', 'https://www.google.com/maps/place/...' या 'https://maps.google.com/...' और आपको इनसे, Google Maps Place ID निकालने हों.
  • एक बैच अनुरोध में, रिज़ॉल्व करने के लिए ज़्यादा से ज़्यादा 20 यूआरएल दिए जा सकते हैं.

इनपुट की ज़रूरी शर्तें (अहम जानकारी):

  • urls (स्ट्रिंग का कलेक्शन - ज़रूरी है): Google Maps के उन यूआरएल की सूची जिन्हें रिज़ॉल्व करना है. हर यूआरएल, Google Maps का मान्य और एक जगह का यूआरएल होना चाहिए.

गड़बड़ी को ठीक करना (अहम जानकारी):

  • यह बैच प्रोसेसिंग टूल है. किसी अनुरोध के लिए "मिले-जुले नतीजे" मिल सकते हैं. जैसे, कुछ यूआरएल रिज़ॉल्व हो जाते हैं, जबकि कुछ नहीं हो पाते हैं.
  • entities की आउटपुट सूची, इनपुट urls के इंडेक्स के साथ 1:1 मैप होती है. अगर कोई यूआरएल रिज़ॉल्व नहीं होता है, तो entities सूची में उसके इंडेक्स पर, Entity मैसेज खाली होगा. इसका मतलब है कि कोई फ़ील्ड सेट नहीं है.
  • आपको यह पता लगाने के लिए, रिस्पॉन्स में failed_requests मैप फ़ील्ड की जांच ज़रूर करनी चाहिए कि किस यूआरएल का इंडेक्स रिज़ॉल्व नहीं हुआ. failed_requests की कुंजी, अनुरोध में रिज़ॉल्व न हुए यूआरएल का 0-आधारित इंडेक्स दिखाती है. यह न मान लें कि आंशिक गड़बड़ी की वजह से, बैच कॉल पूरी तरह से रिज़ॉल्व नहीं हुआ.

एमसीपी टूल की खास जानकारी पाना

किसी एमसीपी सर्वर में मौजूद सभी टूल की खास जानकारी पाने के लिए, tools/list तरीके का इस्तेमाल करें. यहां दिए गए उदाहरण में, curl का इस्तेमाल करके, एमसीपी सर्वर में फ़िलहाल उपलब्ध सभी टूल और उनकी खास जानकारी की सूची बनाने का तरीका बताया गया है.

Curl Request 
                      
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
}'