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

Canonical source: https://maguyva.ai/ar/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

أصلح أعطال إعداد Maguyva الشائعة: مشاكل مفتاح API، ومشاكل جسر @maguyva/mcp، وعمليات البحث عن المستودعات، وأخطاء الاتصال.

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

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

### مشاكل جسر @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 قيمة افتراضية على مستوى الطلب أو عندما يمكن للمفتاح الوصول إلى مستودع واحد فقط.

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

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

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

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