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. سيؤدي تعذُّر تحليل عنوان URL إلى ظهور رسالة Entity فارغة (لم يتم ضبط أي حقول) في الفهرس المقابل في قائمة entities.
  • يجب التحقّق من حقل الخريطة failed_requests في الاستجابة لتحديد فهرس عنوان URL الذي تعذّر إرساله. يمثّل مفتاح failed_requests الفهرس المستند إلى 0 لعنوان URL الذي تعذّر تنفيذه في الطلب. لا تفترض أنّ طلب الدفعة بالكامل قد تعذّر بسبب تعذّر جزئي.

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

طلب 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: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة بحث الويب عالمًا مفتوحًا، في حين أنّ أداة الذاكرة لن تكون عالمًا مفتوحًا.

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