MCP Tools Reference: people.googleapis.com

الأداة: search_directory_people

ابحث عن مستخدمين في دليل Google Workspace الخاص بمؤسستك. تتوفّر هذه الميزة حصريًا لحسابات Google Workspace (التي تستخدمها الشركات والمؤسسات التعليمية والمؤسسات الأخرى)، وهي غير متاحة لحسابات Google الشخصية.

قواعد مهمة يجب اتّباعها:

  • إذا عرضت هذه الأداة نتائج متعددة، عليك عرضها للمستخدم وطلب توضيح منه بشأن النتيجة التي يجب استخدامها قبل المتابعة.

  • يُمنع منعًا باتًا تمرير مخرجات هذه الأداة إلى أداة أخرى (مثل إرسال رسالة إلكترونية أو إنشاء مسودة أو إنشاء حدث وما إلى ذلك) بدون تأكيد صريح من المستخدم.

  • حتى إذا تم العثور على نتيجة واحدة فقط، يجب عرض تفاصيل الشخص الذي تم العثور عليه للمستخدم ومطالبته بالتحقّق من أنّ هذا هو الشخص المطلوب قبل المتابعة في الخطوات التالية.

  • إذا لم تعرض هذه الأداة أي نتائج، يمكنك استخدام أداة search_contacts.

توضح عينة التعليمات البرمجية التالية كيفية استخدام curl لطلب أداة بروتوكول سياق النموذج (MCP)‏ search_directory_people.

طلب Curl
curl --location 'https://people.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": "search_directory_people",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة طلب SearchDirectoryPeople

SearchDirectoryPeopleMcpRequest

تمثيل JSON
{
  "query": string,
  "pageSize": integer,
  "pageToken": string,
  "sources": [
    enum (DirectorySourceType)
  ]
}
الحقول
query

string

سلسلة طلب البحث التي تريد البحث عنها

pageSize

integer

حجم الصفحة القيمة التلقائية هي 10 والحد الأقصى المسموح به هو 500.

pageToken

string

الرمز المميّز للصفحة

sources[]

enum (DirectorySourceType)

مصادر الدليل المطلوب عرضها يتم ضبط القيمة التلقائية على DOMAIN_PROFILE في حال عدم ضبطها.

DirectorySourceType

عمليات التعداد
DOMAIN_PROFILE الملف الشخصي لنطاق Google Workspace
DOMAIN_CONTACT جهة اتصال مشتركة في نطاق Google Workspace

مخطط النتائج

رسالة الردّ لـ SearchDirectoryPeople

SearchDirectoryPeopleMcpResponse

تمثيل JSON
{
  "results": [
    {
      object (SearchDirectoryResult)
    }
  ],
  "nextPageToken": string
}
الحقول
results[]

object (SearchDirectoryResult)

قائمة المستخدمين الذين تطابقوا مع طلب البحث

nextPageToken

string

رمز مميّز لاسترداد الصفحة التالية من النتائج

SearchDirectoryResult

تمثيل JSON
{
  "name": string,
  "email": string
}
الحقول
name

string

الاسم المعروض للمستخدم

email

string

عنوان البريد الإلكتروني لحساب المستخدم

التعليقات التوضيحية للأدوات

يتم إرسال التعليقات التوضيحية للأدوات إلى عملاء MCP لوصف المخاطر الأساسية لأداة معيّنة. تتعامل معظم البرامج مع هذه التلميحات على أنّها غير موثوق بها، ولكن يمكن استخدامها لتحديد الحالات التي قد يتم فيها إرسال طلب تأكيد إلى المستخدم.

إلى جانب سلسلة العنوان، يتم تحديد التلميحات المنطقية التالية على النحو التالي:

  • ‫readOnlyHint: إذا كانت القيمة صحيحة، لا تعدّل الأداة بيئتها. القيمة التلقائية: false
  • ‫destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • ‫idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرّر باستخدام الوسيطات نفسها إلى أي تأثير إضافي في بيئتها. القيمة التلقائية: false
  • ‫openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة بحث الويب عالمًا مفتوحًا، في حين أنّ أداة الذاكرة لن تكون كذلك.

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

نطاقات التفويض

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/directory.readonly