قوالب التعليمات في MCP

التعليمات هي أقل القدرات الثلاث استخداماً، وأكثرها استحقاقاً للاستخدام. فهي بدايات محادثة يقدّمها خادمك إلى المستخدم لا إلى النموذج، ما يجعلها المكان الصحيح لتلك التوجيهات التي يعيد فريقك كتابتها كل مرة بصياغة مختلفة قليلاً.

لماذا التعليمات؟

الحجة الصادقة لصالحها: في مؤسستك فقرة من التوجيهات يكتبها شخص واحد جيداً ويكتبها الباقون بشكل رديء. قالب التعليمات هو المكان الذي تذهب إليه تلك الفقرة لتكفّ عن كونها معرفة شفهية متوارثة.

التعليمات مفيدة في:

• توحيد التفاعلات التي تُنسخ حالياً من صفحة ويكي
• منح نقاط بداية متخصصة لمن لا يعرف كيف يسأل
• تغليف توجيهات أطول من أن يعيد أحد كتابتها بدقة

تشريح تعريف التعليمة

أربعة أجزاء، والفصل بين التعريف والتوليد هو ما يخطئ فيه الناس أولاً:

الأجزاء الثلاثة الأولى تُعلَن مرة واحدة في list_prompts بوصفها مدخلاً في قائمة. أما الرابع فيُبنى من جديد في get_prompt كلما اختاره أحد. ووضوح هذا الفصل هو ما يجعل سرد التعليمة رخيصاً وبناءها مكلفاً.

تعريف التعليمات

@mcp.prompt()
def code_review(language: str, focus: str = "الممارسات الجيدة العامة") -> str:
    """مراجعة الكود بحثاً عن الممارسات الجيدة والمشاكل."""
    return f"""يرجى مراجعة كود {language} التالي.
التركيز على: {focus}

قدم اقتراحات محددة مع أرقام الأسطر حيث ينطبق.
قيّم الكود من 1-10 واشرح تقييمك."""

إعلان الموجَّه وبناؤه دالة واحدة. تصبح المعاملات وسائط الموجَّه، ويُبلَّغ العميل بأن المعامل ذا القيمة الافتراضية اختياري — فتُشتق required من توقيع دالتك بدل إعادة ذكرها بجانبه.

توليد محتوى التعليمات

عندما يُطلب تعليمات، أرجع الرسائل الفعلية:

@mcp.prompt()
def summarize_pr(title: str, diff: str) -> str:
    """تلخيص طلب سحب لمراجع لم يقرأ الفروقات."""
    return f"""لخّص طلب السحب هذا لشخص يراجعه على البارد.

العنوان: {title}

{diff}

ابدأ بتغيّر السلوك لا بقائمة الملفات. ونبّه على أي شيء يمس المصادقة أو
ترحيلات قاعدة البيانات أو شكل الواجهة البرمجية العامة."""

إرجاع سلسلة نصية عادية هو الحالة الشائعة: يغلّفها الـ SDK كرسالة مستخدم واحدة.

تعليمات متعددة الأدوار

يمكن أن تتضمن التعليمات رسائل متعددة لسير العمل المعقد:

from mcp.server.mcpserver.prompts.base import UserMessage, AssistantMessage


@mcp.prompt()
def debug_session(error: str, code: str) -> list:
    """فتح محادثة تصحيح خطوة بخطوة حول خطأ واحد."""
    return [
        UserMessage("سأشارك خطأ. ساعدني في تصحيحه خطوة بخطوة."),
        AssistantMessage("سأساعدك في التصحيح. يرجى مشاركة رسالة الخطأ والكود ذي الصلة."),
        UserMessage(f"الخطأ: {error}\nالكود: {code}"),
    ]

أعِد قائمة رسائل حين يحتاج الموجَّه إلى تحميل محادثة مسبقاً بدل طرح سؤال واحد. ودور الرسالة المزروعة من المساعد هو بيت القصيد: فهي تُلزم النموذج بموقف قبل وصول مُدخل المستخدم الحقيقي.

استخدم UserMessage وAssistantMessage من mcpserver.prompts.base لا mcp.types.PromptMessage. يبدوان قابلين للتبادل وهما ليسا كذلك: فـ PromptMessage يسقط في فرع احتياطي داخل مدير الموجَّهات يَسِم كل رسالة بـ role="user". ولا يظهر أي خطأ — تحصل ببساطة على ثلاث رسائل من المستخدم، وتختفي رسالة المساعد التي كتبتها بصمت، وهي كل سبب استخدامك لقائمة رسائل من الأساس.

وسائط التعليمات الديناميكية

جلب خيارات الوسائط ديناميكياً:

Prompt(
    name="query_database",
    description="الاستعلام عن جدول محدد",
    arguments=[
        PromptArgument(
            name="table",
            description="اسم الجدول",
            required=True,
            # يمكن التحقق منه مقابل المخطط الفعلي
        )
    ]
)

التالي: خادم واحد يقدّم القدرات الثلاث دون أن تتعثر إحداها بالأخرى. :::