MCP Tools Reference: chatmcp.googleapis.com

도구: search_messages

키워드와 필터를 사용하여 Google Chat 메시지를 검색하고 마크다운 형식으로 반환합니다. 사용자가 액세스할 수 있는 모든 스페이스에서 작동하거나 특정 대화로 범위를 지정할 수 있습니다.

search_messages를 사용할지 다른 검색 또는 읽기 도구를 사용할지 결정할 때는 다음 안내를 따르세요.

  • 여러 스페이스에 걸쳐 있거나 알려진 대화 ID가 없는 특정 메시지 콘텐츠, 키워드, 멘션, 링크, 발신자 또는 읽지 않은 메일을 찾을 때는 search_messages를 사용합니다.
  • 특정 스페이스 또는 대화목록 ID를 알고 있고 메시지를 시간순으로 순차적으로 읽으려면 list_messages를 사용합니다.
  • search_conversations를 사용하여 스페이스 표시 이름 또는 참여자로 대화 ID와 같은 스페이스 메타데이터를 찾습니다 (메타데이터만 검색하고 메시지 콘텐츠는 검색하지 않음).

특정 필터 없이 searchParameters가 제공되면 사용자에게 액세스 권한이 있는 대화의 최근 메시지가 반환됩니다.

다음 코드 샘플은 curl를 사용하여 search_messages 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_messages",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

SearchMessagesRequest

JSON 표현 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
필드
searchParameters

object (SearchParameters)

필수 항목입니다. 검색에 사용할 검색 매개변수입니다.
pageSize

integer

선택사항입니다. 반환할 최대 결과 수입니다 (최대 100개). 지정하지 않으면 최대 25개가 반환됩니다.
pageToken

string

선택사항입니다. 이전 search_messages 호출에서 받은 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.

SearchParameters

JSON 표현 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ]
}
필드
keywords[]

string

선택사항입니다. 결과를 필터링하는 데 사용되는 키워드 집합입니다.
conversationId

string

선택사항입니다. search_conversations 도구에서 반환된 특정 대화 식별자로 검색 범위를 지정합니다. 형식은 spaces/{ID}입니다.
sender

string

선택사항입니다. 특정 사용자의 메일을 필터링합니다. 발신자의 이메일 또는 리소스 이름을 사용할 수 있습니다. 사용자 리소스 이름은 users/{ID} 형식으로 지정되며, 여기서 {ID}은 개인 ID 또는 이메일 주소일 수 있습니다.
isUnread

boolean

선택사항입니다. 호출 사용자가 읽지 않은 메일을 필터링합니다.
hasLink

boolean

선택사항입니다. URL이 하나 이상 포함된 메시지를 필터링합니다.
startTime

string

선택사항입니다. 이 시간 이후에 생성된 메일을 필터링합니다. 형식: ISO 8601 타임스탬프입니다.
endTime

string

선택사항입니다. 이 시간 이전에 생성된 메일을 필터링합니다. 형식: ISO 8601 타임스탬프입니다.
mentionsMe

boolean

선택사항입니다. 호출 사용자를 명시적으로 언급하는 메시지를 필터링합니다.
conversationIncludesUser

string

선택사항입니다. 특정 사용자 이메일 또는 ID가 포함된 채팅 메시지 및 그룹 채팅의 메시지를 필터링합니다.
spaceDisplayNames[]

string

선택사항입니다. 스페이스 이름 목록으로 필터링합니다. 스페이스 표시 이름은 부분적으로 일치합니다. 참고: 상위 5개 일치 항목만 반환됩니다.

출력 스키마

Google Chat 메시지 검색에 대한 응답입니다. next_page_token이 채워진 경우 해당 토큰으로 SearchMessages를 다시 호출하여 결과의 다음 페이지를 검색할 수 있습니다.

SearchMessagesResponse

JSON 표현 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
필드
messages[]

object (ChatMessage)

검색 기준과 일치하는 메시지 객체 목록입니다.
nextPageToken

string

다음 페이지를 검색하기 위해 page_token으로 전송할 수 있는 토큰입니다. 이 필드를 생략하면 후속 페이지가 표시되지 않습니다.

ChatMessage

JSON 표현 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ]
}
필드
messageId

string

메시지의 리소스 이름입니다. 형식: spaces/{space}/messages/{message}
threadId

string

이 메시지가 속한 대화목록입니다. 메시지가 스레드되지 않은 경우 비어 있습니다. 형식: spaces/{space}/threads/{thread}
plaintextBody

string

마크다운 서식을 사용하는 메시지의 텍스트 본문입니다.
sender

object (User)

메시지 발신자입니다.
createTime

string

출력 전용입니다. 메시지가 생성된 타임스탬프입니다.
threadedReply

boolean

메일이 대화목록 답장인지 여부입니다.
attachments[]

object (ChatAttachmentMetadata)

메일에 포함된 첨부파일입니다.
reactionSummaries[]

object (ReactionSummary)

메일에 포함된 그림 이모티콘 반응 요약입니다.

사용자

JSON 표현 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
필드
userId

string

Chat 사용자의 리소스 이름입니다. ConvenienceFee: 0.00
displayName

string

Chat 사용자의 표시 이름입니다.
email

string

사용자의 이메일 주소입니다. 이 필드는 사용자 유형이 HUMAN인 경우에만 채워집니다.
userType

enum (UserType)

사용자 유형입니다.

ChatAttachmentMetadata

JSON 표현 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source)
}
필드
attachmentId

string

첨부파일의 리소스 이름입니다. 형식: spaces/{space}/messages/{message}/attachments/{attachment}
filename

string

첨부파일의 이름입니다.
mimeType

string

콘텐츠 유형 (MIME 유형)입니다.
source

enum (Source)

첨부파일의 소스입니다.

ReactionSummary

JSON 표현 
{
  "emoji": string,
  "count": integer
}
필드
emoji

string

그림 이모티콘 유니코드 문자열 또는 맞춤 그림 이모티콘 이름입니다.
count

integer

연결된 이모티콘을 사용한 반응의 총수입니다.

UserType

Google Chat 사용자의 유형입니다.

열거형
USER_TYPE_UNSPECIFIED 지정되지 않음.
HUMAN 실제 사용자
APP 앱 사용자

소스

첨부파일의 소스입니다.

열거형
SOURCE_UNSPECIFIED 예약됨
DRIVE_FILE 파일이 Google Drive 파일입니다.
UPLOADED_CONTENT 파일이 Chat에 업로드됩니다.

도구 주석

도구 주석은 특정 도구의 기본 위험을 설명하기 위해 MCP 클라이언트로 전송됩니다. 대부분의 클라이언트는 이러한 힌트를 신뢰할 수 없는 것으로 취급하지만, 사용자에게 확인 메시지를 전송할 시점을 결정하는 데 사용할 수 있습니다.

제목 문자열과 함께 다음 불리언 힌트가 다음과 같이 정의됩니다.

  • readOnlyHint: true인 경우 도구가 환경을 수정하지 않습니다. 기본값: false.
  • destructiveHint: true인 경우 도구가 파괴적인 작업을 실행할 수 있습니다. false인 경우 도구는 추가 작업만 실행할 수 있습니다. 기본값은 true입니다.
  • idempotentHint: true인 경우 동일한 인수로 도구를 반복적으로 호출해도 환경에 추가적인 영향을 미치지 않습니다. 기본값: false.
  • openWorldHint: true인 경우 도구가 외부 엔티티의 '오픈 월드'와 상호작용할 수 있습니다. false인 경우 도구는 내부 항목과만 상호작용할 수 있습니다. 예를 들어 웹 검색 도구는 오픈 월드이지만 메모리 도구는 오픈 월드가 아닙니다.

파괴적 힌트: ❌ | 멱등성 힌트: ✅ | 읽기 전용 힌트: ✅ | 오픈 월드 힌트: ❌

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

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