MCP Tools Reference: gmailmcp.googleapis.com

الأداة: search_threads

تعرض هذه الطريقة سلاسل الرسائل الإلكترونية من حساب Gmail الخاص بالمستخدم الذي تمّت مصادقته.

يمكن لهذه الأداة فلترة سلاسل المحادثات استنادًا إلى سلسلة طلب بحث وتتيح تقسيم المحتوى إلى صفحات. تعرض هذه الطريقة قائمة بسلاسل المحادثات، بما في ذلك أرقام التعريف والرسائل ذات الصلة. تحتوي كل رسالة ذات صلة على تفاصيل مثل مقتطف من نص الرسالة والموضوع والمُرسِل والمستلِمين وما إلى ذلك. يُرجى العِلم أنّ هذه الأداة لا تعرض نصوص الرسائل الكاملة، لذا استخدِم الأداة get_thread مع رقم تعريف سلسلة المحادثات لاسترداد نص الرسالة الكامل إذا لزم الأمر. قد تظل سلاسل المحادثات التي تتضمّن معايير مستبعدة تظهر في النتائج. يحدث ذلك لأنّ Gmail يحدّد الرسائل المطابقة أولاً. على سبيل المثال، إذا بحثت عن -is:starred، سيعرض لك Gmail سلسلة محادثات بأكملها لمجرد أنها تتضمن رسالة واحدة على الأقل غير مميزة بنجمة، حتى وإن كانت بقية الرسائل في تلك المحادثة مميزة بنجمة.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة search_threads MCP.

طلب Curl 
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_threads",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

طلب رسالة لإجراء SearchThreads RPC.

SearchThreadsRequest

تمثيل JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "includeTrash": boolean
}
الحقول

حقل الربط _page_size

يمكن أن يكون التعليق _page_size إحدى القيم التالية فقط:
pageSize

integer

اختياريّ. الحدّ الأقصى لعدد سلاسل المحادثات المطلوب عرضها إذا لم يتم تحديدها، تكون القيمة التلقائية 20. الحدّ الأقصى المسموح به هو 50.

حقل الربط _page_token

يمكن أن يكون التعليق _page_token إحدى القيم التالية فقط:
pageToken

string

اختياريّ. رمز مميّز للصفحة لاسترداد صفحة معيّنة من النتائج في القائمة. اترك الحقل فارغًا لجلب الصفحة الأولى. يُستخدَم هذا المعرّف بشكل أساسي لتقسيم النتائج على عدّة صفحات من أجل مواصلة جلب النتائج من حيث توقّفت المكالمة السابقة SearchThreads، خاصةً عندما يتجاوز عدد سلاسل المحادثات المطابقة لطلب البحث الحدّ الأقصى المسموح به في page_size.

حقل الربط _query

يمكن أن يكون التعليق _query إحدى القيم التالية فقط:
query

string

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

عوامل التشغيل المتاحة حسب الفئة:

المُرسِل والمستلِم: from: - الرسائل المُرسَلة من مستخدم محدَّد إلى: - الرسائل المُرسَلة إلى مستخدم معيّن cc: - مستخدمون محدَّدون في "نسخة إلى" bcc: - مستخدمون محدّدون في الحقل "نسخة مخفية الوجهة" deliveredto: - تم التسليم إلى عنوان محدّد. list: - من قائمة بريدية معيّنة

الوقت والتاريخ: after:YYYY/MM/DD / newer:YYYY/MM/DD - تم استلامها بعد تاريخ معيّن before:YYYY/MM/DD / older:YYYY/MM/DD - تم استلامها قبل تاريخ معيّن older_than: - أقدم من مدة زمنية (مثلاً، 1y أو 2d) newer_than: - أحدث من مدة زمنية

المحتوى: subject: - الكلمات في سطر الموضوع has: - يحتوي على أنواع محتوى معيّنة (مرفق، Drive، YouTube، مستند). filename: - مرفق باسم أو نوع معيّن "<كلمة/عبارة>": للبحث عن كلمة أو عبارة بالتحديد (مثلاً، "عطلة" أو "عطلة الأعياد"). ‫+ : مطابقة كلمة تمامًا (مثلاً، ‎+holiday أو ‎+unicorn) rfc822msgid: - رأس معرّف رسالة معيّن AROUND : للبحث عن كلمات قريبة من بعضها (مثلاً، holiday AROUND 10 vacation).

التصنيفات والفئات: label: - ضمن تصنيف معيّن تقبل الأداة أرقام تعريف التصنيفات، وليس الأسماء المعروضة. استخدِم أداة list_labels للحصول على المعرّف. category: - في فئة (الرسائل الأساسية، والرسائل الاجتماعية، والرسائل الترويجية، والتحديثات، والمنتديات، والحجوزات، وعمليات الشراء) in:

الحالة: is: - للبحث حسب الحالة (مهمة، مميّزة بنجمة، غير مقروءة، مقروءة، تم تجاهلها).

الحجم: size: - حجم محدّد بالبايت larger: / smaller: - أكبر أو أصغر من حجم معيّن (مثلاً، 10M أي 10 ميغابايت).

المنطق والتجميع: AND - مطابقة جميع المعايير (السلوك التلقائي) OR أو { } - تطابق معيارًا واحدًا أو أكثر (مثلاً، from:سليم OR from:إبراهيم أو {from:سليم from:إبراهيم}). علامة الطرح (-) - استبعاد معايير (مثلاً، -فيلم) ( ) - لجمع عبارات بحث متعددة (مثلاً، subject:(dinner film)).

أمثلة: "subject:OneMCP Update" "from:user@example.com" "to:user2@example.com AND newer_than:7d" "project proposal has:attachment" "is:unread -in:draft"

حقل الربط _include_trash

يمكن أن يكون التعليق _include_trash إحدى القيم التالية فقط:
includeTrash

boolean

اختياريّ. تضمين المسودّات من المهملات في النتائج القيمة التلقائية هي "خطأ".

مخطط النتائج

رسالة الردّ على استدعاء إجراء SearchThreads عن بُعد

SearchThreadsResponse

تمثيل JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
الحقول
threads[]

object (Thread)

قائمة بملخّصات سلاسل المحادثات
nextPageToken

string

رمز مميّز يمكن استخدامه في طلب لاحق لاسترداد الصفحة التالية من سلاسل المحادثات. يجب عرضها فقط إذا كانت هناك نتائج إضافية. إذا كان عدد سلاسل المحادثات المطابقة لطلب البحث يتجاوز الحدّ الأقصى المسموح به في page_size، سيتضمّن الردّ next_page_token. لاسترداد الصفحة التالية من النتائج، مرِّر هذا الرمز المميّز في الحقل page_token لطلب SearchThreadsRequest التالي.

Thread

تمثيل JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
الحقول
id

string

المعرّف الفريد لسلسلة المحادثات.
messages[]

object (Message)

قائمة بالرسائل في سلسلة المحادثات، مرتبة حسب التسلسل الزمني

رسالة

تمثيل JSON 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ]
}
الحقول
id

string

المعرّف الفريد للرسالة.
snippet

string

مقتطف من نص الرسالة
subject

string

موضوع الرسالة المستخرَج من العناوين:
sender

string

عنوان البريد الإلكتروني للمُرسِل
toRecipients[]

string

إلى عناوين البريد الإلكتروني للمستلِمين
ccRecipients[]

string

عناوين البريد الإلكتروني للمستلِمين في الحقل "نسخة إلى"
date

string

تاريخ الرسالة بتنسيق ISO 8601 (YYYY-MM-DD).
plaintextBody

string

محتوى الرسالة الكامل، ويتم ملؤه فقط إذا كانت قيمة MessageFormat هي FULL_CONTENT.
attachmentIds[]

string

النتائج فقط. معرّفات المرفقات، ويتم ملؤها فقط إذا كانت قيمة MessageFormat هي FULL_CONTENT.

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

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