دمج القدرات

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

مثال كامل: خادم قاعدة المعرفة

إليك قاعدة المعرفة نفسها مكشوفة بثلاث طرق في آن واحد. لاحظ أن كل قدرة تجيب عن سؤال مختلف حول المستندات نفسها:

الاقتران الذي يجعل هذا يعمل هو search_knowledge مع doc://{id}. فالموارد معنونة لكنها غير قابلة للاكتشاف من النموذج، إذ لا سبيل له لتخمين معرّف مستند. وأداة البحث موجودة تحديداً لتحويل السؤال إلى معرّفات تستطيع طبقة الموارد تقديمها. اشحن إحداهما دون الأخرى فيصير نصف الخادم غير قابل للوصول.

from mcp.server import MCPServer

mcp = MCPServer(name="knowledge-base")


# 1. الموارد — عروض للقراءة فقط، تُعنون بـ URI
@mcp.resource("doc://{doc_id}", mime_type="text/markdown")
async def document(doc_id: str) -> str:
    """مستند واحد من قاعدة المعرفة."""
    doc = await db.get_document(doc_id)
    return doc.content


# 2. الأدوات — أفعال، بما فيها ذات الآثار الجانبية
@mcp.tool()
async def search_knowledge(query: str, limit: int = 5) -> str:
    """البحث في قاعدة المعرفة وإرجاع أفضل المستندات المطابقة."""
    return await kb.search(query, limit=limit)


@mcp.tool()
async def add_document(title: str, content: str, tags: list[str] | None = None) -> str:
    """إضافة مستند جديد إلى قاعدة المعرفة."""
    doc_id = await db.add_document(title, content, tags or [])
    return f"تم إنشاء doc://{doc_id}"


# 3. الموجَّهات — تفاعلات موحّدة يختارها المستخدم من قائمة
@mcp.prompt()
def summarize_topic(topic: str) -> str:
    """تلخيص كل ما تعرفه قاعدة المعرفة عن موضوع ما."""
    return f"ابحث في قاعدة المعرفة عن '{topic}' ثم لخّص ما تجده. واذكر كل doc:// استخدمته."

القدرات الثلاث تؤدي هنا ثلاث وظائف مختلفة، وهذا الفصل هو التصميم كله. فـ doc://{doc_id} قالب، ولذلك يكشف الخادم كل مستند دون أن يسرد أياً منها. وadd_document أداة لا مورداً قابلاً للكتابة لأن لها أثراً جانبياً. وsummarize_topic موجَّه لأن المستخدم يختاره عن قصد — فالموجَّهات يبدؤها المستخدم، وهو بالضبط ما لا تفعله الأدوات.

سير العمل: الذكاء الاصطناعي يستخدم جميع القدرات

تتبّع طلباً حقيقياً من أوله إلى آخره. الترتيب ليس اعتباطياً، فالبحث يجب أن يأتي أولاً لأن لا شيء غيره يعرف أي المستندات موجودة:

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

تنسيق الموارد والأدوات

صمم الموارد والأدوات للعمل معاً:

# المورد: عرض للقراءة فقط
Resource(uri="user://123", name="ملف المستخدم 123")

# الأداة: تعديل المستخدم
Tool(name="update_user", description="تحديث ملف المستخدم")

أفضل الممارسات

الممارسة	السبب
فصل واضح	الموارد للقراءة، الأدوات للإجراءات
URIs متسقة	تجعل الموارد قابلة للتنبؤ
تسمية ذات صلة	user://123 مع أداة update_user
توثيق العلاقات	اشرح في الأوصاف

الآن دعنا نطبق هذه الأنماط في مختبر عملي. :::