إصدار Laravel MCP 1.0 يضيف ToolSearch ويدعم بروتوكول MCP الأحدث

أصدر فريق Laravel النسخة 1.0 من حزمة Laravel MCP، وهي أول نسخة مستقرة من الحزمة المخصصة لبناء خوادم Model Context Protocol (MCP) ضمن تطبيقات Laravel. تتيح هذه الخوادم لتطبيقات الذكاء الاصطناعي الوصول إلى أدوات وبيانات التطبيق وفق بروتوكول MCP.

يتوافق الإصدار الجديد مع MCP revision 2026-07-28، مع استمرار دعم العملاء الأقدم الذين ما زالوا يبدأون الاتصال عبر initialize. في هذه الحالة، يستجيب الخادم بإصدار البروتوكول 2025-11-25 أو 2025-06-18 بحسب ما يطلبه العميل.

البحث في الأدوات بدلاً من تحميلها كلها

أبرز الإضافات هي Searchable Tool Catalogs عبر ToolSearch. بدلاً من إرسال تعريف جميع أدوات الخادم إلى النموذج منذ البداية، يمكن إبقاء الأدوات الشائعة في القائمة الرئيسية ووضع الأدوات الأقل استخداماً خلف بحث عند الحاجة.

هذا مهم لأن تعريفات الأدوات تستهلك مساحة من context window للنموذج. تسجل الحزمة أداتي search_tools للعثور على الأدوات بالاسم أو الوصف أو المدخلات المتوقعة، وexecute_tools لتشغيل أداة أو أكثر بالاسم بعد اكتشافها.

protected array $tools = [
    CurrentWeatherTool::class,

    ToolSearch::class => [
        HistoricalWeatherTool::class,
        WeatherAlertsTool::class,
    ],
];

Cache hints لاستجابات MCP

يمكن للخادم الآن إعلام العميل بالاستجابات التي يستطيع تخزينها مؤقتاً، ومدة الاحتفاظ بها، وما إذا كان يمكن مشاركتها بين المستخدمين. يُضبط السلوك الافتراضي عبر attribute باسم Cacheable، ويمكن تخصيصه لكل MCP method من خلال cacheHints().

عميل MCP في Laravel يتبع هذه التلميحات عند تفعيل التخزين المؤقت باستخدام withCache(). الاستجابات التي لا تحتوي ttlMs أو تكون قيمته صفراً لا تُخزّن، كما أن استدعاءات الأدوات نفسها غير قابلة للتخزين المؤقت.

خوادم stateless وتغيير في إدارة الجلسات

في البروتوكول الجديد، يعالج الخادم كل طلب بصورة مستقلة. يتضمن كل طلب HTTP أو رسالة stdio إصدار البروتوكول والقدرات التي يدعمها العميل ضمن params._meta.

بناءً على ذلك، أزيلت MCP-Session-Id وRequest::sessionId() وRequest::setSessionId() وحدث SessionInitialized. وإذا احتاج التطبيق إلى ربط الاستدعاءات ذات الصلة، فعليه تمرير معرفه الخاص ضمن arguments الطلب أو _meta.

OAuth يتطلب PKCE

أصبح دعم PKCE مطلوباً في مسار OAuth. سترمي OAuthClient::redirect() استثناء OAuthException إذا لم تعرض بيانات خادم التفويض code_challenge_methods_supported، بعدما كان السلوك السابق يرفض فقط الخوادم التي تعلن الحقل من دون دعم S256.

ويضيف الإصدار دعم Client ID Metadata Documents: يمكن أن يكون client_id رابط HTTPS لوثيقة JSON تعرّف العميل. وتوفر Mcp::oAuthRoutesFor() هذه الوثيقة على المسار GET /mcp/oauth/{client}/client-metadata.json.

عند استخدام وثيقة metadata، ستكون قيمة $token->clientSecret هي null، لذلك يجب أن تسمح قاعدة البيانات بقيمة فارغة في أي عمود يخزنها. ويعالج هذا التغيير أيضاً مشكلة كانت تسجل عميلاً جديداً لدى خادم التفويض في كل مرة يُنفذ فيها redirect().

ما الذي يجب مراجعته عند الترقية؟

على من يرقّي من الإصدار 0.9 مراجعة طريقة اتصال العملاء وإرسالهم للطلبات. يعمل middleware الجديد ValidateMcpHeaders على جميع المسارات المسجلة عبر Mcp::web().

في طلبات POST وفق البروتوكول الجديد، يجب أن تتطابق ترويسات MCP-Protocol-Version وMcp-Method مع محتوى الطلب. كما تحتاج استدعاءات tools/call وprompts/get وresources/read إلى ترويسة Mcp-Name المطابقة لاسم الأداة أو prompt أو URI الخاص بالمورد.

أي اختلاف يعيد HTTP 400 مع خطأ JSON-RPC بالرمز -32020. أما العملاء الأقدم الذين يستخدمون initialize ولا يرسلون metadata للبروتوكول ضمن _meta، فلا تنطبق عليهم هذه المصادقة للترويسات.