استكشاف المشكلات
حدد أولًا الاتصال المتعطل: خطأ إعداد محلي، أو اتصال عميل MCP بالخادم، أو طلب Google صادر. أصلح الطبقة المناسبة ثم أعد تنفيذ العملية المتأثرة.
البدء دون اتصال
mcp-gmap-rs --version
mcp-gmap-rs tools
mcp-gmap-rs doctorيطبع doctor بصيغة JSON حتى عند فشل الفحوص. افحص حالة الخروج وchecks[].status: القيم pass أو fail أو not_tested. لا تثبت الفحوص غير المتصلة IAM أو تفعيل API أو الفوترة أو ثقة الشهادة وانتهاءها أو الوصول إلى ADC. يثبت /health حياة العملية فقط.
إذا منع ملف dotenv محلي غير سليم الاكتشاف، يتجاوزه --no-env-file tools. قد يغيّر ذلك مجموعة الأدوات المختارة، فلا تعتبره تحققًا من إعدادات الملف المقصود.
تفسير الإخفاقات الشائعة
| العَرَض | الفحص التالي |
|---|---|
GOOGLE_MAPS_API_KEY is required | تم اختيار وضع مفتاح API أو تصل العملية إلى نقطة نهاية خاصة بالمفتاح. |
GOOGLE_CLOUD_QUOTA_PROJECT is required | اضبط معرّف أو رقم مشروع الاستهلاك لـ OAuth. |
| Google 403 / API غير مفعّل | فعّل الواجهة المحددة في مشروع استهلاك بيانات الاعتماد؛ وافحص الفوترة وقيود مفتاح API. |
رفض serviceusage.services.use | امنح حساب الخدمة roles/serviceusage.serviceUsageConsumer في مشروع الحصة؛ وانتظر انتشار IAM ثم أعد المحاولة. |
| رفض IP لمفتاح API | اسمح بعنوان الخروج العام للخادم أو العنقود، لا بعنوان الحجرة الخاص. |
| MCP HTTP 401 | أرسل رمز bearer للخادم؛ يصادق رمز وصول Google اتصالًا آخر. |
| رفض Host/Origin | طابق Host وأصل المتصفح المضبوطين تمامًا، بما في ذلك المنافذ المناسبة. |
| HTTP 429 من MCP | نفد محدد العملية؛ احترم Retry-After وافحص تزامن العملاء. |
| انتهاء مهلة OAuth | افحص الاتصال بالرموز وSTS وIAM أو البيانات الوصفية، وساعة النظام ومهلة الطلب. |
| فشل اتصال TLS | افحص سلسلة الشهادة واسم المضيف والثقة وشهادة عميل mTLS الاختيارية بمعزل عن تفويض HTTP. |
| خروج 0 لكن البيانات ناقصة | افحص أخطاء عناصر المصفوفة والأدوات المركبة، وليس حالة خروج العملية فقط. |
التحقق المتعمد من الوصول الحي
تجري المجسات الحية استدعاءات قد تكون قابلة للفوترة. احصرها في واجهات API التي تحتاجها:
mcp-gmap-rs --enabled-tools maps_weather doctor --liveنجاح مجس لا يضمن كل منطقة جغرافية أو عملية. بعد تغيير في Google Cloud، أعد تنفيذ الاستدعاء الفاشل نفسه بدل استنتاج النجاح من إعدادات الوحدة. راجع المصادقة لـ IAM ومصادر بيانات الاعتماد، والإعدادات للأولوية، وتشغيل الإنتاج للميزانيات والمهل والمقاييس. لا تطبع JSON بيانات الاعتماد ولا تفريغ البيئة في بلاغ مشكلة.