MCP Tools Reference: chatmcp.googleapis.com

टूल: search_conversations

Google Chat में हुई बातचीत खोजता है, ताकि बातचीत के आईडी ढूंढे जा सकें. नाम वाले स्पेस, डिसप्ले नेम (space_name_query) से ढूंढे जाते हैं. डायरेक्ट मैसेज (डीएम) और ग्रुप चैट, सिर्फ़ हिस्सा लेने वाले लोगों के ईमेल पतों (participants) से ढूंढे जाते हैं.

यह टूल, बातचीत के मेटाडेटा को खोजता है, न कि मैसेज के कॉन्टेंट को. मैसेज के इतिहास में खोजने या कीवर्ड/भेजने वाले/टाइमस्टैंप के हिसाब से मैसेज ढूंढने के लिए, search_messages का इस्तेमाल करें.

अगर सिर्फ़ participants की जानकारी दी जाती है, तो यह टूल सीधी बातचीत (अगर एक व्यक्ति की जानकारी दी गई है) या ग्रुप चैट (अगर एक से ज़्यादा लोगों की जानकारी दी गई है) ढूंढता है. इनमें, कॉल करने वाले उपयोगकर्ता के साथ-साथ, वे लोग भी शामिल होते हैं जिनकी जानकारी दी गई है. नाम वाले स्पेस नहीं दिखाए जाते.

अगर सिर्फ़ space_name_query दिया गया है, तो यह टूल सिर्फ़ उन स्पेस को खोजता है जिनके नाम में क्वेरी, स्पेस के डिसप्ले नेम की केस-इनसेंसिटिव सबस्ट्रिंग होती है. डीएम और ग्रुप चैट कभी नहीं दिखती हैं. इसलिए, किसी व्यक्ति के साथ डीएम ढूंढने के लिए, उसके नाम को space_name_query के तौर पर पास न करें. इसके बजाय, उसका ईमेल पता ढूंढें और उसे participants में पास करें.

अगर participants और space_name_query, दोनों दिए गए हैं, तो यह टूल, हिस्सा लेने वाले लोगों के हिसाब से डीएम या ग्रुप चैट ढूंढता है. इसके बाद, उन्हें डिसप्ले नेम के हिसाब से फ़िल्टर करता है.

अगर participants या space_name_query में से कोई भी पैरामीटर नहीं दिया जाता है, तो यह टूल उन स्पेस की सूची दिखाता है जिनका सदस्य, कॉल करने वाला उपयोगकर्ता है. इसमें डीएम और ग्रुप चैट शामिल नहीं हैं.

यह टूल सिर्फ़ उन बातचीत को दिखाता है जिनमें कॉल करने वाला उपयोगकर्ता शामिल है.

यह बातचीत के ऑब्जेक्ट की सूची दिखाता है. इसमें बातचीत के आईडी (फ़ॉर्मैट: spaces/{space}), डिसप्ले नेम, और बातचीत के टाइप शामिल होते हैं.

अहम जानकारी: conversations की सूची खाली होने का मतलब यह नहीं है कि कोई और नतीजा नहीं है. अगर next_page_token मौजूद है, तो ज़्यादा पेज फ़ेच किए जा सकते हैं. अगर आपको खाली सूची मिलती है, लेकिन next_page_token मिलता है, तो उपयोगकर्ता से पूछें कि क्या आपको खोज जारी रखनी चाहिए.

यहां दिए गए कोड सैंपल में, curl का इस्तेमाल करके search_conversations एमसीपी टूल को कॉल करने का तरीका बताया गया है.

Curl अनुरोध 
curl --location 'https://chatmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

इनपुट स्कीमा

SearchConversationsRequest

JSON के काेड में दिखाना 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
फ़ील्ड
spaceNameQuery

string

ज़रूरी नहीं. बातचीत के डिसप्ले नेम में खोजने के लिए टेक्स्ट (केस-इनसेंसिटिव सबस्ट्रिंग मैच).

अगर participants खाली है, तो सिर्फ़ नाम वाले स्पेस खोजे जाते हैं. साथ ही, डायरेक्ट मैसेज (डीएम) और ग्रुप चैट कभी नहीं दिखती हैं. इसलिए, यहां किसी व्यक्ति का नाम खोजने पर, उसके साथ किया गया डीएम नहीं मिलेगा. कोई डीएम या ग्रुप चैट ढूंढने के लिए, participants में सदस्यों के ईमेल पते डालें. अगर participants सेट है, तो यह क्वेरी, मैच होने वाले डीएम या ग्रुप चैट को डिसप्ले नेम के हिसाब से फ़िल्टर करती है.
pageSize

integer

ज़रूरी नहीं. ज़्यादा से ज़्यादा कितने स्पेस दिखाए जाएं. सेवा, इस वैल्यू से कम नतीजे दिखा सकती है. अगर यह तय नहीं किया गया है, तो ज़्यादा से ज़्यादा 20 स्पेस दिखाए जाएंगे. ज़्यादा से ज़्यादा वैल्यू 1,000 हो सकती है. इससे ज़्यादा वैल्यू डालने पर, उसे 1,000 माना जाएगा.
pageToken

string

ज़रूरी नहीं. पिछले search_conversations कॉल से मिला पेज टोकन. अगला पेज पाने के लिए, यह टोकन दें.
participants[]

string

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

आउटपुट स्कीमा

जवाब में, मिलती-जुलती बातचीत की सूची शामिल होती है.

SearchConversationsResponse

JSON के काेड में दिखाना 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
फ़ील्ड
conversations[]

object (Conversation)

खोज की शर्तों से मेल खाने वाले बातचीत के ऑब्जेक्ट की सूची. हर बातचीत में conversation_id (फ़ॉर्मैट: spaces/{space}), display_name, conversation_type, और last_active_timestamp शामिल होता है.
nextPageToken

string

एक टोकन, जिसे अगले पेज को वापस पाने के लिए page_token के तौर पर भेजा जा सकता है. अगर इस फ़ील्ड को शामिल नहीं किया जाता है, तो इसके बाद कोई पेज नहीं होगा.

यह जानकारी सिर्फ़ तब अपने-आप भर जाती है, जब अनुरोध को participants के हिसाब से फ़िल्टर किया जाता है.

बातचीत

JSON के काेड में दिखाना 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
फ़ील्ड
conversationId

string

बातचीत का आईडी (जैसे, "spaces/AAAAAAAAA").
displayName

string

बातचीत का डिसप्ले नेम. नाम वाले स्पेस के लिए, यह स्पेस का नाम होता है. सीधी बातचीत के लिए, यह मीटिंग में हिस्सा लेने वाले दूसरे व्यक्ति का नाम होता है. बिना नाम वाली ग्रुप चैट के लिए, यह नाम सदस्यों के नामों के आधार पर जनरेट किया जाता है.
conversationType

enum (ConversationType)

बातचीत का टाइप (DIRECT_MESSAGE, GROUP_CHAT या NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

आईएसओ 8601 फ़ॉर्मैट में, बातचीत के आखिरी बार चालू होने का समय.

यह आरएफ़सी 3339 का इस्तेमाल करता है. इसमें जनरेट किया गया आउटपुट हमेशा Z-नॉर्मलाइज़ किया जाएगा और इसमें 0, 3, 6 या 9 फ़्रैक्शनल अंक इस्तेमाल किए जाएंगे. "Z" के अलावा, अन्य ऑफ़सेट भी स्वीकार किए जाते हैं. उदाहरण: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" या "2014-10-02T15:01:23+05:30".

टाइमस्टैम्प

JSON के काेड में दिखाना 
{
  "seconds": string,
  "nanos": integer
}
फ़ील्ड
seconds

string (int64 format)

यह Unix epoch 1970-01-01T00:00:00Z के बाद से, यूटीसी समय के सेकंड दिखाता है. यह -62135596800 और 253402300799 के बीच होना चाहिए. इसमें ये दोनों संख्याएं भी शामिल हैं. यह 0001-01-01T00:00:00Z से 9999-12-31T23:59:59Z के बीच होना चाहिए.
nanos

integer

नैनोसेकंड रिज़ॉल्यूशन में, सेकंड के नॉन-नेगेटिव फ़्रैक्शन. यह फ़ील्ड, अवधि का नैनोसेकंड वाला हिस्सा है. यह सेकंड का विकल्प नहीं है. फ़्रैक्शन वाली नेगेटिव सेकंड वैल्यू में, अब भी नॉन-नेगेटिव नैनो वैल्यू होनी चाहिए, जो समय के साथ आगे बढ़ती हैं. यह संख्या 0 से 99,99,99,999 के बीच होनी चाहिए. हालांकि, इन दोनों में से भी कोई संख्या हो सकती है.

ConversationType

इससे बातचीत का टाइप तय होता है.

Enums
CONVERSATION_TYPE_UNSPECIFIED नहीं बताया गया है
NAMED_SPACE कोई स्पेस, जिसका नाम रखा गया हो.
GROUP_CHAT तीन या इससे ज़्यादा लोगों के बीच की ग्रुप चैट.
DIRECT_MESSAGE दो लोगों के बीच या किसी व्यक्ति और चैट ऐप्लिकेशन के बीच हुआ डायरेक्ट मैसेज.

टूल एनोटेशन

टूल के एनोटेशन, एमसीपी क्लाइंट को भेजे जाते हैं. इससे उन्हें किसी टूल से जुड़े बुनियादी जोखिम के बारे में जानकारी मिलती है. ज़्यादातर क्लाइंट इन हिंट को भरोसेमंद नहीं मानते. हालांकि, इनका इस्तेमाल यह तय करने के लिए किया जा सकता है कि उपयोगकर्ता को पुष्टि करने का प्रॉम्प्ट कब भेजा जाए.

टाइटल स्ट्रिंग के साथ-साथ, बूलियन हिंट के बारे में यहां बताया गया है:

  • readOnlyHint: अगर इसकी वैल्यू true है, तो टूल अपने एनवायरमेंट में बदलाव नहीं करता. डिफ़ॉल्ट: false.
  • destructiveHint: अगर इसकी वैल्यू true है, तो टूल नुकसान पहुंचाने वाली कार्रवाइयां कर सकता है. अगर इसकी वैल्यू false है, तो टूल सिर्फ़ जोड़ने वाली कार्रवाइयां कर सकता है. डिफ़ॉल्ट: true.
  • idempotentHint: अगर इसकी वैल्यू true है, तो एक ही आर्ग्युमेंट के साथ टूल को बार-बार कॉल करने से, उसके एनवायरमेंट पर कोई और असर नहीं पड़ेगा. डिफ़ॉल्ट: false.
  • openWorldHint: सही होने पर, टूल बाहरी इकाइयों की 'विशाल दुनिया' के साथ इंटरैक्ट कर सकता है. अगर यह वैल्यू false है, तो टूल सिर्फ़ इंटरनल इकाइयों के साथ इंटरैक्ट कर सकता है. उदाहरण के लिए, वेब सर्च टूल ओपन वर्ल्ड होगा, जबकि मेमोरी टूल ओपन वर्ल्ड नहीं होगा.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

अनुमति पाने के लिंक

इनमें से किसी एक OAuth स्कोप की ज़रूरत हाेती है:

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly