mcp-for-beginners / ur

# AGENTS.md

## پروجیکٹ کا جائزہ

**MCP برائے مبتدیان** ماڈل کانٹیکسٹ پروٹوکول (MCP) سیکھنے کے لیے ایک اوپن سورس تعلیمی نصاب ہے - جو AI ماڈلز اور کلائنٹ ایپلیکیشنز کے مابین تعاملات کے لیے ایک معیاری فریم ورک ہے۔ یہ ریپوزٹری مختلف پروگرامنگ زبانوں میں عملی کوڈ کی مثالوں کے ساتھ جامع تعلیمی مواد فراہم کرتی ہے۔

### کلیدی ٹیکنالوجیز

- **پروگرامنگ زبانیں**: C#, Java, JavaScript, TypeScript, Python, Rust  
- **فریم ورکس اور SDKs**:  
  - MCP SDK (`@modelcontextprotocol/sdk`)  
  - Spring Boot (Java)  
  - FastMCP (Python)  
  - LangChain4j (Java)  
- **ڈیٹابیسز**: PostgreSQL بمع pgvector توسیع  
- **کلاؤڈ پلیٹ فارمز**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)  
- **بلڈ ٹولز**: npm, Maven, pip, Cargo  
- **دستاویزات**: مارکڈاؤن بمع خودکار کثیر لسانی ترجمہ (48+ زبانیں)  

### ساخت

- **11 بنیادی ماڈیولز (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. صرف روٹ ماڈیول ڈائریکٹریز (00-11) میں انگریزی مارکڈاؤن فائلز میں ترمیم کریں  
2. `images/` فولڈر میں تصاویر کو ضرورت کے مطابق اپ ڈیٹ کریں  
3. co-op-translator GitHub Action خود بخود ترجمے بنائے گا  
4. ترجمے مین برانچ پر push ہونے پر دوبارہ تخلیق کیے جاتے ہیں  

### ترجموں کے ساتھ کام کرنا

- **خودکار ترجمہ**: GitHub Actions ورک فلو تمام ترجمے ہینڈل کرتا ہے  
- `translations/` فولڈر کی فائلز کو دستی طور پر ترمیم نہ کریں  
- ترجمہ میٹا ڈیٹا ہر ترجمہ شدہ فائل میں شامل ہوتا ہے  
- معاون زبانیں: 48+ زبانیں بشمول عربی، چینی، فرانسیسی، جرمن، ہندی، جاپانی، کوریائی، پرتگالی، روسی، ہسپانوی، اور بہت سی مزید  

## ٹیسٹنگ ہدایات

### دستاویز کی تصدیق

چونکہ یہ بنیادی طور پر دستاویزی ریپوزٹری ہے، اس لیے ٹیسٹنگ کا فوکس درج ذیل ہے:

1. **لنک کی درستی**: یقینی بنائیں کہ تمام اندرونی لنکس کام کر رہے ہیں  
```bash
# ٹوٹے ہوئے مارک ڈاؤن لنکس کے لیے چیک کریں
find . -name "*.md" -type f | xargs grep -n "\[.*\](../../.*)"
```
  
2. **کوڈ سمپل کی تصدیق**: چیک کریں کہ کوڈ کی مثالیں کمپائل/چلتی ہیں  
```bash
# مخصوص نمونہ پر جائیں اور اس کے ٹیسٹ چلائیں
cd 03-GettingStarted/samples/typescript
npm install && npm test
```
  
3. **مارکڈاؤن کی جانچ**: فارمیٹنگ کی مطابقت چیک کریں  
```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
```
  
## کوڈ اسٹائل رہنما اصول

### دستاویزی انداز

- واضح، مبتدی دوست زبان استعمال کریں  
- جہاں مناسب ہو، متعدد زبانوں میں کوڈ مثالیں شامل کریں  
- مارکڈاؤن کی بہترین مشقیں اپنائیں:  
  - ATX اسٹائل ہیڈرز (`#` سینٹیکس)  
  - زبان کے شناخت کنندگان کے ساتھ fenced کوڈ بلاکس  
  - تصاویر کے لیے وضاحتی alt متن شامل کریں  
  - لائن کی لمبائی مناسب رکھیں (سخت حد نہیں لیکن معقول ہوں)  

### کوڈ سمپل اسٹائل

#### TypeScript/JavaScript  
- ES ماڈیولز (`import`/`export`) استعمال کریں  
- TypeScript کے سخت موڈ اصول اپنائیں  
- قسم کے تشریحات شامل کریں  
- ES2022 کو ہدف بنائیں  

#### Python  
- PEP 8 اسٹائل گائیڈ لائنز کی پیروی کریں  
- جہاں مناسب ہو ٹائپ ہنٹس استعمال کریں  
- فنکشنز اور کلاسز کے لیے docstrings شامل کریں  
- جدید 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. حسب ضرورت تصاویر کی لوکلائزیشن  

### کوئی تعمیری عمل ضروری نہیں

یہ ریپوزٹری بنیادی طور پر مارکڈاؤن دستاویزات پر مشتمل ہے۔ بنیادی نصاب کے مواد کے لیے کوئی کمپائل یا تعمیری مرحلہ درکار نہیں۔

### نمونہ پروجیکٹ کی تعیناتی

انفرادی نمونہ پروجیکٹس کے لیے تعیناتی کی ہدایات ہو سکتی ہیں:  
- MCP سرور تعیناتی کی رہنمائی کے لیے `03-GettingStarted/09-deployment/` دیکھیں  
- Azure Container Apps تعیناتی کی مثالیں `11-MCPServerHandsOnLabs/` میں  

## تعاون کے اصول

### پل ریکویسٹ کا عمل

1. **فورک اور کلون کریں**: ریپوزٹری کو فورک کریں اور اپنی فورک کو مقامی طور پر کلون کریں  
2. **برانچ بنائیں**: وضاحتی برانچ نام استعمال کریں (مثلاً `fix/typo-module-3`, `add/python-example`)  
3. **تبدیلیاں کریں**: صرف انگریزی مارکڈاؤن فائلوں میں ترمیم کریں (ترجموں میں نہیں)  
4. **مقامی طور پر ٹیسٹ کریں**: تصدیق کریں کہ مارکڈاؤن صحیح طریقے سے رینڈرز ہو  
5. **PR جمع کروائیں**: واضح PR عنوانات اور وضاحتیں استعمال کریں  
6. **CLA**: جب پوچھا جائے تو Microsoft Contributor License Agreement پر دستخط کریں  

### PR عنوان کی شکل

واضح اور وضاحتی عنوانات استعمال کریں:  
- `[Module XX] مختصر وضاحت` ماڈیول مخصوص تبدیلیوں کے لیے  
- `[Samples] وضاحت` نمونہ کوڈ کی تبدیلیوں کے لیے  
- `[Docs] وضاحت` عمومی دستاویزی اپ ڈیٹس کے لیے  

### کیا تعاون کریں

- دستاویزات یا کوڈ نمونہ جات میں بگ فکسز  
- اضافی زبانوں میں نئے کوڈ مثالیں  
- موجودہ مواد کی وضاحت اور اصلاحات  
- نئے کیس اسٹڈیز یا عملی مثالیں  
- غیر واضح یا غلط مواد کی رپورٹیں  

### کیا نہ کریں

- `translations/` فولڈر کی فائلوں میں مستقیم ترمیم نہ کریں  
- `translated_images/` فولڈر میں ترمیم نہ کریں  
- بغیر گفت و شنید کے بڑے بائنری فائلز نہ شامل کریں  
- ترجمہ ورک فلو فائلوں کو بغیر ہم آہنگی کے تبدیل نہ کریں  

## اضافی نوٹس

### ریپوزٹری کی دیکھ بھال

- **چینج لاگ**: تمام اہم تبدیلیاں `changelog.md` میں دستاویز کی جاتی ہیں  
- **مطالعہ ہدایت نامہ**: نصاب کے نیویگیشن جائزے کے لیے `study_guide.md` استعمال کریں  
- **مسئلہ ٹیمپلیٹس**: بگ رپورٹس اور فیچر درخواستوں کے لیے GitHub مسئلہ ٹیمپلیٹس استعمال کریں  
- **کوڈ آف کنڈکٹ**: تمام تعاون کرنے والے Microsoft Open Source Code of Conduct کی پابندی کریں  

### تعلیمی راستہ

متسلسل ترتیب میں ماڈیولز (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  
- **ڈسکارڈ**: Microsoft Foundry Discord سرور  
- **متعلقہ کورسز**: دیگر Microsoft تعلیمی راستے README.md میں دیکھیں  

### عام دشواریاں

**س: میری PR ترجمہ چیک میں ناکام ہو رہی ہے**  
ج: یقینی بنائیں کہ آپ نے صرف روٹ ماڈیول ڈائریکٹریز میں انگریزی مارکڈاؤن فائلوں میں ترمیم کی ہے، ترجمہ شدہ ورژنز میں نہیں۔

**س: میں نئی زبان کیسے شامل کروں؟**  
ج: زبان کی معاونت co-op-translator ورک فلو کے ذریعے منظم ہوتی ہے۔ نئی زبان شامل کرنے کے لیے ایک مسئلہ کھولیں۔

**س: کوڈ مثالیں کام نہیں کر رہیں**  
ج: یقینی بنائیں کہ آپ نے مخصوص نمونے کی README میں موجود سیٹ اپ ہدایات کی پیروی کی ہے۔ چیک کریں کہ آپ کے پاس درست ورژنز کی dependencies انسٹال ہیں۔

**س: تصاویر ظاہر نہیں ہو رہی ہیں**  
ج: تصدیق کریں کہ تصویر کے راستے رشتہ دار ہیں اور فارورڈ سلیش استعمال ہو رہا ہے۔ تصاویر `images/` فولڈر یا `translated_images/` (مقامی ورژنز) میں ہونی چاہئیں۔

### کارکردگی کے غور طلب نکات

- ترجمہ ورک فلو مکمل ہونے میں کئی منٹ لگ سکتے ہیں  
- بڑی تصاویر کو کمیٹ کرنے سے پہلے بہتر بنائیں  
- فرداً فرداً مارکڈاؤن فائلوں کو مرکوز اور مناسب سائز میں رکھیں  
- بہتر پورٹیبلٹی کے لیے رشتہ دار لنکس استعمال کریں  

### پروجیکٹ گورننس

یہ پروجیکٹ Microsoft اوپن سورس اصولوں کی پیروی کرتا ہے:  
- کوڈ اور دستاویزات کے لیے MIT لائسنس  
- Microsoft Open Source Code of Conduct  
- تعاون کے لیے CLA لازم  
- سیکیورٹی مسائل: SECURITY.md رہنمائی کی پیروی کریں  
- مدد: SUPPORT.md دیکھیں

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ڈس کلیمر**:
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔
<!-- CO-OP TRANSLATOR DISCLAIMER END -->