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 لاستدعاء أداة MCP‏ 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

اختيارية: النص المطلوب البحث عنه ضمن الأسماء المعروضة للمساحات (مطابقة سلسلة فرعية غير حسّاسة لحالة الأحرف)
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 لاسترداد الصفحة التالية. إذا تم حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

لا تتم تعبئة هذا الحقل إلا إذا تمت فلترة الطلب حسب 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)

تمثّل هذه السمة آخر وقت نشط للمحادثة بتنسيق 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: إذا كانت القيمة صحيحة، لا تعدّل الأداة بيئتها. القيمة التلقائية: false
  • ‫destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • ‫idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرّر باستخدام الوسيطات نفسها إلى أي تأثير إضافي على بيئتها. القيمة التلقائية: false
  • ‫openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة بحث الويب عالمًا مفتوحًا، في حين أنّ أداة الذاكرة لن تكون عالمًا مفتوحًا.

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