MCP Tools Reference: chatmcp.googleapis.com

Strumento: search_conversations

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

Questo strumento cerca i metadati delle conversazioni, NON i contenuti dei messaggi. Per cercare nella 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 chiamante.

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 in base ai 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 l'utente chiamante è membro.

Questo strumento elenca solo le conversazioni di cui l'utente chiamante è membro.

Restituisce un elenco di oggetti di 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 altre pagine. Se ricevi un elenco vuoto, ma un next_page_token, chiedi all'utente se devi 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 di elementi. Se non viene 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 chiamata search_conversations precedente. Fornisci questo valore 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 di oggetti di conversazione che corrispondono ai criteri di ricerca. Ogni conversazione include conversation_id (formato: spaces/{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 è 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. Per gli spazi con nome, si tratta del nome dello spazio. Per i messaggi diretti 1:1, si tratta del nome dell'altro partecipante. Per le chat di gruppo senza nome, si tratta di un nome generato in base ai nomi dei membri.
conversationType

enum (ConversationType)

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

string (Timestamp format)

L'ora dell'ultima 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 dell'ora UTC dall'epoca di Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (che corrisponde a un intervallo compreso tra 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 dei secondi negativi con frazioni devono comunque avere valori di nanosecondi non negativi che avanzano 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 degli strumenti 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 un prompt di conferma a un utente.

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

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello 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 entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

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