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 (بولی، اختیاری): اگر داده‌های جدولی باید برگردانده شود، True. پیش‌فرض: نادرست. - fields (آرایه رشته‌ها، اختیاری): ماسک‌های فیلد که مشخص می‌کنند کدام ویژگی‌ها برگردانده شوند (مثلاً ["sheets.properties.sheetId", "sheets.properties.title"]). - comments_included (بولی، اختیاری): اگر درست باشد، نظرات در پاسخ گنجانده خواهند شد. پیش‌فرض: نادرست. - ranges (آرایه رشته‌ها، اختیاری): گستره‌های A1 یا R1C1 برای بازیابی از صفحه‌گسترده. اگر مشخص نشده باشد، کل صفحه‌گسترده برگردانده می‌شود.

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

درخواست 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

اختیاری. ماسک فیلدی برای مشخص کردن اینکه کدام ویژگی‌ها به Spreadsheets API برگردانده شود، برای اطلاعات بیشتر درباره نحوه استفاده از ماسک‌های فیلد، https://developers.google.com/workspace/sheets/api/guides/field-masks را ببینید. مهم: از مسیرهای سلسله‌مراتبی براساس ساختار JSON پاسخ Sheets API استفاده کنید. - برای مثال، برای دریافت عنوان و شناسه برگه، به‌جای «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

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

طرح خروجی

GetContentResponse

نمایش JSON 
{
  "content": {
    object
  }
}
فیلدها
content

object (Struct format)

صفحه‌گسترده، در قالب JSON منبع Sheets API Spreadsheet.

ساختار

نمایش 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

نشان‌دهنده JSON null است.
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

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

NullValue یک نگهبان است که از یک enum با تنها یک مقدار برای نمایش مقدار null برای اتحاد نوع Value استفاده می‌کند.

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

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

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

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

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

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

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

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

به یکی از دامنه‌های 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