MCP Tools Reference: chatmcp.googleapis.com

Narzędzie: search_messages

Wyszukuje wiadomości na czacie w Google Chat za pomocą słów kluczowych i filtrów, zwracając je w formacie Markdown. Działa we wszystkich pokojach, do których użytkownik ma dostęp, lub może być ograniczony do konkretnej rozmowy.

Podejmując decyzję o użyciu search_messages zamiast innych narzędzi do wyszukiwania lub czytania, postępuj zgodnie z tymi wskazówkami:

  • Używaj search_messages, gdy szukasz konkretnych treści wiadomości, słów kluczowych, wzmianek, linków, nadawców lub nieprzeczytanych wiadomości, potencjalnie w wielu pokojach lub bez znanego identyfikatora rozmowy.
  • Użyj list_messages, gdy znasz identyfikator konkretnego pokoju lub wątku i chcesz czytać wiadomości po kolei w porządku chronologicznym.
  • Użyj search_conversations, aby znaleźć metadane pokoju, takie jak identyfikatory rozmów, według wyświetlanej nazwy pokoju lub uczestników (wyszukiwane są tylko metadane, a nie treść wiadomości).

Jeśli parametr searchParameters zostanie podany bez konkretnych filtrów, zwracane są ostatnie wiadomości z rozmów dostępnych dla użytkownika.

Poniższy przykładowy kod pokazuje, jak używać curl do wywoływania narzędzia MCP search_messages.

Żądanie 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
}'

Schemat wejściowy

SearchMessagesRequest

Zapis JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Pola
searchParameters

object (SearchParameters)

Wymagane. Parametry wyszukiwania, których chcesz użyć.
pageSize

integer

Opcjonalnie: Maksymalna liczba wyników do zwrócenia (maksymalnie 100). Jeśli nie podano tego argumentu, zwracanych jest maksymalnie 25 wyników.
pageToken

string

Opcjonalnie: Token strony otrzymany z poprzedniego wywołania search_messages. Podaj go, aby pobrać kolejną stronę.

SearchParameters

Zapis 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
}
Pola
keywords[]

string

Opcjonalnie: Zestaw słów kluczowych, które służą do filtrowania wyników.
conversationId

string

Opcjonalnie: Ogranicza wyszukiwanie do konkretnego identyfikatora rozmowy zwróconego przez narzędzie search_conversations. Format: spaces/{ID}.
sender

string

Opcjonalnie: Filtrowanie wiadomości od określonego użytkownika. Można użyć adresu e-mail lub nazwy zasobu nadawcy. Nazwy zasobów użytkowników mają format users/{ID}, gdzie {ID} może być identyfikatorem osoby lub jej adresem e-mail.
isUnread

boolean

Opcjonalnie: Filtruj wiadomości, które nie zostały przeczytane przez użytkownika wywołującego.
hasLink

boolean

Opcjonalnie: Filtruj wiadomości zawierające co najmniej 1 adres URL.
startTime

string

Opcjonalnie: Filtruj wiadomości utworzone po tym czasie. Format: sygnatura czasowa ISO 8601.
endTime

string

Opcjonalnie: Filtruj wiadomości utworzone przed tym czasem. Format: sygnatura czasowa ISO 8601.
mentionsMe

boolean

Opcjonalnie: Filtruj wiadomości, które wyraźnie wspominają o użytkowniku wywołującym.
conversationIncludesUser

string

Opcjonalnie: Filtruj wiadomości na czatach i czatach grupowych, które zawierają adres e-mail lub identyfikator konkretnego użytkownika.
spaceDisplayNames[]

string

Opcjonalnie: Filtruj według listy nazw pokoi. Wyświetlane nazwy pokoi są częściowo dopasowywane. Uwaga: zwracanych jest tylko 5 najlepszych dopasowań.
conversationTypes[]

enum (ConversationType)

Opcjonalnie: Filtruj według typu rozmowy.
hasAttachment

boolean

Opcjonalnie: Filtruj wiadomości zawierające co najmniej 1 załącznik. Uwaga: to pole jest w trakcie opracowywania i może nie być jeszcze obsługiwane we wszystkich środowiskach.

ConversationType

Określa typ rozmowy.

Wartości w polu enum
CONVERSATION_TYPE_UNSPECIFIED Nie określono.
NAMED_SPACE pokój z nazwą,
GROUP_CHAT czat grupowy z co najmniej 3 osobami;
DIRECT_MESSAGE czat między 2 osobami lub osobą i aplikacją Google Chat;

Schemat wyjściowy

Odpowiedź na wyszukiwanie wiadomości na czacie w Google Chat. Jeśli parametr next_page_token jest wypełniony, można ponownie wywołać SearchMessages z tym tokenem, aby pobrać następną stronę wyników.

SearchMessagesResponse

Zapis JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Pola
messages[]

object (ChatMessage)

Lista obiektów wiadomości, które spełniają kryteria wyszukiwania.
nextPageToken

string

Token, który można wysłać jako page_token, aby pobrać następną stronę. Jeśli pominiesz to pole, nie będzie kolejnych stron.

ChatMessage

Zapis JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Pola
messageId

string

Nazwa zasobu wiadomości. Format: spaces/{space}/messages/{message}
threadId

string

Wątek, do którego należy ta wiadomość. Jeśli wiadomość nie jest częścią wątku, to pole będzie puste. Format: spaces/{space}/threads/{thread}
plaintextBody

string

Treść wiadomości w formacie Markdown.
sender

object (User)

Nadawca wiadomości.
createTime

string

Tylko dane wyjściowe. Sygnatura czasowa utworzenia wiadomości. Format: sygnatura czasowa ISO 8601.
threadedReply

boolean

Określa, czy wiadomość jest odpowiedzią w wątku.
attachments[]

object (ChatAttachmentMetadata)

Załączniki dołączone do wiadomości.
reactionSummaries[]

object (ReactionSummary)

Podsumowanie reakcji emotikonami zawarte w wiadomości.
quotedMessageMetadata

object (QuotedMessageMetadata)

Tylko dane wyjściowe. Informacje o oryginalnej wiadomości, która jest cytowana lub przekazywana w tej wiadomości. Uwaga: to pole jest w trakcie opracowywania i może nie być jeszcze dostępne we wszystkich środowiskach.

Użytkownik

Zapis JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Pola
userId

string

Nazwa zasobu użytkownika Google Chat. Format: users/{user}.
displayName

string

Wyświetlana nazwa użytkownika Google Chat.
email

string

Adres e-mail użytkownika. To pole jest wypełniane tylko wtedy, gdy typ użytkownika to HUMAN.
userType

enum (UserType)

Typ użytkownika.

ChatAttachmentMetadata

Zapis JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Pola
attachmentId

string

Nazwa zasobu załącznika. Format: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nazwa załącznika.
mimeType

string

Typ treści (typ MIME).
source

enum (Source)

Źródło załącznika.
driveFileId

string

Tylko dane wyjściowe. Identyfikator pliku na Dysku Google. Wypełniane tylko wtedy, gdy źródłem jest DRIVE_FILE. Używaj z MCP Dysku Google.

ReactionSummary

Zapis JSON 
{
  "emoji": string,
  "count": integer
}
Pola
emoji

string

Ciąg znaków unicode emotikona lub nazwa niestandardowego emotikona.
count

integer

Łączna liczba reakcji z użyciem powiązanego emotikona.

QuotedMessageMetadata

Zapis JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Pola
messageId

string

Tylko dane wyjściowe. Nazwa zasobu oryginalnej wiadomości, która jest cytowana lub przekazywana dalej. Format: spaces/{space}/messages/{message}
lastUpdateTime

string

Tylko dane wyjściowe. Sygnatura czasowa określająca, kiedy oryginalna wiadomość została utworzona lub ostatnio zaktualizowana przed jej zacytowaniem lub przekazaniem dalej. Format: sygnatura czasowa ISO 8601.
quoteType

enum (QuoteType)

Tylko dane wyjściowe. Typ cytatu.
plaintextBody

string

Tylko dane wyjściowe. Zrzut treści oryginalnej wiadomości w momencie cytowania lub przekazywania. Sformatowane za pomocą Markdown w przypadku FORWARD i zwykłego tekstu w przypadku REPLY.
sender

string

Tylko dane wyjściowe. Wyświetlana nazwa autora oryginalnej wiadomości.
attachments[]

object (ChatAttachmentMetadata)

Tylko dane wyjściowe. załączniki, które były częścią oryginalnej wiadomości; Wartość podawana tylko w przypadku typu wyceny FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Tylko dane wyjściowe. Metadane dotyczące rozmowy źródłowej przekazanej wiadomości. Wartość podawana tylko w przypadku typu wyceny FORWARD.

ForwardedMetadata

Zapis JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Pola
conversationId

string

Tylko dane wyjściowe. Nazwa zasobu rozmowy źródłowej. Format: spaces/{space}
conversationDisplayName

string

Tylko dane wyjściowe. Wyświetlana nazwa rozmowy źródłowej w momencie przekazania wiadomości. W przypadku nazwanych pokoi jest to nazwa pokoju. W przypadku czatów indywidualnych jest to nazwa drugiego uczestnika. W przypadku czatów grupowych bez nazwy jest to nazwa wygenerowana na podstawie nazw użytkowników.

UserType

Typ użytkownika Google Chat.

Wartości w polu enum
USER_TYPE_UNSPECIFIED Nie określono.
HUMAN Użytkownik.
APP Użytkownik aplikacji.

Źródło

Źródło załącznika.

Wartości w polu enum
SOURCE_UNSPECIFIED Zarezerwowane.
DRIVE_FILE Plik jest plikiem z Dysku Google.
UPLOADED_CONTENT Plik zostanie przesłany do Google Chat.

QuoteType

Typ cytatu wskazujący, czy wiadomość jest odpowiedzią z cytatem czy przekazaną wiadomością.

Wartości w polu enum
QUOTE_TYPE_UNSPECIFIED Zarezerwowane. Niezdefiniowany typ cytatu.
REPLY Wiadomość jest odpowiedzią z cytatem na oryginalną wiadomość w tym samym wątku.
FORWARD Wiadomość została przekazana z oryginalnej wiadomości w innej rozmowie lub z innego wątku w tej samej rozmowie.

Adnotacje dotyczące narzędzi

Adnotacje narzędzi są wysyłane do klientów MCP, aby opisać podstawowe ryzyko związane z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich użyć do określenia, kiedy wysłać użytkownikowi prośbę o potwierdzenie.

Oprócz ciągu tytułu zdefiniowane są te wskazówki logiczne:

  • readOnlyHint: jeśli ma wartość „true”, narzędzie nie modyfikuje swojego środowiska. Wartość domyślna: false.
  • destructiveHint: jeśli ma wartość „true”, narzędzie może wykonywać działania destrukcyjne. Jeśli ma wartość false, narzędzie może wykonywać tylko działania dodawania. Wartość domyślna: true.
  • idempotentHint: jeśli ma wartość „true”, wielokrotne wywoływanie narzędzia z tymi samymi argumentami nie będzie miało dodatkowego wpływu na jego środowisko. Wartość domyślna: false.
  • openWorldHint: jeśli ma wartość true, narzędzie może wchodzić w interakcje z „otwartym światem” elementów zewnętrznych. Jeśli ma wartość false, narzędzie może wchodzić w interakcje tylko z encjami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie jest narzędziem typu Otwarty świat, ale narzędzie do zapamiętywania już nie.

Wskazówka dotycząca niszczenia: ❌ | Wskazówka dotycząca idempotencji: ✅ | Wskazówka dotycząca tylko do odczytu: ✅ | Wskazówka dotycząca otwartego świata: ❌

Zakresy autoryzacji

Wymaga jednego z tych zakresów 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