MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: get_spreadsheet

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

با spreadsheets.get در REST API مطابقت دارد: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده‌ای که باید درخواست شود. - include_grid_data (بولی، اختیاری): اگر داده‌های جدول باید برگردانده شود، درست است. به‌طور پیش‌فرض روی نادرست تنظیم می‌شود. - fields (آرایه رشته‌ها، اختیاری): ماسک‌های فیلدی که مشخص می‌کنند کدام دارایی‌ها برگردانده شوند (برای نمونه ["sheets.properties.sheetId", "sheets.properties.title"]). - comments_included (بولی، اختیاری): اگر درست باشد، نظرات در پاسخ گنجانده خواهد شد. به‌طور پیش‌فرض روی نادرست تنظیم می‌شود. - ranges (آرایه رشته‌ها، اختیاری): محدوده‌های A1 یا R1C1 برای بازیابی از صفحه‌گسترده. اگر مشخص نشده باشد، کل صفحه‌گسترده برگردانده می‌شود.

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

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

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

GetContentRequest

نمایش JSON 
{
  "spreadsheetId": string,
  "includeGridData": boolean,
  "fields": [
    string
  ],
  "ranges": [
    string
  ],

  "commentsIncluded": boolean
}
فیلدها
spreadsheetId

string

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

boolean

اگر داده‌های جدول باید برگردانده شود، درست است.
fields[]

string

اختیاری. پوشش فیلد برای مشخص کردن اینکه کدام دارایی‌های «میانای برنامه‌سازی کاربردی کاربرگ‌نگار» برگردانده شود، برای اطلاعات بیشتر درباره نحوه استفاده از پوشش‌های فیلد، https://developers.google.com/workspace/sheets/api/guides/field-masks را ببینید. مهم: از مسیرهای سلسله‌مراتبی براساس ساختار JSON پاسخ «میانای برنامه‌سازی کاربردی Sheets» استفاده کنید. - برای مثال، برای دریافت عنوان و شناسه برگ، به‌جای «title,sheetId»، از «sheets.properties.sheetId» و «sheets.properties.title» استفاده کنید. - فقط فیلدهایی را که نیاز دارید اضافه کنید. - برای دریافت جدول‌ها، از «sheets.tables» یا «sheets.properties» استفاده کنید. - برای دریافت عنوان‌ها و شناسه‌های برگ، از این‌ها استفاده کنید: «sheets.properties.sheetId» و «sheets.properties.title».
ranges[]

string

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

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

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

boolean

اختیاری. اگر درست باشد، نظرات در پاسخ گنجانده خواهد شد. به‌طور پیش‌فرض، نظرات اضافه نمی‌شوند.

طرح‌واره برونداد

نشان‌دهنده شیء JSON است.

نقشه مقدار-کلید بدون ترتیب که هدف آن به‌طور کامل گرفتن معنای شیء JSON است. این کار باعث می‌شود هر پیام‌واره JSON دلخواهی به‌عنوان فیلد پیام در قالب ProtoJSON تجزیه شود.

این نوع از دستورالعمل‌های RFC 8259 برای JSON قابل‌تعامل پیروی می‌کند: به‌ویژه این نوع نمی‌تواند مقادیر بزرگ Int64 یا اعداد NaN/Infinity را نشان دهد، زیرا قالب JSON به‌طورکلی از این مقادیر در نوع عدد خود پشتیبانی نمی‌کند.

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

Struct

نمایش JSON 
{
  "fields": {
    string: value,
    ...
  }
}
فیلدها
fields

map (key: string, value: value (Value format))

نقشه نامرتب مقادیر با نوع پویا.

شیئی حاوی فهرستی از "key": value جفت. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

نمایش JSON 
{
  "key": string,
  "value": value
}
فیلدها
key

string
value

value (Value format)

مقدار

نمایش JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
فیلدها
فیلد اتحادیه kind. نوع مقدار. ‫kind فقط می‌تواند یکی از موارد زیر باشد:
nullValue

null

نشان‌دهنده null در JSON است.
numberValue

number

نشان‌دهنده عدد JSON است. نباید NaN، Infinity، یا -Infinity باشد، زیرا در JSON پشتیبانی نمی‌شوند. این همچنین نمی‌تواند مقادیر بزرگ Int64 را نشان دهد، زیرا قالب JSON به‌طورکلی از آن‌ها در نوع عدد خود پشتیبانی نمی‌کند.
stringValue

string

نشان‌دهنده رشته JSON است.
boolValue

boolean

نشان‌دهنده مقدار بولی JSON (حرفی true یا false در JSON).
structValue

object (Struct format)

نشان‌دهنده شیء JSON است.
listValue

array (ListValue format)

نشان‌دهنده آرایه JSON است.

ListValue

نمایش JSON 
{
  "values": [
    value
  ]
}
فیلدها
values[]

value (Value format)

فیلد تکراری مقادیر با نوع پویا.

NullValue

نشان‌دهنده null در JSON است.

‫NullValue نگهبان است و از شمارشی با فقط یک مقدار برای نشان دادن مقدار تهی برای اجتماع نوع Value استفاده می‌کند.

فیلدی از نوع NullValue با هر مقداری به‌جز 0 نامعتبر درنظر گرفته می‌شود. اکثر سریال‌سازهای ProtoJSON صرف‌نظر از مقدار عدد صحیح، Value را با null_value تنظیم‌شده به‌عنوان null در JSON منتشر می‌کنند و بنابراین به مقدار 0 تبدیل می‌شوند.

شمارشی‌ها
NULL_VALUE مقدار تهی.

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

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

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

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

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

دوربین تفنگ مجوز

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

  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/spreadsheets.readonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets