MCP Tools Reference: gmailmcp.googleapis.com

الأداة: get_message

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

استخدِم هذه الأداة لفحص رسالة إلكترونية واحدة عندما يكون لديك رقم تعريف الرسالة. إذا أراد المستخدم قراءة رسالة إلكترونية معيّنة بالتفصيل أو التحقّق من الصياغة الدقيقة لرسالة أو فحص البيانات الوصفية للمرفقات في رسالة إلكترونية واحدة، فهذه هي الأداة المناسبة. لا تناسب هذه الأداة استرداد محادثات كاملة أو عرض سلاسل مناقشات، لذا استخدِم أداة "get_thread" بدلاً منها. تشمل المؤشرات الرئيسية ما إذا كان المستخدم يطلب المحتوى الكامل لرقم تعريف رسالة معيّن تم عرضه في عملية بحث سابقة، أو إذا كان طلب البحث يطلب فحص رسالة إلكترونية فردية معيّنة بدلاً من سلسلة محادثات كاملة. في ما يلي أمثلة على طلبات المستخدمين: "احصل على النص الكامل لرقم تعريف الرسالة 18f123456789abcd."، "اقرأ آخر رسالة في سلسلة المحادثات هذه من سارة"، و"ما هي أسماء المرفقات في الرسالة الإلكترونية التي تلقّيتُها للتو من قسم الموارد البشرية؟"

يتحكّم المَعلمة الاختيارية messageFormat في تنسيق الرسالة التي يتم عرضها. تعرض القيمة التلقائية (أو FULL_CONTENT) المحتوى الكامل للرسالة. استخدِم MINIMAL لتضمين الموضوع والمقتطف فقط (باستثناء النص). استخدِم METADATA_ONLY لتضمين البيانات الوصفية الأساسية فقط (رقم تعريف الرسالة ورقم تعريف سلسلة المحادثات والتصنيفات والطابع الزمني وتقدير الحجم).

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

طلب Curl 
curl --location 'https://gmailmcp.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": "get_message",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة الطلب لـ GetMessage RPC.

GetMessageRequest

تمثيل JSON 
{
  "messageId": string,
  "messageFormat": enum (MessageFormat)
}
الحقول
messageId

string

الحقل مطلوب. المعرّف الفريد للرسالة التي سيتم جلبها.
messageFormat

enum (MessageFormat)

اختياريّ. يحدّد تنسيق الرسالة التي يتم عرضها. القيمة التلقائية هي FULL_CONTENT.

MessageFormat

عملية تعداد للتحكّم في مستوى التفاصيل للرسائل في سلسلة المحادثات

عمليات التعداد
MESSAGE_FORMAT_UNSPECIFIED القيمة التلقائية هي FULL_CONTENT.
MINIMAL تعرض مقتطفات الرسائل والعناوين الرئيسية (الموضوع، من، إلى، نسخة إلى، التاريخ)
FULL_CONTENT تعرض كل المعلومات في `MINIMAL` بالإضافة إلى المحتوى الكامل لنص كل رسالة.
METADATA_ONLY البيانات الوصفية فقط: لا تتضمّن الموضوع والمقتطف والنص وأسماء ملفات المرفقات

مخطط النتائج

رسالة ضمن سلسلة محادثات

رسالة

تمثيل JSON 
{
  "id": string,
  "snippet": string,
  "subject": string,
  "sender": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "date": string,
  "plaintextBody": string,
  "attachmentIds": [
    string
  ],
  "htmlBody": string,
  "attachments": [
    {
      object (AttachmentMetadata)
    }
  ],
  "labelIds": [
    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
htmlBody

string

محتوى HTML للرسالة الإلكترونية، لا تتم تعبئته إلا إذا كانت MessageFormat هي FULL_CONTENT
attachments[]

object (AttachmentMetadata)

النتائج فقط. المرفقات، لا تتم تعبئتها إلا إذا كانت MessageFormat هي FULL_CONTENT
labelIds[]

string

أرقام تعريف التصنيفات المرفقة بالرسالة تشمل أرقام تعريف تصنيفات المستخدم وتصنيفات النظام العادية التي تقتصر على INBOX وSPAM وTRASH وUNREAD وSTARRED وIMPORTANT وSENT وDRAFT وCHAT

AttachmentMetadata

تمثيل JSON 
{
  "id": string,
  "mimeType": string,
  "filename": string
}
الحقول
id

string

النتائج فقط. رقم تعريف المرفق
mimeType

string

نوع MIME للمرفق
filename

string

اسم ملف المرفق

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

تلميح بشأن الإجراءات المدمّرة: ❌ | تلميح بشأن الإجراءات غير المدمّرة: ✅ | تلميح بشأن الإجراءات للقراءة فقط: ✅ | تلميح بشأن الإجراءات في العالم المفتوح: ❌

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

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

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.metadata