دليل اختبار خادم MCP: يدوي + آلي باستخدام Apidog

منشور "Ableton Live MCP" على Show HN وصل إلى 118 نقطة و 78 تعليقًا في وقت سابق من هذا الأسبوع. النمط أصبح مألوفًا الآن: أحدهم كتب خادم بروتوكول سياق النموذج (Model Context Protocol) لأداة غير متوقعة، وقد أحبه جمهور Claude Desktop، وتلت ذلك موجة من منشورات "هل يجب أن أكتب واحدًا لـ X؟". تحول MCP من تجربة مقتصرة على Anthropic إلى طبقة تكامل وكيل افتراضية في أقل من عام.

ما تخفيه هذه النمو هو ثغرة في الأدوات: لم يقم أحد بعد بتوفير طريقة نظيفة لاختبار خوادم MCP. تشغيل JSON-RPC يدويًا عبر stdio باستخدام مصحح الأخطاء جيد لـ "hello-world"؛ لكنه ينهار بمجرد أن يحتوي خادمك على 12 أداة، و 3 مطالبات، وواجهة برمجة تطبيقات عليا متقلبة. يقدم هذا الدليل خطة عمل عملية لاختبار خوادم MCP يدويًا وأتمتة هذه الاختبارات باستخدام Apidog، بحيث يمكنك شحن خوادم MCP بنفس الطريقة التي تشحن بها أي واجهة برمجة تطبيقات أخرى: بعقد، ونموذج، وحزمة اختبار تراجعي.

إذا كنت قادمًا من سياق وكيل أكثر عمومية، فإن دليل agents.md الخاص بنا يتناسب جيدًا مع هذا؛ فالاتفاقيات الواردة فيه تجعل عقود خادم MCP أسهل في التواصل مع فريقك.

باختصار

• MCP هو بروتوكول سياق النموذج (Model Context Protocol) من Anthropic؛ وهو JSON-RPC 2.0 عبر stdio أو HTTP ويكشف عن ثلاثة بدائيات: الأدوات، الموارد، والمطالبات.
• اختبار خادم MCP يعني التحقق من استجاباته لـ initialize، tools/list، tools/call، resources/read، و prompts/get مقابل عقد.
• ابدأ يدويًا: قم بتشغيل الخادم من سطر الأوامر باستخدام stdio، وتأكد من الاستجابات بالعين، وقم بإصلاح أخطاء الشكل قبل إضافة العملاء.
• انتقل إلى الأتمتة: التقط حركة مرور JSON-RPC في Apidog، وحوّل كل استدعاء إلى طلب محفوظ، وابنِ تأكيدات على شكل المحتوى والاستجابة، وقم بتشغيل الحزمة في CI.
• استخدم خادم Apidog الوهمي لمحاكاة واجهات برمجة التطبيقات العليا التي يستدعيها خادم MCP الخاص بك، بحيث تظل الاختبارات حتمية.
• قم بتنزيل Apidog للحصول على مجموعة الطلبات والخادم الوهمي ومُشغّل CI في مكان واحد.

ما هو MCP حقًا، في دقيقتين

مواصفات بروتوكول سياق النموذج تُعرّف تنسيق سلك JSON-RPC 2.0 بواجهة صغيرة. يقوم العميل (Claude Desktop، Cursor، وكيلك الخاص) بتشغيل خادم MCP، ويُجري مصافحة initialize، ثم يُصدر الاستدعاءات.

الاستدعاءات الخمسة التي ستقضي 90 بالمائة من وقتك في اختبارها:

• initialize: التفاوض على الإصدار والكشف عن الإمكانيات.
• tools/list: يُرجع الخادم الأدوات التي يكشفها، بما في ذلك JSON Schema للوسائط.
• tools/call: يستدعي العميل أداة بالاسم مع وسائط.
• resources/list و resources/read: يكشف الخادم عن محتوى يمكن قراءته مُعنون بواسطة URI.
• prompts/list و prompts/get: يكشف الخادم عن قوالب المطالبات التي يمكن للعميل عرضها.

النقل إما stdio (إطارات JSON-RPC مفصولة بأسطر جديدة على stdin/stdout) أو HTTP قابل للتدفق (عادةً POST / مع SSE للتدفق). تستخدم معظم الخوادم المحلية stdio؛ بينما تستخدم الخوادم البعيدة HTTP.

لماذا يهم الاختبار: كل مستخدم لـ Claude Desktop، كل مستخدم لـ Cursor، كل بيئة تطوير متكاملة (IDE) تضيف دعم MCP ستستدعي خادمك. الأخطاء في شكل tools/list ستعطل كل العملاء دفعة واحدة. تكلفة التراجع عالية.

ما يجب عليك اختباره

تغطية مجموعة اختبار MCP قوية ستة أبعاد.

امتثال البروتوكول. هل تُرجع initialize قيمة protocolVersion الصحيحة؟ هل يُعلن الخادم عن الإمكانيات التي يدعمها بالفعل؟

صحة المخطط. هل تحتوي كل أداة في tools/list على JSON Schema صالح للوسائط؟ هل الحقول المطلوبة معلمة؟ هل الوصف أطول من ثلاث كلمات؟ الأوصاف الفارغة تعطل اختيار الأداة في Claude.

سلوك الأداة. لكل أداة، هل تُرجع tools/call كتل محتوى من النوع الصحيح (text، image، resource)؟ هل تُرجع حالات الخطأ نتيجة isError: true بدلاً من إلقاء أخطاء JSON-RPC؟

الوصول إلى الموارد. هل يتم حل عناوين URI لـ resources/list عند استدعائها عبر resources/read؟ هل يعمل التصفح بعد الصفحة الأولى؟

عرض المطالبات. هل تُرجع المطالبات مصفوفات messages حسنة التكوين؟ هل تصل استبدالات الوسائط إلى الأماكن الصحيحة؟

أوضاع الفشل. ماذا يحدث عندما تكون واجهة برمجة تطبيقات عليا معطلة؟ عندما تكون وسيطة أداة مفقودة؟ عندما ينتهي وقت العميل؟ هذه هي الأخطاء التي تظهر في الإنتاج، وليس في "hello-world".

بقية هذا الدليل يتناول كل واحدة من هذه، يدويًا أولاً، ثم آليًا.

الاختبار اليدوي باستخدام stdio

ابدأ بأبسط إعداد ممكن: محطة طرفية، ملف الخادم الثنائي الخاص بك، ومفتش MCP أو JSON-RPC الخام يدويًا.

إذا لم تكن قد قمت ببناء خادم بعد، فقم بتأسيس واحد باستخدام البدء السريع الرسمي لـ MCP SDK في Python أو TypeScript. مثال الطقس ذو الأداتين يكفي للاختبار ضده.

قم بتشغيل الخادم في وضع المفتش:

npx @modelcontextprotocol/inspector node your-server.js

يقوم المفتش بتشغيل واجهة مستخدم ويب محلية تتحدث MCP مع خادمك وتعرض لك كل طلب واستجابة. هذه هي أسرع طريقة للتأكد من أن الخادم يبدأ، ويعلن عن الإمكانيات، ويستجيب لـ tools/list.

بمجرد أن تبدو واجهة المفتش صحيحة، قم بتشغيل نفس التدفق باستخدام stdio الخام حتى تتمكن من التقاط الإطارات لـ Apidog:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

ستحصل على استجابة JSON-RPC على stdout. احفظ الطلب والاستجابة. كرر ذلك لـ tools/list و tools/call و resources/list والباقي. بنهاية هذا التمرين، سيكون لديك 6 إلى 12 زوجًا من الطلبات والاستجابات الكنسية التي تحدد العقد على مستوى السلك لخادمك.

شيئان يجب الانتباه إليهما.

أولاً، كتل المحتوى. تُرجع نتيجة الأداة content: [{ type: "text", text: "..." }] أو content: [{ type: "image", data: "...", mimeType: "image/png" }]. يُسمح بخلط الأنواع في استجابة واحدة؛ وتختلف العملاء في كيفية عرضها.

ثانيًا، الأخطاء. مواصفات MCP واضحة: تُرجع أخطاء تنفيذ الأداة نتيجة طبيعية مع isError: true وكتلة محتوى تصف الفشل. لا تُلقِ استجابات أخطاء JSON-RPC من داخل أداة؛ فهذا يشير إلى فشل على مستوى البروتوكول، وليس على مستوى الأداة. العديد من العملاء يقطعون الاتصال عند حدوث أخطاء في البروتوكول.

من اليدوي إلى الآلي: بناء مجموعة الاختبار في Apidog

يكشف الاختبار اليدوي عن الأخطاء الواضحة. تنتقل إلى الأتمتة عندما تبدأ في التساؤل، "هل أحدث تغيير أجريته كسر مخطط وسيطة الأداة 7؟" ولا ترغب في كتابة 12 أمر curl لمعرفة ذلك.

النمط: خذ كل زوج طلب-استجابة قمت بحفظه أثناء الاختبار اليدوي، والصقه في Apidog كطلب محفوظ، ثم أضف تأكيدات، وقم بتشغيل المجموعة عند كل دفع.

1. إنشاء مشروع Apidog لخادم MCP

افتح Apidog، أنشئ مشروعًا جديدًا، اضبط عنوان URL الأساسي لنقطة نهاية HTTP لخادم MCP الخاص بك (أو عنوان URL لجسر stdio؛ انظر أدناه). تدعم مشاريع Apidog كلاً من REST و JSON-RPC؛ قم بإنشاء بيئة JSON-RPC.

بالنسبة لخوادم stdio التي لا تحتوي على واجهة HTTP، قم بتشغيلها خلف غلاف HTTP رقيق للاختبار. يوفر المفتش الرسمي واحدًا؛ بدلاً من ذلك، فإن نص Node من 30 سطرًا يقرأ JSON-RPC عبر HTTP ويعيد توجيهه إلى stdio يعمل بشكل جيد. نستخدم نفس النمط في اختبار واجهة برمجة التطبيقات بدون Postman في 2026 للخلفيات غير HTTP.

2. حفظ الطلبات الكنسية

لكل من initialize و tools/list و tools/call و resources/list و resources/read و prompts/list و prompts/get، احفظ نص JSON-RPC كطلب. يخزن Apidog هذه الطلبات مع النص الأساسي والرؤوس والحالة المتوقعة.

طلب tools/call يبدو هكذا في عرض نص طلب Apidog:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. إضافة تأكيدات

الهدف من الأتمتة هو التأكيد على الاستجابة، وليس إرسال الطلب. يدعم Apidog تأكيدات JSONPath بشكل أصلي. بالنسبة لـ tools/list، ستحتاج على الأقل إلى:

• وجود $.result.tools
• $.result.tools.length أكبر من صفر
• كل أداة تحتوي على name و description و inputSchema
• كل inputSchema هو JSON Schema صالح

بالنسبة لـ tools/call على مدخل معروف جيد، ستحتاج إلى:

• $.result.isError خاطئ (أو غير موجود)
• $.result.content هو مصفوفة
• كتلة المحتوى الأولى تحتوي على type والمحتوى المتوقع

بالنسبة لـ tools/call على مدخل معروف سيء (وسيطة مطلوبة مفقودة) ستحتاج إلى:

• $.result.isError صحيح
• $.result.content[0].text يطابق رسالة الخطأ المتوقعة

يخزن Apidog هذه التأكيدات لكل طلب. تظهر الأخطاء في تقرير التشغيل.

4. محاكاة واجهات برمجة التطبيقات العليا

معظم خوادم MCP تغلف واجهة برمجة تطبيقات خارجية: بيانات الطقس، GitHub، Linear، قاعدة بيانات داخلية. لا ترغب في أن تصل عمليات تشغيل CI إلى واجهات برمجة التطبيقات الحية مع كل التزام. لسببين: التكلفة والتقلب.

خادم Apidog الوهمي المدمج يحل هذه المشكلة. قم بتعريف كل نقطة نهاية عليا كمسار وهمي يُرجع نص JSON واقعي. وجه تهيئة خادم MCP الخاص بك إلى عنوان URL الوهمي أثناء الاختبارات وإلى الإنتاج أثناء التشغيلات الفعلية. نغطي سير عمل المحاكاة بالتفصيل في تطوير واجهة برمجة التطبيقات القائم على العقد أولاً.

النتيجة: مجموعة اختبار تعمل في ثوانٍ، ولا تتطلب شبكة خارجية، وتلتقط انحدارات المخطط قبل وقت طويل من شحنها.

5. تشغيل المجموعة في CI

يمكن لمشاريع Apidog التصدير إلى أدوات تشغيل CLI. يأخذ أمر apidog run معرّف مشروع، ويشغل كل طلب محفوظ، ويقيّم التأكيدات، ويخرج بقيمة غير صفرية عند الفشل. قم بربطه بـ GitHub Actions أو أي مزود CI تستخدمه بالفعل.

تدفق عمل بسيط:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

كل دفع يقوم بتشغيل عقد MCP بالكامل. لا يمكن أن يتم الوصول إلى تراجع مخطط الأداة 7 دون أن يظهر.

كيف تبدو التغطية الجيدة للاختبار

خطة اختبار خادم MCP كاملة في Apidog تتضمن عادةً:

• 1 طلب initialize مع تأكيدات القدرة
• 1 طلب tools/list مع تأكيدات الشكل و JSON Schema
• 2 إلى 4 طلبات tools/call لكل أداة: المسار الصحيح، وسيطة مفقودة، نوع غير صالح، خطأ في النظام العلوي
• 1 resources/list بالإضافة إلى 1 resources/read لكل عائلة موارد
• 1 prompts/list بالإضافة إلى 1 prompts/get لكل قالب مطالبة

لخادم يحتوي على 10 أدوات مع 3 موارد و 4 مطالبات، تصل المجموعة إلى 50 إلى 70 طلبًا. يقوم Apidog بتشغيلها محليًا في أقل من 10 ثوانٍ مع تشغيل الخادم الوهمي.

الأخطاء الشائعة عند اختبار خوادم MCP

هذه هي الأنماط التي نراها غالبًا.

تخطي جولة initialize. تتعطل العديد من الخوادم عند tools/list إذا لم يتم استدعاء initialize مطلقًا لأنها تبني سجل أدواتها ببطء داخل عملية المصافحة. قم دائمًا بتشغيل initialize أولاً.

التأكيد على سلاسل الأخطاء الخام. ستتغير رسائل فشل الأداة. أكد على isError: true وعلى رمز خطأ ثابت أو تعبير عادي، وليس على تطابقات السلسلة الدقيقة.

ترك المحاكاة تنجرف عن الإنتاج. محاكاة تُرجع أشكالًا لا تُرجعها واجهة برمجة التطبيقات الحقيقية أبدًا تمنحك اختبارات ناجحة على تكامل معطل. أعد تسجيل تركيبات المحاكاة من الاستجابات الحقيقية في كل إصدار.

نسيان التدفق (Streaming). خوادم HTTP MCP تُدفق نتائج الأدوات عبر SSE. يجب أن يتعامل مُشغّل الاختبار الخاص بك مع SSE؛ و Apidog يفعل ذلك، ولكن عليك تمكين التدفق في الطلب.

عدم اختبار التزامن. ترسل عملاء MCP طلبات tools/call متزامنة في حلقات الوكيل. إذا كان خادمك يحتفظ بحالة مشتركة بدون أقفال، فإن اختبارات الطلب الواحد ستنجح وينهار الإنتاج. أضف اختبار تشغيل متوازي إلى المجموعة.

خلط أخطاء البروتوكول مع أخطاء الأداة. مواصفات MCP تفصل بينهما عمدًا؛ خلطهما يجعل Claude Desktop يغلق الاتصال. لقد غطينا نفس النوع من أخطاء العقد في تطوير منصة API القائم على العقد أولاً.

حالات الاستخدام الواقعية

فريق يقوم ببناء خادم MCP داخلي لواجهة برمجة تطبيقات إدارة الحوادث في شركته اكتشف ثلاثة تراجعات في أسبوع واحد باستخدام تأكيدات Apidog على شكل tools/list. بدون الاختبار، كانت الأخطاء ستصل إلى كل مهندس يستخدم Claude Desktop في وقت واحد.

يستخدم مطور منفرد ينشر خادم MCP مفتوح المصدر لـ Notion نماذج Apidog لتشغيل مجموعة الاختبار دون الوصول إلى حدود معدل Notion خلال CI. تعمل مجموعتهم على كل طلب سحب، وتستغرق 8 ثوانٍ، وتخزن تركيبات Apidog الوهمية في المستودع حتى لا يحتاج المساهمون إلى الوصول إلى واجهة برمجة التطبيقات للتطوير.

فريق المنصة الذي يدير 14 خادم MCP داخليًا قام ببناء مساحة عمل Apidog مشتركة حيث تعيش عقود كل خادم. ترث الخوادم الجديدة مجموعة اختبار أساسية؛ يمكن للمراجعين مقارنة اختلافات المخطط جنبًا إلى جنب قبل الدمج. أبلغ الفريق عن منع انقطاعين في الربع الأول، وكلاهما تم اكتشافهما بواسطة تأكيدات شكل tools/list على طلب سحب كان سيشحن وسيطة معاد تسميتها لكل مستخدم لـ Claude Desktop داخل الشركة.

فريق ثانٍ يقوم ببناء خادم MCP لمنصة مراقبة داخلية يستخدم مبدل بيئة Apidog لتشغيل نفس المجموعة ضد بيئات التطوير والإنتاج. تشير كل بيئة إلى ملف تركيب وهمي مختلف، لذا تؤكد نفس الـ 60 تأكيدًا كلا النشرتين دون إعادة كتابة طلب واحد.

الخاتمة

أصبح MCP شائعًا هذا العام، لكن قصة الاختبار لا تزال حيث كانت اختبار واجهات برمجة تطبيقات REST قبل عقد من الزمان: مخصص، يدوي، هش. ليس عليك الانتظار حتى يلحق النظام البيئي. تعامل مع خادم MCP الخاص بك كواجهة برمجة تطبيقات حقيقية، صمم عقدًا، قم بمحاكاة الأنظمة العليا، وقم بتشغيل التأكيدات في CI.

خمس نقاط رئيسية:

• خادم MCP هو واجهة برمجة تطبيقات JSON-RPC؛ اختبره بنفس الدقة التي تختبر بها واجهة برمجة تطبيقات REST.
• ابدأ يدويًا باستخدام المفتش الرسمي، ثم التقط الطلبات الكنسية وانتقل إلى الأتمتة.
• يتعامل Apidog مع JSON-RPC، والتأكيدات، والمحاكاة، و CI في مشروع واحد.
• غطِ الأبعاد الستة: امتثال البروتوكول، صحة المخطط، سلوك الأداة، الوصول إلى الموارد، عرض المطالبات، وأوضاع الفشل.
• قم بمحاكاة واجهات برمجة التطبيقات العليا في Apidog بحيث تظل مجموعة الاختبار سريعة وحتمية.

الخطوة التالية: افتح Apidog، أنشئ مشروعًا، الصق نصوص الطلبات التي التقطتها يدويًا، أضف تأكيدات JSONPath لـ tools/list، وقم بتشغيل المجموعة. ستعرف في غضون ساعة ما إذا كان عقد خادمك قويًا بما يكفي للشحن.

الأسئلة الشائعة

ما هو MCP؟

MCP، بروتوكول سياق النموذج (Model Context Protocol)، هو مواصفات Anthropic المفتوحة لكيفية استدعاء عملاء الذكاء الاصطناعي (مثل Claude Desktop) للأدوات والموارد والمطالبات الخارجية. إنه JSON-RPC 2.0 عبر stdio أو HTTP قابل للتدفق. المواصفات الكاملة لـ MCP منشورة على modelcontextprotocol.io.

هل يمكنني اختبار خادم MCP بدون غلاف HTTP؟

نعم. المفتش الرسمي لـ MCP يتحدث stdio مباشرة ويوفر لك واجهة مستخدم للاختبار اليدوي. للاختبار الآلي في Apidog، قم بتغليف stdio في خادم HTTP رفيع أثناء CI؛ لا تزال حركة مرور الإنتاج تمر عبر stdio.

كيف أقوم بمحاكاة واجهات برمجة التطبيقات العليا التي يستدعيها خادم MCP الخاص بي؟

حدد كل نقطة نهاية عليا كنموذج (mock) في مشروع Apidog الخاص بك، وجه إعدادات خادم MCP إلى عنوان URL للنموذج أثناء الاختبارات، ثم قم بالتبديل إلى عناوين URL الإنتاجية أثناء التشغيل. نشرح نفس النمط في أدوات اختبار واجهة برمجة التطبيقات لمهندسي ضمان الجودة.

ماذا عن نتائج أدوات التدفق؟

تقوم خوادم HTTP MCP ببث نتائج الأدوات عبر Server-Sent Events. يدعم Apidog SSE في الطلبات المحفوظة؛ قم بتشغيله في إعدادات الطلب وتأكد من التدفق المجمع.

هل يجب علي اختبار إصدار البروتوكول؟

نعم. قم بتثبيت protocolVersion الذي تدعمه في initialize وتأكد منه. عدم التطابق يسبب عدم توافق صامت للعميل.

هل يمكنني اختبار خادم MCP الخاص بي مقابل Claude Desktop الحقيقي؟

يمكنك ذلك، ويجب عليك مرة واحدة على الأقل قبل كل إصدار. لكن لا تعتمد على Claude Desktop كحلقة اختبار لك؛ إنه بطيء، يدوي، وغير حتمي. استخدم Apidog لمجموعة اختبار الانحدار و Claude Desktop لاختبار الدخان.

أين يمكنني رؤية أمثلة لخوادم MCP حقيقية؟

يحتوي مستودع خوادم MCP الرسمي على تطبيقات مرجعية لأنظمة الملفات، GitHub، Slack، Postgres، والعشرات غيرها. اقرأ تعريفات الأدوات؛ إنها أسهل طريقة لفهم كيف يبدو شكل MCP الجيد.