ar

Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/microsoft@mcp-for-beginners/translations/ar/AGENTS.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill ar. Copyright stays with the author.

AGENTS.md

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

MCP للمبتدئين هو منهج تعليمي مفتوح المصدر لتعلم بروتوكول سياق النموذج (MCP) - إطار عمل معياري للتفاعلات بين نماذج الذكاء الاصطناعي وتطبيقات العملاء. يوفر هذا المستودع مواد تعليمية شاملة مع أمثلة تعليمية عملية عبر لغات برمجة متعددة.

التقنيات الرئيسية

• لغات البرمجة: C#، Java، JavaScript، TypeScript، Python، Rust
• الأُطُر ومجموعات تطوير البرمجيات (SDKs):
  • MCP SDK (@modelcontextprotocol/sdk)
  • Spring Boot (جافا)
  • FastMCP (بايثون)
  • LangChain4j (جافا)
• قواعد البيانات: PostgreSQL مع ملحق pgvector
• منصات السحابة: Azure (تطبيقات الحاويات، OpenAI، أمان المحتوى، إحصائيات التطبيقات)
• أدوات البناء: npm، Maven، pip، Cargo
• التوثيق: Markdown مع ترجمة آلية متعددة اللغات (48+ لغة)

الهيكلية

• 11 وحدة أساسية (00-11): مسار تعليمي تسلسلي من الأساسيات إلى المواضيع المتقدمة
• معامل عملية: تمارين عملية مع كود حلي كامل بلغات متعددة
• مشاريع نموذجية: تطبيقات خادم وعميل MCP عاملة
• نظام الترجمة: سير عمل آلي عبر GitHub Actions لدعم تعدد اللغات
• موارد الصور: مجلد مركزي للصور مع نسخ مترجمة

أوامر التهيئة

هذا المستودع موجه للوثائق. يتم معظم الإعداد داخل المشاريع النموذجية والمعامل الفردية.

تهيئة المستودع

# استنساخ المستودع
git clone https://github.com/microsoft/mcp-for-beginners.git
cd mcp-for-beginners

العمل مع المشاريع النموذجية

تقع المشاريع النموذجية في:

• 03-GettingStarted/samples/ - أمثلة خاصة بكل لغة
• 03-GettingStarted/01-first-server/solution/ - تنفيذات الخادم الأولى
• 03-GettingStarted/02-client/solution/ - تنفيذات العميل
• 11-MCPServerHandsOnLabs/ - معامل تكامل قواعد بيانات شاملة

يحتوي كل مشروع نموذجي على تعليمات الإعداد الخاصة به:

مشاريع TypeScript/JavaScript

cd <project-directory>
npm install
npm start

مشاريع Python

cd <project-directory>
pip install -r requirements.txt
# أو
pip install -e .
python main.py

مشاريع Java

cd <project-directory>
mvn clean install
mvn spring-boot:run

سير عمل التطوير

الجاهزية لـ MCP 7-28

قائمة التحقق من جاهزية المستودع

• وضوح للمساهمين الجدد: هذا الملف يحدد هدف المستودع، هيكلته، قواعد المساهمة، ومسارات إعداد العينات.

• أوامر البناء/الاختبار/التحقق من النمط مع العلامات الدقيقة:

  • تدقيق نمط وثائق المستودع: npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"
  • تدقيق نمط الروابط في وثائق المستودع: find . -name "*.md" -not -path "*/node_modules/*" -not -path "./translations/*" -not -path "./translated_images/*" -print0 | xargs -0 grep -En "\[.*\]\(.*\)"
  • التحقق من صحة عينات TypeScript: cd 03-GettingStarted/samples/typescript && npm ci && npm test && npm run build
  • التحقق من صحة عينات Python: cd 10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab3/code/weather_mcp && python -m pip install -e . && pytest -q
  • التحقق من صحة عينات Java: cd 03-GettingStarted/samples/java/calculator && mvn -B -ntp test verify

• تدفق عمل واقعي واحد يمكن أن يصبح أداة MCP: validate_curriculum_change

• المدخلات/المخرجات واضحة وصريحة (انظر المواصفات أدناه).

• الأذونات وأنماط الفشل موثقة (انظر المواصفات أدناه).

• قابلية الاختبار في CI صريحة (أوامر حتمية، رموز خروج صريحة، ومخرجات قابلة للقراءة آليًا). exit codes, and machine-readable outputs).

تدفق عمل أداة MCP المرشحة: validate_curriculum_change

الهدف

التحقق من صحة تغييرات وثائق المنهج الدراسي والعينة التمثيلية للكود قبل الدمج.

المدخلات

• changed_paths: string[] (مطلوب) - المسارات النسبية التي تم تغييرها في PR.
• run_docs_lint: boolean (افتراضي true)
• run_links_audit: boolean (افتراضي true)
• run_samples: { typescript?: boolean, python?: boolean, java?: boolean } (افتراضي جميعها false)

المخرجات

• status: "ok" | "failed"
• checks: Array<{ name: string, command: string, exit_code: number, summary: string }>
• artifacts: Array<{ type: "log" | "report", path: string }>
• failed_checks: string[]

الأذونات

• قراءة ملفات مساحة العمل وكتابة العناصر التي تنشئها الأداة فقط (مثل تقارير التنقيح، سجلات الاختبار)؛ لا كتابة إلى translations/ أو translated_images/.
• تنفيذ أوامر shell محلية.
• الوصول إلى الشبكة اختياري فقط لاستعادة الحزم (npm ci, python -m pip install, mvn لحل التبعيات).
• لا يوجد إذن للدفع، الدمج، أو تعديل translations/ أو translated_images/.

أنماط الفشل

• E_NO_INPUT_PATHS: changed_paths فارغة.
• E_INVALID_PATH: مسار الإدخال يخرج عن جذر المستودع.
• E_LINT_FAILED: خروج تنقيح markdown برمز غير صفر.
• E_LINK_AUDIT_FAILED: خرج أمر مراجعة الروابط برمز غير صفر.
• E_SAMPLE_TEST_FAILED: خرج اختبار/بناء العينة برمز غير صفر.
• E_TIMEOUT: تجاوز الأمر المهلة المخصصة.

عقد CI الموصى به

لأتمتة التحقق، قم بتكوين مهمة CI التي:

• تبدأ عند طلبات السحب التي تمس ملفات *.md، كود العينات، أو هذا الملف.
• تنفذ الأوامر الدقيقة المذكورة أعلاه.
• تحفظ السجلات كعناصر.
• تفشل المهمة عند أي رمز خروج غير صفر.

إذا قمت بإطلاق خادم MCP من هذا المستودع

• اقرأ سجل التغييرات النهائي MCP 2026-07-28: https://modelcontextprotocol.io/specification/2026-07-28/changelog

• تحقق من أن إصدار SDK المختار يدعم MCP 2026-07-28: https://modelcontextprotocol.io/docs/sdk

• أزل الافتراضات المتعلقة بالجلسة والمصافحة؛ عامل كل طلب كونه مستقلًا بذاته: https://modelcontextprotocol.io/specification/2026-07-28/basic/lifecycle

• أرسل رؤوس Mcp-Method و Mcp-Name لطلبات HTTP الخام: https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http

• راجع رموز الخطأ المشفرة صلبًا (missing resource انتقل من -32002 إلى -32602).

• ترحيل الجذور والاختيار والتسجيل الديناميكي للعميل المسجل المهمل التسجيل: https://modelcontextprotocol.io/specification/2026-07-28/deprecated

• الترحيل من واجهة برمجة التطبيقات التجريبية 2025-11-25 للمهام: https://modelcontextprotocol.io/extensions/tasks

• مراجعة التفويض لتقوية OAuth وOpenID Connect: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization

هيكلية التوثيق

• الوحدات 00-11: محتوى المنهج الأساسي بترتيب متسلسل
• translations/: نسخ مخصصة للغات (مولدة تلقائيًا، لا تعدل مباشرة)
• translated_images/: نسخ صور مترجمة (مولدة تلقائيًا)
• images/: الصور والمخططات المصدرية

إجراء تغييرات في التوثيق

1. حرر فقط ملفات الماركداون الإنجليزية في دلائل الوحدات الجذرية (00-11)
2. حدِّث الصور في دليل images/ إذا لزم الأمر
3. ستقوم عملية GitHub Action المسماة co-op-translator بتوليد الترجمات تلقائيًا
4. تُعاد توليد الترجمات عند دفع التغييرات إلى الفرع الرئيسي

العمل مع الترجمات

• الترجمة الآلية: سير عمل GitHub Actions يتولى كل الترجمات
• لا تعدل يدويًا في ملفات دليل translations/
• بيانات وصفية للترجمة مدمجة داخل كل ملف مترجم
• اللغات المدعومة: أكثر من 48 لغة تشمل العربية، والصينية، والفرنسية، والألمانية، والهندية، واليابانية، والكورية، والبرتغالية، والروسية، والإسبانية، وغيرها الكثير

تعليمات الاختبار

التحقق من التوثيق

بما أن هذا المستودع يختص في التوثيق أساسًا، يركز الاختبار على:

1. تدقيق نمط الروابط: سرد روابط ماركداون للمراجعة

   # سرد روابط ماركداون (تدقيق النمط)
   find . -name "*.md" -not -path "*/node_modules/*" -not -path "./translations/*" -not -path "./translated_images/*" -print0 | xargs -0 grep -En "\[.*\]\(.*\)"

2. التحقق من أمثلة الشفرة: اختبار أن أمثلة الشفرة تترجم وتعمل

   # انتقل إلى العينة المحددة وقم بتشغيل اختباراتها
   cd 03-GettingStarted/samples/typescript
   npm install && npm test

3. مراجعة تنسيق الماركداون: التحقق من اتساق التنسيق

   # استخدم markdownlint إذا لزم الأمر
   npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"

اختبار مشروع عينة

كل عينة لكل لغة تشمل نهج اختبار خاص بها:

TypeScript/JavaScript

npm test
npm run build

Python

pytest
python -m pytest tests/

Java

mvn test
mvn verify

إرشادات أسلوب الشفرة

أسلوب التوثيق

• استخدم لغة واضحة ومناسبة للمبتدئين
• أضف أمثلة شفرة بلغات متعددة عند الاقتضاء
• اتبع أفضل الممارسات في الماركداون:
  • استخدم رؤوس ATX (# الدلالة)
  • استخدم أقسام شفرة محاطة مع محددات اللغة
  • أدرج نصًا بديلًا وصفيًا للصور
  • حافظ على طول الأسطر معقولًا (بدون حد صارم، لكن كن معقولًا)

أسلوب مثال الشفرة

TypeScript/JavaScript

• استخدم وحدات ES (import/export)
• اتبع قواعد الوضع الصارم لـ TypeScript
• أدرج تعليقات نوعية
• استهدف ES2022

Python

• اتبع إرشادات أسلوب PEP 8
• استخدم تلميحات النوع حيثما كان مناسبًا
• أدرج سلاسل توثيقية للدوال والفئات
• استخدم ميزات Python الحديثة (3.8+)

Java

• اتبع قواعد Spring Boot
• استخدم ميزات Java 21
• اتبع هيكل مشروع Maven القياسي
• أدرج تعليقات Javadoc

تنظيم الملفات

<module-number>-<ModuleName>/
├── README.md              # Main module content
├── samples/               # Code examples (if applicable)
│   ├── typescript/
│   ├── python/
│   ├── java/
│   └── ...
└── solution/              # Complete working solutions
    └── <language>/

البناء والنشر

نشر التوثيق

يستخدم المستودع GitHub Pages أو ما شابه لاستضافة التوثيق (إذا كان ذلك ممكنًا). تؤدي التغييرات في الفرع الرئيسي إلى:

1. سير العمل الخاص بالترجمة (.github/workflows/co-op-translator.yml)

2. الترجمة الآلية لكل ملفات الماركداون الإنجليزية

3. توطين الصور حسب الحاجة

لا حاجة لعملية بناء

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

نشر مشروع نموذجي

قد تحتوي بعض مشاريع العينات الفردية على تعليمات نشر:

• انظر 03-GettingStarted/09-deployment/ للحصول على إرشادات نشر خادم MCP
• أمثلة نشر تطبيقات حاويات Azure في 11-MCPServerHandsOnLabs/

إرشادات المساهمة

عملية طلب السحب

1. افعل فورك واستنسخ: قم بعمل فورك للمستودع واستنسخ فوركك محليًا
2. أنشئ فرعًا: استخدم أسماء فروع وصفية (مثل fix/typo-module-3، add/python-example)
3. قم بالتغييرات: حرر ملفات الماركدوان الإنجليزية فقط (ليس الترجمات)
4. اختبر محليًا: تحقق من أن الماركدوان يعرض بشكل صحيح
5. قدّم طلب السحب: استخدم عناوين وأوصاف واضحة لطلبات السحب
6. CLA: وقع على اتفاقية ترخيص المساهمين الخاصة بـ Microsoft عند الطلب

صيغة عنوان طلب السحب

استخدم عناوين واضحة ووصفية:

• [Module XX] وصف مختصر للتغييرات الخاصة بالوحدة
• [Samples] وصف لتغييرات كود الأمثلة
• [Docs] وصف لتحديثات التوثيق العامة

ما يجب المساهمة به

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

ما لا يجب القيام به

• لا تقم بتحرير الملفات مباشرة في دليل translations/
• لا تعدل دليل translated_images/
• لا تضف ملفات ثنائية كبيرة دون مناقشة
• لا تغير ملفات سير عمل الترجمة بدون تنسيق

ملاحظات إضافية

صيانة المستودع

• سجل التغييرات: جميع التغييرات المهمة موثقة في changelog.md
• دليل الدراسة: استخدم study_guide.md لمراجعة تنقل المنهج
• قوالب القضايا: استخدم قوالب قضايا GitHub للإبلاغ عن الأخطاء وطلبات الميزات
• مدونة السلوك: يجب على جميع المساهمين اتباع مدونة سلوك المصدر المفتوح لشركة Microsoft

مسار التعلم

اتبع الوحدات بالترتيب التسلسلي (00-11) لتحقيق أفضل تعلم:

1. 00-02: الأساسيات (مقدمة، مفاهيم أساسية، الأمان)
2. 03: البدء مع التنفيذ العملي
3. 04-05: التنفيذ العملي والمواضيع المتقدمة
4. 06-10: المجتمع، الممارسات الأفضل، والتطبيقات الواقعية
5. 11: مختبرات تكامل قاعدة بيانات شاملة (13 مختبر متتابع)

موارد الدعم

• التوثيق: https://modelcontextprotocol.io/
• المواصفة: https://modelcontextprotocol.io/specification/2026-07-28/
• المجتمع: https://github.com/orgs/modelcontextprotocol/discussions
• ديسكورد: خادم Microsoft Foundry Discord
• الدورات ذات الصلة: انظر README.md لمسارات تعلم Microsoft الأخرى

استكشاف المشكلات الشائعة

س: طلب السحب الخاص بي يفشل في فحص الترجمة ج: تأكد من أنك حررت فقط ملفات ماركداون الإنجليزية في دلائل الوحدات الأساسية، لا النسخ المترجمة.

س: كيف أضيف لغة جديدة؟ ج: يتم إدارة دعم اللغات عبر سير عمل co-op-translator. افتح قضية لمناقشة إضافة لغات جديدة.

س: عينات الكود لا تعمل

أ: تأكد من أنك اتبعت تعليمات الإعداد في ملف README الخاص بالعينة المحددة. تحقق من أنك قد قمت بتثبيت الإصدارات الصحيحة من التبعيات.

س: الصور لا تظهر

أ: تحقق من أن مسارات الصور نسبية وتستخدم الشرط المائل للأمام. يجب أن تكون الصور في دليل images/ أو translated_images/ للإصدارات المترجمة.

اعتبارات الأداء

• قد يستغرق سير عمل الترجمة عدة دقائق لإكماله
• يجب تحسين الصور الكبيرة قبل الالتزام بها
• حافظ على ملفات الماركدوان الفردية مركزة وبحجم معقول
• استخدم روابط نسبية لسهولة النقل

حوكمة المشروع

يتبع هذا المشروع ممارسات المصدر المفتوح لشركة Microsoft:

• ترخيص MIT للكود والوثائق
• مدونة سلوك كود المصدر المفتوح لمايكروسوفت
• اتفاقية تقديم المساهمة مطلوبة للمساهمات
• قضايا الأمان: اتبع إرشادات SECURITY.md
• الدعم: راجع SUPPORT.md لمصادر المساعدة

تنويه: تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي Co-op Translator. بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.