خادم MCP في 360 سطرًا بلا SDK: خمسة قرارات جعلت الوكيل يتوقف عن إفساد الروابط
بعد الرد «tool failed» يبدأ الوكيل بالتخمين: يكرّر الاستدعاء، أو يغيّر المعاملات، أو يعتذر. كتب مطوّر خدمة اختصار الروابط خادم MCP في 360 سطرًا بلغة Node.js دون SDK، وهو يكتفي بتمرير الطلبات إلى REST API الخاص بالخدمة. وصار يعيد الأخطاء كنتيجة عادية للأداة، والعمليات الدفعية مع نجاح جزئي. الخلاصة: ينبغي تصميم ردود API مع مراعاة النموذج أيضًا.
معالج بواسطة الذكاء الاصطناعي من Habr AI؛ بتحرير Hamidun News
ربط وكيل ذكي بخدمتك عبر Model Context Protocol (MCP) ليس أمرًا صعبًا. الصعوبة في جعله لا يرتبك ولا يرسل طلبات زائدة ولا يفسد البيانات. شارك مطوّر خدمة اختصار الروابط تجربته: خادم MCP الذي كتبه يشغل نحو 360 سطرًا بلغة Node.js الخالصة، بلا SDK ولا اعتماديات، وكل سطر تقريبًا ظهر بعد أن تصرّف Claude Code أو Cursor بطريقة غير متوقعة. السيناريو بسيط: الوكيل يكتب رسالة بريدية أو release notes، وينشئ بنفسه رابطًا مزوّدًا بوسوم UTM، ثم يراجع عدد النقرات.
غلاف رقيق بدل نسخة ثانية من المنطق
لا يحتوي الخادم على منطق أعمال خاص به. يستقبل استدعاء الأداة، ويتوجه إلى REST API القائم أصلًا باستخدام مفتاح، ثم يعيد الرد. أما التحقق من صحة المدخلات والحدود وفحوص الأمان فتبقى في جانب API.
وهذا يمنح ثلاث مزايا. القواعد تعيش في مكان واحد: إذا تغيّر حدّ ما أو فحص URL، حصلت جميع عملاء MCP على التغيير دون تحديث الحزمة. ويعمل الخادم محليًا عبر npx، ولا يحتاج إلا إلى المفتاح وعنوان API. واختباره سهل، لأنه مجرد ربط «أداة ← طلب HTTP».
والنقل بسيط أيضًا. يتواصل الخادم المحلي مع العميل عبر stdin وstdout برسائل JSON-RPC 2.0، سطر JSON واحد لكل رسالة. وتحسبًا لأي طارئ، يفهم المحلّل أيضًا الصيغة ذات الترويسة Content-Length كما في LSP. وهناك أمران صغيران يسهل التعثر بهما: يصل stdin على شكل أجزاء بأطوال عشوائية، لذا يلزم مخزن مؤقت يحتفظ بالباقي غير المعالَج، ولا يجوز الكتابة إلى stdout بأي شيء غير البروتوكول. يكفي console.log واحد منسي ليفصل العميل الخادم بصمت. ينبغي توجيه التصحيح إلى stderr.
خمسة قرارات تبيّن أنها أهم من غيرها
الأخطاء بوصفها بيانات. إذا أُعيد فشل API كخطأ JSON-RPC، فغالبًا ما يعرض العميل للنموذج عبارة «tool failed» فقط. بعدها يبدأ النموذج بالتخمين: يكرّر الاستدعاء، أو يغيّر المعاملات، أو يعتذر للمستخدم. أعاد المؤلف الخطأ كنتيجة عادية مع العلم isError: true، فدخل النص إلى السياق. وبقيت أخطاء البروتوكول للأعطال الحقيقية فقط: طريقة غير معروفة، أو أداة غير معروفة، أو JSON غير صالح. ويُكتب نص الخطأ موجّهًا للنموذج: فبدل «401» المجرّدة يرد «API_KEY is invalid. Create a key at…». وعند تلقي ذلك، لا يطرق الوكيل API مرارًا في الغالب، بل يرشد المستخدم إلى مكان الحصول على المفتاح.
وسوم الأدوات الخطرة. للأدوات تلميحات readOnlyHint وdestructiveHint وidempotentHint وopenWorldHint، وبها يقرّر العملاء متى يطلبون التأكيد. وُسمت أداتا حذف الرابط وتعطيله بأنهما destructive، وقراءة القائمة والإحصاءات بأنها read-only. يُضاف إلى ذلك عبارة «This cannot be undone» في الوصف، فيعيد النموذج السؤال إلى المستخدم من تلقاء نفسه. لكن هذه مجرد تلميحات لا حماية. القيود الحقيقية هي صلاحيات المفتاح والفحوص على الخادم.
تعامل متوقَّع مع URL. تحب النماذج «تصحيح» الروابط. إذا طلب المستخدم إضافة utm_source=newsletter بينما يحتوي URL أصلًا على utm_source=partner، فأيهما يغلب؟ قرر المؤلف: المعاملات الموجودة لا يُعاد كتابتها، والمرساة #fragment تُحفظ، فالوسوم في حملة جاهزة وضعها أحدهم عن قصد. وتثبّتت هذه القاعدة باختبار على API وكُتبت في وصف الأداة. والخلاصة عامة: إذا كان بوسع النموذج أن يمرّر معاملات زائدة أو متناقضة، فيجب أن يكون سلوك الخادم حتميًا وموصوفًا.
النجاح الجزئي في الدفعات. تنشئ الأداة shorten_urls عدة روابط دفعة واحدة. فإذا لم ينجح رابط واحد من عشرة في الفحص، فإن الاستثناء سيجعل النموذج يستنتج أن شيئًا لم ينجح، فيعيد تشغيل كل شيء من جديد، مع أن تسعة روابط أُنشئت فعلًا. لذلك يردّ API بكائن فيه المصفوفتان created وerrors، ويسلّمه الخادم كنتيجة عادية، حتى عند حدوث خطأ HTTP. فيعيد النموذج المحاولة للعناصر الفاشلة فقط.
الصور بوصفها صورًا. رمز QR بنص base64 يعني عدة كيلوبايتات من الرموز عديمة المعنى في السياق، أي رموز (tokens) زائدة وأموالًا مهدورة. في MCP نوع محتوى image: يعرض العميل الصورة، وبجانبها كتلة نصية قصيرة بالنوع والحجم. وهذا يكفي ليقول النموذج: «رمز QR جاهز، PNG، 4 كيلوبايت».
ما الذي كان المؤلف سيفعله بشكل مختلف
يستغرق الربط أمرًا واحدًا: claude mcp add مع المفتاح والعنوان عبر npx، أما في Cursor وClaude Desktop فيوصف الأمر نفسه في mcp.json. بعد ذلك يمكن مخاطبة الوكيل بنص عادي.
ويذكر المؤلف حدود هذا النهج بصراحة. كان ينبغي تصميم ردود API للنموذج منذ البداية: أسباب الأخطاء القصيرة والنجاح الجزئي الصريح مفيدان للتكاملات العادية أيضًا. وكتابة البروتوكول يدويًا مبرَّرة لأجل الفهم، لكن SDK الرسمي سيوفّر الوقت في الموارد والـprompts ونقل HTTP. ويجب الاختبار منذ البداية على عدة عملاء: Claude Code وCursor وMCP Inspector تعرض الأخطاء بطرق مختلفة، وتقرّر بطرق مختلفة متى تطلب التأكيد.
الخلاصة العملية لمن يبني MCP فوق API الخاص به: أبقِ المنطق على الخادم، واكتب الأخطاء كتعليمات للنموذج، ووسِم العمليات الخطرة، ولا تضع في السياق ما لا يستطيع النموذج قراءته.
- 21 نوفمبر 2026Text-to-cad: وكيل ذكاء اصطناعي يرسم أجزاء الروبوت من وصف نصي، والمشروع يحصد 26 ألف نجمة
- 21 نوفمبر 2026فيديو Claude في GTA 6 يبدو مفبركًا: نصف ساعة من التحكم استنزفت حد الساعات الخمس في اشتراك Pro
- 21 نوفمبر 2026Claude Code يسرّع فك تجميع لعبة Snowboard Kids 2: من 20% إلى 45% من الدوال خلال ثلاثة أشهر
- 21 نوفمبر 2026عدد وظائف FDE تضاعف 4.6 مرة خلال عام: ماذا يفعل المهندس في موقع العميل
أسئلة وأجوبة حول الخبر
ما أبرز التفاصيل حول غلاف رقيق بدل نسخة ثانية من المنطق؟
لا يحتوي الخادم على منطق أعمال خاص به. يستقبل استدعاء الأداة، ويتوجه إلى REST API القائم أصلًا باستخدام مفتاح، ثم يعيد الرد. أما التحقق من صحة المدخلات والحدود وفحوص الأمان فتبقى في جانب API. وهذا يمنح ثلاث مزايا. القواعد تعيش في مكان واحد: إذا تغيّر حدّ ما أو فحص URL، حصلت جميع عملاء MCP على التغيير دون تحديث الحزمة. ويعمل الخادم محليًا عبر npx، ولا يحتاج إلا إلى المفتاح وعنوان API. واختباره سهل، لأنه مجرد ربط «أداة ← طلب HTTP». والنقل بسيط أيضًا.
ما أبرز التفاصيل حول خمسة قرارات تبيّن أنها أهم من غيرها؟
الأخطاء بوصفها بيانات. إذا أُعيد فشل API كخطأ JSON-RPC، فغالبًا ما يعرض العميل للنموذج عبارة «tool failed» فقط. بعدها يبدأ النموذج بالتخمين: يكرّر الاستدعاء، أو يغيّر المعاملات، أو يعتذر للمستخدم. أعاد المؤلف الخطأ كنتيجة عادية مع العلم isError: true، فدخل النص إلى السياق. وبقيت أخطاء البروتوكول للأعطال الحقيقية فقط: طريقة غير معروفة، أو أداة غير معروفة، أو JSON غير صالح. ويُكتب نص الخطأ موجّهًا للنموذج: فبدل «401» المجرّدة يرد «API_KEY is invalid. Create a key at…».
ما أبرز التفاصيل حول ما الذي كان المؤلف سيفعله بشكل مختلف؟
يستغرق الربط أمرًا واحدًا: claude mcp add مع المفتاح والعنوان عبر npx، أما في Cursor وClaude Desktop فيوصف الأمر نفسه في mcp.json. بعد ذلك يمكن مخاطبة الوكيل بنص عادي. ويذكر المؤلف حدود هذا النهج بصراحة. كان ينبغي تصميم ردود API للنموذج منذ البداية: أسباب الأخطاء القصيرة والنجاح الجزئي الصريح مفيدان للتكاملات العادية أيضًا. وكتابة البروتوكول يدويًا مبرَّرة لأجل الفهم، لكن SDK الرسمي سيوفّر الوقت في الموارد والـprompts ونقل HTTP.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
أهم ما في عالم الذكاء الاصطناعي — مرة كل أسبوع
سبع قصص مهمة فعلاً هذا الأسبوع، مختارة بعناية. بلا ضجيج ولا بيانات صحفية.
تم! تحقق من بريدك للتأكيد.