دليل الوصفات

وصفات عملية للعمل اليومي باستخدام Maguyva MCP. تحدد كل وصفة الأدوات وتسلسلها، وليست مرجعًا كاملًا للمعاملات. راجع مرجع MCP API لمعاملات الأدوات، واستخدم البدء السريع للإعداد لأول مرة.

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

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

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

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

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

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

هل تعطلت عند المفاتيح أو الجسور أو المستودعات المفقودة؟ راجع استكشاف الأخطاء.

حدّد الرموز ونطاق التأثير قبل تغيير الشفرة المشتركة. لا تعدّل أدوات 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 وحداثة الفهرس قبل اعتبار النتيجة دليلًا على النسخة الجديدة من الكود، وشغّل الاختبارات المحلية.

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

جميع المعاملات: مرجع 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 مخصص للاكتشاف والتحقق، لا للكتابة.

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

لماذا تنجح هذه الحلقة: كيف يعمل.

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

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

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

أعطال الإعداد: استكشاف الأخطاء.

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

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

تفاصيل تنسيق المستودع: مرجع MCP API.

• البدء السريع — المفتاح والفهرسة والاتصال وأول إجابة قابلة للتقييم
• دليل التثبيت — إعداد MCP لكل عميل
• مرجع MCP API — كل أداة، معاملًا بعد معامل
• استكشاف الأخطاء — أعطال مفتاح API والجسر والمستودع