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 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 (التنسيق: مساحات/{مساحة}) و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 محادثة جماعية بين ثلاثة أشخاص أو أكثر
DIRECT_MESSAGE رسالة مباشرة بين شخصين أو بين شخص وتطبيق Chat

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

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

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

  • ‫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