# دليل الوصفات

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

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 MCP. تحدد كل وصفة الأدوات وتسلسلها، وليست مرجعًا كاملًا للمعاملات. راجع [مرجع MCP API](https://maguyva.ai/docs/mcp-api) لمعاملات الأدوات، واستخدم [البدء السريع](https://maguyva.ai/docs/quickstart) للإعداد لأول مرة.

### اختر الأداة المناسبة

تبدأ معظم الأسئلة باستدعاء واحد. انتقل إلى خطوة أعمق فقط عندما تكون الإجابة الأولى واسعة جدًا أو محدودة جدًا.

- `intelligent_search` — ابدأ هنا لطرح سؤال بلغة طبيعية عن قاعدة الشيفرة. يوجّه الوضع الافتراضي auto/balanced أسئلة التعريف التي يمكن تحديد مقصدها بثقة إلى البحث البنيوي، وأسئلة المراجع أو التأثير إلى الرسم البياني، وأسئلة التطابق التام إلى النص. وتستخدم الأسئلة الأخرى البحث الدلالي والنص المفهرس. لطلب الأنماط الأربعة جميعًا، استخدم mode=hybrid أو auto مع quality=thorough. تكون الأولوية للوضع المحدد صراحةً على quality.
- `find_symbol` — عندما تعرف مسبقًا اسم الدالة أو الفئة أو المتغير.
- `dependency_search` — لمعرفة نطاق التأثير: المستدعون والعناصر المعتمدة والأثر قبل التعديل وبعده.
- `get_task_context` — لمنطقة غير مألوفة؛ يعيد حزمة محدودة من الملفات والرموز والتبعيات بناءً على وصف المهمة.
- `repository_context` — لسرد المستودعات المتاحة أو فحص كيفية تحديد المستودع من اسمه.
- `ask_maguyva` مع `operation="guidance"` — مساعدة محلية لاختيار الأدوات واستخدام Maguyva من دون تعديل المستودع.

كتل JSON هي مدخلات MCP tools/call. استبدل owner/repo واسم الفرع وأسماء الرموز بقيم من مستودعك.

### ثبّت العميل وتحقق منه

أضف Maguyva إلى عميل MCP وتأكد من الاتصال باستخدام قائمة مستودعات حقيقية.

1. أنشئ مفتاح API في [app.maguyva.ai](https://app.maguyva.ai)؛ تبدأ المفاتيح بـ `mgv_`.
2. صِل مستودع GitHub واحدًا على الأقل تعرفه جيدًا وأنشئ فهرسه.
3. اضبط عميلك باستخدام [دليل التثبيت](https://maguyva.ai/docs/installation): إضافة Claude Code أو الإعداد البعيد الأصلي لـ Cursor وVS Code وDevin Desktop وZed وغيرها.
4. اسأل وكيلك "ما المستودعات المتصلة لدي؟" — فهذا يختبر المصادقة و`repository_context` من البداية إلى النهاية.
5. اطرح سؤالًا حقيقيًا عن ذلك المستودع يمكنك تقييم إجابته. ينبغي أن ترى مسارات الملفات وأرقام الأسطر من الشجرة المفهرسة.

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

هل تعطلت عند المفاتيح أو الجسور أو المستودعات المفقودة؟ راجع [استكشاف الأخطاء](https://maguyva.ai/docs/troubleshooting).

### اسأل قبل أن تعدّل

حدّد الرموز ونطاق التأثير قبل تغيير الشفرة المشتركة. لا تعدّل أدوات Maguyva مستودعاتك؛ بل توفّر الأدلة للتعديل الذي يطبقه عميلك محليًا.

1. إذا كنت تعرف اسم الرمز، فاستدعِ `find_symbol` للوصول إلى التعريفات ومواضع الاستخدام.
2. إذا لم يكن لديك سوى وصف للمهمة، مثل «إضافة SSO» أو «إصلاح webhook للفوترة»، فابدأ بـ `get_task_context` أو `intelligent_search`.
3. قبل تعديل رمز مشترك، استدعِ `dependency_search` لتحليل العناصر المعتمدة أو التأثير، أو مرّر المسارات المتغيرة لتحليل شبيه بطلبات PR، حتى ترى نطاق التأثير.
4. افتح الملفات المشار إليها — قراءة محلية للملفات على القرص، و`get_file` للمسارات البعيدة أو عبر المستودعات — ثم طابق الخطة مع الشفرة الفعلية.
5. بعد التعديل، أعد فحص الرموز نفسها باستخدام `dependency_search` مع verify_after_edit=true وtargets أو changed_paths. يقرأ هذا المخطط المفهرس، لا التغييرات المحلية التي لم تُودَع بعد: تحقّق من indexed_commit_sha وحداثة الفهرس قبل اعتبار النتيجة دليلًا على النسخة الجديدة من الكود، وشغّل الاختبارات المحلية.

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

جميع المعاملات: [مرجع MCP API](https://maguyva.ai/docs/mcp-api).

### ابحث ثم غيّر

حلقة الوكيل الافتراضية: استكشاف ← تثبيت الرموز ← تعديل مدعوم بالأدلة.

1. ابدأ بـ `intelligent_search` واستعلام بلغة عادية، مثل «كيف يعمل انتهاء الجلسة؟» أو «أين منطق إعادة المحاولة؟».
2. ضيّق النتائج بمرشّحات اللغة أو المسار إذا كانت المجموعة الأولى كثيرة النتائج غير ذات الصلة. يستبعد language_filter الرسم البياني من auto/hybrid؛ وإذا وُجّه استعلام auto إلى الرسم البياني وحده، يعود إلى البحث الدلالي والنصي. يُرفض الجمع بين وضع الرسم البياني الصريح وlanguage_filter. افحص routing_decision.modalities_used لمعرفة خطة البحث المختارة؛ أما warnings فلا يظهر إلا عندما يصدر الخادم تحذيرًا.
3. انقل النتائج الواعدة إلى `find_symbol` أو `dependency_search` بدل إعادة السؤال الغامض نفسه.
4. استخدم `get_file` فقط عندما تحتاج إلى مسار مفهرس محدد غير موجود على القرص.
5. عدّل بأدوات عميلك المعتادة. Maguyva مخصص للاكتشاف والتحقق، لا للكتابة.

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

لماذا تنجح هذه الحلقة: [كيف يعمل](https://maguyva.ai/docs/how-it-works).

### نتائج فارغة أو محدودة

عندما لا تعيد الأدوات شيئًا مفيدًا، أصلح تحديد المستودع وفهرسته قبل إعادة صياغة الاستعلام بلا نهاية.

1. تأكد في [app.maguyva.ai](https://app.maguyva.ai) من اتصال المستودع واكتمال فهرسته.
2. تحقق من نص المستودع: يستخدم `"owner/repo"` الفرع الافتراضي، بينما يثبت `"owner/repo:branch"` فرعًا محددًا. المطابقة لا تميّز حالة الأحرف لكنها ليست تقريبية، لذلك لا تُصحح الأخطاء المطبعية تلقائيًا.
3. استدعِ `repository_context` مع `action="info"` وافحص البيانات الوصفية لتحديد المستودع، مثل `metadata.resolution_reason`.
4. احذف `repository` فقط إذا كان عميل MCP يوفّر قيمة افتراضية للطلب أو كان المفتاح يصل إلى مستودع واحد فقط؛ وإلا فمرّره صراحة.
5. أعد المحاولة باستعلام أدق أو اسم رمز معروف عبر `find_symbol` أو مرشح لغة/مسار. إذا كان الاتصال نفسه معطلًا، فاستخدم [استكشاف الأخطاء](https://maguyva.ai/docs/troubleshooting).

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

أعطال الإعداد: [استكشاف الأخطاء](https://maguyva.ai/docs/troubleshooting).

### العمل عبر مستودعات متعددة

استهدف المستودع المفهرس الصحيح عندما يستطيع المفتاح رؤية أكثر من مستودع.

1. استدعِ `repository_context` مرة واحدة مع `action="list"` لمعرفة الأسماء الدقيقة التي يمكن لمفتاحك البحث فيها.
2. مرّر `repository` صراحة إلى أدوات البحث والرموز عندما تحتاج إلى مستودع غير افتراضي، مثل `"owner/other-repo"` أو `"owner/other-repo:develop"`.
3. اجعل كل سؤال لمستودع واحد، إلا إذا كنت تقارن عمدًا بين المستودعات في استدعاءات منفصلة.
4. استخدم `get_file` عندما يكون الملف في مستودع مفهرس لا في شجرة العمل الحالية.
5. تذكّر: لا تكتب الأدوات إلى GitHub مطلقًا؛ سياق المستودعات المتعددة للقراءة والتخطيط فقط.

تفاصيل تنسيق المستودع: [مرجع MCP API](https://maguyva.ai/docs/mcp-api).

تُجري الإعداد للمرة الأولى؟ ابدأ بـ [البدء السريع](https://maguyva.ai/docs/quickstart)، ثم استخدم هذه الوصفات للمهام اليومية.