project-graph-mcp يساعد وكلاء AI على رؤية معمارية المشروع من دون توكنات إضافية

ظهرت طريقة جديدة لوكلاء الذكاء الاصطناعي للتنقل بسرعة في الأكواد غير المألوفة: يقوم project-graph-mcp بإنشاء رسم بياني هيكلي للمشروع وإرجاعه كـ JSON مضغوط. بدلاً من قراءة عشرات الملفات بالتسلسل، يتلقى الوكيل خريطة العمارة، ويرى التبعيات، ثم ينغمس في المناطق الضرورية.

كيف يعمل الخادم

الفكرة الأساسية وراء project-graph-mcp هي ما يسمى بهيكل المشروع. يقوم الخادم بتحليل الكود المصدري، وجمع المعلومات عن الملفات والفئات والدوال والاستيرادات والاستدعاءات، ثم إرجاع كل ذلك في هيكل مضغوط. وفقاً للمؤلف، يصل الضغط إلى 10-50 مرة، مما يسمح للنموذج بفهم العمارة العامة دون استهلاك سياق ضخم. هذا النهج مفيد بشكل خاص لمحررات الوكلاء والمنسقين الذين يحتاجون إلى تحديد السريع لأي ملف يجب قراءته وأين يجب تفويض المهام الفرعية وكيف ترتبط الوحدات ببعضها.

يصل الضغط إلى 10-50 مرة.

في البداية، كانت الأداة تعمل فقط مع JavaScript من خلال محلل Acorn AST، لكن في الإصدار 1.1 حصلت على دعم TypeScript وPython وGo. بالنسبة للغات الجديدة، اختار المؤلف نهجاً قائماً على regex: فهو أبسط وأخف وزناً ولا يتطلب سحب مكتبات خارجية ثقيلة فقط للتنقل الأساسي في الكود. في الوقت نفسه، يتم توحيد جميع المحللات للحصول على نفس المخرجات — قوائم من الفئات والدوال والاستيرادات والاستدعاءات — بحيث يعمل الوكيل مع نفس نموذج المشروع بغض النظر عن مجموعة التكنولوجيا.

ما المشاكل التي يحلها

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

• `get_dead_code` يجد الدوال والوحدات غير المستخدمة
• `get_complexity` يقيم التعقيد الحلقي
• `get_large_files` يحدد الملفات المرشحة للإعادة الهيكلية
• `get_call_chain` يعرض المسار بين الدوال ذات الصلة
• Health Score يجمع نتائج الفحوصات في درجة من 0 إلى 100

بالإضافة إلى ذلك، يتضمن project-graph-mcp قوائم تحقق الاختبار من خلال التعليقات التوضيحية JSDoc `@test` و `@expect`. يمكن للوكيل تلقي قائمة بالفحوصات المفتوحة وكتابة الكود وتحديد الاختبارات كمجتازة. يعمل هذا كجسر بين التنقل في المشروع والدورة الإنمائية الفعلية: أولاً يفهم النموذج بنية التطبيق، ثم يجري التغييرات ويتحقق على الفور من السلوك المتوقع. بالنسبة للمجموعات النموذجية، هناك أيضاً قواعد مدمجة: 11 مجموعة تتضمن 86 اتفاقية لـ React وVue وExpress وTypeScript وSymbiote.js.

التكامل والأمان

تم تصميم الأداة كجزء من إطار عمل أوسع للوكلاء. يصف المؤلف سيناريو يطلب فيه الوكيل الرئيسي في IDE أولاً هيكل المشروع، ثم يفوض المهام الفردية إلى العمال في الخلفية عبر agent-pool-mcp. يقوم كل عامل بتشغيل نفس الخادم محلياً واستدعاء `expand` و `deps` وطرق أخرى لأقسام كود محددة. بهذه الطريقة، لا يسحب المنسق ملفات غير ضرورية إلى السياق ويمكنه توزيع العمل بشكل أسرع بين النماذج ذات التخصصات المختلفة.

من حيث المراحل التنفيذية، حاجز الدخول منخفض: Node.js 18+ مطلوب، الخادم يعمل عبر `npx`، ويزن 132 كيلوبايت، يتكون من 47 ملف وليس له أي تبعيات خارجية. الإصدار 1.2.0 متاح بالفعل على npm. تناول المؤلفون أيضاً الأمان بشكل محدد. تمر جميع المسارات عبر التحقق من خلال `resolve` و `startsWith`، لذا لا يمكن للوكيل الهروب من مجلد العمل. محاولة الوصول إلى شيء مثل `../../etc/passwd` ترجع خطأ. بالنسبة لأدوات MCP التي تقرأ الملفات والتبعيات، يكون هذا الحماية حرجة.

ماذا يعني هذا

ينتقل وكلاء الذكاء الاصطناعي تدريجياً من الإكمال التلقائي البسيط إلى فهم عمارة المشاريع بأكملها. project-graph-mcp مثير للاهتمام لأنه يحل مشكلة سياقية عملية: بدلاً من مئات الأسطر من الكود، يحصل النموذج على خريطة نظام مضغوطة ويعمل بدقة أكبر. بالنسبة للفرق التي تبني وكلاءها الخاصة من الذكاء الاصطناعي للتطوير، فهذا لم يعد تجربة بل طبقة بنية تحتية عملية تماماً. إذا أصبحت خوادم MCP مماثلة معياراً، فإن التطوير القائم على الوكلاء سيواجه حدوداً أقل من الرموز وغالباً ما يقتصر على جودة المنطق الهندسي نفسه.