MCP Tools Reference: mapstools.googleapis.com

الأداة: resolve_maps_urls

تحوّل هذه الطريقة قائمة بعناوين URL على "خرائط Google" إلى أرقام تعريف أساسية للأماكن على "خرائط Google".

حالات استخدام هذه الأداة (مهم):

  • استخدِم هذه الأداة عندما يقدّم المستخدم رابطًا أو أكثر من روابط المشاركة أو عناوين URL في "خرائط Google" (مثل "https://maps.app.goo.gl/..."، ‫'https://www.google.com/maps/place/...‎' أو ‎ 'https://maps.google.com/...‎') وتحتاج إلى استخراج معرّفات الأماكن الأساسية الأساسية.
  • يمكنك تحديد ما يصل إلى 20 عنوان URL ليتم حلّها في طلب دُفعة واحد.

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

  • استبدِل urls (صفيف من السلاسل - إلزامي) بقائمة عناوين URL التي يجب حلّها في "خرائط Google". يجب أن يكون كل عنوان URL صالحًا ويؤدي إلى مكان واحد على "خرائط Google".

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

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

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

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

يوضّح نموذج الرمز التالي كيفية استخدام curl لاستدعاء أداة resolve_maps_urls 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_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة الطلب ResolveMapsUrls

ResolveMapsUrlsRequest

تمثيل JSON 
{
  "urls": [
    string
  ]
}
الحقول
urls[]

string

الحقل مطلوب. عناوين URL التي سيتم تحليلها في "خرائط Google" يجب أن يكون كل عنوان URL صالحًا على "خرائط Google"، مثل https://maps.app.goo.gl/... أو https://www.google.com/maps/place/... أو https://maps.google.com/.... في الوقت الحالي، لا تتوفّر سوى عناوين URL التي تشير إلى مكان واحد. يمكنك تحديد ما يصل إلى 20 عنوان URL.

مخطط النتائج

رسالة الردّ على ResolveMapsUrls

ResolveMapsUrlsResponse

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

object (Entity)

النتائج فقط. قائمة العناصر التي تم حلّها من عناوين URL الخاصة بـ "خرائط Google"، ويُضمَن أن يتم الربط بنسبة 1:1 مع فهارس الطلب urls. تشير الرسالة الفارغة في الفهرس i (حيث لم يتم ضبط entity) إلى تعذُّر تحديد عنوان URL هذا. إذا تعذّر إكمال عملية التحويل، يُرجى التحقّق من الحقل failed_requests لمعرفة حالة الخطأ.
failedRequests

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

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

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

string

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

الكيان

تمثيل 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

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

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

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

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

تلميح تدميري: ❌ | تلميح متكرّر: ❌ | تلميح للقراءة فقط: ✅ | تلميح للعالم المفتوح: ❌