MCP Tools Reference: chatmcp.googleapis.com

כלי: search_conversations

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

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

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

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

אם גם participants וגם space_name_query צוינו, הכלי הזה מוצא צ'אטים אישיים או צ'אטים קבוצתיים לפי המשתתפים, ואז מסנן אותם לפי השם המוצג.

אם לא צוינו participants או space_name_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

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

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

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