MCP Tools Reference: chatmcp.googleapis.com

Narzędzie: search_conversations

Wyszukuje rozmowy w Google Chat, aby znaleźć ich identyfikatory. Nazwane pokoje są wyszukiwane według wyświetlanej nazwy (space_name_query). Czaty i czaty grupowe są wyszukiwane tylko według adresów e-mail uczestników (participants).

To narzędzie przeszukuje metadane rozmowy, a NIE treść wiadomości. Aby przeszukać historię wiadomości lub znaleźć wiadomości według słowa kluczowego, nadawcy lub sygnatury czasowej, użyj search_messages.

Jeśli podano tylko parametr participants, to narzędzie znajduje czaty indywidualne (jeśli podano jednego uczestnika) lub czaty grupowe (jeśli podano wielu uczestników), które obejmują określonych uczestników i użytkownika wywołującego. Pokoje z nazwą nie są zwracane.

Jeśli podasz tylko space_name_query, to narzędzie wyszuka TYLKO nazwane pokoje, w których zapytanie jest podłańcuchem wyświetlanej nazwy pokoju (wielkość liter nie jest rozróżniana). Czaty i czaty grupowe nigdy nie są zwracane, więc NIE przekazuj imienia i nazwiska osoby jako space_name_query, aby znaleźć czat z nią. Zamiast tego wyszukaj jej adres e-mail i przekaż go w participants.

Jeśli podano zarówno participants, jak i space_name_query, to narzędzie wyszukuje czaty 1:1 lub czaty grupowe według uczestników, a następnie filtruje je według wyświetlanej nazwy.

Jeśli nie podano ani participants, ani space_name_query, to narzędzie wyświetla listę nazwanych pokoi, do których należy wywołujący użytkownik (czaty prywatne i czaty grupowe nie są uwzględniane).

To narzędzie wyświetla tylko rozmowy, których uczestnikiem jest dzwoniący użytkownik.

Zwraca listę obiektów rozmów zawierających identyfikatory rozmów (format: spaces/{space}), wyświetlane nazwy i typy rozmów.

WAŻNE: pusta lista conversations nie oznacza, że nie ma już żadnych wyników. Jeśli obecny jest parametr next_page_token, można pobrać więcej stron. Jeśli lista jest pusta, ale next_page_token, zapytaj użytkownika, czy kontynuować wyszukiwanie.

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

Żą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_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat wejściowy

SearchConversationsRequest

Zapis JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Pola
spaceNameQuery

string

Opcjonalnie: Tekst do wyszukania w wyświetlanych nazwach rozmów (dopasowanie podłańcucha, wielkość liter nie jest rozróżniana).

Jeśli parametr participants jest pusty, wyszukiwane są tylko pokoje z nazwą, a czaty i czaty grupowe nie są zwracane, więc wyszukiwanie imienia i nazwiska osoby nie spowoduje znalezienia czatu z nią. Aby znaleźć czat lub czat grupowy, podaj adresy e-mail uczestników w polu participants. Jeśli ustawiono parametr participants, to zapytanie dodatkowo filtruje dopasowane czaty 1:1 lub czaty grupowe według wyświetlanej nazwy.
pageSize

integer

Opcjonalnie: Maksymalna liczba pokoi do zwrócenia. Usługa może zwrócić mniej niż ta wartość. Jeśli nie zostanie określona, zwróconych zostanie maksymalnie 20 pokoi. Maksymalna wartość to 1000. Wartości powyżej 1000 zostaną zmienione na 1000.
pageToken

string

Opcjonalnie: Token strony otrzymany z poprzedniego wywołania search_conversations. Podaj tę wartość, aby pobrać kolejną stronę.
participants[]

string

Opcjonalnie: Lista adresów e-mail uczestników, według których mają być filtrowane rozmowy, z wyłączeniem rozmówcy. Użyj tej opcji, aby znaleźć czaty i czaty grupowe: pojedynczy uczestnik zwraca czat 1:1 z tą osobą, a wielu uczestników zwraca czaty grupowe, które ich obejmują. Gdy to pole jest ustawione, pokoje nazwane nie są zwracane.

Schemat wyjściowy

Odpowiedź zawierająca listę pasujących rozmów.

SearchConversationsResponse

Zapis JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Pola
conversations[]

object (Conversation)

Lista obiektów rozmowy, które spełniają kryteria wyszukiwania. Każda rozmowa zawiera conversation_id (format: spaces/{space}), display_name, conversation_type i last_active_timestamp.
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.

Wartość jest podawana tylko wtedy, gdy żądanie jest filtrowane według participants.

Rozmowa

Zapis JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Pola
conversationId

string

Identyfikator rozmowy (np. „spaces/AAAAAAAAA”).
displayName

string

Wyświetlana nazwa rozmowy. W przypadku nazwanych pokoi jest to nazwa pokoju. W przypadku wiadomości prywatnych jest to nazwa drugiego uczestnika. W przypadku czatów grupowych bez nazwy jest to nazwa wygenerowana na podstawie nazw użytkowników.
conversationType

enum (ConversationType)

Typ rozmowy (DIRECT_MESSAGE, GROUP_CHAT lub NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Czas ostatniej aktywności w rozmowie w formacie ISO 8601.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

Sygnatura czasowa

Zapis JSON 
{
  "seconds": string,
  "nanos": integer
}
Pola
seconds

string (int64 format)

Reprezentuje sekundy czasu UTC od epoki uniksowej 1970-01-01T00:00:00Z. Musi mieścić się w zakresie od -62135596800 do 253402300799 włącznie (co odpowiada zakresowi od 0001-01-01T00:00:00Z do 9999-12-31T23:59:59Z).
nanos

integer

Nieujemne ułamki sekundy w rozdzielczości nanosekundowej. To pole zawiera nanosekundową część czasu trwania, a nie alternatywę dla sekund. Ujemne wartości sekund z ułamkami muszą mieć nieujemne wartości nanosekund, które są liczone do przodu. Musi mieścić się w zakresie od 0 do 999 999 999 włącznie.

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.

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” podmiotów zewnętrznych. Jeśli ma wartość false, narzędzie może wchodzić w interakcje tylko z elementami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie jest narzędziem typu Otwarty świat, a narzędzie do zapamiętywania – 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.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly