MCP Inspector مع npx و CLI: كيف تختبر خادم MCP

يمكن أن يبدأ خادم MCP دون أي خطأ وما يزال عديم الفائدة. العملية تعمل، والسجل هادئ، والعميل الذي تربطه به يعرض قائمة أدوات فارغة أو رسالة غامضة مفادها "فشل الاتصال". قبل أن تلوم العميل، اختبر الخادم وحده. MCP Inspector هو الأداة الرسمية لمشروع Model Context Protocol لهذه المهمة: يؤدي دور العميل، وينفّذ المصافحة، ويتيح لك عرض كل ما يكشفه الخادم واستدعاءه. يشرح هذا المقال كيفية تشغيله باستخدام npx، وكيفية التحكم فيه من CLI، وكيفية قراءة رموز الخروج، وكيفية إصلاح الأخطاء التي تستهلك أكبر قدر من الوقت.

💡 التحقق من الإصدار: معظم الشروح المتاحة على الإنترنت تصف Inspector v1. أحدث إصدار على npm وقت كتابة هذا المقال هو 2.9.0، وقد غيّرت الإصدار v2 المنافذ ومتغيرات البيئة والأعلام ورموز الخروج. تتبع كل الأوامر أدناه توثيق v2.

ماذا يفعل MCP Inspector

Inspector عميل MCP مصمم للتصحيح. يشغّل خادمك (stdio) أو يتصل به (HTTP أو SSE)، وينفّذ مصافحة initialize، ويعرض لك بدقة ما يعود منها. لا يوجد نموذج لغوي في هذه الحلقة، لذلك عندما يفشل شيء ما تعرف أن الخلل في الخادم أو في الاتصال، وليس في سلوك الأوامر النصية.

المصافحة التي يتحقق منها

الاستدعاء الأول، initialize، يثبت أن الخادم يتحدث بروتوكول MCP. يحمل الرد أربعة أشياء تستحق القراءة سطرًا سطرًا:

• serverInfo: اسم الخادم وإصداره كما يعلنهما.
• protocolVersion: مراجعة البروتوكول التي اتفق عليها الطرفان.
• capabilities: الميزات المتاحة، مثل الأدوات والموارد والأوامر.
• instructions: نص اختياري يقدّمه الخادم للعملاء.

إذا لم يحتوِ capabilities على مدخل tools، فلن يعرض أي عميل أداة، مهما سجّلت من أدوات في الشيفرة. هذا الفحص وحده يفسّر نسبة كبيرة من تقارير "الأدوات لا تظهر".

الواجهة الويب و CLI و TUI

حزمة واحدة بثلاث واجهات. يجب أن يأتي علم الوضع أولًا، مباشرة بعد اسم الحزمة.

استخدم الواجهة الويب أثناء البناء، واستخدم CLI عندما تحتاج إلى نتيجة يمكنك تكرارها.

تشغيله باستخدام npx

لا يوجد شيء لتثبيته. يقوم npx بتنزيل الحزمة وتشغيلها، ويمرر كل ما يلي اسم الحزمة إلى الخادم الذي تريد اختباره. تستغرق أول تجربة معقولة سطرًا واحدًا ودقيقة واحدة.

إصدار Node والمنافذ

يحتاج v2 إلى Node.js 22.19.0 أو أحدث. شغّل node --version قبل أي شيء آخر، لأن بيئة تشغيل قديمة هي أول ما يجب استبعاده.

تسبب تغييرات المنافذ والمتغيرات مشكلات لمن يتبع المقالات القديمة، لذلك إليك مقارنة مختصرة:

غيّر منفذ الواجهة الويب باستخدام CLIENT_PORT، وهو عدد صحيح ثابت بين 1 و65535. يحجز v2 أيضًا المنفذ 6275 لبيئة MCP Apps المعزولة والمنفذ 6278 لخادم أصل التطبيق، لذلك أبقِ الاثنين خاليين.

CLIENT_PORT=6280 npx @modelcontextprotocol/inspector node build/index.js

نسخ الأمر النصي

في Windows PowerShell، اضبط المتغير أولًا باستخدام $env:CLIENT_PORT = "6280"، ثم شغّل السطر نفسه npx.

تمرير الوسائط ومتغيرات البيئة

بالنسبة لخادم Node مبني، ضع الأمر مباشرة بعد اسم الحزمة:

npx @modelcontextprotocol/inspector node build/index.js

نسخ الأمر النصي

تُمرَّر متغيرات البيئة باستخدام -e:

npx @modelcontextprotocol/inspector -e API_TOKEN=your-token -- node build/index.js

نسخ الأمر النصي

يعمل خادم TypeScript دون خطوة بناء بالطريقة نفسها، مثل npx @modelcontextprotocol/inspector tsx src/index.ts. تلفّ معظم المشاريع السطر في سكربت npm حتى يشغّل الفريق كله الأمر نفسه:

{
  "scripts": {
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  }
}

نسخ الأمر النصي

💡 الشرطتان المزدوجتان تعكسان المعنى. في وضع الواجهة الويب وTUI، كل ما يأتي بعد -- يذهب إلى خادمك. في وضع CLI، كل ما يسبق -- هو الهدف، وكل ما يليه خيار من خيارات Inspector. وفي وضع CLI يجب أن يأتي أمر الخادم أولًا أيضًا: إذ يُسقط --cli --method tools/list node build/index.js الهدف بصمت.

الرمز الذي يقف خلف الواجهة

يُنشئ v2 رمز API عشوائيًا عند كل تشغيل، ويطلبه في كل مسار من /api/*. تُرفض أي صفحة تُفتح دونه. اضبط MCP_INSPECTOR_API_TOKEN بنفسك إذا أردت قيمة ثابتة، وأعد التشغيل إذا اشتكى أحد التبويبات، لأن الرمز القديم مات مع العملية القديمة.

يرتبط خادم الويب بـ 127.0.0.1 افتراضيًا عبر HOST. يتطلب فتحه لواجهات أخرى DANGEROUSLY_BIND_ALL_INTERFACES صريحًا، وDANGEROUSLY_OMIT_AUTH=true يعطّل فحص الرمز تمامًا. يشغّل Inspector عمليات محلية نيابة عنك، لذلك عامل الرمز كأنه كلمة مرور، وأبعد هذين التجاوزين عن الأجهزة المشتركة.

استخدام ملف إعدادات

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

يقع الكتالوج الافتراضي في ~/.mcp-inspector/mcp.json. لا يمكن دمج أي من العلمين مع هدف مخصص في سطر الأوامر نفسه.

مدخلات stdio

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_TOKEN": "your-token" },
      "cwd": "/path/to/server"
    }
  }
}

نسخ الأمر النصي

أبقِ command وكل عنصر من args مدخلات منفصلة. يشغّلها Inspector مباشرة بدلًا من دمجها في نص واحد، وهذا يحافظ على حدود الوسائط عندما يحتوي مسار على مسافات.

مدخلات HTTP وSSE

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.internal.example/mcp",
      "headers": { "X-Tenant": "acme" }
    }
  }
}

نسخ الأمر النصي

يقبل حقل type القيم stdio، وhttp (Streamable HTTP) أو sse. في CLI تختار مدخلًا باستخدام --server:

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server my-server --method tools/list

نسخ الأمر النصي

--server يختار خادمًا في وضع CLI فقط. يحذّر عميل الويب ويتجاهله عند تحميل ملف، ويرفضه TUI كخيار غير معروف.

اختبار خادم MCP من CLI

يتجاوز وضع CLI المتصفح ويطبع الرد على stdout، مما يجعله الأداة المناسبة للفحوصات السريعة ولكل ما تريد أتمتته. لكل أمر الشكل نفسه: الهدف أولًا، ثم --method، ثم ما تحتاجه تلك الطريقة.

اعرض الأدوات أولًا

ابدأ دائمًا بسؤال الخادم عمّا يعتقد أنه يقدّمه:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

نسخ الأمر النصي

استبدل الطريقة بـ resources/list أو prompts/list لفحص الميزتين الأخريين. يحتاج الخادم البعيد إلى عنوان ونقل، وإلى رمز bearer إذا كان محميًا:

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://example.com/mcp \
  --header 'Authorization: Bearer <token>' \
  --method tools/list

نسخ الأمر النصي

قارن الأسماء في المخرجات بما يتوقعه عميلك. الأداة المسجلة باسم generateImage والمطلوبة باسم generate_image حالة كلاسيكية، ولا يلزم سوى أمر واحد لاكتشافها.

استدعِ أداة بوسائط JSON

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name generate_image \
  --tool-args-json '{"prompt":"a ceramic mug on an oak desk, soft window light","aspect_ratio":"16:9"}'

نسخ الأمر النصي

يأخذ --tool-args-json كائن JSON واحدًا ولا يطبّق أي تحويل للأنواع، فتبقى الأرقام أرقامًا والقيم المنطقية قيمًا منطقية. للاختبار السريع، --tool-arg prompt="a red door" أقصر، لكن قيمه تُحلَّل على أنها JSON عندما تكون صالحة، فتصبح السلسلة التي تبدو كرقم رقمًا. عندما تكون الأنواع مهمة، استخدم صيغة JSON.

💡 ملاحظة لنظام Windows: يُزيل Windows PowerShell 5.1 علامات الاقتباس المزدوجة الداخلية من JSON الممرر إلى البرامج الأصلية. اسبق كل واحدة منها بشرطة مائلة عكسية، أو استخدم --tool-arg للقيم القصيرة.

اقرأ رموز الخروج

يبلغ CLI عن النتيجة في رمز الخروج الخاص به، فلا يحتاج السكربت أبدًا إلى تحليل النص ليعرف ما حدث.

الرمز 5 هو الأهم للاختبار. الأداة التي تفشل بوضوح الآن تُفشل الأمر، لذلك يتوقف inspector --cli ... && next-step حيث كان v1 سيستمر. تنتهي الاتصالات بعد 15 ثانية افتراضيًا في التشغيلات المخصصة، ويرفع --connect-timeout <ms> هذا الحد عندما يحمّل خادمك قاعدة بيانات أو نموذجًا عند بدء التشغيل.

تشغيل فحوصات Inspector في CI

يؤكد اختبار الدخان المفيد أربعة أشياء: أن الخادم يتصل، وأن الأداة موجودة، وأن استدعاءً صالحًا ينجح، وأن استدعاءً غير صالح يفشل. أربعة أوامر، دون متصفح، ولن يصل إصدار معطوب إلى المستخدمين.

ثبّت الإصدار

ثبّت إصدارًا دقيقًا في CI، وليس نطاقًا مثل @2.x، لأن الأعلام ورموز الخروج تغيرت بين الإصدارات الرئيسية:

npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js --method initialize

نسخ الأمر النصي

امنح كل مهمة مخزن رموز خاصًا بها حتى لا يعيد تشغيل واحد استخدام حالة تسجيل الدخول لتشغيل آخر:

export MCP_STORAGE_DIR="$(mktemp -d)"
export MCP_INSPECTOR_OAUTH_STATE_PATH="$MCP_STORAGE_DIR/oauth.json"

نسخ الأمر النصي

تحقق باستخدام jq

أضف --format json فيطبع CLI كائن JSON واحدًا يحتوي على حقل result، جاهزًا للمعالجة بواسطة jq. هناك فخان يستحقان معرفتهما. لا تدمج stderr في stdout باستخدام 2>&1 أثناء التحليل أبدًا، لأن التشخيصات ستدخل داخل JSON. والتقط حالة الخروج قبل الأنابيب، لأن الأنبوب يُبلغ عن حالة آخر أمر فيه، وهذا يخفي CLI فاشلًا خلف jq ناجح.

#!/usr/bin/env bash
set -u
INSPECT="npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js"

# 1. The handshake works
$INSPECT --method initialize --format json > init.json || exit 1

# 2. The tool exists (status captured before the pipe)
tools=$($INSPECT --method tools/list --format json); code=$?
[ "$code" -eq 0 ] || { echo "tools/list failed with $code"; exit "$code"; }
echo "$tools" | jq -e '.result.tools | map(.name) | index("generate_image")' > /dev/null || exit 1

# 3. A valid call succeeds
$INSPECT --method tools/call --tool-name list_models --tool-args-json '{}' \
  --format json > call.json || exit 1

# 4. An invalid call fails
if $INSPECT --method tools/call --tool-name generate_image --tool-args-json '{}' \
  > /dev/null 2>&1; then
  echo "tool accepted empty input"; exit 1
fi

نسخ الأمر النصي

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

إصلاح الأخطاء التي ستراها

تقع معظم الأعطال ضمن عدد قليل من الأنماط. طابق العرض أولًا، ثم اقرأ القسم الذي يشرحه.

تلوّث stdout في stdio

ينقل نقل stdio رسائل JSON-RPC الخاصة به عبر stdout، وينص البروتوكول على أن الخادم لا يجوز له كتابة أي شيء هناك ليس رسالة MCP صالحة. سطر console.log عابر، أو شعار بدء التشغيل، أو تحذير تطبعه إحدى المكتبات يفسد التدفق. عندها تفشل المصافحة بأخطاء تحليل، أو تتعلق ببساطة.

لإصلاح ذلك، أرسل كل سطر سجل إلى stderr (console.error في Node، وsys.stderr في Python). لتتبع المتسبب، شغّل أمر الخادم وحده: الخادم السليم من نوع stdio لا يطبع شيئًا حتى يتحدث إليه عميل.

لم يُكتشف النقل

لم يعد v2 يخمّن. يستنتج النقل فقط عندما ينتهي مسار عنوان URL بـ /mcp أو /sse، وأي حالة أخرى تحتاج إلى العلم مكتوبًا صراحة:

npx @modelcontextprotocol/inspector --cli --server-url https://example.com/api \
  --transport http --method tools/list

نسخ الأمر النصي

عندما تكون رسالة الخطأ غير مفهومة بالنسبة لك، الصق مخرجات stderr ومخطط أداتك في Claude Sonnet 5 أو GPT 5.6 Sol، واطلب أرجح ثلاثة أسباب. كلاهما يقرأ تتبعات المكدس جيدًا، ومع ذلك تتحقق من الإجابة باستخدام Inspector.

اختبار خادم توليد الصور

الخوادم التي تجعل الوسائط تتصرف بشكل مختلف أثناء الاختبار. الاستدعاءات بطيئة، وقد تكلّف مالًا، والعمل عادةً ما يجري في الخلفية. تُظهر واجهة API للمطورين في PicassoIA هذا النمط بوضوح. وهي على نمط Replicate: تنشئ تنبؤًا باستخدام POST /v1/models/{owner}/{name}/predictions على https://api.picassoia.com/v1، وتوثّق هويتك برمز حامل (bearer token)، وتستعلم GET /v1/predictions/{id}، وتقرأ النتيجة عند اكتمالها.

في وقت كتابة هذا المقال، تعرض API واتصال MCP النماذج الأربعة نفسها: PicassoIA Image، وPicassoIA Image Editor Pro، وPicassoIA Video، و Seedance 2.5 Lite. يسمح الحساب بخمسة تنبؤات متزامنة، تُشارَك بين الرموز واتصالات MCP، مع أوامر نصية يصل طولها إلى 4,000 حرف.

💡 اختبر بالتسلسل. حلقة من استدعاءات الأدوات في جلسة Inspector واحدة قد تملأ الخانات الخمس كلها وتحرم عميلك الحقيقي. شغّل اختبارات الصور استدعاءً واحدًا في كل مرة.

الأدوات غير المتزامنة تحتاج إلى أداة للحالة

الأداة التي تبدأ مهمة يجب أن تعيد معرفًا خلال ثوانٍ، وينبغي لأداة ثانية أن تعرض التقدم. اختبر النصفين كلًّا على حدة:

• استدعاء البدء يعود سريعًا بمعرّف بدلًا من إبقاء الاتصال مفتوحًا لدقائق.
• استدعاء الحالة يقبل ذلك المعرّف ويعرض حالة تقدم وحالة نهائية.
• المهمة الفاشلة تعود كنتيجة مع isError: true، لا كاستدعاء معلّق.
• المعرّف الخاطئ ينتج رمز الخروج 5، لا تعطلًا في عملية الخادم.
• عنوان URL للمخرجات يستجيب برمز الحالة 200 ونوع محتوى صورة عند جلبه.

الفحص الأخير هو الأرخص، وهو يلتقط العطل الذي يلاحظه القراء أولًا: صورة مكسورة في صفحة منشورة.

أنشئ صورتك الأولى التالية

لديك الآن طريقة لإثبات أن الخادم يعمل قبل أن يعتمد عليه أحد. تؤتي العادة نفسها ثمارها في الجانب الإبداعي: شغّل اختبارًا صغيرًا، واقرأ النتيجة، وغيّر شيئًا واحدًا في كل مرة.

افتح Picasso IA وجرّب الحلقة بنفسك. اكتب أمرًا نصيًا من جملة واحدة في PicassoIA Image، ثم حسّن النتيجة باستخدام PicassoIA Image Editor Pro، ثم أحيِ الصورة الثابتة باستخدام PicassoIA Video. غيّر العدسة أو الإضاءة أو الشخص بين التشغيلات، وقارن المخرجات جنبًا إلى جنب. خمسة أوامر من هذا المقال تستحق أن تحتفظ بها بجانب طرفيتك:

• --method initialize لتأكيد المصافحة.
• --method tools/list لتأكيد أسماء الأدوات.
• --method tools/call --tool-args-json لتأكيد السلوك.
• --format json مع jq للتحقق من الإجابة.
• رمز الخروج، ويُقرأ دائمًا قبل المخرجات.