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

يمثّل هذا الحقل 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.

بنية

تمثيل 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 قيمة فارغة

مخطط النتائج

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

يمثّل هذا الحقل 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: إذا كانت القيمة صحيحة، لا تعدّل الأداة بيئتها. القيمة التلقائية: 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