MCP Tools Reference: drivemcp.googleapis.com

ابزار: search_files

جستجوی فایل‌های Drive بااستفاده از پُرسمان ساختاریافته (نحو: query_term operator values). ترکیب بندها با and، or، not، و پرانتز. مقادیر رشته‌ای باید در گیومه تکی قرار بگیرند؛ گیومه‌های جاسازی‌شده را به‌صورت \' گریز دهید.

عبارت‌ها و اپراتورهای پُرسمان:

  • ‫title (ops: contains, =, !=) — عنوان فایل
  • ‫fullText (ops: contains) — عنوان یا نوشتار اصلی
  • mimeType (ops: contains, =, !=) — MIME type
  • modifiedTime، viewedByMeTime، createdTime (عملیات: <=، <، =، !=، >، >=). از RFC 3339 UTC استفاده کنید، مثلاً 2012-06-04T12:00:00-08:00. انواع تاریخ قابل‌مقایسه نیستند.
  • parentId (ops: =, !=). Use 'root' for the user's "My Drive".
  • ‫owner (ops: =، !=). از 'me' برای کاربر درخواست‌کننده استفاده کنید.
  • ‫sharedWithMe (ops: =، !=). مقادیر: true یا false.

اپراتورهای دیگر: and، or، not.

مثال‌ها:

  • title contains 'hello' and title contains 'goodbye'
  • modifiedTime > '2024-01-01T00:00:00Z' and (mimeType contains 'image/' or mimeType contains 'video/')
  • parentId = '1234567'
  • fullText contains 'hello'
  • owner = 'test@example.org'
  • sharedWithMe = true
  • owner = 'me' (برای فایل‌هایی که کاربر مالک آن‌ها است)

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

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

درخواست Curl
curl --location 'https://drivemcp.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_files",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'
                

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

درخواست جستجوی فایل‌ها.

SearchFilesRequest

نمایش JSON
{
  "query": string,
  "pageToken": string,
  "pageSize": integer,
  "excludeContentSnippets": boolean
}
فیلدها
query

string

پرسمان جستجو.

فیلد اتحادیه _page_token.

_page_token فقط می‌تواند یکی از موارد زیر باشد:

pageToken

string

نشان صفحه برای استفاده در صفحه‌بندی.

فیلد اتحادیه _page_size.

_page_size فقط می‌تواند یکی از موارد زیر باشد:

pageSize

integer

حداکثر تعداد فایل‌ها برای برگرداندن در هر صفحه.

فیلد اتحادیه _exclude_content_snippets.

_exclude_content_snippets فقط می‌تواند یکی از موارد زیر باشد:

excludeContentSnippets

boolean

اگر درست باشد، گزیده محتوا از پاسخ حذف خواهد شد.

طرح برونداد

پاسخ به فایل‌های جستجو.

SearchFilesResponse

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

object (File)

فقط خروجی. فهرست فایل‌ها.

فیلد اتحادیه _next_page_token.

_next_page_token فقط می‌تواند یکی از موارد زیر باشد:

nextPageToken

string

کد صفحه بعدی.

فایل

نمایش JSON
{
  "id": string,
  "title": string,
  "parentId": string,
  "mimeType": string,
  "fileSize": string,
  "description": string,
  "fileExtension": string,
  "contentSnippet": string,
  "viewUrl": string,
  "sharedWithMeTime": string,
  "createdTime": string,
  "modifiedTime": string,
  "viewedByMeTime": string,
  "owner": string,
  "canAddChildren": boolean
}
فیلدها
id

string

شناسه فایلی که واکشی شده است.

title

string

عنوان فایل.

parentId

string

شناسه (اختیاری) والد فایل.

فیلد اتحادیه _mime_type.

_mime_type فقط می‌تواند یکی از موارد زیر باشد:

mimeType

string

نوع رسانه فایل.

فیلد اتحادیه _file_size.

_file_size فقط می‌تواند یکی از موارد زیر باشد:

fileSize

string (int64 format)

اندازه فایل برحسب بایت.

فیلد اتحادیه _description.

_description فقط می‌تواند یکی از موارد زیر باشد:

description

string

شرح فایل.

فیلد اتحادیه _file_extension.

_file_extension فقط می‌تواند یکی از موارد زیر باشد:

fileExtension

string

پسوند فایل اصلی فایل، این فقط برای فایل‌هایی با محتوای ذخیره‌شده در Drive پر می‌شود.

فیلد اتحادیه _content_snippet.

_content_snippet فقط می‌تواند یکی از موارد زیر باشد:

contentSnippet

string

گزیده تولیدشده درباره محتوای فایل.

فیلد اتحادیه _view_url.

_view_url فقط می‌تواند یکی از موارد زیر باشد:

viewUrl

string

نشانی وب برای مشاهده فایل.

فیلد اتحادیه _shared_with_me_time.

_shared_with_me_time فقط می‌تواند یکی از موارد زیر باشد:

sharedWithMeTime

string (Timestamp format)

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

از RFC 3339 استفاده می‌کند، که در آن برونداد تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «Z» نیز پذیرفته می‌شود. مثال‌ها: "2014-10-02T15:01:23Z"، "2014-10-02T15:01:23.045123456Z"، یا "2014-10-02T15:01:23+05:30".

فیلد اتحادیه _created_time.

_created_time فقط می‌تواند یکی از موارد زیر باشد:

createdTime

string (Timestamp format)

زمانی که فایل ایجاد شده است.

از RFC 3339 استفاده می‌کند، که در آن برونداد تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «Z» نیز پذیرفته می‌شود. مثال‌ها: "2014-10-02T15:01:23Z"، "2014-10-02T15:01:23.045123456Z"، یا "2014-10-02T15:01:23+05:30".

فیلد اتحادیه _modified_time.

_modified_time فقط می‌تواند یکی از موارد زیر باشد:

modifiedTime

string (Timestamp format)

آخرین زمانی که فایل اصلاح شده است.

از RFC 3339 استفاده می‌کند، که در آن برونداد تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «Z» نیز پذیرفته می‌شود. مثال‌ها: "2014-10-02T15:01:23Z"، "2014-10-02T15:01:23.045123456Z"، یا "2014-10-02T15:01:23+05:30".

فیلد اتحادیه _viewed_by_me_time.

_viewed_by_me_time فقط می‌تواند یکی از موارد زیر باشد:

viewedByMeTime

string (Timestamp format)

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

از RFC 3339 استفاده می‌کند، که در آن برونداد تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «Z» نیز پذیرفته می‌شود. مثال‌ها: "2014-10-02T15:01:23Z"، "2014-10-02T15:01:23.045123456Z"، یا "2014-10-02T15:01:23+05:30".

فیلد اتحادیه _owner.

_owner فقط می‌تواند یکی از موارد زیر باشد:

owner

string

نشانی ایمیل مالک فایل.

فیلد اتحادیه _can_add_children.

_can_add_children فقط می‌تواند یکی از موارد زیر باشد:

canAddChildren

boolean

آیا درخواست‌کننده می‌تواند فرزندان را به این پوشه اضافه کند. این مقدار برای انواع غیرپوشه همیشه نادرست است.

مُهر زمان

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

string (int64 format)

نشان‌دهنده ثانیه‌های ساعت هماهنگ جهانی از تاریخ یونیکس 1970-01-01T00:00:00Z است. باید بین ‎-۶۲۱۳۵۵۹۶۸۰۰ و ۲۵۳۴۰۲۳۰۰۷۹۹ باشد (که با 0001-01-01T00:00:00Z تا 9999-12-31T23:59:59Z مطابقت دارد).

nanos

integer

کسرهای غیرمنفی ثانیه با وضوح نانوثانیه. این فیلد بخش نانوثانیه مدت است، نه جایگزینی برای ثانیه. مقادیر منفی ثانیه با کسرها باید همچنان مقادیر نانو غیرمنفی داشته باشند که در زمان به جلو شمارش می‌شوند. باید بین ۰ و ۹۹۹٬۹۹۹٬۹۹۹ باشد.

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

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

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

به یکی از دامنه‌های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.meet.readonly
  • https://www.googleapis.com/auth/drive.metadata
  • https://www.googleapis.com/auth/drive.metadata.readonly
  • https://www.googleapis.com/auth/drive.photos.readonly
  • https://www.googleapis.com/auth/drive.readonly