mcp-for-beginners / fa

# AGENTS.md

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

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

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

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

### معماری

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

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

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

### راه‌اندازی مخزن

```bash
# مخزن را کلون کنید
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
```bash
cd <project-directory>
npm install
npm start
```

#### پروژه‌های Python
```bash
cd <project-directory>
pip install -r requirements.txt
# یا
pip install -e .
python main.py
```

#### پروژه‌های Java
```bash
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 به صورت خودکار انجام می‌شود
4. ترجمه‌ها هنگام push به شاخه اصلی دوباره تولید می‌شوند

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

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

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

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

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

1. **اعتبارسنجی پیوندها**: اطمینان از کارکرد تمام پیوندهای داخلی
```bash
# بررسی لینک‌های خراب شده در مارک‌داون
find . -name "*.md" -type f | xargs grep -n "\[.*\](../../.*)"
```

2. **اعتبارسنجی نمونه کدها**: تست کامپایل/اجرای نمونه‌های کد
```bash
# به نمونه خاصی بروید و آزمایش‌های آن را اجرا کنید
cd 03-GettingStarted/samples/typescript
npm install && npm test
```

3. **لینت کردن Markdown**: بررسی ثبات قالب‌بندی
```bash
# در صورت نیاز از markdownlint استفاده کنید
npx markdownlint-cli2 "**/*.md" "#node_modules"
```

### تست پروژه نمونه

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

#### TypeScript/JavaScript
```bash
npm test
npm run build
```

#### Python
```bash
pytest
python -m pytest tests/
```

#### Java
```bash
mvn test
mvn verify
```

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

### سبک مستندسازی

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

### سبک نمونه کد

#### TypeScript/JavaScript
- استفاده از ماژول‌های ES (`import`/`export`)
- رعایت قواعد حالت سخت TypeScript
- درج توضیحات نوع
- هدف ES2022

#### Python
- رعایت راهنمای سبک PEP 8
- استفاده از type hints در صورت مناسب بودن
- درج docstrings برای توابع و کلاس‌ها
- استفاده از ویژگی‌های مدرن Python (نسخه ۳.۸ به بالا)

#### 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 است. برای محتوای اصلی برنامه آموزشی نیازی به مرحله کامپایل یا ساخت نیست.

### استقرار پروژه نمونه

پروژه‌های نمونه جداگانه ممکن است دستورالعمل‌های استقرار داشته باشند:
- برای راهنمای استقرار سرور MCP به `03-GettingStarted/09-deployment/` مراجعه کنید
- مثال‌های استقرار Azure Container Apps در `11-MCPServerHandsOnLabs/`

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

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

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

### قالب عنوان PR

از عناوین روشن و توصیفی استفاده کنید:
- `[Module XX] شرح مختصر` برای تغییرات ماژول خاص
- `[Samples] شرح` برای تغییرات نمونه کد
- `[Docs] شرح` برای به‌روزرسانی مستندات عمومی

### چه چیزی مشارکت کنیم

- رفع باگ‌های موجود در مستندات یا نمونه‌های کد
- افزودن نمونه‌های کد جدید در زبان‌های بیشتر
- توضیحات و بهبودهای محتوا
- مطالعات موردی جدید یا نمونه‌های عملی
- گزارش مسائل برای محتوای نامشخص یا نادرست

### چه کار نکنیم

- فایل‌های موجود در پوشه `translations/` را مستقیماً ویرایش نکنید
- پوشه `translated_images/` را ویرایش نکنید
- فایل‌های باینری بزرگ بدون بحث اضافه نکنید
- فایل‌های جریان کاری ترجمه را بدون هماهنگی تغییر ندهید

## نکات اضافی

### نگهداری مخزن

- **تغییرات**: تمام تغییرات مهم در `changelog.md` مستند شده‌اند
- **راهنمای مطالعه**: برای مروری بر ناوبری برنامه آموزشی از `study_guide.md` استفاده کنید
- **الگوهای گزارش مشکل**: از الگوهای گزارش GitHub برای باگ و درخواست ویژگی استفاده کنید
- **قواعد رفتاری**: همه مشارکت‌کنندگان باید از قوانین کد رفتار منبع باز مایکروسافت پیروی کنند

### مسیر یادگیری

برای یادگیری بهتر ماژول‌ها را به ترتیب پیگیری کنید (00-11):
1. **00-02**: اصول پایه (مقدمه، مفاهیم اصلی، امنیت)
2. **03**: شروع به کار با پیاده‌سازی عملی
3. **04-05**: پیاده‌سازی عملی و مباحث پیشرفته
4. **06-10**: جامعه، بهترین شیوه‌ها و کاربردهای دنیای واقعی
5. **11**: آزمایشگاه‌های جامع اتصال به پایگاه داده (۱۳ آزمایشگاه متوالی)

### منابع پشتیبانی

- **مستندات**: https://modelcontextprotocol.io/
- **مشخصات**: https://spec.modelcontextprotocol.io/
- **جامعه**: https://github.com/orgs/modelcontextprotocol/discussions
- **دیسکورد**: سرور دیسکورد Microsoft Foundry
- **دوره‌های مرتبط**: برای مسیرهای آموزشی مایکروسافت دیگر به README.md مراجعه کنید

### رفع مشکل رایج

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

**س: چگونه زبان جدید اضافه کنم؟**  
ج: پشتیبانی زبانی توسط جریان کاری co-op-translator مدیریت می‌شود. برای افزودن زبان‌های جدید یک Issue باز کنید.

**س: نمونه‌های کد کار نمی‌کنند**  
ج: مطمئن شوید دستورالعمل‌های راه‌اندازی در README نمونه خاص را دنبال کرده‌اید. نسخه‌های صحیح وابستگی‌ها باید نصب باشند.

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

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

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

### حاکمیت پروژه

این پروژه از روش‌های منبع باز مایکروسافت پیروی می‌کند:  
- مجوز MIT برای کد و مستندات  
- قوانین کد رفتار منبع باز مایکروسافت  
- قرارداد مشارکت‌دهنده (CLA) برای مشارکت‌ها الزامی است  
- مسائل امنیتی: دستورالعمل‌های SECURITY.md را دنبال کنید  
- پشتیبانی: برای منابع کمکی SUPPORT.md را ببینید

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**سلب مسئولیت**:
این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->