دمج القدرات

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

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

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

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

from mcp.server import Server
from mcp.types import Tool, Resource, Prompt, TextContent

server = Server(name="knowledge-base")

# 1. الموارد: كشف المستندات
@server.list_resources()
async def list_resources():
    docs = await db.get_all_documents()
    return [
        Resource(
            uri=f"doc://{doc.id}",
            name=doc.title,
            description=f"مستند: {doc.title}",
            mimeType="text/markdown"
        )
        for doc in docs
    ]

@server.read_resource()
async def read_resource(uri: str):
    doc_id = uri.replace("doc://", "")
    doc = await db.get_document(doc_id)
    return [TextContent(type="text", text=doc.content)]

# 2. الأدوات: البحث والتعديل
@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="search_knowledge",
            description="البحث في قاعدة المعرفة",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "limit": {"type": "integer", "default": 5}
                },
                "required": ["query"]
            }
        ),
        Tool(
            name="add_document",
            description="إضافة مستند جديد إلى قاعدة المعرفة",
            inputSchema={
                "type": "object",
                "properties": {
                    "title": {"type": "string"},
                    "content": {"type": "string"},
                    "tags": {"type": "array", "items": {"type": "string"}}
                },
                "required": ["title", "content"]
            }
        )
    ]

# 3. التعليمات: تفاعلات موحدة
@server.list_prompts()
async def list_prompts():
    return [
        Prompt(
            name="summarize_topic",
            description="تلخيص جميع المستندات حول موضوع",
            arguments=[
                PromptArgument(name="topic", required=True)
            ]
        )
    ]

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

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

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

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

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

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

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

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

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

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