MCP Tools Reference: gmailmcp.googleapis.com

כלי: search_threads

רשימה של שרשורי אימייל מחשבון Gmail של המשתמש המאומת.

הכלי הזה יכול לסנן שרשורים על סמך מחרוזת שאילתה, והוא תומך בחלוקה לעמודים. הפונקציה מחזירה רשימה של שרשורים, כולל המזהים שלהם וההודעות שקשורות אליהם. כל הודעה קשורה מכילה פרטים כמו קטע מגוף ההודעה, הנושא, השולח, הנמענים וכו'. שימו לב שהכלי הזה לא מחזיר את גוף ההודעה המלא. אם אתם צריכים את גוף ההודעה המלא, אתם יכולים להשתמש בכלי get_thread עם מזהה השרשור. יכול להיות שעדיין יופיעו בתוצאות שרשורים עם קריטריונים מוחרגים. זה קורה כי Gmail מזהה קודם הודעות תואמות. לדוגמה, אם מחפשים ‎-is:starred, ‏ Gmail ימצא שרשור שלם אם הוא מכיל לפחות הודעה אחת שלא סומנה בכוכב, גם אם הודעות אחרות באותה שיחה סומנו בכוכב.

בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להפעיל את כלי ה-MCP‏ search_threads.

בקשת 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
}'

סכימת הקלט

הודעת בקשה ל-RPC של SearchThreads.

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: – נשלח מאדם מסוים. אל: – הודעות שנשלחו לאדם מסוים. עותק: – אנשים ספציפיים בעותק. עותק מוסתר: – אנשים ספציפיים בשדה 'עותק מוסתר'. deliveredto: – נמסר לכתובת ספציפית. list: – מרשימת תפוצה ספציפית.

תאריך ושעה: after:YYYY/MM/DD / newer:YYYY/MM/DD – התקבל אחרי תאריך מסוים. before:YYYY/MM/DD / older:YYYY/MM/DD – התקבל לפני תאריך מסוים. older_than: – נתונים ישנים יותר מתקופה מסוימת (למשל, 1y, ‏ 2d). newer_than: – חדש יותר מפרק זמן מסוים.

תוכן: נושא: - מילים בשורת הנושא. has: – כולל סוגי תוכן ספציפיים (קובץ מצורף, Drive, ‏ YouTube, מסמך). filename: – קובץ מצורף עם שם או סוג ספציפיים. ‫"<מילה/ביטוי>" – חיפוש של מילה או ביטוי מדויקים. (לדוגמה, "חג", "חופשת חג"). ‫+ – התאמה מדויקת של מילה. (לדוגמה, +חג, +חד-קרן) rfc822msgid: – כותרת של מזהה הודעה ספציפי. ‫AROUND – חיפוש מילים שנמצאות זו ליד זו (לדוגמה, holiday AROUND 10 vacation).

תוויות וקטגוריות: label: - חיפוש בתווית ספציפית. הכלי מקבל מזהי תוויות, לא שמות לתצוגה. אפשר להשתמש בכלי list_labels כדי לקבל את המזהה. category: – בקטגוריה (ראשי, רשתות חברתיות, קידומי מכירות, עדכונים, פורומים, הזמנות, רכישות). in:

סטטוס: is: - חיפוש לפי סטטוס (חשוב, מסומן בכוכב, לא נקרא, נקרא, מושתק).

גודל: size: – גודל ספציפי בבייטים. larger:‎ / smaller:‎ – גדול יותר או קטן יותר מגודל מסוים (לדוגמה, ‎10M‎ ל-10 מגה-בייט).

לוגיקה וקיבוץ: AND – התאמה לכל הקריטריונים (התנהגות ברירת המחדל). OR או { } – התאמה לקריטריון אחד או יותר (לדוגמה, from:amy OR from:david, {from:amy from:david}). ‫- (מינוס) – החרגת קריטריונים (למשל, ‎-movie). ‫( ) – קיבוץ של כמה מונחי חיפוש (למשל, 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

אופציונלי. הכללת טיוטות מתיקיית האשפה בתוצאות. ברירת המחדל היא False.

סכימת פלט

הודעת התגובה של RPC מסוג SearchThreads.

SearchThreadsResponse

ייצוג ב-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

כתובות אימייל של נמענים בשדה 'עותק'.
date

string

התאריך של ההודעה בפורמט ISO 8601‏ (YYYY-MM-DD).
plaintextBody

string

תוכן מלא של גוף ההודעה, מאוכלס רק אם MessageFormat היה FULL_CONTENT.
attachmentIds[]

string

פלט בלבד. מזהי הקבצים המצורפים, מאוכלסים רק אם MessageFormat היה FULL_CONTENT.

הערות על כלי

רמז הרסני: ❌ | רמז אידמפוטנטי: ✅ | רמז לקריאה בלבד: ✅ | רמז לעולם פתוח: ❌