MCP Tools Reference: chatmcp.googleapis.com

כלי: search_messages

חיפוש הודעות ב-Google Chat באמצעות מילות מפתח ומסננים, והחזרת התוצאות בפורמט Markdown. הוא יכול לעבוד בכל המרחבים שלמשתמש יש גישה אליהם, או רק בשיחה ספציפית.

כדאי לפעול לפי ההנחיות הבאות כשמחליטים אם להשתמש ב-search_messages או בכלים אחרים לחיפוש או לקריאה:

  • כדאי להשתמש ב-search_messages כשמחפשים תוכן ספציפי בהודעות, מילות מפתח, תיוגים, קישורים, שולחים או הודעות שלא נקראו, במיוחד אם מחפשים בכמה מרחבים או אם לא יודעים מה מזהה השיחה.
  • כדאי להשתמש ב-list_messages כשאתם יודעים את המזהה הספציפי של המרחב או השרשור ואתם רוצים לקרוא את ההודעות ברצף לפי סדר כרונולוגי.
  • אפשר להשתמש ב-search_conversations כדי למצוא מטא-נתונים של מרחבים, כמו מזהי שיחות, לפי שם התצוגה של המרחב או המשתתפים (החיפוש מתבצע רק במטא-נתונים, לא בתוכן ההודעות).

אם מספקים את searchParameters בלי מסננים ספציפיים, מוחזרות הודעות אחרונות מכל השיחות שהמשתמש יכול לגשת אליהן.

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

בקשת 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_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

SearchMessagesRequest

ייצוג ב-JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
שדות
searchParameters

object (SearchParameters)

חובה. הפרמטרים לחיפוש.
pageSize

integer

אופציונלי. המספר המקסימלי של תוצאות שיוחזרו (עד 100). אם לא מציינים ערך, יוחזרו עד 25 פריטים.
pageToken

string

אופציונלי. טוקן של דף שהתקבל מקריאה קודמת של search_messages. צריך להזין את הטוקן כדי לאחזר את הדף הבא.

SearchParameters

ייצוג ב-JSON 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
שדות
keywords[]

string

אופציונלי. קבוצה של מילות מפתח שמשמשות לסינון התוצאות.
conversationId

string

אופציונלי. מגדיר את היקף החיפוש למזהה שיחה ספציפי, כמו זה שמוחזר מהכלי search_conversations. פורמט: spaces/{ID}
sender

string

אופציונלי. סינון הודעות ממשתמש ספציפי. אפשר להשתמש בכתובת האימייל או בשם המשאב של השולח. שמות המשאבים של המשתמשים הם בפורמט users/{ID}, כאשר {ID} יכול להיות מזהה של אדם או כתובת האימייל שלו.
isUnread

boolean

אופציונלי. סינון הודעות שהמשתמש ששלח את הבקשה לא קרא.
hasLink

boolean

אופציונלי. סינון הודעות שמכילות לפחות כתובת URL אחת.
startTime

string

אופציונלי. סינון הודעות שנוצרו אחרי השעה הזו. פורמט: חותמת זמן לפי תקן ISO 8601.
endTime

string

אופציונלי. סינון הודעות שנוצרו לפני הזמן הזה. פורמט: חותמת זמן לפי תקן ISO 8601.
mentionsMe

boolean

אופציונלי. סינון הודעות שבהן המשתמש שביצע את הקריאה מתויג באופן מפורש.
conversationIncludesUser

string

אופציונלי. אפשר לסנן הודעות בצ'אטים אישיים ובצ'אטים קבוצתיים שכוללות את כתובת האימייל או המזהה של המשתמש הספציפי.
spaceDisplayNames[]

string

אופציונלי. סינון לפי רשימה של שמות מרחבים. השמות המוצגים של המרחבים תואמים חלקית. הערה: המערכת מחזירה רק את 5 ההתאמות המובילות.
conversationTypes[]

enum (ConversationType)

אופציונלי. לסנן לפי סוג השיחה.
hasAttachment

boolean

אופציונלי. סינון הודעות שמכילות לפחות קובץ מצורף אחד. הערה: השדה הזה נמצא בפיתוח ויכול להיות שהוא עדיין לא נתמך בכל הסביבות.

ConversationType

מגדיר את סוג השיחה.

טיפוסים בני מנייה (enum)
CONVERSATION_TYPE_UNSPECIFIED לא צוין.
NAMED_SPACE מרחב משותף עם שם.
GROUP_CHAT צ'אט קבוצתי עם 3 אנשים או יותר.
DIRECT_MESSAGE צ'אט אישי בין שני אנשים, או בין אדם לאפליקציה ל-Chat.

סכימת הפלט

תשובה לחיפוש הודעות צ'אט ב-Google Chat. אם next_page_token מאוכלס, אפשר לקרוא שוב ל-SearchMessages עם הטוקן הזה כדי לאחזר את דף התוצאות הבא.

SearchMessagesResponse

ייצוג ב-JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
שדות
messages[]

object (ChatMessage)

רשימה של אובייקטים של הודעות שתואמים לקריטריונים של החיפוש.
nextPageToken

string

טוקן שאפשר לשלוח כ-page_token כדי לאחזר את הדף הבא. אם משמיטים את השדה הזה, לא יופיעו דפים נוספים.

ChatMessage

ייצוג ב-JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
שדות
messageId

string

שם המשאב של ההודעה. פורמט: spaces/{space}/messages/{message}
threadId

string

השרשור שההודעה הזו שייכת אליו. השדה הזה יהיה ריק אם ההודעה לא בשרשור. פורמט: spaces/{space}/threads/{thread}
plaintextBody

string

גוף הטקסט של ההודעה בפורמט Markdown.
sender

object (User)

השולח של ההודעה.
createTime

string

פלט בלבד. חותמת הזמן של מועד יצירת ההודעה. פורמט: חותמת זמן לפי תקן ISO 8601.
threadedReply

boolean

אם ההודעה היא תשובה בשרשור.
attachments[]

object (ChatAttachmentMetadata)

קבצים מצורפים שכלולים בהודעה.
reactionSummaries[]

object (ReactionSummary)

סיכום התגובות באמוג'י שכלולות בהודעה.
quotedMessageMetadata

object (QuotedMessageMetadata)

פלט בלבד. מידע על הודעה מקורית שצוטטה או הועברה בהודעה הזו. הערה: השדה הזה נמצא בפיתוח ויכול להיות שהוא עדיין לא מופיע בכל הסביבות.

משתמש

ייצוג ב-JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
שדות
userId

string

שם המשאב של המשתמש ב-Chat. פורמט: users/{user}.
displayName

string

השם המוצג של המשתמש ב-Chat.
email

string

כתובת האימייל של המשתמש. השדה הזה מאוכלס רק כשסוג המשתמש הוא HUMAN.
userType

enum (UserType)

סוג המשתמש.

ChatAttachmentMetadata

ייצוג ב-JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
שדות
attachmentId

string

שם המשאב של הקובץ המצורף. פורמט: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

שם הקובץ המצורף.
mimeType

string

סוג התוכן (סוג MIME).
source

enum (Source)

המקור של הקובץ המצורף.
driveFileId

string

פלט בלבד. המזהה של הקובץ ב-Google Drive. מאוכלס רק כשהמקור הוא DRIVE_FILE. אפשר להשתמש בה עם ה-MCP של Google Drive.

ReactionSummary

ייצוג ב-JSON 
{
  "emoji": string,
  "count": integer
}
שדות
emoji

string

מחרוזת ה-Unicode של האמוג'י או השם של האמוג'י בהתאמה אישית.
count

integer

המספר הכולל של התגובות באמצעות האמוג'י המשויך.

QuotedMessageMetadata

ייצוג ב-JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
שדות
messageId

string

פלט בלבד. שם המשאב של ההודעה המקורית שצוטטה או הועברה. פורמט: spaces/{space}/messages/{message}
lastUpdateTime

string

פלט בלבד. חותמת הזמן של מועד היצירה או העדכון האחרון של ההודעה המקורית, לפני שהיא צוטטה או הועברה. פורמט: חותמת זמן לפי תקן ISO 8601.
quoteType

enum (QuoteType)

פלט בלבד. סוג הציטוט.
plaintextBody

string

פלט בלבד. תמונת מצב של גוף הטקסט של ההודעה המקורית בזמן הציטוט או ההעברה. מעוצב באמצעות Markdown עבור FORWARD, וטקסט פשוט עבור REPLY.
sender

string

פלט בלבד. השם המוצג של מחבר ההודעה המקורית.
attachments[]

object (ChatAttachmentMetadata)

פלט בלבד. קבצים מצורפים שהיו חלק מההודעה המקורית. השדה הזה מאוכלס רק בסוג הצעת המחיר FORWARD.
forwardedMetadata

object (ForwardedMetadata)

פלט בלבד. מטא-נתונים על השיחה שממנה הועברה ההודעה. השדה הזה מאוכלס רק בסוג הצעת המחיר FORWARD.

ForwardedMetadata

ייצוג ב-JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
שדות
conversationId

string

פלט בלבד. שם המשאב של השיחה המקורית. פורמט: spaces/{space}
conversationDisplayName

string

פלט בלבד. השם המוצג של השיחה המקורית בזמן שההודעה הועברה. במרחבים משותפים עם שם, זה השם של המרחב. בצ'אטים אישיים, זה השם של המשתתף השני. בצ'אטים קבוצתיים ללא שם, השם נוצר על סמך שמות המשתתפים.

UserType

סוג המשתמש ב-Google Chat.

טיפוסים בני מנייה (enum)
USER_TYPE_UNSPECIFIED לא צוין.
HUMAN משתמש אנושי.
APP משתמש באפליקציה.

מקור

המקור של הקובץ המצורף.

טיפוסים בני מנייה (enum)
SOURCE_UNSPECIFIED שמורות.
DRIVE_FILE הקובץ הוא קובץ ב-Google Drive.
UPLOADED_CONTENT הקובץ יועלה ל-Chat.

QuoteType

סוג הציטוט, שמציין אם ההודעה היא תשובה עם ציטוט או הודעה שהועברה.

טיפוסים בני מנייה (enum)
QUOTE_TYPE_UNSPECIFIED שמורות. סוג הציטוט לא מוגדר.
REPLY ההודעה היא תשובה עם ציטוט להודעה מקורית באותו שרשור.
FORWARD ההודעה הועברה מהודעה מקורית בשיחה אחרת, או משרשור אחר באותה שיחה.

הערות לגבי הכלים

הערות הכלים נשלחות ללקוחות MCP כדי לתאר את הסיכון הבסיסי של כלי מסוים. רוב הלקוחות מתייחסים לרמזים האלה כלא מהימנים, אבל אפשר להשתמש בהם כדי להחליט מתי לשלוח למשתמש בקשה לאישור.

בנוסף למחרוזת הכותרת, הרמזים הבוליאניים הבאים מוגדרים כך:

  • ‫readOnlyHint: אם הערך הוא True, הכלי לא משנה את הסביבה שלו. ברירת המחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא False, הכלי יכול לבצע רק פעולות הוספה. ברירת המחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת המחדל: false.
  • ‫openWorldHint: אם הערך הוא True, הכלי יכול לקיים אינטראקציה עם "עולם פתוח" של ישויות חיצוניות. אם הערך הוא false, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly