MCP Tools Reference: chatmcp.googleapis.com

Araç: search_conversations

Görüşme kimliklerini bulmak için Google Chat görüşmelerini arar. Adlandırılmış alanlar, görünen ada (space_name_query) göre bulunur. Doğrudan mesajlar (DM'ler) ve grup sohbetleri yalnızca katılımcı e-posta adreslerine (participants) göre bulunur.

Bu araç, mesaj içeriklerini DEĞİL, görüşme meta verilerini arar. Mesaj geçmişinde arama yapmak veya anahtar kelimeye/gönderene/zaman damgasına göre mesaj bulmak için search_messages kullanın.

Yalnızca participants sağlanırsa bu araç, belirtilen katılımcıları ve arayan kullanıcıyı içeren bire bir doğrudan mesajları (bir katılımcı sağlanırsa) veya grup sohbetlerini (birden fazla katılımcı sağlanırsa) bulur. Adlandırılmış alanlar döndürülmez.

Yalnızca space_name_query sağlanırsa bu araç, sorgunun alanın görünen adının büyük/küçük harfe duyarlı olmayan bir alt dizesi olduğu YALNIZCA adlandırılmış alanları arar. DM'ler ve grup sohbetleri hiçbir zaman döndürülmez. Bu nedenle, bir kişiyle DM bulmak için kişinin adını space_name_query olarak iletmeyin. Bunun yerine, kişinin e-posta adresini arayın ve participants olarak iletin.

Hem participants hem de space_name_query sağlanırsa bu araç, katılımcılara göre DM'leri veya grup sohbetlerini bulur ve ardından bunları görünen ada göre filtreler.

participants veya space_name_query sağlanmazsa bu araç, arayan kullanıcının üyesi olduğu adlandırılmış alanları listeler (DM'ler ve grup sohbetleri dahil değildir).

Bu araç yalnızca arayan kullanıcının üyesi olduğu görüşmeleri listeler.

Görüşme kimliklerini (biçim: spaces/{space}), görünen adları ve görüşme türlerini içeren görüşme nesnelerinin listesini döndürür.

ÖNEMLİ: conversations listesinin boş olması, genel olarak başka sonuç olmadığı anlamına gelmez. next_page_token varsa daha fazla sayfa getirilebilir. Boş bir liste alırsanız ancak next_page_token varsa kullanıcıya aramaya devam edip etmeyeceğinizi sorun.

Aşağıdaki kod örneğinde, search_conversations MCP aracını çağırmak için curl öğesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği 
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
}'

Giriş şeması

SearchConversationsRequest

JSON gösterimi 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Alanlar
spaceNameQuery

string

İsteğe bağlıdır. Görüşme görünen adlarında aranacak metin (büyük/küçük harfe duyarlı olmayan alt dize eşleşmesi).

participants boşsa yalnızca adlandırılmış alanlar aranır ve doğrudan mesajlar (DM'ler) ile grup sohbetleri hiçbir zaman döndürülmez. Bu nedenle, burada bir kişinin adını aradığınızda o kişiyle olan DM'ler bulunmaz. DM veya grup sohbeti bulmak için participants alanına üyelerin e-posta adreslerini girin. participants ayarlanırsa bu sorgu, eşleşen DM'leri veya grup sohbetlerini görünen ada göre daha ayrıntılı bir şekilde filtreler.
pageSize

integer

İsteğe bağlıdır. Döndürülecek maksimum alan sayısı. Hizmet, bu değerden daha az sonuç döndürebilir. Belirtilmezse en fazla 20 alan döndürülür. Maksimum değer 1.000'dir. 1.000'in üzerindeki değerler 1.000'e zorlanır.
pageToken

string

İsteğe bağlıdır. Önceki bir search_conversations çağrısından alınan sayfa jetonu. Sonraki sayfayı almak için bu değeri sağlayın.
participants[]

string

İsteğe bağlıdır. Görüşmeleri filtrelemek için katılımcıların e-posta adreslerinin listesi (arayan hariç). Doğrudan mesajları (DM'ler) ve grup sohbetlerini bulmak için bu yöntemi kullanın: Tek bir katılımcı, o kişiyle olan bire bir DM'yi döndürür ve birden fazla katılımcı, hepsini içeren grup sohbetlerini döndürür. Bu alan ayarlandığında adlandırılmış alanlar döndürülmez.

Çıkış şeması

Eşleşen görüşmelerin listesini içeren yanıt.

SearchConversationsResponse

JSON gösterimi 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Alanlar
conversations[]

object (Conversation)

Arama ölçütleriyle eşleşen görüşme nesnelerinin listesi. Her görüşme; conversation_id (biçim: spaces/{space}), display_name, conversation_type ve last_active_timestamp bilgilerini içerir.
nextPageToken

string

Sonraki sayfayı almak için page_token olarak gönderilebilecek bir jeton. Bu alan atlanırsa sonraki sayfa yoktur.

Yalnızca istek participants ile filtrelenirse doldurulur.

Sohbet

JSON gösterimi 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Alanlar
conversationId

string

Görüşmenin kimliği (ör. "spaces/AAAAAAAAA").
displayName

string

Görüşmenin görünen adı. Adlandırılmış alanlar için bu, alan adıdır. Bire bir doğrudan mesajlarda bu, diğer katılımcının adıdır. Adsız grup sohbetleri için bu, üyelerin adlarına göre oluşturulan bir addır.
conversationType

enum (ConversationType)

Görüşme türü (DIRECT_MESSAGE, GROUP_CHAT veya NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Görüşmenin son etkin olduğu zaman (ISO 8601 biçiminde).

Zaman damgasında RFC 3339 kullanılır. Yani oluşturulan çıkış her zaman Z ile normalleştirilir ve 0, 3, 6 veya 9 kesirli basamak kullanılır. "Z" dışındaki zaman farkları da kabul edilir. Örnekler: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" veya "2014-10-02T15:01:23+05:30".

Zaman damgası

JSON gösterimi 
{
  "seconds": string,
  "nanos": integer
}
Alanlar
seconds

string (int64 format)

Unix epoch 1970-01-01T00:00:00Z'den bu yana geçen UTC zamanının saniye cinsinden değerini temsil eder. -62135596800 ile 253402300799 (başlangıç ve bitiş değerleri dahil) arasında olmalıdır (0001-01-01T00:00:00Z ile 9999-12-31T23:59:59Z aralığına karşılık gelir).
nanos

integer

Nanosaniye çözünürlüğünde, saniyenin negatif olmayan kesirleri. Bu alan, sürenin nanosaniye kısmıdır, saniyeye alternatif değildir. Kesirli negatif saniye değerleri, zamanı ileriye doğru sayan negatif olmayan nanos değerlerine sahip olmalıdır. 0 ile 999.999.999 (her iki değer de dahil) arasında olmalıdır.

ConversationType

Görüşmenin türünü tanımlar.

Sıralamalar
CONVERSATION_TYPE_UNSPECIFIED Belirtilmedi.
NAMED_SPACE Adlandırılmış bir alan.
GROUP_CHAT 3 veya daha fazla kişi arasında yapılan grup sohbeti.
DIRECT_MESSAGE İki kişi veya bir kişi ile bir Chat uygulaması arasındaki doğrudan mesaj.

Araç Notları

Araç ek açıklamaları, belirli bir aracın temel riskini açıklamak için MCP istemcilerine gönderilir. Çoğu istemci bu ipuçlarını güvenilir olarak değerlendirmez ancak kullanıcıya ne zaman onay istemi gönderileceğine karar vermek için kullanılabilir.

Başlık dizesiyle birlikte aşağıdaki boole ipuçları şu şekilde tanımlanır:

  • readOnlyHint: Doğru ise araç, ortamını değiştirmez. Varsayılan: false.
  • destructiveHint: Doğru ise araç, yıkıcı işlemler gerçekleştirebilir. Yanlış ise araç yalnızca ekleme işlemleri gerçekleştirebilir. Varsayılan: true.
  • idempotentHint: Doğru ise aracın aynı bağımsız değişkenlerle tekrar tekrar çağrılması, ortamı üzerinde ek bir etki yaratmaz. Varsayılan: false.
  • openWorldHint: Doğru ise araç, harici varlıkların "açık dünyası" ile etkileşim kurabilir. Yanlış ise araç yalnızca dahili varlıklarla etkileşim kurabilir. Örneğin, web arama aracı açık dünya olurken bellek aracı açık dünya olmaz.

Yıkıcı İpucu: ❌ | Idempotent İpucu: ✅ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌

Yetkilendirme Kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

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