MCP Tools Reference: chatmcp.googleapis.com

כלי: search_messages

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

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

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

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

בדוגמת הקוד הבאה מוצג שימוש בפקודה curl כדי להפעיל את הכלי search_messages MCP.

בקשת 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)
  ]
}
שדות
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)

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

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)
    }
  ]
}
שדות
messageId

string

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

string

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

string

גוף ההודעה בפורמט Markdown.
sender

object (User)

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

string

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

boolean

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

object (ChatAttachmentMetadata)

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

object (ReactionSummary)

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

משתמש

ייצוג 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)
}
שדות
attachmentId

string

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

string

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

string

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

enum (Source)

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

ReactionSummary

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

string

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

integer

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

UserType

הסוג של משתמש Google Chat.

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

מקור

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

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

הערות על כלים

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

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

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

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

היקפי הרשאות

נדרשת אחת מההרשאות הבאות של 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