خادم CircleCI MCP - تطبيق خادم متخصص مصمم خصيصًا لبروتوكول سياق النموذج، ومصمم لدمج سير عمل تطوير CircleCI

مقدمة عن مشروع خادم CircleCI MCP

نظرة عامة على المشروع

خادم CircleCI MCP هو تطبيق خادم متخصص مصمم لبروتوكول سياق النموذج (MCP)، ويهدف إلى دمج سير عمل تطوير CircleCI. يعمل هذا المشروع كجسر بين البنية التحتية لـ CircleCI وبروتوكول سياق النموذج، مما يوفر تجربة تطوير معززة مدعومة بالذكاء الاصطناعي.

يمكّن هذا الخادم أدوات الذكاء الاصطناعي مثل Cursor و Claude Code و Windsurf من فهم نظام البناء الخاص بك. وهو مبني على بروتوكول سياق النموذج (MCP)، وهو معيار خفيف الوزن يسمح للوكلاء المدعومين بنماذج اللغة الكبيرة (LLM) بالحصول على بيانات منظمة من الأنظمة الخارجية.

الوظائف الأساسية

الأدوات والوظائف الرئيسية

1. get_build_failure_logs

استرجاع سجلات الفشل التفصيلية لبناء CircleCI. تدعم هذه الأداة طريقتين للاستخدام:

باستخدام عنوان URL لـ CircleCI:

• قم بتوفير عنوان URL لوظيفة فاشلة أو مسار (pipeline) مباشرةً.
• مثال: "احصل على سجلات https://app.circleci.com/pipelines/github/org/repo/123"

باستخدام سياق المشروع المحلي:

• العمل من مساحة العمل المحلية عن طريق توفير المعلومات التالية:
  • مسار جذر مساحة العمل
  • عنوان URL البعيد لـ Git
  • اسم الفرع
• مثال: "ابحث عن أحدث مسار فاشل على فرعي الحالي"

تتضمن السجلات المنسقة التي تم إرجاعها ما يلي:

• اسم الوظيفة
• تفاصيل التنفيذ خطوة بخطوة
• رسائل وسياق الفشل

2. find_flaky_tests

تحديد الاختبارات غير المستقرة في مشروع CircleCI عن طريق تحليل سجل تنفيذ الاختبار. تدعم هذه الأداة طريقتين للاستخدام:

باستخدام عنوان URL لمشروع CircleCI:

• قم بتوفير عنوان URL للمشروع مباشرةً من CircleCI.
• مثال: "ابحث عن الاختبارات غير المستقرة في https://app.circleci.com/pipelines/github/org/repo"

باستخدام سياق المشروع المحلي:

• العمل من مساحة العمل المحلية عن طريق توفير مسار جذر مساحة العمل وعنوان URL البعيد لـ Git.

إرجاع معلومات تفصيلية عن الاختبارات غير المستقرة، بما في ذلك:

• اسم الاختبار وموقع الملف
• رسائل وسياق الفشل

3. get_latest_pipeline_status

استرجاع حالة أحدث مسار لفرع معين. تُرجع الأداة الحالة المنسقة لأحدث مسار:

• اسم سير العمل وحالته الحالية
• مدة كل سير عمل
• الطوابع الزمنية للإنشاء والإكمال
• الصحة العامة للمسار

مثال على الإخراج:

---
سير العمل: build
الحالة: نجاح
المدة: 5 دقائق
تم الإنشاء: 20/4/2025، 10:15:30 صباحًا
تم الإيقاف: 20/4/2025، 10:20:45 صباحًا
---
سير العمل: test
الحالة: قيد التشغيل
المدة: غير معروفة
تم الإنشاء: 20/4/2025، 10:21:00 صباحًا
تم الإيقاف: قيد التقدم

4. get_job_test_results

استرجاع بيانات تعريف اختبار وظيفة CircleCI، مما يسمح لك بتحليل نتائج الاختبار دون مغادرة بيئة التطوير المتكاملة (IDE).

إرجاع معلومات تفصيلية عن نتائج الاختبار:

• ملخص لجميع الاختبارات (إجمالي، ناجح، فاشل)
• تفاصيل الاختبارات الفاشلة، بما في ذلك:
  • اسم الاختبار والفئة
  • موقع الملف
  • رسالة الخطأ
  • مدة وقت التشغيل
• قائمة بالاختبارات الناجحة مع معلومات الوقت

5. config_helper

المساعدة في مهام تكوين CircleCI، وتوفير التوجيه والتحقق. تساعدك هذه الأداة على:

• التحقق من صحة تكوين CircleCI:
  • التحقق من وجود أخطاء نحوية ودلالية في .circleci/config.yml الخاص بك.
  • مثال: "تحقق من صحة تكوين CircleCI الخاص بي"

توفير:

• نتائج التحقق التفصيلية
• اقتراحات التكوين

6. create_prompt_template

إنشاء قوالب مطالبات منظمة للتطبيقات التي تدعم الذكاء الاصطناعي بناءً على متطلبات الوظائف. هذه الأداة:

• تحويل متطلبات الوظائف إلى مطالبات منظمة:
  • تحويل متطلبات المستخدم إلى قوالب مطالبات محسنة.
  • مثال: "إنشاء قالب مطالبة لإنشاء قصص ما قبل النوم حسب العمر والموضوع"

7. recommend_prompt_template_tests

إنشاء حالات اختبار لقوالب المطالبات، والتأكد من أنها تنتج النتائج المتوقعة.

التثبيت والتكوين

متطلبات النظام

• مدير حزم pnpm - اعرف المزيد
• Node.js >= v18.0.0
• رمز API لـ CircleCI - يمكنك إنشاء واحد من خلال CircleCI. اعرف المزيد أو انقر هنا للوصول السريع.

بيئات التطوير المتكاملة والأدوات المدعومة

Cursor IDE

أضف ما يلي إلى تكوين MCP الخاص بـ Cursor:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // اختياري - مطلوب فقط لعملاء النشر المحلي
      }
    }
  }
}

VS Code

قم بتثبيت خادم CircleCI MCP في .vscode/mcp.json:

{
  // 💡 يتم إدخال المطالبات في أول تشغيل للخادم، ثم يتم تخزينها بشكل آمن بواسطة VS Code
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

أضف ما يلي إلى claude_desktop_config.json الخاص بك:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // اختياري - مطلوب فقط لعملاء النشر المحلي
      }
    }
  }
}

موقع ملف التكوين:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

بعد تثبيت Claude Code، قم بتشغيل الأمر التالي:

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci

Windsurf

أضف ما يلي إلى mcp_config.json الخاص بـ Windsurf:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // اختياري - مطلوب فقط لعملاء النشر المحلي
      }
    }
  }
}

التثبيت التلقائي

قم بتثبيت خادم CircleCI MCP تلقائيًا لـ Claude Desktop عبر Smithery:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

التطوير والمساهمة

إعداد التطوير المحلي

1. استنساخ المستودع:

git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

2. تثبيت التبعيات:

pnpm install

3. بناء المشروع:

pnpm build

التطوير باستخدام مدقق MCP

أسهل طريقة لتكرار خادم MCP هي استخدام مدقق MCP.

1. تشغيل خادم التطوير:

pnpm watch # استمر في التشغيل في محطة طرفية واحدة

2. تشغيل المدقق في محطة طرفية منفصلة:

pnpm inspector

3. تكوين البيئة:
   • أضف CIRCLECI_TOKEN الخاص بك في قسم المتغيرات البيئية في واجهة مستخدم المدقق.
   • يجب أن يكون للرمز المميز حق الوصول للقراءة إلى مشروع CircleCI الخاص بك.
   • اختياريًا، قم بتعيين عنوان URL الأساسي لـ CircleCI الخاص بك، والذي يتم تعيينه افتراضيًا على https://circleci.com.

الاختبار

تشغيل مجموعة الاختبار:

pnpm test

تشغيل الاختبارات في وضع المراقبة أثناء التطوير:

pnpm test:watch

حالات الاستخدام

هذه الأداة مفيدة بشكل خاص لـ:

• تصحيح أخطاء البناء الفاشلة
• تحليل فشل الاختبار
• التحقيق في مشاكل النشر
• الوصول السريع إلى سجلات البناء دون مغادرة بيئة التطوير المتكاملة (IDE)
• التحقق من حالة أحدث مسار
• تحديد الاختبارات غير الموثوقة في مجموعة الاختبار
• اتخاذ قرارات مستندة إلى البيانات بشأن تحسينات الاختبار

مزايا المشروع

تم تصميم خادم CircleCI MCP لدعم اللحظات الفعلية في دورة حياة التطوير. سواء كنت تراجع بناءً فاشلاً، أو تصحح أخطاء نشر فاشل، أو تركز على فرع مهم، فإنه يساعد مساعدك على فهم الإخفاقات واقتراح الإصلاحات في ثوانٍ - دون تبديل السياق.

من خلال دمج خادم MCP هذا، يمكن للمطورين:

• التفاعل مع CircleCI باستخدام اللغة الطبيعية
• الحصول على معلومات البناء في بيئة التطوير المألوفة
• تشخيص وحل مشاكل CI/CD بسرعة
• تحسين كفاءة سير عمل التطوير

موارد ذات صلة

• مقدمة بروتوكول سياق النموذج
• وثائق CircleCI
• دليل جمع بيانات الاختبار
• إدارة رموز API لـ CircleCI

للحصول على إرشادات مساهمة أكثر تفصيلاً، يرجى الرجوع إلى ملف CONTRIBUTING.md في المشروع.