MCP Inspector - أداة تصحيح خوادم Model Context Protocol (Cheatsheet)
MCP Inspector هي أداة الاختبار والتصحيح المرئي الرسمية لخوادم Model Context Protocol. عندما تقوم ببناء خادم MCP، تحتاج إلى معرفة ما يكشفه بالفعل وكيف يستجيب — يتصل Inspector بخادمك، يسرد أدواته والموارد والمطالبات، يتيح لك استدعاء كل واحد بحجج اعتباطية، ويعرض رسائل JSON-RPC الخام التي تتدفق في كلا الاتجاهين. إنها الطريقة الأسرع للتحقق من أن خادم يعمل قبل توصيله بـ Claude أو Cursor أو عميل آخر.
تشغيله
| الطريقة | الأمر |
|---|
| npx (بدون تثبيت) | npx @modelcontextprotocol/inspector |
| مع خادمك | npx @modelcontextprotocol/inspector node build/index.js |
| خادم Python | npx @modelcontextprotocol/inspector uv run server.py |
| خادم Remote/SSE | شغل، ثم ادخل URL في الواجهة |
| الواجهة | تفتح في المتصفح (الافتراضي http://localhost:6274) |
أنواع الاتصال
| النقل | الاستخدام |
|---|
| STDIO | خادم محلي يعمل كعملية فرعية (الأكثر شيوعاً) |
| SSE | خادم بعيد عبر Server-Sent Events |
| Streamable HTTP | نقل بعيد حديث |
# فحص خادم stdio محلي، تمرير args و env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
الواجهة
| التبويب | يعرض |
|---|
| الأدوات | كل أداة، مخطط JSON الخاص بها، ونموذج لاستدعاؤها |
| الموارد | الموارد المكشوفة ومحتوياتها |
| المطالبات | قوالب المطالبات وحجتها |
| الإخطارات | الرسائل/السجلات التي يبدأها الخادم |
| السجل | كل زوج طلب/استجابة |
أدوات الاختبار
| الخطوة | الإجراء |
|---|
| 1 | افتح تبويب الأدوات؛ أكد أن أداتك مدرجة |
| 2 | تحقق من عرض مخطط الإدخال بشكل صحيح (الأنواع، الحقول المطلوبة) |
| 3 | ملء النموذج المولد والنقر لاستدعاء |
| 4 | فحص المحتوى المرجع وأي علم isError |
| 5 | اقرأ JSON-RPC الخام في السجل لتصحيح مشاكل الشكل |
هذه الحلقة تمسك معظم أخطاء MCP الشائعة: مخطط مشوه، أداة ترجع شكل محتوى خاطئ، أو خطأ غير معالج.
ما يجب التحقق منه قبل الشحن
| التحقق | لماذا |
|---|
| أسماء الأدوات فريدة/وصفية | العملاء يسطحونها للنموذج |
| تشرح الأوصاف متى استخدام الأداة | يقود اختيار النموذج الصحيح |
| مخطط الإدخال دقيق | يمنع الاستدعاءات المشوهة |
الأخطاء ترجع isError برسالة | النموذج يمكنه التعافي |
| المخرجات الكبيرة مقسمة/مقطوعة | تجنب نفخ نافذة السياق |
| الموارد لها URIs مستقرة | العملاء يخزنونها/يرجعون إليها |
نصائح التصحيح
| العرض | انظر إلى |
|---|
| الخادم لن يتصل | الأمر/args؛ stderr في المحطة الطرفية التي تطلق |
| أداة مفقودة | كود التسجيل؛ أعد تشغيل الخادم |
| المخطط يعرض بشكل غريب | أنواع JSON Schema في تعريف الأداة |
| السلوك المختلف للعميل | قارن JSON-RPC الخام في السجل |
| خطأ يعتمد على Env | أعد تشغيل Inspector مع -e KEY=value |
سير العمل الشائع
# حلقة تطوير واختبار لخادم TypeScript MCP
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# اختبر خادم Python مع uv
npx @modelcontextprotocol/inspector uv run my_server.py
# تحقق من خادم SSE البعيد قبل إضافته إلى عميل
npx @modelcontextprotocol/inspector # اختر SSE، الصق URL
MCP Inspector مقابل البدائل
| الطريقة | المقايضة |
|---|
| MCP Inspector | المقصود، مرئي، يعرض البروتوكول الخام |
| توصيل بعميل حقيقي | واقعي لكن حلقة ردود فعل بطيئة |
| JSON-RPC المكتوبة يدوياً | السيطرة الكاملة، مملة |
| اختبارات الوحدة | سريع وقابل للتكرار؛ اقترنه مع Inspector للاستكشاف |
استخدم Inspector أثناء البناء، ثم أضف اختبارات آلية؛ انظر MCP servers لأنماط تنفيذ الخادم.
الموارد
