عن المشروع

jarvis، المنشور على PyPI باسم jarvis-mcp، هو طبقة ذكاء كود تعتمد على النهج المحلي أولاً لوكلاء البرمجة. يتم شحنه كخادم Model Context Protocol (MCP) يتحدث عبر stdio، بحيث يمكن لـ Claude Code أو Cursor أو Claude Desktop أو أي عميل MCP آخر الاستعلام عن مستودع مفهرس مسبقاً. لا توجد خدمة مستضافة، ولا مصادقة، ولا اعتماد على الشبكة: لا شيء يغادر الجهاز. كيفية تكامل النصفين تم تقسيم المشروع عمداً إلى كاتب (writer) وقارئ (reader) يتشاركان عقداً واحداً فقط، وهو دليل بيانات محلي (افتراضياً ~/.jarvis). - واجهة سطر أوامر الفهرسة (Indexing CLI): يقوم jarvis index بأخذ مسار المستودع، وبناء أساس بناء جملة Tree-sitter لكل ملف مدعوم، وتشغيل مفهرس SCIP الخاص باللغة اختيارياً وتحويل المخرجات إلى SQLite، وبناء أجزاء Zoekt بالإضافة إلى تضمينات (embeddings) اختيارية، ثم نشر كل شيء كلقطة ثابتة (immutable snapshot) يتم اختيارها بواسطة مؤشر حالي صغير. - وقت التشغيل (Runtime): يقوم jarvis-server بتوفير الأدوات عبر stdio، مدعوماً بـ lazy singletons. يتم تشغيل zoekt-webserver عند أول عملية بحث ويتم مشاركته بين العمليات من خلال pidfile. تفتح الاستعلامات قاعدة البيانات المنشورة للقراءة فقط، لذا فإن مسار الخدمة لا يكتب أبداً. عملية النشر ذرية (atomic)؛ حيث يستمر الاستعلام الذي يقرأ الملف القديم في العمل بينما يقوم إعادة الفهرسة بتبديل المؤشر، وأي فشل في أي مرحلة اختيارية يترك اللقطة السابقة تعمل. كما تقوم كل عملية إعادة فهرسة بإعادة بناء حواف الحزم الصادرة لهذا المستودع بدلاً من تراكمها. أدوات MCP التسع تقوم goToDefinition بحل الرمز إلى الملف والنطاق المعرف له، ويتم توفير ذلك عبر SCIP حيثما توفرت تغطية تعريفات SCIP، وإلا عبر تصريح أساس بناء الجملة، مع وسم كل موقع بمزوده. تقوم findReferences بسرد حالات ظهور الرمز وهي مقتصرة على SCIP. تعيد callHierarchy المكالمات الواردة والصادرة، وهي أيضاً مقتصرة على SCIP. تعيد typeHierarchy الأنواع العليا والفرعية، وهي مقتصرة على SCIP. تقوم documentSymbols بتحديد الرموز المعرفة في ملف واحد، ويتم توجيهها لكل ملف بين مخطط SCIP وتصريحات Tree-sitter. تقوم searchCode بإجراء بحث معجمي أو بحث بالتعبيرات النمطية عبر Zoekt مع مرشح مستودع اختياري. أما semanticSearch فهو بحث باللغة الطبيعية يدمج نتائج المتجهات مع نتائج Zoekt ومطابقات تعريف رموز SCIP باستخدام reciprocal rank fusion. توضح blastRadius المستودعات المفهرسة الأخرى التي تعتمد على حزمة ما، حتى قفزتين. يقدم getIndexStatus تقريراً عن الالتزام (commit) المنشور، والحداثة، والتقادم مقابل شجرة العمل، وقدرات المزود لكل أداة. الأدوات المقتصرة على SCIP لا تعيد نتائج فارغة بصمت عند فقدان البيانات؛ بل تبلغ عن القدرة المطلوبة، والسبب، وتلميح للاسترداد. يتم إرجاع إخفاقات الأدوات ككائنات حمولة (payload objects) بدلاً من أخطاء نقل، لذا فإن الاستعلام السيئ لا يتسبب في إيقاف خادم stdio. الفهرسة والمراقبة تشمل الأوامر jarvis index و list و status و reindex و forget، بالإضافة إلى jarvis watch لإعادة الفهرسة التلقائية مع مهلة (خمس ثوانٍ افتراضياً) باستخدام إضافة watchdog الاختيارية. يتم اكتشاف اللغة من الملفات المتتبعة بواسطة git عبر تعدد الامتدادات ويمكن تجاوز ذلك باستخدام --language. قيم الحالة هي indexing و indexed و partial و degraded و failed؛ حيث تقوم التشغيلات المتدهورة (degraded) بنشر أساس بناء الجملة وتخرج بالقيمة صفر مع تسجيل السبب. المتطلبات والقيود المشروع صريح بشأن كونه محدود النطاق. - macOS و Linux فقط؛ Windows غير مدعوم. - لغة واحدة لكل مستودع؛ يتم فهرسة المستودعات أحادية البناء متعددة اللغات (polyglot monorepos) وفقاً للغة التي تمتلك أكبر عدد من الملفات المتتبعة. - يغطي أساس Tree-sitter الذي لا يتطلب بناءً 17 لغة (Python, JavaScript, TypeScript/TSX, Java, Kotlin, Swift, Go, Ruby, Rust, C, C++, C#, PHP, Scala, Bash, SQL) ويتم تثبيته كاعتماد pip للحزمة نفسها. - تغطي ملاحة SCIP الدقيقة أربع عائلات لغوية: TypeScript/TSX و Python و Java/Kotlin و Swift. - يتطلب إثراء SCIP و Zoekt الاختياري تثبيت ملفات ثنائية خارجية عبر نص إعداد: scip (الحد الأدنى v0.9.0)، و zoekt-git-index و zoekt-webserver، و universal-ctags، و scip-typescript، و scip-python، و scip-swift (لـ macOS arm64 فقط) و scip-java (كشف فقط، يطلب قبل سحب صورة Docker). - الفهرسة خطوة صريحة؛ لا يتم تحليل أي شيء بشكل مباشر. - jarvis للقراءة فقط ولا يقوم أبداً بتعديل الكود. يضعه ملف README كمكمل لـ Serena، التي تتعامل مع إعادة التسمية الدلالية وإعادة الهيكلة. البحث والتكوين تتطلب semanticSearch إضافة semantic الاختيارية (lancedb و sentence-transformers) وتدمج البحث المتجهي عبر الكود المقسم بواسطة Tree-sitter مع النتائج المعجمية. يحترم الفهرس الدلالي ملف .gitignore، ويتخطى الملفات التي تزيد عن 1 ميجابايت واستدلالات الملفات المولدة، وكل ذلك يمكن تجاوزه عبر علامة include. تغطي متغيرات البيئة دليل البيانات وبادئات تعليمات الاستعلام/المستند للتضمين، مع اكتشاف تلقائي لنماذج bge-m3 و e5 و nomic-embed. يوثق ملف README أيضاً قيود SCIP المعروفة في المصدر (بيانات علاقات معرفة ولكن غير مكتوبة لتسلسلات الأنواع، وأسماء وأنواع العرض المعبأة، وعدم قدرة scip-java على فهرسة مستودعات Android/Gradle، وتطلب Kotlin تطابقاً دقيقاً في إصدار المترجم، ومتطلبات إصدار bash لبناءات Java القائمة على Maven) ويعاملها كسلوكيات للأدوات الأساسية وليس كأخطاء في jarvis. يتم شحن ثلاث مهارات لوكيل Claude Code مع المكون الإضافي: jarvis-setup و jarvis-use و jarvis-issues. المشروع مرخص بموجب MIT، ويتم تشغيل مجموعة الاختبارات الخاصة به باستخدام pytest، مع تمييز اختبارات التكامل التي تستدعي ملفات ثنائية حقيقية للمفهرس بشكل منفصل.