fa

Imported from ShunheWang/maison-ai-learning-sandbox (docs-resources/mcp/mcp-for-beginners-main/translations/fa/AGENTS.md). Install upstream with npx skills add ShunheWang/maison-ai-learning-sandbox --skill fa. Copyright stays with the author.

AGENTS.md

نمای کلی پروژه

MCP برای مبتدیان یک برنامه آموزشی متن‌باز برای یادگیری پروتکل مدل کانتکست (MCP) است - یک چارچوب استاندارد برای تعاملات بین مدل‌های هوش مصنوعی و برنامه‌های مشتری. این مخزن مواد آموزشی جامع همراه با مثال‌های کدنویسی عملی در زبان‌های برنامه‌نویسی مختلف ارائه می‌دهد.

فناوری‌های کلیدی

• زبان‌های برنامه‌نویسی: C#، Java، JavaScript، TypeScript، Python، Rust
• فریم‌ورک‌ها و SDKها:
  • MCP SDK (@modelcontextprotocol/sdk)
  • Spring Boot (Java)
  • FastMCP (Python)
  • LangChain4j (Java)
• پایگاه‌های داده: PostgreSQL با افزونه pgvector
• پلتفرم‌های ابری: Azure (برنامه‌های کانتینری، OpenAI، ایمنی محتوا، Application Insights)
• ابزارهای ساخت: npm، Maven، pip، Cargo
• مستندسازی: Markdown با ترجمه خودکار به چندین زبان (بیش از 48 زبان)

معماری

• 11 ماژول اصلی (00-11): مسیر یادگیری ترتیبی از مبانی تا موضوعات پیشرفته
• آزمایشگاه‌های عملی: تمرین‌های عملی با کدهای حل کامل در زبان‌های مختلف
• پروژه‌های نمونه: پیاده‌سازی‌های سرور و مشتری MCP
• سیستم ترجمه: گردش کار خودکار GitHub Actions برای پشتیبانی چندزبانه
• دارایی‌های تصویری: دایرکتوری مرکزی تصاویر با نسخه‌های ترجمه‌شده

دستورات راه‌اندازی

این مخزن بر مستندسازی متمرکز است. بیشتر تنظیمات در پروژه‌های نمونه و آزمایشگاه‌های جداگانه انجام می‌شود.

تنظیم مخزن

# Clone the repository
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
# or
pip install -e .
python main.py

پروژه‌های Java

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

گردش کار توسعه

ساختار مستندات

• ماژول‌های 00-11: محتوای اصلی برنامه آموزشی به ترتیب
• translations/: نسخه‌های زبان‌های مختلف (خودکار تولید شده، مستقیماً ویرایش نکنید)
• translated_images/: نسخه‌های تصویری محلی‌سازی شده (خودکار تولید شده)
• images/: تصاویر و نمودارهای منبع

ایجاد تغییرات در مستندات

1. فقط فایل‌های Markdown انگلیسی را در دایرکتوری‌های ماژول اصلی (00-11) ویرایش کنید
2. در صورت نیاز تصاویر را در دایرکتوری images/ به‌روزرسانی کنید
3. GitHub Action co-op-translator به‌طور خودکار ترجمه‌ها را تولید می‌کند
4. ترجمه‌ها با هر بار ارسال به شاخه اصلی دوباره تولید می‌شوند

کار با ترجمه‌ها

• ترجمه خودکار: گردش کار GitHub Actions تمام ترجمه‌ها را مدیریت می‌کند
• فایل‌ها را به صورت دستی ویرایش نکنید در دایرکتوری translations/
• متادیتای ترجمه در هر فایل ترجمه‌شده جاسازی شده است
• زبان‌های پشتیبانی‌شده: بیش از 48 زبان از جمله عربی، چینی، فرانسوی، آلمانی، هندی، ژاپنی، کره‌ای، پرتغالی، روسی، اسپانیایی و بسیاری دیگر

دستورالعمل‌های تست

اعتبارسنجی مستندات

از آنجا که این مخزن عمدتاً مستندات است، تست‌ها بر موارد زیر تمرکز دارند:

1. اعتبارسنجی لینک‌ها: اطمینان حاصل کنید که تمام لینک‌های داخلی کار می‌کنند

# Check for broken markdown links
find . -name "*.md" -type f | xargs grep -n "\[.*\](../../.*)"

2. اعتبارسنجی نمونه‌های کد: بررسی کنید که نمونه‌های کد کامپایل/اجرا شوند

# Navigate to specific sample and run its tests
cd 03-GettingStarted/samples/typescript
npm install && npm test

3. بررسی Markdown: بررسی سازگاری قالب‌بندی

# Use markdownlint if needed
npx markdownlint-cli2 "**/*.md" "#node_modules"

تست پروژه‌های نمونه

هر نمونه خاص زبان شامل روش تست خود است:

TypeScript/JavaScript

npm test
npm run build

Python

pytest
python -m pytest tests/

Java

mvn test
mvn verify

دستورالعمل‌های سبک کدنویسی

سبک مستندات

• از زبان واضح و مناسب برای مبتدیان استفاده کنید
• نمونه‌های کد را در زبان‌های مختلف در صورت امکان درج کنید
• بهترین شیوه‌های Markdown را دنبال کنید:
  • از هدرهای سبک ATX (# syntax) استفاده کنید
  • از بلوک‌های کد محصور با شناسه‌های زبان استفاده کنید
  • متن جایگزین توصیفی برای تصاویر درج کنید
  • طول خطوط را معقول نگه دارید (بدون محدودیت سخت، اما منطقی باشید)

سبک نمونه‌های کد

TypeScript/JavaScript

• از ماژول‌های ES (import/export) استفاده کنید
• کنوانسیون‌های حالت سخت TypeScript را دنبال کنید
• حاشیه‌نویسی نوع را درج کنید
• هدف ES2022 باشد

Python

• دستورالعمل‌های سبک PEP 8 را دنبال کنید
• در صورت مناسب از نوع‌گذاری استفاده کنید
• برای توابع و کلاس‌ها docstring درج کنید
• از ویژگی‌های مدرن 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. ترجمه خودکار تمام فایل‌های Markdown انگلیسی
3. محلی‌سازی تصاویر در صورت نیاز

نیازی به فرآیند ساخت نیست

این مخزن عمدتاً شامل مستندات Markdown است. برای محتوای اصلی برنامه آموزشی نیازی به کامپایل یا مرحله ساخت نیست.

استقرار پروژه‌های نمونه

پروژه‌های نمونه جداگانه ممکن است دستورالعمل‌های استقرار داشته باشند:

• به 03-GettingStarted/09-deployment/ برای راهنمایی استقرار سرور MCP مراجعه کنید
• مثال‌های استقرار برنامه‌های کانتینری Azure در 11-MCPServerHandsOnLabs/

دستورالعمل‌های مشارکت

فرآیند درخواست کشش (Pull Request)

1. Fork و Clone: مخزن را Fork کنید و Fork خود را به صورت محلی Clone کنید
2. ایجاد شاخه: از نام‌های شاخه توصیفی استفاده کنید (مانند fix/typo-module-3، add/python-example)
3. ایجاد تغییرات: فقط فایل‌های Markdown انگلیسی را ویرایش کنید (نه ترجمه‌ها)
4. تست محلی: بررسی کنید که Markdown به درستی نمایش داده شود
5. ارسال PR: از عناوین و توضیحات واضح برای PR استفاده کنید
6. CLA: توافق‌نامه مجوز مشارکت‌کننده Microsoft را هنگام درخواست امضا کنید

قالب عنوان PR

از عناوین واضح و توصیفی استفاده کنید:

• [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://spec.modelcontextprotocol.io/
• جامعه: https://github.com/orgs/modelcontextprotocol/discussions
• Discord: سرور Discord Microsoft Azure AI Foundry
• دوره‌های مرتبط: README.md را برای مسیرهای آموزشی دیگر Microsoft مشاهده کنید

مشکلات رایج

سؤال: PR من در بررسی ترجمه شکست خورده است پاسخ: اطمینان حاصل کنید که فقط فایل‌های Markdown انگلیسی را در دایرکتوری‌های ماژول اصلی ویرایش کرده‌اید، نه نسخه‌های ترجمه‌شده.

سؤال: چگونه یک زبان جدید اضافه کنم؟ پاسخ: پشتیبانی زبان از طریق گردش کار co-op-translator مدیریت می‌شود. برای بحث در مورد افزودن زبان‌های جدید یک مشکل باز کنید.

سؤال: نمونه‌های کد کار نمی‌کنند پاسخ: اطمینان حاصل کنید که دستورالعمل‌های تنظیم در README نمونه خاص را دنبال کرده‌اید. بررسی کنید که نسخه‌های صحیح وابستگی‌ها نصب شده باشند.

سؤال: تصاویر نمایش داده نمی‌شوند پاسخ: بررسی کنید که مسیرهای تصاویر نسبی باشند و از اسلش‌های جلو استفاده کنند. تصاویر باید در دایرکتوری images/ یا translated_images/ برای نسخه‌های محلی‌سازی شده باشند.

ملاحظات عملکرد

• گردش کار ترجمه ممکن است چند دقیقه طول بکشد
• تصاویر بزرگ باید قبل از ارسال بهینه شوند
• فایل‌های Markdown را متمرکز و با اندازه معقول نگه دارید
• از لینک‌های نسبی برای قابلیت حمل بهتر استفاده کنید

حاکمیت پروژه

این پروژه از شیوه‌های متن‌باز Microsoft پیروی می‌کند:

• مجوز MIT برای کد و مستندات
• کد اخلاقی متن‌باز Microsoft
• CLA برای مشارکت‌ها لازم است
• مسائل امنیتی: دستورالعمل‌های SECURITY.md را دنبال کنید
• پشتیبانی: برای منابع کمک به SUPPORT.md مراجعه کنید

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.