استكشاف الأخطاء وإصلاحها

تندرج معظم أعطال الإعداد ضمن أربع فئات: مفتاح API لا يصل إلى الخادم، أو جسر mcp-remote لا يبدأ التشغيل، أو تعذّر تحديد المستودع، أو تعذّر اتصال العميل بالكامل. اطّلع على القسم الذي يطابق عرَضك.

مشاكل مفتاح API#

تُصادَق كل طلب باستخدام مفتاح API الخاص بك، المُرسَل كترويسة Authorization: Bearer. إذا رُفضت استدعاءات الأدوات:

• تحقق من أن مفتاحك يبدأ بالبادئة mgv_.
• تأكد من أنك استبدلت العنصر النائب mgv_xxxx في أمثلة الإعداد بمفتاحك الحقيقي من app.maguyva.ai.
• إذا كان إعدادك يقرأ المفتاح من MAGUYVA_API_KEY، تأكد من أن المتغير مضبوط في البيئة التي يُشغَّل منها عميلك فعليًا. عمليات التصدير (exports) المضافة إلى ~/.zshrc أو ~/.bashrc لا تُطبَّق إلا بعد إعادة تحميل الصدفة (shell) — وقد لا ترثها تطبيقات الواجهة الرسومية إطلاقًا. عند الشك، ضع المفتاح في كتلة env الخاصة بالإعداد.
• تأكد من أن المفتاح لم تنتهِ صلاحيته ولم يُلغَ.

مشاكل جسر mcp-remote#

تُشغّل معظم إعدادات العملاء الموثّقة عملية جسر محلية تُعيد توجيه حركة بيانات MCP عبر stdio إلى الخادم البعيد:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

إذا لم يظهر الخادم أبدًا في عميلك، أو ظهر وانقطع فورًا:

• تحقق من توفر npx في متغير PATH الخاص بك — يحتاج الجسر تثبيتًا يعمل من Node.js. شغّل npx -y mcp-remote --help في الطرفية للتأكد من إمكانية بدء تشغيله.
• تحقق من صياغة إعداد MCP في عميلك — ملف JSON غير صحيح يفشل بصمت في بعض العملاء.
• لا تحتاج عملاء كثيرون إلى الجسر إطلاقًا. يستخدم Claude⁠ ⁠Code إضافة Maguyva (/plugin install maguyva@maguyva)، بينما يتصل Cursor وVS⁠ ⁠Code وWindsurf وZed بالخادم البعيد أصليًا بترويسة Bearer (يتصل Zed عبر context_servers). الجسر مخصص فقط للعملاء الذين لا يدعمون ترويسة الاتصال البعيد أصليًا، مثل موصلات Claude⁠ ⁠Desktop المقتصرة على OAuth.

المستودع غير موجود#

• تحقّق أن المستودع متصل ومفهرس في app.maguyva.ai.
• تحقّق من الصيغة: "owner/repo" يستهدف الفرع الافتراضي، و"owner/repo:branch" يستهدف فرعًا محددًا (مثلًا: "owner/repository:develop").
• تأكّد أن حسابك يملك صلاحية الوصول إلى المستودع.
• استخدم repository_context(action="info", repository="...") لفحص كيفية حلّ المستودع؛ احذف معامل repository فقط عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يمكن للمفتاح الوصول إلى مستودع واحد فقط.

مشاكل اتصال MCP#

• اختبر الاتصال بـhttps://maguyva.tools/mcp من جهازك — الوسطاء والجدران النارية الخاصة بالشركات هي المتسببة عادة.
• تحقق من أن رمز API الخاص بك صالح ولم تنتهِ صلاحيته.
• أعد التحقق من إعداد عميلك مقارنةً بـدليل التثبيت الخاص بعميلك — يختلف موقع ملف الإعداد وشكله من عميل لآخر.

تحقق من الإصلاح#

بعد أي تغيير، اسأل وكيلك "ما المستودعات المتصلة لديّ؟" — فهذا يتحقق من الاتصال من طرف إلى طرف. ثم اطرح سؤالاً حقيقيًا عن مستودعك؛ يجب أن ترى إجابات تتضمن مسارات الملفات وأرقام الأسطر من مستودعك المتصل.