MCP Tools Reference: mapstools.googleapis.com

الأداة: resolve_names

تحوّل هذه الأداة قائمة مجمّعة من طلبات البحث عن مواقع جغرافية معيّنة (أسماء معالم أو عناوين دقيقة) إلى أرقام تعريف أماكن أساسية في "خرائط Google".

متطلبات الإدخال (مهمة):

  1. queries (مصفوفة من العناصر - إلزامية): قائمة بطلبات البحث عن المواقع الجغرافية التي يجب حلّها. يمكنك تحديد ما يصل إلى 20 طلب بحث.

    • يجب أن يتضمّن كل عنصر طلب بحث ما يلي:
      • ‫text (سلسلة - إلزامية): طلب البحث النصي الذي يمثّل اسم مكان أو عنوانًا معيّنًا لحلّه.
        • أمثلة: 'Googleplex, Mountain View, CA' و'1600 Amphitheatre Pkwy, Mountain View, CA' و'Eiffel Tower, Paris'

  2. ‫location_bias (عنصر - اختياري): استخدِم هذه المَعلمة لإعطاء الأولوية للنتائج القريبة من منطقة جغرافية معيّنة.

    • التنسيق: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (سلسلة - اختيارية): رمز منطقة CLDR في Unicode (رمز بلد مكوّن من حرفَين، مثل US وCA) للمستخدم من أجل تحسين النتائج

تعليمات طلب استخدام الأداة:

  • التحديد (مهم): يجب أن تمثّل طلبات البحث اسم مكان أو عنوانًا محدّدًا. لا يمكن إجراء عمليات بحث عامة مثل 'restaurants' أو أسماء سلاسل مثل 'Starbucks'.
  • يُرجى عدم استدعاء هذه الأداة إذا كانت الأدوات اللاحقة التي تخطّط لاستدعائها تقبل سلاسل العناوين أو أسماء الأماكن الأولية مباشرةً.

الحفظ في "خرائط Google":

  • يتضمّن الردّ حقل save_to_maps_url: رابط واحد إلى "خرائط Google" يحتوي على جميع الأماكن التي تم حلّها بنجاح.
  • عندما يريد المستخدم حفظ الأماكن التي تم حلّها أو مشاركتها أو فتحها كقائمة في "خرائط Google"، اعرِض هذا الرابط له. لا تنشئ هذا الرابط بنفسك.

معالجة الأخطاء (مهمة):

  • هذه أداة معالجة على دفعات. قد يعرض الطلب "نتائج مختلطة" (على سبيل المثال، يتم حلّ بعض طلبات البحث بنجاح بينما يتعذّر حلّ البعض الآخر).
  • يضمن أن تكون قائمة مخرجات results مطابقة تمامًا لمؤشرات الإدخال queries. سيؤدي طلب البحث الذي تعذّر تنفيذه إلى ظهور رسالة Result فارغة (لم يتم ضبط entity) في الفهرس المقابل في قائمة results.
  • يجب التحقّق من حقل الخريطة failed_requests في الاستجابة لتحديد فهرس طلب البحث الذي تعذّر تنفيذه. يمثّل مفتاح failed_requests الفهرس المستند إلى 0 لطلب البحث الذي تعذّر تنفيذه في الطلب. لا تفترض أنّ طلب الدفعة بالكامل قد تعذّر بسبب تعذّر جزئي.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة MCP‏ resolve_names.

طلب Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة طلب ResolveNames.

ResolveNamesRequest

تمثيل JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
الحقول
queries[]

object (LocationQuery)

الحقل مطلوب. قائمة بطلبات البحث عن المواقع الجغرافية التي يجب حلّها يمكنك تحديد ما يصل إلى 20 طلب بحث.
locationBias

object (LocationBias)

اختيارية: منطقة اختيارية لتوجيه نتائج الحلّ في حال تحديد هذه السمة، ستكون نتائج الحلّ منحازة إلى الكيانات الأقرب إلى هذه المنطقة. يؤدي تضمين location_bias أو region_code غالبًا إلى الحصول على نتائج أفضل من خلال تضييق نطاق البحث.

إذا تم تحديد كل من location_bias وregion_code، تكون الأولوية لـ location_bias على region_code.
regionCode

string

اختيارية: رمز منطقة اختياري لتوجيه نتائج الحلّ في حال تحديد هذه السمة، ستكون نتائج الحلّ منحازة إلى الكيانات الموجودة في المنطقة المحدّدة أو بالقرب منها. يجب أن يكون هذا رمز منطقة CLDR. على سبيل المثال، "US" أو "CA". يؤدي تضمين location_bias أو region_code غالبًا إلى الحصول على نتائج أفضل من خلال تضييق نطاق البحث.

إذا تم تحديد كل من location_bias وregion_code، تكون الأولوية لـ location_bias على region_code.

LocationQuery

تمثيل JSON 
{
  "text": string
}
الحقول
text

string

الحقل مطلوب. يمثّل هذا الحقل طلب البحث النصي الذي يتم تحليله إلى كيان جغرافي مكاني محدّد على "خرائط Google"، مثل مكان أو عنوان. كلما كان طلب البحث أكثر تحديدًا، كان الحل أكثر دقة. على سبيل المثال، "القاهرة" أو "Googleplex, Mountain View, CA" أو "1600 Amphitheatre Parkway, Mountain View, CA" أو "برج إيفل، باريس". يجب أن تكون طلبات البحث عنوانًا أو اسم مكان محدّدًا. لا يمكن استخدام المواقع الجغرافية العامة، مثل اسم سلسلة متاجر (مثل Starbucks) أو طلب بحث مثل "مطاعم".

LocationBias

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
الحقول
حقل الربط type نوع الانحياز للموقع الجغرافي يمكن أن يكون التعليق type إحدى القيم التالية فقط:
viewport

object (Viewport)

إطار عرض محدّد بمربّع محيط

إطار العرض

تمثيل JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
الحقول
low

object (LatLng)

الحقل مطلوب. النقطة المنخفضة لإطار العرض
high

object (LatLng)

الحقل مطلوب. النقطة العليا لإطار العرض

LatLng

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

خط العرض بالدرجات يجب أن يكون في النطاق [-90.0, +90.0].
longitude

number

خط الطول بالدرجات يجب أن يكون في النطاق [-180.0, +180.0].

مخطط النتائج

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

ResolveNamesResponse

تمثيل JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
الحقول
results[]

object (Result)

للعرض فقط. قائمة الكيانات التي تم حلّها من طلبات البحث عن الموقع الجغرافي يضمن ذلك الربط بنسبة 1:1 مع فهارس الطلب queries. تشير السلسلة الفارغة في الفهرس i إلى تعذُّر التحويل لطلب البحث هذا. في حال تعذُّر إكمال عملية التحويل، يُرجى التحقّق من حقل failed_requests لمعرفة حالة الخطأ.
failedRequests

map (key: integer, value: object (Status))

للعرض فقط. خريطة توضّح حالات الفشل الجزئية المفتاح هو فهرس الطلب الذي تعذّر تنفيذه في الحقل queries. القيمة هي حالة الخطأ التي توضّح سبب تعذُّر إكمال عملية التحويل.

عنصر يحتوي على قائمة بأزواج "key": value. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }
saveToMapsUrl

string

للعرض فقط. رابط لحفظ جميع الكيانات التي تم حلّها بنجاح في "خرائط Google"

النتيجة

تمثيل JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
الحقول
entity

object (Entity)

للعرض فقط. تمثّل هذه السمة الكيان الذي تم حلّه من طلب البحث عن الموقع الجغرافي.
confidence

enum (Confidence)

للعرض فقط. مستوى الثقة في الحلّ

الكيان

تمثيل JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
الحقول
حقل الربط entity نوع الكيان الذي تم حلّه يمكن أن يكون التعليق entity إحدى القيم التالية فقط:
place

string

اسم مورد المكان الذي تم حلّه

FailedRequestsEntry

تمثيل JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
الحقول
key

integer
value

object (Status)

الحالة

تمثيل JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
الحقول
code

integer

هو رمز الحالة، ويجب أن يكون قيمة محدّدة مسبقًا من google.rpc.Code.
message

string

يشير إلى رسالة خطأ موجّهة للمطوّرين، ويجب أن تكون الرسالة بالإنجليزية. أما رسائل الخطأ الموجّهة للمستخدمين، فيجب ترجمتها وإرسالها في حقل google.rpc.Status.details أو ترجمتها من قِبل العميل.
details[]

object

يشير إلى قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. تتوفّر مجموعة شائعة من أنواع الرسائل التي يمكن لواجهات برمجة التطبيقات استخدامها.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

أي

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

string

يحدّد نوع رسالة Protobuf المتسلسلة باستخدام مرجع URI يتألف من بادئة تنتهي بشرطة مائلة واسم النوع المؤهَّل بالكامل.

مثال: type.googleapis.com/google.protobuf.StringValue

يجب أن تحتوي هذه السلسلة على حرف / واحد على الأقل، ويجب أن يكون المحتوى بعد آخر / هو الاسم المؤهَّل بالكامل للنوع في شكل أساسي، بدون نقطة بادئة. لا تكتب مخططًا على مراجع معرّفات الموارد المنتظمة (URI) هذه حتى لا يحاول العملاء الاتصال بها.

تكون البادئة عشوائية، ومن المتوقّع أن تزيل عمليات تنفيذ Protobuf ببساطة كل شيء حتى آخر / لتحديد النوع. ‫type.googleapis.com/ هي بادئة تلقائية شائعة تتطلّبها بعض عمليات التنفيذ القديمة. لا تشير هذه البادئة إلى مصدر النوع، ولا يُتوقع أن تستجيب معرّفات الموارد المنتظمة التي تحتوي عليها لأي طلبات.

يجب أن تكون جميع سلاسل عناوين URL الخاصة بالنوع مراجع URI قانونية مع فرض قيود إضافية (على تنسيق النص) بأنّ محتوى المرجع يجب أن يتألف فقط من أحرف أبجدية رقمية ورموز هروب بترميز النسبة المئوية وأحرف في المجموعة التالية (لا تشمل علامات الاقتباس المائلة الخارجية): /-.~_!$&()*+,;=. على الرغم من أنّنا نسمح بالترميز بالنسبة المئوية، يجب ألا تلغي عمليات التنفيذ تسلسل الهروب لتجنُّب حدوث التباس مع المحللات اللغوية الحالية. على سبيل المثال، يجب رفض type.googleapis.com%2FFoo.

في التصميم الأصلي لـ Any، تم النظر في إمكانية إطلاق خدمة تحليل النوع في عناوين URL هذه، ولكن لم يتم تنفيذها في Protobuf، ويُعتبر الاتصال بعناوين URL هذه مشكلة محتملة في الأمان. لا تحاول كتابة عناوين URL.
value

string (bytes format)

يحتوي على تسلسل Protobuf للنوع الموضّح في type_url.

سلسلة بترميز base64

الثقة

مستوى الثقة في الحلّ

عمليات التعداد
CONFIDENCE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
MEDIUM تشير الثقة المتوسطة إلى أنّ الحلّ صحيح على الأرجح، ولكن قد تكون هناك حلول أخرى محتملة.
HIGH تشير الثقة العالية إلى أنّ الحلّ صحيح ويمثّل كيانًا جغرافيًا مكانيًا معيّنًا (مثل مكان معيّن).

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

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

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

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

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