هذه سلسلة مكونة من 10 أجزاء تشارك كيف طورت Apidog أداة Apidog CLI، وهي أداة سطر أوامر لاختبار واجهات برمجة التطبيقات وإدارة دورة حياة واجهة برمجة التطبيقات. اقرأ بالترتيب أو انتقل إلى أي منشور يثير اهتمامك:
| العنوان | التركيز | |
|---|---|---|
| 1 | بنينا 126 أداة MCP. لكنها ليست الحل الأفضل للوكيل | اكتشاف المشكلة |
| 2 | لماذا قمنا بتطوير Apidog CLI جديد كليًا | تطوير البنية |
| 3 | القاعدة الذهبية: CLI ينتج الحقائق، والنموذج يعمل بناءً على الحقائق | الفلسفة الأساسية |
| 4 | agentHints: تعليم أدوات سطر الأوامر (CLIs) التحدث إلى الوكلاء |
مخرجات منظمة |
| 5 | SKILL: شحن الخبرة التشغيلية كتعليمات برمجية | الخبرة التشغيلية |
| 6 | الأرقام لا تكذب: 30% مكالمات أدوات أقل، 25% رموز أقل | نتائج كمية |
| 7 | من وثيقة متطلبات المنتج (PRD) إلى حلقة الاختبار: سير عمل وكيل كامل مع Apidog CLI | برنامج تعليمي عملي |
| 8 | لماذا تعد توافقية CI/CD غير قابلة للتفاوض لأدوات الوكيل | منظور DevOps |
| 9 | فرع الذكاء الاصطناعي: تغييرات مشروع أكثر أمانًا مع وكلاء الذكاء الاصطناعي | طبقة الأمان |
| 10 | التركيز على المواصفات كان بالأمس. مرحبًا بك في التركيز على المهارات أولاً. | الرؤية والمستقبل |
عندما أصبح MCP نقطة ساخنة في الصناعة، قمنا ببناء خادم MCP كامل يضم 126 أداة تم إنشاؤها. إليك ما سار بشكل خاطئ—ولماذا لا يعني المزيد من الأدوات تمكينًا أفضل للوكيل.
ضجة MCP
في أوائل عام 2025، أصبح MCP (بروتوكول سياق النموذج) نقطة ساخنة في الصناعة.
روّجت Anthropic للبروتوكول. وسرعان ما حذت حذوها Cursor، وClaude Code، وAntigravity، والعديد من بيئات التطوير المتكاملة (IDEs) للوكلاء، والعديد من منتجات SaaS. وعد البروتوكول بطريقة موحدة لوكلاء الذكاء الاصطناعي للاتصال بالأدوات الخارجية ومصادر البيانات.
خلال تلك الفترة، سُئل كل منتج تقريبًا يحتوي على واجهة برمجة تطبيقات (API) نفس السؤال:
"هل لديك MCP؟"
بالنسبة لـ Apidog، بدا هذا الخيار طبيعيًا بشكل خاص.
لماذا بدا MCP هو الحل
لقد راكمت Apidog نفسها مجموعة شاملة من إمكانيات تطوير واجهة برمجة التطبيقات:
- وثائق واجهة برمجة التطبيقات
- تعريفات المخطط
- خوادم وهمية
- حالات الاختبار
- سيناريوهات الاختبار
- مجموعات الاختبار
- تقارير الاختبار
- سير عمل الاستيراد/التصدير
- التعاون بين الفروع
- والعديد غيرها
إذا كان للوكلاء أن يصبحوا نقطة الدخول الجديدة للبرامج—طريقة جديدة يتفاعل بها المستخدمون مع المنتجات—فإن كشف هذه الإمكانيات عبر MCP بدا وكأنه تذكرة ضرورية لتحقيق ذلك.
اعتقدنا أنه إذا تمكنا من تجميع قدراتنا كأدوات MCP، فسيكون الوكلاء قادرين على:
- الاستعلام عن وثائق واجهة برمجة التطبيقات
- إنشاء حالات اختبار
- تشغيل سيناريوهات الاختبار
- استيراد/تصدير بيانات المشروع
- إدارة البيئات والمتغيرات
- التعاون عبر الفروع
كان المنطق مباشرًا: المزيد من الإمكانيات المكشوفة = المزيد من تمكين الوكيل.
ما بنيناه بالفعل
لم نأخذ هذا باستخفاف.
Apidog MCP لم يكن مجرد عرض توضيحي بسيط مع عدد قليل من نقاط النهاية المكتوبة يدويًا. لقد كان خادم MCP كاملاً:
نظام الجلسة
يقوم عميل MCP أولاً بتهيئة جلسة. يقوم الخادم بإنشاء sessionId ويحفظ حالة الجلسة عبر Redis. تستمر الطلبات اللاحقة في الوصول باستخدام sessionId.
بمعنى آخر، لم تكن مكالمة HTTP لمرة واحدة، بل كانت نظام جلسة على مستوى البروتوكول.
فئات الأدوات
لم تكن طبقة الأدوات مكتوبة يدويًا أيضًا مع عدد قليل من نقاط النهاية الثابتة. لقد قسمنا أدوات Apidog إلى عدة فئات:
| الفئة | الوصف | أمثلة |
|---|---|---|
| أدوات المشروع الأصلية | مصممة لعمليات على مستوى المشروع | ملخصات المشروع، هياكل المجلدات، تفاصيل الموارد |
| أدوات النطاق المضمنة | وظائف Apidog الأساسية | الاستيراد/التصدير، تفاصيل نقطة النهاية، حالات الاختبار، سيناريوهات الاختبار |
| أدوات OpenAPI المُنشأة | محولة تلقائيًا من تعريفات OpenAPI | 126 أداة بمعرفات فريدة، مسارات، طرق HTTP، مخطط إدخال |
تلك الفئة الأخيرة: 126 أداة مُنشأة.
كان لكل أداة مُنشأة:
- معرف فريد
- مسار API محدد
- طريقة HTTP (GET, POST, PUT, DELETE, إلخ.)
- مخطط إدخال كامل مع أوصاف الحقول، والأنواع، وقيم التعداد
- بنية إرجاع معرفة
الكشف التدريجي
لتقليل ضغط تعرض الأدوات، قمنا أيضًا ببناء طبقة اكتشاف ديناميكية:
يمكن للوكيل:
- البحث أولاً عن أدوات نقطة النهاية المتاحة (`listOpenApiEndpoints`)
- ثم الحصول على تفاصيل OpenAPI لأداة معينة (`getOpenApiDetails`)
- أخيرًا تنفيذ مكالمة HTTP الفعلية بواسطة معرف الأداة (`executeOpenApi`)
كانت هذه محاولتنا للكشف التدريجي. لم نكشف ببساطة عن جميع نقاط النهاية الأساسية بشكل مباشر وصريح. كنا نأمل أن يبحث الوكلاء أولاً، ثم يحصلوا على التفاصيل، وأخيرًا ينفذوا.
جدار الأدوات العشوائية
لكن عند الدخول في مهام حقيقية، ظهرت المشاكل بسرعة.
فكر في طلب مستخدم بسيط:
"ساعدني في إضافة اختبار لنقطة النهاية هذه وتشغيل التحقق."
من منظور التنفيذ، هذا طلب معقول. تمتلك Apidog القدرات على:
- العثور على نقاط النهاية
- إنشاء حالات اختبار
- تشغيل سيناريوهات الاختبار
- إنشاء تقارير
لكن من منظور الوكيل، هذا الطلب البسيط يثير في الواقع سلسلة من الأحكام المستمرة:
| نقطة القرار | الخيارات | عدم اليقين |
|---|---|---|
| من أين نبدأ؟ | العثور على المشروع أولاً؟ العثور على نقطة النهاية أولاً؟ | لا توجيه واضح |
| ماذا نقرأ؟ | قراءة تفاصيل نقطة النهاية؟ سرد حالات الاختبار الموجودة؟ | كلاهما يبدو صالحًا |
| كيف ننشئ؟ | استخدام createTestCase مباشرة؟ العثور على مجموعة الحالات أولاً؟ |
متطلب غير معروف |
| كيف نحدث؟ | استدعاء أداة update مباشرة؟ استيراد الخطوات ثم القراءة مرة أخرى؟ |
سير عمل مخفي |
لا يحتاج الوكيل فقط إلى العثور على الأداة الصحيحة. بل يحتاج إلى حل مشكلة "أي أداة نستخدم" أولاً، قبل أن يتمكن من البدء في حل مشكلة المستخدم.
من منظور التنفيذ، يمكن حل كل هذه المشاكل من خلال الأدوات. من منظور تجربة الوكيل، فإنها تشكل جدارًا من الأدوات العشوائية.
المشاكل الهيكلية الأربعة
من خلال الاختبارات الواقعية والملاحظات الداخلية، حددنا أربع مشاكل هيكلية في نهج MCP.
المشكلة 1: ترتفع تكاليف اكتشاف الأدوات بسرعة
Apidog ليس منتجًا يمكن وصفه بعدد قليل من نقاط النهاية.
| الوحدة | التفاصيل |
|---|---|
| نقاط النهاية | قائمة، جلب، إنشاء، تحديث، حذف |
| المخططات | قائمة، جلب، إنشاء، تحديث، حذف |
| البيئات | قائمة، جلب، إنشاء، تحديث، حذف، متغيرات |
| المحاكاة | تكوين، تمكين، تعطيل |
| حالات الاختبار | قائمة، جلب، إنشاء، تحديث، حذف، تكرار |
| سيناريوهات الاختبار | قائمة، جلب، إنشاء، تحديث، حذف، استيراد الخطوات، تشغيل |
| مجموعات الاختبار | قائمة، جلب، إنشاء، تحديث، حذف |
| التقارير | قائمة، جلب، إنشاء، تنزيل |
| الاستيراد/التصدير | تنسيقات متعددة، خيارات |
| الفروع | قائمة، إنشاء، دمج، حذف |
عندما تنمو الأدوات من عشرات إلى عشرات أو مئات، يحتاج الوكيل إلى حل مشكلة "أي أداة نستخدم" قبل أن يتمكن من البدء في حل مشاكل المستخدم.
حاولنا كتابة سير العمل في description الأداة (الحقل المستخدم لتعريض الأدوات لوكلاء الذكاء الاصطناعي). على سبيل المثال، قد تنص وصف الأداة صراحةً على:
"قبل الاستعلام عن بيانات نقطة النهاية، تحتاج إلى تأكيد المشروع من خلال أداة أخرى أولاً، ثم الحصول على بيانات تعريف المشروع من خلال أداة ثالثة، وأخيرًا استدعاء الأداة الحالية."
هذه الطريقة تعمل في مجموعات الأدوات صغيرة النطاق. ولكن في جدار هائل من الأدوات، يتنافس description نفسه على انتباه النموذج.
كلما زاد عدد التوجيهات التي كتبناها في الأوصاف، زادت الرموز المستهلكة—وقل احتمال أن يقرأها الوكيل ويتبعها بالفعل.
المشكلة 2: مخطط الأعمال يغزو السياق
كل أداة MCP ليست مجرد اسم أداة.
خلف كل أداة توجد:
description(ما تفعله الأداة)input schema(المعلمات، الأنواع، مطلوب/اختياري)- شروحات الحقول (هياكل متداخلة، قيود)
- قيم التعداد (الخيارات المسموح بها)
- هياكل الإرجاع (تنسيق الاستجابة، معالجة الأخطاء)
دعنا نقوم بتقدير متحفظ:
| العامل | القيمة |
|---|---|
| عدد الأدوات | 100+ |
| متوسط الرموز لكل أداة | ~500 |
| إجمالي رموز وصف الأداة | ~50,000 |
قد يكون سؤال المستخدم 50 حرفًا فقط. لكن النموذج يُجبر على تقديم 50,000 رمز من أوصاف الأدوات أولاً—لمجرد خادم MCP واحد.
هذا ليس نظريًا. تدعمه بيانات الصناعة.
قدم منشور المدونة الرسمي لـ Cursor "اكتشاف السياق الديناميكي" بيانات مرجعية قيمة: عن طريق تحويل أوصاف أدوات MCP، وجلسات الطرفية، والمحادثات الطويلة إلى سياق قابل للتحميل عند الطلب، تم تقليل استهلاك الرمز في وقت التشغيل بنسبة 46.9%.
نهج Trae كان أكثر مباشرة: الحد من عدد أدوات MCP وطول وصف الأداة الواحدة:
- الحد الأعلى لعدد الأدوات: 40
- الحد الأقصى لوصف الأداة الواحدة: 8000 حرف
في الواقع، خلال الاختبارات الداخلية المبكرة، أبلغ العديد من الفرق أن Apidog MCP واجه مشاكل مع بعض الأدوات التي لا يمكن استدعاؤها في Trae. اضطر الوكيل إلى إجراء مقايضات بسبب سياق النموذج المحدود، وكانت الأدوات الخارجية هي أول من "قُصت".
تشير كل هذه الحلول إلى نفس الحقيقة:
لا يمكن أن تدخل أوصاف الأدوات سياق النموذج إلى ما لا نهاية.
المشكلة 3: جلسات البروتوكول تجعل سلاسل التنفيذ أثقل
يحتاج خادم Apidog MCP إلى التعامل مع:
| حالة البروتوكول | الوصف |
|---|---|
| تهيئة MCP | مصافحة بين العميل والخادم |
إنشاء sessionId |
معرف فريد للجلسة |
| تخزين جلسة Redis | استمرار الحالة |
| اتصال/إغلاق النقل | إدارة الاتصال |
| آلية إبقاء الجلسة نشطة | آلية إبقاء الجلسة نشطة |
| تنظيف عند الانتهاء | تنظيف عند الانتهاء |
| استجابة JSON أو تكوين SSE | خيارات تنسيق الإخراج |
بالنسبة لاستدعاء أداة بسيط، هذه التكاليف مقبولة. لمهام الوكيل ذات الأعداد الكبيرة من الاستدعاءات والاستكشاف المتكرر، تزيد متطلبات إدارة الحالة هذه من التعقيد على جانبي الخادم والعميل.
عند تنفيذ Apidog MCP، استهلك الفريق طاقة كبيرة في استكشاف الأخطاء وإصلاحها والتكيف مع عملاء الوكلاء المختلفين (Cursor، Claude Code، Antigravity، Trae، إلخ). ومع ذلك، استمرت مشاكل توافق البروتوكول، واستمر بروتوكول MCP الرسمي في التحديث بإصدارات جديدة.
عانت جميع الأطراف كثيرًا.
المشكلة 4: الأدوات الذرية لا يمكنها التعبير عن دلالات المنتج بشكل طبيعي
في سيناريوهات اختبار Apidog، الأمر ليس مجرد تعبير بسيط عن مصفوفة `steps`.
يتضمن سيناريو الاختبار:
| المكون | التعقيد |
|---|---|
| الاستيراد | خطوات من نقاط النهاية أو حالات موجودة |
| القراءة الراجعة | الحصول على البنية الكاملة بعد الاستيراد |
| حالات داخلية | طلبات HTTP مضمنة في الخطوات |
| معالجات ما قبل/بعد | نصوص برمجية قبل/بعد الطلبات |
| التأكيدات | قواعد التحقق من الاستجابة |
| استخراج المتغيرات | التقاط القيم من الاستجابات |
| بيئة التشغيل | اختيار البيئة، المتغيرات |
| التحقق من التقرير | التحقق من نتائج الاختبار |
بعد تقسيم هذه المكونات إلى أدوات MCP متعددة، لا يزال يتعين على الوكيل القيام بـ عمل تنسيق الاختبار بنفسه.
كلما كانت الأدوات أكثر ذرية، كلما احتاج النموذج إلى فهم دلالات المنتج الداخلية:
- لماذا يحتاج الاستيراد إلى القراءة الراجعة؟
- لماذا تحتوي الحالات الداخلية على علامات تحديث مختلفة؟
- لماذا تتطلب التأكيدات مقارنات محددة؟
- لماذا يحتوي استخراج المتغيرات على قيود النوع؟
هذا يتجاوز بوضوح نطاق قدرة النموذج.
أجبر هذا فريق Apidog على إجراء تعديلات هندسية تقنية بشكل استباقي لدلالات المنتج الداخلية. أضافت نقاط النهاية الذرية بشكل سلبي طبقة تحويل، فقط للتكيف مع إرسال طبقة أداة MCP واحدة.
التحديات الهندسية وتكاليف ما بعد الصيانة هي بلا شك شاقة.
السبب الجذري
السبب الجذري لهذه المشاكل الأربع هو الشيء نفسه:
MCP أفضل في ربط الأدوات، لكن مهام البحث والتطوير المعقدة تحتاج إلى أكثر من مجرد ربط الأدوات—فهي تحتاج إلى عمليات هندسية قابلة للتنفيذ.
| قوة MCP | قيود MCP |
|---|---|
| اتصال موحد | لا يمكن التعبير عن سير العمل |
| بروتوكول موحد | لا يمكن توجيه التسلسل |
| كشف الأدوات | لا يمكن فرض التحقق |
| اكتشاف ديناميكي | لا يمكن توفير حكم |
بالنسبة للمنتجات البسيطة التي تحتوي على عشرات العمليات المحددة جيدًا، يعمل MCP بشكل جيد. يمكن للوكيل تخمين الأداة الصحيحة بشكل معقول، واستدعائها، والحصول على نتيجة.
بالنسبة للمنتجات مثل Apidog—التي تحتوي على عشرات الوحدات، ومئات العمليات، وهياكل متداخلة، وسير عمل مخفي، ودلالات خاصة بالمنتج—يخلق MCP وحده جدارًا من الأدوات العشوائية التي يجد الوكلاء صعوبة في التنقل فيها.
ما تعلمناه
| الدرس | التضمين |
|---|---|
| المزيد من الأدوات ≠ تمكين أفضل للوكيل | عدد الأدوات تكلفة، وليس فائدة |
| أوصاف الأدوات تتنافس على السياق | 500 رمز لكل أداة × 100 أداة = عبء 50,000 رمز |
| بروتوكولات الجلسة تضيف أعباء تنفيذية | كل استدعاء يحمل إدارة حالة البروتوكول |
| الأدوات الذرية تتطلب معرفة بالمنتج | يجب على الوكلاء فهم التفاصيل الداخلية للتنسيق |
| الاتصال ≠ التنفيذ | MCP يربط؛ CLI + SKILL ينفذ |
المحور
قادنا هذا الإدراك إلى طرح سؤال مختلف:
إذا لم يكن MCP هو الحل لتمكين الوكيل، فما هو الحل؟
لم نتخل عن قيمة MCP—فهو يوفر اتصالات موحدة، وهو أمر مهم للنظام البيئي. لكننا كنا بحاجة إلى شيء يمكنه:
- التعبير عن سير العمل، وليس مجرد الأدوات
- توجيه الوكلاء عبر التسلسلات
- التحقق قبل الكتابة
- فرض بوابات جودة هندسية
- استيعاب التعقيد في النظام
الإجابة التي توصلنا إليها: CLI + SKILL.
في المنشور التالي، لماذا قمنا بتطوير Apidog CLI جديد كليًا، سنستكشف التحول المعماري—حيث انتقل التعقيد من سياق النموذج إلى النظام الهندسي، ولماذا يغير ذلك كل شيء لتمكين الوكيل.
النقاط الرئيسية
- أصبح MCP إجابة الصناعة على سؤال "كيف يتصل الوكلاء بالأدوات"
- بنينا 126 أداة MCP، معتقدين أن المزيد من الأدوات = تمكين أفضل
- كشفت المهام الحقيقية عن أربع مشاكل هيكلية: تكاليف الاكتشاف، غزو السياق، أعباء الجلسة، دلالات المنتج
- السبب الجذري: MCP يربط الأدوات، لكن المهام المعقدة تحتاج إلى عمليات قابلة للتنفيذ
- المزيد من الأدوات يمثل تكلفة، وليس فائدة، عندما تستهلك أوصاف الأدوات السياق
قم بتنزيل Apidog لـ تصميم، محاكاة، اختبار، وتوثيق واجهات برمجة التطبيقات في مساحة عمل واحدة. تعرف على المزيد حول Apidog CLI لاختبار واجهة برمجة التطبيقات عبر سطر الأوامر، وأتمتة CI، وسير عمل وكلاء الذكاء الاصطناعي.
زر