# دليل التثبيت

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

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).

ابدأ العمل الفعلي خلال أقل من 5 دقائق. يتضمن هذا الدليل إعدادًا لـ 23 من عملاء MCP، بما في ذلك Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT، وWarp، وغيرها.

**المتطلبات الأساسية**: ستحتاج إلى مفتاح API من [app.maguyva.ai](https://app.maguyva.ai) ومستودع GitHub متصل.

## إعداد البيئة

أولًا، عيِّن مفتاح API في متغيّر بيئة. احذف `repository` عندما يوفّر عميل MCP قيمة افتراضية على مستوى الطلب أو عندما يمكن للمفتاح الوصول إلى مستودع واحد فقط؛ وإلا فمرِّره صراحةً.

### macOS/Linux (Bash/Zsh)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

استبدل `mgv_xxxx` بمفتاح API الفعلي الخاص بك من [app.maguyva.ai](https://app.maguyva.ai).

## إعداد العميل

اختر عميل MCP الخاص بك أدناه للحصول على تعليمات إعداد محددة.

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

يستخدم Maguyva بروتوكول MCP القياسي. يمكن لأي عميل يدعم البروتوكول الاتصال — حتى إن لم يكن هناك دليل رسمي أعلاه. 23 عميل موثّق، ويُضاف المزيد بانتظام.

## تحقّق من إعدادك

بعد الاتصال، جرّب طرح بضعة أسئلة على وكيلك:

- "ما المستودعات المتصلة لديّ؟" — يتحقّق من أن الاتصال يعمل
- "كيف تُعالَج المصادقة في قاعدة الكود هذه؟" — يختبر البحث الدلالي
- "ابحث عن جميع الدوال التي تستدعي قاعدة البيانات" — يختبر بحث الاعتماديات
- "على ماذا تعتمد فئة UserService؟" — يختبر البحث عن الرموز

يجب أن ترى نتائج تتضمن مسارات الملفات وأرقام الأسطر من مستودعك المتصل. إن لم يحدث ذلك، راجع [troubleshooting](https://maguyva.ai/ar/docs/troubleshooting) أدناه.

## صيغة المستودع

عند تحديد المستودعات:

- مع تحديد الفرع: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- الفرع الافتراضي: `"owner/repo"`

**نصيحة**: استخدم `repository_context(action="info", repository="...")` للتحقق من تحديد المستودع. ينطبق تجاوز المستودع الافتراضي على الاستدعاء الحالي فقط.

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

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

- تحقّق من أن مفتاحك يبدأ بالبادئة mgv_
- تحقّق من أن المفتاح مضبوط بشكل صحيح في بيئتك
- تأكّد من أن المفتاح لم تنتهِ صلاحيته

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

- تحقّق من أن المستودع متصل في app.maguyva.ai
- تحقّق من صحة صيغة owner/repo
- تأكّد من أن لديك صلاحية الوصول إلى المستودع

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

- إذا كان عميلك يستخدم جسر @maguyva/mcp، فتحقّق من توفر npx في PATH
- تحقّق من أن رمز API الخاص بك صالح ولم تنتهِ صلاحيته
- اختبر الاتصال بـ https://maguyva.tools/mcp
- تحقّق من صيغة إعداد MCP الخاصة بعميلك

## الخطوات التالية

- مرجع MCP API: وثائق API الكاملة
- كيف يعمل: افهم تحسين السياق
- استكشاف الأخطاء وإصلاحها: حلّ مشكلات الإعداد والاتصال