MCP Tools Reference: chatmcp.googleapis.com

כלי: search_conversations

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

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

אם מספקים רק את participants, הכלי הזה מוצא שיחות ישירות אחד על אחד (אם מספקים משתתף אחד) או צ'אטים קבוצתיים (אם מספקים כמה משתתפים) שכוללים את המשתתפים שצוינו ואת המשתמש שמתקשר.

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

אם מספקים את שני השמות participants ו-query, הכלי הזה מוצא שיחות לפי המשתתפים ואז מסנן אותן לפי השם המוצג.

אם לא מספקים את participants או את query, הכלי הזה מציג רשימה של כל השיחות שהמשתמש המתקשר הוא חבר בהן.

בכלי הזה מופיעות רק שיחות שהמשתמש המתקשר הוא חלק מהן.

מחזירה רשימה של אובייקטים של שיחות שמכילים מזהי שיחות (פורמט: spaces/{space}), שמות לתצוגה וסוגי שיחות.

חשוב: רשימה ריקה של conversations לא אומרת שאין עוד תוצאות באופן כללי. אם הערך next_page_token קיים, אפשר לאחזר עוד דפים. אם מקבלים רשימה ריקה אבל next_page_token, שואלים את המשתמש אם להמשיך בחיפוש.

Aware.curlsearch_conversations

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

סכימת הקלט

SearchConversationsRequest

ייצוג ב-JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
שדות
spaceNameQuery

string

אופציונלי. הטקסט לחיפוש בשמות המוצגים של המרחבים (התאמה של מחרוזת משנה שלא תלויה באותיות רישיות).
pageSize

integer

אופציונלי. המספר המקסימלי של מרחבים שיוחזרו. יכול להיות שהשירות יחזיר פחות מהערך הזה. Aware API יחזיר לכל היותר 20 מקומות אם לא מציינים ערך. הערך המקסימלי הוא 1,000. ערכים גבוהים יותר יומרו ל-1,000.
pageToken

string

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

string

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

סכימת הפלט

תשובה שמכילה את רשימת השיחות שתואמות לחיפוש.

SearchConversationsResponse

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

object (Conversation)

רשימה של אובייקטים של שיחות שתואמים לקריטריוני החיפוש. כל שיחה כוללת את מזהה השיחה (בפורמט: spaces/{space}), שם התצוגה, סוג השיחה וחותמת הזמן של הפעילות האחרונה.
nextPageToken

string

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

שיחה

ייצוג ב-JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
שדות
conversationId

string

המזהה של השיחה (למשל, spaces/AAAAAAAAA).
displayName

string

השם המוצג של השיחה.
conversationType

enum (ConversationType)

סוג השיחה (DIRECT_MESSAGE,‏ GROUP_CHAT או NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

השעה האחרונה שבה הייתה פעילות בשיחה בפורמט ISO 8601.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

חותמת זמן

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

string (int64 format)

מייצג את השניות של זמן UTC מאז ראשית זמן יוניקס (Unix epoch) ב-1970-01-01T00:00:00Z. הערך חייב להיות בין ‎-62135596800 ל-‎253402300799, כולל (שמתאים לטווח 0001-01-01T00:00:00Z עד 9999-12-31T23:59:59Z).
nanos

integer

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

ConversationType

הגדרה של סוג השיחה.

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

הערות על כלים

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

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

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

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

היקפי הרשאות

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

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