MCP Tools Reference: chatmcp.googleapis.com

כלי: search_conversations

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

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

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

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

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

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

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

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

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

בדוגמת הקוד הבאה מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP‏ search_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 MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

SearchConversationsRequest

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

string

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

integer

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

string

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

string

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

סכימת הפלט

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

SearchConversationsResponse

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

object (Conversation)

רשימה של אובייקטים של שיחות שתואמים לקריטריונים של החיפוש. כל שיחה כוללת את conversation_id (בפורמט: spaces/{space}),‏ display_name,‏ conversation_type ו-last_active_timestamp.
nextPageToken

string

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

השדה הזה מאוכלס רק אם הבקשה מסוננת לפי participants.

שיחה

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

string

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

string

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

enum (ConversationType)

סוג השיחה (צ'אט אישי, צ'אט קבוצתי או מרחב משותף עם שם).
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, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

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

היקפי הרשאות

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

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