MCP Tools Reference: gmailmcp.googleapis.com

ابزار: search_threads

رشته‌های ایمیل از حساب Gmail کاربر احراز هویت‌شده را فهرست می‌کند.

این ابزار می‌تواند رشته‌ها را بر اساس یک رشته پرس‌وجو فیلتر کند و از صفحه‌بندی پشتیبانی می‌کند. این ابزار لیستی از رشته‌ها، شامل شناسه‌های آنها و پیام‌های مرتبط را برمی‌گرداند. هر پیام مرتبط حاوی جزئیاتی مانند بخشی از متن پیام، موضوع، فرستنده، گیرندگان و غیره است. توجه داشته باشید که متن کامل پیام توسط این ابزار برگردانده نمی‌شود؛ در صورت نیاز از ابزار 'get_thread' با شناسه رشته برای دریافت متن کامل پیام استفاده کنید. رشته‌هایی با معیارهای حذف‌شده ممکن است همچنان در نتایج ظاهر شوند. این اتفاق می‌افتد زیرا Gmail ابتدا پیام‌های منطبق را شناسایی می‌کند. به عنوان مثال، اگر عبارت -is:starred را جستجو کنید، Gmail در صورتی که یک رشته حداقل یک پیام بدون ستاره داشته باشد، آن را پیدا می‌کند، حتی اگر ایمیل‌های دیگر در همان مکالمه ستاره‌دار باشند.

نمونه زیر نحوه استفاده از curl برای فراخوانی ابزار search_threads MCP را نشان می‌دهد.

درخواست کرل 
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
}'

طرحواره ورودی

درخواست پیام برای RPC مربوط به SearchThreads.

جستجوموضوعاتدرخواست

نمایش 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

اختیاری. یک رشته پرس‌وجو برای فیلتر کردن رشته‌ها. برای استفاده از این ابزار، پرس‌وجوهای زبان طبیعی باید از قبل به پرس‌وجوهای نحوی جیمیل تبدیل شوند. در صورت حذف، همه رشته‌ها (به استثنای هرزنامه و زباله به طور پیش‌فرض) فهرست می‌شوند.

اپراتورهای پشتیبانی شده بر اساس دسته بندی:

فرستنده و گیرنده: از: - ارسال شده از یک شخص خاص. به: - برای یک شخص خاص ارسال شد. رونوشت: - افراد خاص در رونوشت مخفی: - افراد خاص در Bcc. تحویل داده شده به: - به یک آدرس خاص تحویل داده شد. لیست: - از یک لیست پستی خاص.

زمان و تاریخ: بعد از:YYYY/MM/DD / جدیدتر:YYYY/MM/DD - دریافت شده پس از یک تاریخ. قبل از:YYYY/MM/DD / قدیمی‌تر:YYYY/MM/DD - دریافت شده قبل از یک تاریخ. مسن‌تر از: - قدیمی‌تر از یک مدت زمان (مثلاً ۱ سال، ۲ روز). جدیدتر از: - جدیدتر از یک مدت زمان.

محتوا: موضوع: - کلمات موجود در قسمت موضوع: - انواع محتوای خاص (پیوست، درایو، یوتیوب، سند) دارد. نام فایل: - پیوست با نام یا نوع خاص. "<word/phrase>" - جستجوی یک کلمه یا عبارت دقیق. (مثلاً "holiday"، "holiday vacation"). + - دقیقاً یک کلمه را مطابقت دهید. (مثلاً، +holiday، +unicorn) rfc822msgid: - هدر شناسه پیام خاص. اطراف - کلمات نزدیک به هم را پیدا کنید (مثلاً، holiday AROUND 10 vacation).

برچسب‌ها و دسته‌بندی‌ها: برچسب: - تحت یک برچسب خاص. این ابزار شناسه‌های برچسب را می‌پذیرد، نه نام‌های نمایشی. از ابزار list_labels برای دریافت شناسه استفاده کنید. دسته: - در یک دسته (اصلی، اجتماعی، تبلیغات، به‌روزرسانی‌ها، انجمن‌ها، رزروها، خریدها). in:

وضعیت: است: - جستجو بر اساس وضعیت (مهم، ستاره‌دار، خوانده نشده، خوانده شده، بی‌صدا).

اندازه: اندازه: - اندازه خاص بر حسب بایت. بزرگتر: / کوچکتر: - بزرگتر یا کوچکتر از یک اندازه (مثلاً 10M برای 10 مگابایت).

منطق و گروه‌بندی: AND - همه معیارها را مطابقت می‌دهد (رفتار پیش‌فرض). OR یا { } - یک یا چند معیار را مطابقت می‌دهد (مثلاً from:amy یا from:david، {from:amy from:david}). - (منها) - معیارها را حذف می‌کند (مثلاً -movie). ( ) - چندین عبارت جستجو را گروه‌بندی می‌کند (مثلاً subject:(dinner film)).

مثال‌ها: "موضوع: به‌روزرسانی OneMCP" "از: user@example.com " "به: user2@example.com و جدیدتر از: 7 روز" "پیشنهاد پروژه دارای: پیوست است" "خوانده نشده -در: پیش‌نویس است"

فیلد یونیون _include_trash .

_include_trash ‎‏ فقط می‌تواند یکی از موارد زیر باشد:

includeTrash

boolean

اختیاری. پیش‌نویس‌های TRASH را در نتایج لحاظ کنید. پیش‌فرض‌ها false است.

طرحواره خروجی

پیام پاسخ برای RPC مربوط به SearchThreads.

جستجوموضوعاتپاسخ

نمایش JSON 
{
  "threads": [
    {
      object (Thread)
    }
  ],
  "nextPageToken": string
}
فیلدها
threads[]

object ( Thread )

فهرست خلاصه موضوعات.

nextPageToken

string

توکنی که می‌تواند در فراخوانی بعدی برای بازیابی صفحه بعدی رشته‌ها استفاده شود. فقط در صورتی ارائه می‌شود که نتایج بیشتری وجود داشته باشد. اگر تعداد رشته‌های منطبق با پرس‌وجو از حد page_size بیشتر شود، پاسخ حاوی next_page_token خواهد بود. برای بازیابی صفحه بعدی نتایج، این توکن را در فیلد page_token از SearchThreadsRequest بعدی ارسال کنید.

موضوع

نمایش 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

آدرس‌های ایمیل گیرنده‌ی CC.

date

string

تاریخ پیام در قالب ISO 8601 (YYYY-MM-DD).

plaintextBody

string

محتوای کامل بدنه، فقط در صورتی پر می‌شود که MessageFormat برابر با FULL_CONTENT باشد.

attachmentIds[]

string

فقط خروجی. شناسه‌های پیوست، فقط در صورتی که MessageFormat برابر با FULL_CONTENT باشد، پر می‌شوند.

حاشیه‌نویسی ابزار

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌