MCP Tools Reference: chatmcp.googleapis.com

الأداة: search_conversations

تبحث هذه الأداة عن محادثات Google Chat (المساحات المُسمّاة أو الرسائل المباشرة أو المحادثات الجماعية) حسب الاسم المعروض أو المشاركين للعثور على أرقام تعريف المحادثات.

تبحث هذه الأداة في البيانات الوصفية للمحادثة، وليس في محتوى الرسائل. للبحث في سجلّ الرسائل أو العثور على الرسائل حسب الكلمة الرئيسية أو المُرسِل أو الطابع الزمني، استخدِم search_messages.

إذا تم توفير participants فقط، تعثر هذه الأداة على الرسائل المباشرة بين شخصين (إذا تم توفير مشارك واحد) أو المحادثات الجماعية (إذا تم توفير عدة مشاركين) التي تتضمّن المشاركين المحدّدين والمستخدم الذي يستدعي الأداة.

إذا تم توفير query فقط، تبحث هذه الأداة عن المحادثات التي يكون فيها طلب البحث سلسلة فرعية غير حسّاسة لحالة الأحرف من الاسم المعروض للمحادثة.

إذا تم توفير كل من participants وquery، تعثر هذه الأداة على المحادثات حسب المشاركين ثم تفلترها حسب الاسم المعروض.

إذا لم يتم توفير participants أو query، تسرد هذه الأداة جميع المحادثات التي يكون المستخدم الذي يستدعي الأداة عضوًا فيها.

لا تسرد هذه الأداة سوى المحادثات التي يكون المستخدم الذي يستدعي الأداة عضوًا فيها.

تعرض هذه الأداة قائمة بكائنات المحادثات التي تحتوي على أرقام تعريف المحادثات (بالتنسيق spaces/{space}) والأسماء المعروضة وأنواع المحادثات.

ملاحظة مهمة: لا تعني قائمة conversations الفارغة أنّه ما مِن نتائج أخرى بشكل عام. إذا كان next_page_token متوفرًا، يمكن جلب المزيد من الصفحات. إذا ظهرت لك قائمة فارغة ولكن كان هناك next_page_token، اسأل المستخدم عمّا إذا كان عليك مواصلة البحث.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة search_conversations في MCP.

طلب 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 tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

SearchConversationsRequest

تمثيل JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
الحقول
spaceNameQuery

string

اختياريّ. النص المطلوب البحث عنه في الأسماء المعروضة للمساحة (مطابقة السلسلة الفرعية غير الحساسة لحالة الأحرف)
pageSize

integer

اختياريّ. الحد الأقصى لعدد المساحات المطلوب عرضها قد تعرض الخدمة عددًا أقل من هذه القيمة. إذا لم يتم تحديد هذه القيمة، سيتم عرض 20 مساحة على الأكثر. الحد الأقصى للقيمة هو 1000، وسيتم فرض القيمة 1000 على القيم التي تزيد عن 1000.
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 لاسترداد الصفحة التالية إذا تم حذف هذا الحقل، ما مِن صفحات لاحقة.

المحادثة

تمثيل 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)

آخر وقت نشاط للمحادثة بتنسيق ISO 8601

يستخدم المعيار RFC 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)

تشير هذه السمة إلى عدد ثواني التوقيت العالمي المنسق (UTC) المنقضية منذ بداية حقبة يونكس 1970-01-01T00:00:00Z. يجب أن تكون القيمة بين ‎-62135596800 و253402300799 ضِمنًا (ما يعادل 0001-01-01T00:00:00Z إلى 9999-12-31T23:59:59Z).
nanos

integer

تشير هذه السمة إلى أجزاء الثانية غير السالبة بدقة النانو ثانية هذا الحقل هو جزء النانو ثانية من المدة، وليس بديلاً للثواني. يجب أن تتضمّن قيم الثواني السالبة التي تحتوي على أجزاء قيمًا غير سالبة للنانو ثانية يتم احتسابها للأمام في الوقت. يجب أن تكون القيمة بين 0 و999,999,999 ضِمنًا.

ConversationType

تحدّد هذه السمة نوع المحادثة.

عمليات التعداد
CONVERSATION_TYPE_UNSPECIFIED غير محدد
NAMED_SPACE مساحة مُسمّاة
GROUP_CHAT محادثة جماعية بين 3 أشخاص أو أكثر
DIRECT_MESSAGE رسالة مباشرة بين شخصين أو بين شخص وتطبيق Chat

التعليقات التوضيحية للأداة

يتم إرسال التعليقات التوضيحية للأداة إلى عملاء MCP لوصف المخاطر الأساسية لأداة معيّنة. تتعامل معظم البرامج مع هذه التلميحات على أنّها غير موثوق بها، ولكن يمكن استخدامها لتحديد متى قد يتم إرسال طلب تأكيد إلى المستخدم.

بالإضافة إلى سلسلة العنوان، يتم تعريف التلميحات المنطقية التالية على النحو التالي:

  • readOnlyHint: إذا كانت القيمة "صحيح"، لا تعدِّل الأداة بيئتها. القيمة التلقائية: "خطأ"
  • destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: "صحيح"
  • idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرر باستخدام الوسيطات نفسها إلى أي تأثير إضافي على بيئتها. القيمة التلقائية: "خطأ"
  • openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة البحث على الويب "عالمًا مفتوحًا"، بينما لن تكون أداة الذاكرة "عالمًا مفتوحًا".

تلميح مدمّر: ❌ | تلميح متكرّر: ✅ | تلميح للقراءة فقط: ✅ | تلميح للعالم المفتوح: ❌

نطاقات التفويض

يجب توفير أحد نطاقات OAuth التالية:

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