MCP Tools Reference: chatmcp.googleapis.com

Strumento: search_conversations

Cerca conversazioni di Google Chat (spazi denominati, messaggi diretti o chat di gruppo) in base al nome visualizzato o ai partecipanti per trovare gli ID conversazione.

Questo strumento esegue ricerche nei metadati delle conversazioni, NON nei contenuti dei messaggi. Per cercare all'interno della cronologia dei messaggi o trovare messaggi per parola chiave/mittente/timestamp, utilizza search_messages.

Se vengono forniti solo participants, questo strumento trova i messaggi diretti 1:1 (se viene fornito un partecipante) o le chat di gruppo (se vengono forniti più partecipanti) che includono i partecipanti specificati e l'utente che chiama.

Se viene fornito solo un query, questo strumento cerca le conversazioni in cui la query è una sottostringa senza distinzione tra maiuscole e minuscole del nome visualizzato della conversazione.

Se vengono forniti sia participants sia query, questo strumento trova le conversazioni per partecipanti e poi le filtra in base al nome visualizzato.

Se non vengono forniti né participants né query, questo strumento elenca tutte le conversazioni di cui fa parte l'utente chiamante.

Questo strumento elenca solo le conversazioni di cui fa parte l'utente che chiama.

Restituisce un elenco di oggetti conversazione contenenti ID conversazione (formato: spaces/{space}), nomi visualizzati e tipi di conversazione.

IMPORTANTE: un elenco conversations vuoto non significa che non ci siano più risultati in generale. Se è presente next_page_token, è possibile recuperare più pagine. Se visualizzi un elenco vuoto ma un next_page_token, chiedi all'utente se vuoi continuare la ricerca.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP search_conversations.

Richiesta 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
}'

Schema di input

SearchConversationsRequest

Rappresentazione JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Campi
spaceNameQuery

string

Facoltativo. Il testo da cercare nei nomi visualizzati degli spazi (corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole).
pageSize

integer

Facoltativo. Il numero massimo di spazi da restituire. Il servizio potrebbe restituire un numero inferiore a questo valore. Se non specificato, verranno restituiti al massimo 20 spazi. Il valore massimo è 1000; i valori superiori a 1000 verranno forzati a 1000.
pageToken

string

Facoltativo. Un token di pagina ricevuto da una precedente chiamata search_conversations. Forniscilo per recuperare la pagina successiva.
participants[]

string

Facoltativo. Elenco degli indirizzi email dei partecipanti per filtrare le conversazioni, escluso il chiamante.

Schema di output

Risposta contenente l'elenco delle conversazioni corrispondenti.

SearchConversationsResponse

Rappresentazione JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Campi
conversations[]

object (Conversation)

Elenco degli oggetti conversazione che corrispondono ai criteri di ricerca. Ogni conversazione include conversation_id (formato: spazi/{space}), display_name, conversation_type e last_active_timestamp.
nextPageToken

string

Un token che può essere inviato come page_token per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

Compilato solo se la richiesta viene filtrata in base a participants.

Conversazione

Rappresentazione JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Campi
conversationId

string

L'ID della conversazione (ad es. "spaces/AAAAAAAAA").
displayName

string

Il nome visualizzato della conversazione.
conversationType

enum (ConversationType)

Il tipo di conversazione (DIRECT_MESSAGE, GROUP_CHAT o NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

L'ultima ora di attività della conversazione nel formato ISO 8601.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

Timestamp

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Rappresenta i secondi di tempo UTC dall'epoca di Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (corrispondenti a 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z).
nanos

integer

Frazioni di secondo non negative con risoluzione in nanosecondi. Questo campo è la parte in nanosecondi della durata, non un'alternativa ai secondi. I valori negativi dei secondi con frazioni devono comunque avere valori di nanosecondi non negativi che vengono conteggiati in avanti nel tempo. Deve essere compreso tra 0 e 999.999.999 inclusi.

ConversationType

Definisce il tipo di conversazione.

Enum
CONVERSATION_TYPE_UNSPECIFIED Non specificato.
NAMED_SPACE Uno spazio con nome.
GROUP_CHAT Una chat di gruppo tra 3 o più persone.
DIRECT_MESSAGE Un messaggio diretto tra due persone o tra una persona e un'app di chat.

Annotazioni dello strumento

Le annotazioni dello strumento vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti non attendibili, ma possono essere utilizzati per decidere quando inviare a un utente una richiesta di conferma.

Oltre alla stringa del titolo, sono definiti i seguenti suggerimenti booleani:

  • readOnlyHint: se è true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se è true, lo strumento può eseguire azioni distruttive. Se il valore è false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se è true, chiamare ripetutamente lo strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se è true, lo strumento può interagire con un "open world" di entità esterne. Se è false, lo strumento può interagire solo con le entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria no.

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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