MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: update_values

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

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

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده برای به‌روزرسانی. - range (رشته، الزامی): نماد A1 مقادیر برای به‌روزرسانی (مثلاً "Sheet1!A1:B2"). - values (آرایه آرایه‌ها، الزامی): آرایه دوبعدی مقادیر سلول. انواع مقدار پشتیبانی‌شده عبارت‌اند از: بولی، رشته، و عدد (اعشاری/ صحیح).

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

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

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

UpdateValuesRequest

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

string

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

string

الزامی. نماد A1 مقادیر برای به‌روزرسانی.
values[]

array (ListValue format)

الزامی. داده‌هایی که خوانده شده‌اند یا قرار است نوشته شوند. این آرایه‌ای از آرایه‌ها است، آرایه بیرونی نشان‌دهنده همه داده‌ها و هر آرایه درونی نشان‌دهنده یک ردیف است. هر مورد در آرایه داخلی با یک سلول مطابقت دارد. انواع مقدار پشتیبانی‌شده عبارت‌اند از: bool،‏ string، و double. مقادیر تهی رد خواهند شد. برای تنظیم سلول روی مقدار خالی، مقدار رشته را روی رشته خالی تنظیم کنید.

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

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

ساختار

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

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

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

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

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

طرح خروجی

UpdateValuesResponse

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

object (Struct format)

پاسخ spreadsheets.values.update، در قالب JSON از Sheets API، به‌علاوه فیلد status.

ساختار

نمایش 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
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets