MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: insert_dimension

ردیف‌ها یا ستون‌ها را در یک برگ در یک نمایه خاص درج می‌کند.

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

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده برای به‌روزرسانی. - sheet_id (عدد صحیح، الزامی): شناسه برگه‌ای که باید درج شود. - dimension (رشته، الزامی): "ROWS" یا "COLUMNS". - start_index (عدد صحیح، الزامی): شاخص شروع درج با پایه ۰ (فراگیر). - end_index (عدد صحیح، الزامی): نمایه پایانی مبتنی بر ۰ درج (که در اجرا وارد نمی‌شود). - inherit_from_before (بولی، اختیاری): آیا ویژگی‌های بُعد باید از ابعاد قبل (true) یا بعد (false) گسترش یابد.

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

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

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

InsertDimensionRequest

نمایش JSON 
{
  "spreadsheetId": string,
  "sheetId": integer,
  "dimension": enum (Dimension),
  "startIndex": integer,
  "endIndex": integer,
  "inheritFromBefore": boolean
}
فیلدها
spreadsheetId

string

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

integer

الزامی. شناسه برگی که باید در آن درج شود.
dimension

enum (Dimension)

الزامی. بعدی که باید درج شود.
startIndex

integer

الزامی. نمایه شروع مبتنی بر ۰ درج (فراگیر).
endIndex

integer

الزامی. نمایه پایانی مبتنی بر ۰ درج (انحصاری).
inheritFromBefore

boolean

اینکه آیا ویژگی‌های بُعد باید از ابعاد قبل یا بعداز ابعاد جدید درج‌شده گسترش یابد. اگر درست باشد، از ابعاد قبلی ارث‌بری می‌کند (در این حالت، نمایه شروع باید بزرگ‌تر از ۰ باشد)، و اگر نادرست باشد، از ابعاد بعدی ارث‌بری می‌کند.

ابعاد

نشان می‌دهد که عملیات باید روی کدام بُعد اعمال شود.

شمارشی‌ها
DIMENSION_UNSPECIFIED مقدار پیش‌فرض، استفاده نکنید.
COLUMNS روی ستون‌های برگه عمل می‌کند.
ROWS روی ردیف‌های برگ کار می‌کند.

طرح خروجی

InsertDimensionResponse

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

object (Struct format)

پاسخ spreadsheets.batchUpdate، در قالب 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/spreadsheets