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

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

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

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

إذا كان عميلك يستخدم جسر @maguyva/mcp، فإنه يشغّل عملية محلية تتصل بخادم Maguyva البعيد:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

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

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

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

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

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