MCP Tools Reference: chatmcp.googleapis.com

ツール: search_conversations

Google Chat の会話を検索して会話 ID を見つけます。名前付きスペースは表示名(space_name_query)で検索されます。ダイレクト メッセージ(DM)とグループ チャットは、参加者のメールアドレス(participants)でのみ検索されます。

このツールは、メッセージの内容ではなく、会話のメタデータを検索します。メッセージの履歴内を検索したり、キーワード、送信者、タイムスタンプでメッセージを検索したりするには、search_messages を使用します。

participants のみが指定されている場合、このツールは、指定された参加者と呼び出し元ユーザーを含む 1 対 1 のダイレクト メッセージ(1 人の参加者が指定されている場合)またはグループ チャット(複数の参加者が指定されている場合)を検索します。名前付きスペースは返されません。

space_name_query のみが指定されている場合、このツールは、クエリがスペースの表示名の大文字と小文字を区別しない部分文字列である名前付きスペースのみを検索します。DM とグループ チャットは返されないため、DM を検索するために space_name_query としてユーザーの名前を渡さないでください。代わりに、メールアドレスを検索して participants に渡してください。

participants と space_name_query の両方が指定されている場合、このツールは参加者別に DM またはグループ チャットを検索し、表示名でフィルタします。

participants と space_name_query のどちらも指定されていない場合、このツールは、呼び出し元ユーザーがメンバーになっている名前付きスペースを一覧表示します(DM とグループ チャットは含まれません)。

このツールには、呼び出し元のユーザーがメンバーになっている会話のみが一覧表示されます。

会話 ID(形式: spaces/{space})、表示名、会話タイプを含む会話オブジェクトのリストを返します。

重要: conversations リストが空の場合でも、全体として結果がこれ以上ないとは限りません。next_page_token が存在する場合は、さらにページを取得できます。リストが空で next_page_token が返された場合は、検索を続行するかどうかをユーザーに尋ねます。

次のコードサンプルは、curl を使用して search_conversations MCP ツールを呼び出す方法を示しています。

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

入力スキーマ

SearchConversationsRequest

JSON 表現
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
フィールド
spaceNameQuery

string

省略可。会話の表示名内で検索するテキスト(大文字と小文字を区別しない部分文字列一致)。

participants が空の場合、名前付きスペースのみが検索され、ダイレクト メッセージ(DM)とグループ チャットは返されません。そのため、ここでユーザーの名前を検索しても、そのユーザーとの DM は見つかりません。DM またはグループ チャットを検索するには、代わりに participants にメンバーのメールアドレスを指定します。participants が設定されている場合、このクエリは一致した DM またはグループ チャットを表示名でさらにフィルタします。

pageSize

integer

省略可。返されるスペースの最大数。サービスが返す値はこれよりも少ないことがあります。指定されていない場合は、最大で 20 個のスペースが返されます。最大値は 1,000 です。1,000 を超える値は 1,000 に強制変換されます。

pageToken

string

省略可。前回の search_conversations 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

participants[]

string

省略可。会話をフィルタする参加者のメールアドレスのリスト(発信者を除く)。このパラメータを使用して、ダイレクト メッセージ(DM)とグループ チャットを検索します。1 人の参加者を指定すると、そのユーザーとの 1 対 1 の DM が返され、複数の参加者を指定すると、それらのユーザー全員が含まれるグループ チャットが返されます。このフィールドが設定されている場合、名前付きスペースは返されません。

出力スキーマ

一致する会話のリストを含むレスポンス。

SearchConversationsResponse

JSON 表現
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
フィールド
conversations[]

object (Conversation)

検索条件に一致する会話オブジェクトのリスト。各会話には、conversation_id(形式: spaces/{space})、display_name、conversation_type、last_active_timestamp が含まれます。

nextPageToken

string

次のページを取得するために page_token として送信できるトークン。このフィールドを省略すると、後続のページはなくなります。

リクエストが participants でフィルタされている場合にのみ入力されます。

会話

JSON 表現
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
フィールド
conversationId

string

会話の ID(例: 「spaces/AAAAAAAAA」)。

displayName

string

会話の表示名。名前付きスペースの場合、これはスペース名です。1 対 1 のダイレクト メッセージの場合、これは相手の名前です。名前のないグループ チャットの場合、これはメンバーの名前に基づいて生成された名前です。

conversationType

enum (ConversationType)

会話の種類(DIRECT_MESSAGE、GROUP_CHAT、NAMED_SPACE)。

lastActiveTimestamp

string (Timestamp format)

会話が最後にアクティブだった日時(ISO 8601 形式)。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。

タイムスタンプ

JSON 表現
{
  "seconds": string,
  "nanos": integer
}
フィールド
seconds

string (int64 format)

UNIX エポック 1970-01-01T00:00:00Z からの UTC 時刻の秒数を表します。-62135596800~253402300799 の範囲(両端を含む)にする必要があります(これは 0001-01-01T00:00:00Z~9999-12-31T23:59:59Z に対応します)。

nanos

integer

ナノ秒分解能による、秒の負ではない小数以下部分。このフィールドは、秒の代替ではなく、期間のナノ秒部分です。小数以下を含む負の秒の値は、時間を前方にカウントする負ではない nanos 値を持つ必要があります。0~999,999,999 にする必要があります(両端を含む)。

ConversationType

会話の種類を定義します。

列挙型
CONVERSATION_TYPE_UNSPECIFIED 指定なし。
NAMED_SPACE 名前付きスペース。
GROUP_CHAT 3 人以上のユーザーによるグループ チャット。
DIRECT_MESSAGE 2 人のユーザー間、またはユーザーと Chat 用アプリ間のダイレクト メッセージ。

ツールのアノテーション

ツールのアノテーションは、特定のツールの基本的なリスクを説明するために MCP クライアントに送信されます。ほとんどのクライアントは、これらのヒントを信頼できないものとして扱いますが、確認プロンプトをユーザーに送信するタイミングを決定するために使用できます。

タイトル文字列とともに、次のブール値ヒントが定義されています。

  • readOnlyHint: true の場合、ツールは環境を変更しません。デフォルトは false です。
  • destructiveHint: true の場合、ツールは破壊的なアクションを実行できます。false の場合、ツールは追加アクションのみを実行できます。デフォルト値は true です。
  • idempotentHint: true の場合、同じ引数でツールを繰り返し呼び出しても、環境に副次的影響は発生しません。デフォルトは false です。
  • openWorldHint: true の場合、ツールは外部エンティティの「オープンワールド」とやり取りできます。false の場合、ツールは内部エンティティとのみやり取りできます。たとえば、ウェブ検索ツールはオープン ワールドですが、メモリツールはオープン ワールドではありません。

破壊的ヒント: ❌ | べき等ヒント: ✅ | 読み取り専用ヒント: ✅ | オープン ワールド ヒント: ❌

認可スコープ

次の OAuth スコープのいずれかが必要です。

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