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

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

جرّب Apidog اليوم

لكن النمو السريع كشف فجوة واضحة: اختبار خوادم MCP ما زال بدائيًا. تشغيل JSON-RPC يدويًا عبر stdio مناسب لتجربة "hello world"، لكنه ينهار عندما يحتوي الخادم على 12 أداة، و3 مطالبات، وتكاملات خارجية غير مستقرة. في هذا الدليل سنبني طريقة عملية لاختبار خادم MCP يدويًا، ثم تحويل نفس الاختبارات إلى مجموعة آلية في Apidog، بحيث تتعامل مع خادم MCP مثل أي API: عقد واضح، نماذج mock، وتأكّدات regression في CI.

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

باختصار

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

ما هو MCP عمليًا؟

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

أغلب الاختبارات ستدور حول هذه الاستدعاءات:

• 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.

سبب أهمية الاختبار بسيط: أي خطأ في شكل tools/list أو tools/call قد يكسر Claude Desktop وCursor وأي عميل MCP آخر في نفس اللحظة.

ما الذي يجب اختباره؟

غطِّ ستة محاور رئيسية.

1. امتثال البروتوكول

تأكد من أن initialize يعيد:

• protocolVersion المتوقعة.
• capabilities التي يدعمها الخادم فعليًا.
• معلومات الخادم الأساسية إن كانت مطلوبة في تطبيقك.

مثال طلب:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. صحة المخطط

في tools/list، تحقق من أن كل أداة تحتوي على:

• name
• description
• inputSchema

ولا تكتفِ بوجود inputSchema. تأكد أنه JSON Schema صالح، وأن الحقول المطلوبة مذكورة في required.

3. سلوك الأدوات

لكل أداة، اختبر:

• مسار النجاح.
• وسيطة مفقودة.
• نوع غير صحيح.
• فشل في API خارجي.
• timeout إن كان ممكنًا.

الاستجابة الناجحة يجب أن تحتوي على content بشكل صحيح:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Weather in Tokyo: 22°C"
      }
    ]
  }
}

أما خطأ تنفيذ الأداة فيجب أن يكون نتيجة عادية مع isError: true، وليس JSON-RPC protocol error:

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Missing required argument: city"
      }
    ]
  }
}

4. الوصول إلى الموارد

اختبر أن كل URI يظهر في resources/list يمكن قراءته عبر resources/read.

وتأكد من:

• نوع المحتوى.
• الترميز.
• pagination إن كان المورد يدعم صفحات.
• السلوك عند طلب URI غير موجود.

5. عرض المطالبات

في prompts/get، تحقق من أن الاستجابة تحتوي على messages سليمة، وأن الوسائط تُحقن في الأماكن الصحيحة.

6. أوضاع الفشل

اختبر الحالات التي تحدث في الإنتاج:

• API خارجي متوقف.
• credentials غير صالحة.
• rate limit.
• timeout.
• بيانات upstream بشكل غير متوقع.

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

ابدأ بأبسط إعداد:

• الطرفية.
• ملف خادم MCP.
• MCP Inspector أو JSON-RPC خام.

إذا لم تبنِ خادمًا بعد، استخدم البدء السريع الرسمي لـ MCP SDK في Python أو TypeScript. مثال الطقس كافٍ لبناء مجموعة اختبار أولية.

شغّل الخادم عبر المفتش:

npx @modelcontextprotocol/inspector node your-server.js

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

• أن الخادم يبدأ بدون أخطاء.
• أن initialize ينجح.
• أن tools/list يعرض الأدوات.
• أن tools/call يعيد محتوى مفهومًا.

بعد ذلك، شغّل نفس التدفق يدويًا عبر stdio لالتقاط الطلبات التي ستنقلها لاحقًا إلى Apidog:

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

احفظ الطلب والاستجابة. كرر ذلك مع:

• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

في النهاية، سيكون لديك 6 إلى 12 زوجًا من الطلبات والاستجابات تمثل العقد الفعلي لخادمك.

نقاط يجب الانتباه لها أثناء الاختبار اليدوي

كتل المحتوى

نتيجة الأداة يجب أن تعيد content كمصفوفة. أمثلة صحيحة:

{
  "content": [
    {
      "type": "text",
      "text": "done"
    }
  ]
}

{
  "content": [
    {
      "type": "image",
      "data": "base64...",
      "mimeType": "image/png"
    }
  ]
}

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

أخطاء الأداة

لا تستخدم JSON-RPC error لفشل منطقي داخل الأداة. استخدم:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Upstream API failed"
    }
  ]
}

JSON-RPC error يجب أن يبقى لأخطاء البروتوكول، مثل method غير معروف أو payload غير صالح.

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

الاختبار اليدوي يكشف الأخطاء الواضحة. لكنه لا يجيب بسرعة على سؤال مثل:

هل التغيير الأخير كسر inputSchema للأداة السابعة؟

الحل: حوّل الطلبات التي حفظتها إلى مجموعة اختبار آلية في Apidog.

النمط العملي:

1. أنشئ مشروعًا.
2. أضف طلبات JSON-RPC.
3. أضف تأكيدات JSONPath.
4. استخدم mock server للأنظمة الخارجية.
5. شغّل المجموعة في CI.

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

افتح Apidog وأنشئ مشروعًا جديدًا.

إذا كان خادم MCP لديك يعمل عبر HTTP، اضبط Base URL مباشرة على endpoint الخاص به.

إذا كان يعمل عبر stdio فقط، استخدم غلاف HTTP رقيق أثناء الاختبار. الفكرة:

• Apidog يرسل HTTP request.
• wrapper يستقبل JSON-RPC.
• wrapper يمرره إلى خادم MCP عبر stdio.
• يعيد الاستجابة إلى Apidog.

يمكنك استخدام المفتش الرسمي أو كتابة wrapper بسيط في Node.js. نفس النمط مفيد عند اختبار خدمات غير HTTP، كما في اختبار واجهة برمجة التطبيقات بدون Postman في 2026.

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

أنشئ طلبًا لكل استدعاء مهم:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

مثال طلب tools/call:

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

احفظ نسخة لمسار النجاح ونسخًا أخرى لحالات الفشل.

مثال لمدخل غير صالح:

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

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

الهدف ليس فقط إرسال الطلب. الهدف هو التأكد من شكل الاستجابة.

تأكيدات initialize

أضف تأكيدات مثل:

• $.result.protocolVersion يساوي الإصدار المتوقع.
• $.result.capabilities موجود.
• لا توجد $.error.

تأكيدات tools/list

تأكد من:

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

مثال checks عملية:

$.result.tools exists
$.result.tools[0].name exists
$.result.tools[0].description exists
$.result.tools[0].inputSchema exists

تأكيدات tools/call لمسار النجاح

تأكد من:

• $.result.isError غير موجود أو يساوي false.
• $.result.content مصفوفة.
• $.result.content[0].type موجود.
• $.result.content[0].text يحتوي على قيمة متوقعة إن كانت الاستجابة نصية.

تأكيدات tools/call لمسار الفشل

لوسيطة مفقودة مثلًا، تأكد من:

• $.result.isError يساوي true.
• $.result.content[0].type يساوي text.
• $.result.content[0].text يطابق regex ثابتًا بدل مقارنة النص الكامل.

لا تجعل الاختبار هشًا بمقارنة رسالة خطأ كاملة قد تتغير لاحقًا.

4. محاكاة واجهات API الخارجية

معظم خوادم MCP تغلف أنظمة خارجية:

• Weather API
• GitHub
• Linear
• Notion
• قاعدة بيانات داخلية
• منصة مراقبة

لا تجعل CI يعتمد على هذه الخدمات مباشرة. ستواجه:

• rate limits.
• تكلفة أعلى.
• نتائج غير حتمية.
• فشل عابر خارج سيطرتك.

استخدم mock server في Apidog:

1. عرّف endpoint الخارجي كمسار mock.
2. أعد JSON واقعيًا يشبه الإنتاج.
3. اجعل خادم MCP يقرأ Base URL من متغير بيئة.
4. في CI، وجّه المتغير إلى mock URL.
5. في الإنتاج، وجّهه إلى API الحقيقي.

مثال:

UPSTREAM_BASE_URL=https://mock.apidog.local npm test

هذا يجعل مجموعة الاختبار سريعة وحتمية. نغطي نفس الفكرة في تطوير واجهة برمجة التطبيقات القائم على العقد أولًا.

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

بعد حفظ الطلبات والتأكيدات، شغّلها مع كل push أو pull request.

مثال GitHub Actions:

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 }}

بهذا، أي تغيير يكسر tools/list أو inputSchema أو سلوك أداة سيظهر قبل الدمج.

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

لخادم MCP متوسط، استخدم هذا الحد الأدنى:

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

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

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

تخطي initialize

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

اجعل initialize أول خطوة في كل سيناريو.

التأكيد على نص الخطأ الكامل

رسائل الأخطاء تتغير. الأفضل:

• أكد على isError: true.
• استخدم error code إن كان موجودًا.
• أو استخدم regex ثابتًا بدل مطابقة النص كاملًا.

ترك mock يبتعد عن الإنتاج

إذا كان mock يعيد شكلًا لا يعيده API الحقيقي، فالاختبارات ستنجح بينما التكامل مكسور.

حدّث fixtures من استجابات حقيقية عند كل إصدار مهم.

نسيان Streaming

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

عدم اختبار التزامن

عملاء MCP قد يرسلون عدة tools/call بالتوازي داخل agent loop. إذا كان خادمك يستخدم حالة مشتركة بدون حماية، فقد تنجح اختبارات الطلب الواحد ويفشل الإنتاج.

أضف اختبارًا يشغّل عدة استدعاءات للأداة نفسها بالتوازي.

خلط أخطاء البروتوكول مع أخطاء الأداة

فشل الأداة يجب أن يعود داخل result مع isError: true. أما JSON-RPC error فهو لفشل البروتوكول نفسه. الخلط بينهما قد يجعل Claude Desktop يغلق الاتصال. هذا شبيه بمشاكل العقود التي تظهر في تطوير منصة API القائم على العقد أولًا.

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

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

مطور مستقل يبني خادم MCP مفتوح المصدر لـ Notion استخدم mock server في Apidog لتشغيل الاختبارات في CI بدون استهلاك rate limits من Notion. المجموعة تعمل على كل pull request، وتستخدم fixtures مخزنة في المستودع.

فريق منصة يدير 14 خادم MCP داخليًا أنشأ workspace مشتركة في Apidog لعقود الخوادم. كل خادم جديد يبدأ من مجموعة اختبار أساسية، والمراجعون يقارنون تغييرات المخطط قبل الدمج.

فريق آخر يبني خادم MCP لمنصة مراقبة داخلية يستخدم environments في Apidog لتشغيل نفس المجموعة ضد التطوير والإنتاج، بدون إعادة كتابة الطلبات.

الخاتمة

MCP أصبح شائعًا بسرعة، لكن اختبار خوادمه ما زال غالبًا يدويًا وهشًا. لا تنتظر أن ينضج النظام البيئي. تعامل مع خادم MCP كواجهة API حقيقية:

• صمّم عقدًا واضحًا.
• اختبر initialize وtools/list وtools/call.
• غطِّ الموارد والمطالبات.
• حاكِ الأنظمة الخارجية.
• شغّل التأكيدات في CI.

الخلاصة العملية:

• خادم MCP هو JSON-RPC API؛ اختبره بنفس جدية REST API.
• ابدأ بالمفتش الرسمي وطلبات stdio الخام.
• انقل الطلبات إلى Apidog.
• أضف تأكيدات JSONPath.
• استخدم mock server للـ upstream APIs.
• شغّل المجموعة مع كل push.

الخطوة التالية: افتح Apidog، أنشئ مشروعًا، الصق طلبات JSON-RPC التي التقطتها، أضف تأكيدات tools/list، ثم شغّل المجموعة. خلال ساعة ستعرف إن كان عقد خادم MCP لديك جاهزًا للشحن.

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

ما هو MCP؟

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

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

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

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

عرّف كل endpoint خارجي كـ mock في Apidog، ثم وجّه إعدادات خادم MCP إلى mock URL أثناء الاختبارات. في الإنتاج، استخدم URL الحقيقي. نفس النمط موضح في أدوات اختبار واجهة برمجة التطبيقات لمهندسي ضمان الجودة.

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

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

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

نعم. ثبّت protocolVersion في initialize وأضف تأكيدًا عليه. عدم التطابق قد يسبب مشاكل توافق صامتة مع العملاء.

هل أختبر خادمي مقابل Claude Desktop الحقيقي؟

نعم، مرة واحدة على الأقل قبل كل إصدار. لكن لا تجعله حلقة regression الأساسية. استخدم Apidog للاختبارات الآلية، وClaude Desktop لاختبار smoke نهائي.

أين أجد أمثلة لخوادم MCP حقيقية؟

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