خادم MCP

يأتي كل تطبيق Agent-Lab مع خادم Model Context Protocol مبني على FastMCP، ومركّب على المسار /mcp (Streamable HTTP، عديم الحالة). يمكن لعملاء MCP — مثل Claude Desktop وبيئات التطوير المتكاملة ووكلائك الخاصين — اكتشاف وكلاء التطبيق، وقراءة سجل المحادثات، والتحدث إلى الوكلاء مباشرة. ويشارك الخادم ومُسجِّلات الأدوات/الموجّهات الخاصة به في آلية الاكتشاف نفسها التي يستخدمها الوكلاء: scan_packages ومجموعة نقاط الدخول agent_lab.agents.

ما يوفّره الخادم

يعرض ثلاثي الموجّهات هذا موجّهات النظام الافتراضية لكل نوع وكيل، مع إمكانية التجاوز لكل مستأجر عبر agent_type + setting_key.

جرّبه باستخدام MCP Inspector

شغّل MCP Inspector واتصل بتطبيقك (مثل http://localhost:18000/mcp، مع النقل: Streamable HTTP):

npx @modelcontextprotocol/inspector

افتح وحدة التحكم على الويب (استخدم رابط الوكيل proxy المطبوع في الطرفية).

ربط Claude Desktop

ملاحظة: يُستخدم Claude Desktop هنا لأغراض العرض التوضيحي فقط. ولا يرتبط هذا المشروع بشركة Anthropic AI.

1. ثبّت جسر mcp-proxy الذي يستخدمه Claude Desktop للوصول إلى خوادم HTTP البعيدة:

   pip install mcp-proxy

2. افتح Settings → Developer → Edit Config وعدّل claude_desktop_config.json (عدّل نقطة النهاية بما يناسب تثبيتك؛ ويجب أن تحتوي بيئة Python على mcp-proxy):

3. أعد تشغيل Claude Desktop وانتقل مجدداً إلى Settings → Developer — ينبغي أن يظهر Agent-Lab:

4. جرّبه: اطلب من Claude عرض قائمة الوكلاء، أو جلب سجل محادثات نسخة من وكيل البرمجة الخاضع للإشراف، أو عرض مقتطف شيفرة أنشأه الوكيل سابقاً:

OpenAI Responses API

تسهّل أداة Model Context Protocol (MCP) المستضافة في Responses API الاتصال بالخدمات الخارجية: اضبط نموذجك مرة واحدة ليشير إلى خادم MCP — فيعمل بوصفه مضيفاً مركزياً للأدوات. (المصدر: MCP Tool Guide)

يتوفر دفتر يوضّح تكامل OpenAI Responses API مع خادم MCP في Agent-Lab على notebooks/11_mcp_client-openai-responses.ipynb.

إضافة أدواتك وموجّهاتك الخاصة

يُكتشف كل شيء بالطريقة نفسها التي يُكتشف بها الوكلاء — أضف المُزخرِف (decorator)، و(لمستخدمي المكتبة) تأكّد من أن حزمتك مدرجة في scan_packages أو منشورة عبر مجموعة نقاط الدخول agent_lab.agents.

أداة — دالة غير متزامنة (async) عادية؛ يُحقن المعامل الأول container فيها من حاوية حقن التبعيات (DI) ويكون مخفياً عن العملاء:

from agent_lab import discoverable_mcp_tool


@discoverable_mcp_tool(
    "my_hello_tool",
    description="Returns a friendly greeting.",
    annotations={"readOnlyHint": True},
)
async def hello_tool(container, name: str) -> str:
    return f"Hello, {name}!"

موجّه — يُتاح عبر ثلاثي الموجّهات الكامل (أداة / prompts/get / مورد prompt://):

from agent_lab import discoverable_mcp_prompt


@discoverable_mcp_prompt("my_greeting_prompt")
def greeting_prompt() -> str:
    return "Greet the user warmly and briefly."

متقدم — فئة فرعية كاملة من McpRegistrar (أو PromptSetRegistrar) لمجموعات مخصّصة من الأدوات/الموجّهات/الموارد، عبر @discoverable_mcp_registrar(extra_deps=(...)). لإضافة تعليمات MCP للعملاء، مرّر أجزاء نصية عند التجميع:

app = create_app(mcp_instructions=["Extra guidance for MCP clients."])

يأتي مثال عملي ضمن هيكل المشروع المُولَّد (mcp/tools.py، وmcp/prompts.py) — راجع وكيلك الأول.

المصادقة

عند تفعيل المصادقة، يصادق عملاء MCP عبر وكيل OAuth (OAuth proxy) يعتمد على Keycloak: التحقق من JWT مقابل JWKS الخاص بالـ realm (النطاقات openid وprofile وemail)، وتخزين عملاء OAuth في Redis (بشكل مشفّر). وينشر التطبيق نقاط نهاية البيانات الوصفية القياسية (/.well-known/oauth-protected-resource/mcp، /.well-known/oauth-authorization-server/mcp) لكي تتمكن العملاء المتوافقة من إعداد نفسها تلقائياً.