inspector

MCP Inspector أداة موجهة للمطورين لفحص واختبار خوادم Model Context Protocol (MCP). تُوزَّع كحزمة npm واحدة، `@modelcontextprotocol/inspector`، وتوفّر ملفاً تنفيذياً عالمياً واحداً، `mcp-inspector`، يعمل بثلاثة أوضاع: - **Web** — تطبيق صفحة واحدة مبني بـ Vite + React + Mantine مع خادم Node.js، يوفّر واجهة مرئية لفحص الخادم. - **CLI** — عميل سطر أوامر قابل للبرمجة النصية مصمم للأتمتة وخطوط CI وحلقات التغذية السريعة للوكلاء. - **TUI** — واجهة طرفية تفاعلية مبنية بـ Ink للمستخدمين الذين يفضّلون سير عمل قائماً على الطرفية. تُستدعى الأوضاع الثلاثة جميعها عبر الملف التنفيذي نفسه باستخدام أعلام: ```bash npx @modelcontextprotocol/inspector # web UI (default) npx @modelcontextprotocol/inspector --cli # CLI mode npx @modelcontextprotocol/inspector --tui # TUI mode ``` ## البنية المعمارية المشروع ليس مساحة عمل npm. يحتفظ كل عميل تحت `clients/` بملف `package.json` ومجلد `node_modules` الخاص به. توجد الشيفرة المشتركة في `core/` ويُستهلك عبر اسم مستعار وقت البناء `@inspector/core`. تُعلَن تبعيات وقت التشغيل التي يستوردها `core/` مرة واحدة في جذر المستودع، بينما يعلن كل عميل فقط حزمة واجهته الخاصة، والحزم المضمّنة في المُجمِّع، وأدوات التطوير. لا تمتلك حزمتا `clients/cli` و`clients/launcher` أي تبعيات وقت تشغيل خاصة بهما. ## تخطيط المشروع - `clients/web/` — عميل الويب (Vite + React + Mantine). يحتوي مجلد `src/` على تطبيق المتصفح؛ ويضم `server/` الواجهة الخلفية بـ Node. - `clients/cli/` — عميل CLI، يُجمَّع باستخدام tsup مع الاسم المستعار `@inspector/core`. - `clients/tui/` — عميل TUI، مبني بـ Ink + React ويُجمَّع باستخدام tsup. - `clients/launcher/` — مشغّل مشترك يوفّر الملف التنفيذي `mcp-inspector` ويوجّه إلى العميل المناسب. - `core/` — شيفرة مشتركة تُستهلك عبر الاسم المستعار `@inspector/core`؛ لا يحتوي على `package.json`. - `test-servers/` — خوادم MCP اختبارية قابلة للتركيب وعناصر تجريبية تُستخدم في اختبارات التكامل والاختبارات السريعة. - `scripts/` — أدوات البناء والتحقق في الجذر، بما في ذلك سلاسل التثبيت والاختبارات السريعة وأتمتة CI. - `docs/` — أدلة موجهة للمهام تغطي البنية المعمارية والاختبار وبوابات الجودة وتخزين الأسرار والترحيل واستخدام Docker والمزيد. - `specification/` — مواصفات التصميم والبناء. - `.claude/skills/` — مهارات الوكلاء، كل منها في مجلد خاص، تُحمَّل عند الطلب باسم الإجراء. ## سير عمل التطوير يُشترط Node `>=22.19.0`. بعد تشغيل `npm install` في جذر المستودع (يتسلسل سكربت postinstall إلى كل عميل)، شغّل `npm run build` لترجمة الويب وCLI وTUI والمشغّل بالتتابع. لتطوير الويب السريع، يمكنك تشغيل Vite مباشرة من `clients/web` للحصول على استبدال وحدات ساخن سريع دون إعادة بناء المشغّل. بوابة ما قبل الدفع الإلزامية هي `npm run local:gate`، التي تسلسل فحوصات التنسيق والتدقيق البرمجي وفحص الأنواع وعمليات البناء واختبارات الوحدة والتحقق من التغطية (عتبة 90% لكل ملف) والاختبارات السريعة واختبارات Storybook. وهذا يحاكي فحص GitHub CI الكامل محلياً. ## أبرز ما في التوثيق - **البنية المعمارية** — تفاصيل حول حزمة `@inspector/core` المشتركة ونموذج مكوّنات عميل الويب. - **الاختبار وبوابة الجودة** — تغطية لما يتحقق منه كل سكربت تحقق وانقسام البوابة بين CI والمحلي. - **تخزين الأسرار** — كيفية إدارة الأسرار عبر سلاسل مفاتيح أنظمة التشغيل والملفات النصية الصريحة والمخازن في الذاكرة، بما في ذلك التشفير والقفل. - **الاختبار السريع لخادم MCP** — سير عمل اتصال ← سرد ← استدعاء ← تأكيد لمهام shell أو CI، مع مخرجات JSON وربط رموز الخروج. - **الترحيل من v1 إلى v2** — تغييرات أعلام CLI، وانقسام `--config` مقابل `--catalog`، ورفع إصدار محرك Node، وإعادة تسمية متغيرات البيئة. - **خارطة الطريق** — خطة لستة أشهر متوافقة مع خارطة طريق MCP المنشورة، تغطي الامتثال للمواصفات ودعم الإضافات الرسمية وتحسينات التجربة. ## المساهمة تتبع المساهمات سير عمل مدفوعاً بالمشكلات. يجب تتبع جميع الأعمال على لوحة مشروع v2، مع فتح طلبات السحب مقابل `v2/main` وربطها عبر `Closes #<issue>`. تُقبل المساهمات الخارجية كمشكلات بدلاً من طلبات السحب. يحدد ملف `AGENTS.md` قواعد المشروع لكل من المساهمين البشر والذكاء الاصطناعي، ويغطي الإصدارات ومعايير TypeScript واصطلاحات Mantine/React ومتطلبات الاختبار. يعمل ملف `CLAUDE.md` كنقطة دخول لـ Claude Code، ويحمّل `AGENTS.md` تلقائياً بحيث يعمل الوكلاء والبشر من المصدر نفسه للحقيقة. ## الترخيص ينتقل مشروع MCP من MIT إلى Apache-2.0. تُرخَّص المساهمات الجديدة بموجب Apache-2.0، والتوثيق (باستثناء المواصفات) بموجب CC-BY-4.0، وتبقى المساهمات القديمة التي لم تمنح موافقة إعادة الترخيص بموجب MIT.