MCP Tools Reference: chatmcp.googleapis.com

ابزار: search_messages

با استفاده از کلمات کلیدی و فیلترهایی که آنها را در قالب Markdown برمی‌گرداند، پیام‌های Google Chat را جستجو می‌کند. در تمام فضاهایی که کاربر به آنها دسترسی دارد یا می‌تواند به یک مکالمه خاص محدود شود، کار می‌کند.

هنگام تصمیم‌گیری برای استفاده search_messages در مقابل سایر ابزارهای جستجو یا خواندن، این راهنمایی را دنبال کنید:

  • هنگام جستجوی محتوای پیام خاص، کلمات کلیدی، موارد ذکر شده، پیوندها، فرستندگان یا پیام‌های خوانده نشده که احتمالاً در چندین فضا یا بدون شناسه مکالمه شناخته شده هستند، search_messages استفاده کنید.
  • وقتی شناسه‌ی فضا یا رشته‌ی خاص را می‌دانید و می‌خواهید پیام‌ها را به ترتیب زمانی بخوانید، list_messages استفاده کنید.
  • از search_conversations برای یافتن فراداده‌های فضایی مانند شناسه‌های مکالمه بر اساس نام نمایشی فضا یا شرکت‌کنندگان استفاده کنید (فقط فراداده‌ها را جستجو می‌کند، نه محتوای پیام را).

اگر searchParameters بدون فیلترهای خاص ارائه شود، پیام‌های اخیر در مکالمات قابل دسترسی برای کاربر بازگردانده می‌شوند.

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار search_messages MCP را نشان می‌دهد.

درخواست کرل 
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
}'

طرحواره ورودی

جستجوپیام‌هادرخواست

نمایش JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
فیلدها
searchParameters

object ( SearchParameters )

پارامترهای جستجو که برای جستجو استفاده می‌شوند.

pageSize

integer

اختیاری. حداکثر تعداد نتایجی که باید برگردانده شود (حداکثر تا ۱۰۰). اگر مشخص نشود، حداکثر ۲۵ نتیجه برگردانده می‌شود.

pageToken

string

اختیاری. یک توکن صفحه، که از فراخوانی قبلی search_messages دریافت شده است. این را برای بازیابی صفحه بعدی ارائه دهید.

پارامترهای جستجو

نمایش 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} می‌تواند شناسه شخص یا آدرس ایمیل او باشد.

isUnread

boolean

اختیاری. فیلتر برای پیام‌هایی که توسط کاربر تماس‌گیرنده خوانده نشده‌اند.

hasLink

boolean

اختیاری. فیلتر برای پیام‌هایی که حداقل شامل یک URL هستند.

startTime

string

اختیاری. فیلتر برای پیام‌های ایجاد شده پس از این زمان. قالب: مهر زمانی ISO 8601.

endTime

string

اختیاری. فیلتر برای پیام‌های ایجاد شده قبل از این زمان. قالب: مهر زمانی ISO 8601.

mentionsMe

boolean

اختیاری. فیلتر برای پیام‌هایی که صریحاً از کاربر تماس‌گیرنده نام می‌برند.

conversationIncludesUser

string

اختیاری. فیلتر کردن پیام‌ها در دایرکت‌ها و چت‌های گروهی که شامل ایمیل یا شناسه کاربری خاص هستند.

spaceDisplayNames[]

string

اختیاری. فیلتر بر اساس لیستی از نام‌های فضا؛ نام‌های نمایشی فضا تا حدی مطابقت دارند. توجه: فقط ۵ مورد برتر مطابقت داده می‌شوند.

طرحواره خروجی

پاسخ به جستجوی پیام‌های گوگل چت. اگر next_page_token پر شده باشد، می‌توان تابع SearchMessages را دوباره با آن توکن فراخوانی کرد تا صفحه بعدی نتایج بازیابی شود.

جستجوپیام‌هاپاسخ

نمایش JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
فیلدها
messages[]

object ( ChatMessage )

فهرست اشیاء پیام که با معیارهای جستجو مطابقت دارند.

nextPageToken

string

یک توکن که می‌تواند به عنوان page_token برای بازیابی صفحه بعدی ارسال شود. اگر این فیلد حذف شود، صفحات بعدی وجود نخواهند داشت.

چتپیام

نمایش JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ]
}
فیلدها
messageId

string

نام منبع پیام. قالب: فاصله‌ها/{فاصله}/پیام‌ها/{پیام}

threadId

string

رشته‌ای که این پیام به آن تعلق دارد. اگر پیام رشته‌بندی نشده باشد، این قسمت خالی خواهد بود. قالب: space/{space}/threads/{thread}

plaintextBody

string

متن اصلی پیام با استفاده از قالب‌بندی Markdown.

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

نام منبع یک کاربر چت. فرمت: users/{user}.

displayName

string

نام نمایشی کاربر چت.

email

string

آدرس ایمیل کاربر. این فیلد فقط زمانی پر می‌شود که نوع کاربر HUMAN باشد.

userType

enum ( UserType )

نوع کاربر.

فراداده پیوست چت

نمایش JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source)
}
فیلدها
attachmentId

string

نام منبع پیوست. قالب: space/{space}/messages/{message}/attachments/{attachment}.

filename

string

نام فایل پیوست.

mimeType

string

نوع محتوا (نوع MIME).

source

enum ( Source )

منبع پیوست.

خلاصه واکنش

نمایش JSON 
{
  "emoji": string,
  "count": integer
}
فیلدها
emoji

string

رشته یونیکد ایموجی یا نام ایموجی سفارشی.

count

integer

تعداد کل واکنش‌ها با استفاده از ایموجی مرتبط.

نوع کاربر

نوع کاربر گوگل چت.

انوم‌ها
USER_TYPE_UNSPECIFIED نامشخص.
HUMAN کاربر انسانی.
APP کاربر برنامه.

منبع

منبع پیوست.

انوم‌ها
SOURCE_UNSPECIFIED رزرو شده.
DRIVE_FILE فایل، فایل گوگل درایو است.
UPLOADED_CONTENT فایل در چت آپلود شد.

حاشیه‌نویسی ابزار

حاشیه‌نویسی‌های ابزار برای توصیف ریسک اولیه‌ی یک ابزار مشخص به کلاینت‌های MCP ارسال می‌شوند. اکثر کلاینت‌ها این نکات را غیرقابل اعتماد می‌دانند، اما می‌توان از آنها برای تصمیم‌گیری در مورد زمان ارسال پیام تأیید به کاربر استفاده کرد.

همراه با رشته عنوان، نکات بولی زیر به صورت زیر تعریف می‌شوند:

  • readOnlyHint : اگر درست باشد، ابزار محیط خود را تغییر نمی‌دهد. پیش‌فرض: نادرست.
  • destructiveHint : اگر درست باشد، ابزار می‌تواند اقدامات مخرب انجام دهد. اگر نادرست باشد، ابزار فقط می‌تواند اقدامات افزایشی انجام دهد. پیش‌فرض: درست.
  • idempotentHint : اگر مقدار آن درست باشد، فراخوانی مکرر ابزار با آرگومان‌های یکسان، هیچ تأثیر اضافی بر محیط آن نخواهد داشت. پیش‌فرض: false.
  • openWorldHint : اگر درست باشد، ابزار می‌تواند با «دنیای باز» از موجودیت‌های خارجی تعامل داشته باشد. اگر نادرست باشد، ابزار فقط می‌تواند با موجودیت‌های داخلی تعامل داشته باشد. برای مثال، یک ابزار جستجوی وب جهان‌باز خواهد بود، در حالی که یک ابزار حافظه جهان‌باز نخواهد بود.

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌

دامنه‌های مجوز

به یکی از حوزه‌های 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