MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: get_values

محدوده مقادیر را از صفحه‌گسترده برمی‌گرداند.

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

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده‌ای که باید داده‌ها از آن بازیابی شود. - range (رشته، الزامی): نماد A1 یا نماد R1C1 محدوده برای بازیابی مقادیر از آن (برای نمونه "Sheet1!A1:B10").

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار get_values 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_values",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

GetValuesRequest

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

string

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

string

الزامی. نشانه‌گذاری A1 یا نشانه‌گذاری R1C1 گستره‌ای که مقادیر از آن بازیابی می‌شود.

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

داده‌های درون محدوده صفحه‌گسترده. https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values

ValueRange

نمایش JSON 
{
  "range": string,
  "values": [
    array
  ]
}
فیلدها
range

string

محدوده مقادیر، در نمانام A1.
values[]

array (ListValue format)

داده‌هایی که خوانده شده است. این آرایه‌ای از آرایه‌ها است، آرایه بیرونی نشان‌دهنده همه داده‌ها و هر آرایه درونی نشان‌دهنده یک ردیف است. هر عنصر در آرایه داخلی با یک سلول مطابقت دارد. ردیف‌ها و ستون‌های خالی انتهایی اضافه نخواهند شد.

ListValue

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

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 است.

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)

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