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 (سلسلة - اختياري): رمز Unicode CLDR للمنطقة (رمز البلد المكوّن من حرفين، مثل US أو CA) الخاص بالمستخدم لتحديد النتائج.

تعليمات بشأن استدعاء الأدوات:

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

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

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

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة resolve_names MCP.

طلب 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 tool's MCP 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، ماونتن فيو، كاليفورنيا" أو "1600 Amphitheatre Parkway، ماونتن فيو، كاليفورنيا" أو "برج إيفل، باريس". يجب أن تكون طلبات البحث عبارة عن عنوان أو اسم مكان محدّد. لا تتوفّر المواقع الجغرافية العامة، مثل اسم سلسلة متاجر (مثل 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)
    },
    ...
  }
}
الحقول
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" }

النتيجة

تمثيل 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 تشير الثقة العالية إلى أنّ عملية تحديد الموقع الجغرافي صحيحة وتمثّل كيانًا جغرافيًا مكانيًا معيّنًا (مثل مكان معيّن).

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

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