mcp-for-beginners / th

# AGENTS.md

## ภาพรวมโครงการ

**MCP สำหรับผู้เริ่มต้น** เป็นหลักสูตรการศึกษาที่เปิดเผยแหล่งที่มาเพื่อเรียนรู้ Model Context Protocol (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
- **เอกสารประกอบ**: Markdown พร้อมการแปลอัตโนมัติหลายภาษา (48+ ภาษา)

### สถาปัตยกรรม

- **11 โมดูลหลัก (00-11)**: เส้นทางการเรียนรู้ต่อเนื่องจากพื้นฐานถึงหัวข้อขั้นสูง
- **ห้องปฏิบัติการใช้งานจริง**: แบบฝึกหัดเชิงปฏิบัติพร้อมโค้ดโซลูชันครบถ้วนในหลายภาษา
- **โครงการตัวอย่าง**: การใช้งานเซิร์ฟเวอร์และไคลเอนต์ MCP ที่ทำงานได้จริง
- **ระบบแปลภาษา**: เวิร์กโฟลว์ GitHub Actions อัตโนมัติสำหรับรองรับหลายภาษา
- **แอสเซทภาพ**: โฟลเดอร์เก็บภาพรวมศูนย์พร้อมเวอร์ชันแปลภาษา

## คำสั่งการตั้งค่า

นี่เป็นที่เก็บข้อมูลที่เน้นเอกสาร วิธีการตั้งค่าส่วนใหญ่อยู่ในโครงการตัวอย่างและห้องปฏิบัติการแต่ละรายการ

### การตั้งค่า Repository

```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
```

## เวิร์กโฟลว์การพัฒนา

### ความพร้อม MCP 7-28

#### รายการตรวจสอบความพร้อมของ Repo

- [x] **ความชัดเจนของผู้ร่วมพัฒนาใหม่**: ไฟล์นี้กำหนดวัตถุประสงค์ของ repository,
  โครงสร้าง กฎการร่วมพัฒนา และเส้นทางการตั้งค่าตัวอย่าง
- [x] **คำสั่ง build/test/lint พร้อมออปชันที่แน่นอน**:
  - ตรวจสอบเอกสาร repository lint:
    `npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"`
  - ตรวจสอบรูปแบบลิงก์เอกสาร repository:
    `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`

- [x] **เวิร์กโฟลว์ที่สมจริงหนึ่งรายการซึ่งสามารถกลายเป็นเครื่องมือ MCP**:
  `validate_curriculum_change`
- [x] **อินพุต/เอาต์พุตเป็นไปอย่างชัดเจน** (ดูข้อกำหนดด้านล่าง)
- [x] **สิทธิ์และโหมดความล้มเหลวได้รับการบันทึกไว้** (ดูข้อกำหนดด้านล่าง)
- [x] **การทดสอบ CI เป็นไปอย่างชัดเจน** (คำสั่งที่มีความเป็นเหตุเป็นผล, รหัสออกอย่างชัดเจน,
  และเอาต์พุตที่อ่านโดยเครื่องจักรได้)

#### เวิร์กโฟลว์เครื่องมือ 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[]`

##### สิทธิ์

- อ่านไฟล์ในเวิร์กสเปซและเขียนผลลัพธ์ที่เครื่องมือสร้างเท่านั้น (เช่น รายงาน lint,
  บันทึกผลการทดสอบ); ห้ามเขียนลงในโฟลเดอร์ `translations/` หรือ
  `translated_images/`
- เรียกใช้คำสั่ง shell ในเครื่อง
- เข้าถึงเครือข่ายได้เฉพาะการกู้คืนแพ็กเกจ (`npm ci`,
  `python -m pip install`, การแก้ไข dependency ของ `mvn`)
- ไม่มีสิทธิ์ผลักดัน, ผสาน หรือแก้ไข `translations/` หรือ
  `translated_images/`

##### โหมดความล้มเหลว

- `E_NO_INPUT_PATHS`: ไม่มีค่าใน `changed_paths`
- `E_INVALID_PATH`: เส้นทางอินพุตหลุดออกจากราก repository
- `E_LINT_FAILED`: markdown lint จบการทำงานด้วยรหัสไม่เป็นศูนย์
- `E_LINK_AUDIT_FAILED`: คำสั่งสอบทานลิงก์จบการทำงานด้วยรหัสไม่เป็นศูนย์
- `E_SAMPLE_TEST_FAILED`: การทดสอบ/สร้างตัวอย่างจบการทำงานด้วยรหัสไม่เป็นศูนย์
- `E_TIMEOUT`: คำสั่งเกินเวลา timeout ที่ตั้งไว้

##### สัญญา CI ที่แนะนำ

เพื่อทำให้อัตโนมัติการตรวจสอบนี้ ตั้งค่าการทำงาน CI ที่:

- เรียกใช้เมื่อ pull request ที่สัมผัสไฟล์ `*.md`, โค้ดตัวอย่าง หรือไฟล์นี้
- รันคำสั่งที่ระบุไว้ด้านบนอย่างแม่นยำ
- เก็บบันทึกเป็นผลลัพธ์
- ผิดพลาดงานเมื่อมีรหัสออกไม่เป็นศูนย์

#### หากคุณปล่อยเซิร์ฟเวอร์ MCP จาก repo นี้

- [ ] อ่านบันทึกการเปลี่ยนแปลง MCP สุดท้าย `2026-07-28`:
  <https://modelcontextprotocol.io/specification/2026-07-28/changelog>
- [ ] ตรวจสอบว่า SDK ที่เลือกสนับสนุน MCP `2026-07-28`:
  <https://modelcontextprotocol.io/docs/sdk>
- [ ] ลบสมมติฐานเกี่ยวกับ session และ handshake; ถือแต่ละคำขอเป็น
  เรื่องอิสระ:
  <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`)

- [ ] ย้าย Roots, Sampling, Logging และ Dynamic Client ที่เลิกใช้แล้ว
  การลงทะเบียน:
  <https://modelcontextprotocol.io/specification/2026-07-28/deprecated>
- [ ] ย้ายออกจาก experimental `2025-11-25` Tasks API:
  <https://modelcontextprotocol.io/extensions/tasks>
- [ ] ทบทวนการอนุญาตสำหรับการเสริมความแข็งแกร่ง OAuth และ OpenID Connect:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization>

### โครงสร้างเอกสาร

- **Modules 00-11**: เนื้อหาหลักสูตรหลักตามลำดับ
- **translations/**: เวอร์ชันตามภาษาที่กำหนด (สร้างอัตโนมัติ ห้ามแก้ไขโดยตรง)
- **translated_images/**: เวอร์ชันรูปภาพที่แปลตามท้องถิ่น (สร้างอัตโนมัติ)
- **images/**: รูปภาพและไดอะแกรมต้นทาง

### การทำการเปลี่ยนแปลงเอกสาร

1. แก้ไขไฟล์ markdown ภาษาอังกฤษในไดเรกทอรีโมดูลหลัก (00-11) เท่านั้น
2. อัปเดตรูปภาพในไดเรกทอรี `images/` ตามความจำเป็น
3. GitHub Action ของ co-op-translator จะสร้างการแปลอัตโนมัติ
4. การแปลจะถูกสร้างใหม่เมื่อต้นทางหลักถูกผลักดัน

### การทำงานกับการแปล

- **การแปลอัตโนมัติ**: กระบวนการทำงาน GitHub Actions จัดการการแปลทั้งหมด
- **ห้ามแก้ไขด้วยตนเอง** ไฟล์ในไดเรกทอรี `translations/`
- ข้อมูลเมตาการแปลถูกฝังในแต่ละไฟล์ที่แปลแล้ว
- ภาษาที่รองรับ: มากกว่า 48 ภาษา รวมทั้งอารบิก, จีน, ฝรั่งเศส, เยอรมัน, ฮินดี, ญี่ปุ่น, เกาหลี, โปรตุเกส, รัสเซีย, สเปน และอื่น ๆ อีกมากมาย

## คำแนะนำการทดสอบ

### การตรวจสอบเอกสาร

เนื่องจากเป็นที่เก็บเอกสารเป็นหลัก การทดสอบจึงเน้นที่:

1. **ตรวจสอบรูปแบบลิงก์**: แสดงรายการลิงก์ Markdown เพื่อทบทวน

   ```bash
   # รายการลิงก์ Markdown (ตรวจสอบรูปแบบ)
   find . -name "*.md" -not -path "*/node_modules/*" -not -path "./translations/*" -not -path "./translated_images/*" -print0 | xargs -0 grep -En "\[.*\]\(.*\)"
   ```

2. **ตรวจสอบตัวอย่างโค้ด**: ทดสอบว่าสามารถคอมไพล์/รันโค้ดตัวอย่างได้

   ```bash
   # ไปยังตัวอย่างเฉพาะและรันการทดสอบของมัน
   cd 03-GettingStarted/samples/typescript
   npm install && npm test
   ```

3. **ตรวจสอบ Markdown Linting**: ตรวจสอบความสม่ำเสมอของการจัดรูปแบบ

   ```bash
   # ใช้ markdownlint หากจำเป็น
   npx --yes markdownlint-cli2 "**/*.md" "#node_modules" "#translations" "#translated_images"
   ```

### การทดสอบโปรเจกต์ตัวอย่าง

ตัวอย่างแต่ละภาษาจะมีวิธีการทดสอบของตนเอง:

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

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

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

## แนวทางสไตล์โค้ด

### สไตล์เอกสาร

- ใช้ภาษาที่ชัดเจนและเข้าใจง่ายสำหรับผู้เริ่มต้น
- รวมตัวอย่างโค้ดในหลายภาษาเมื่อเหมาะสม
- ปฏิบัติตามแนวทางที่ดีที่สุดของ markdown:
  - ใช้หัวเรื่องสไตล์ ATX (`#` syntax)
  - ใช้โค้ดบล็อคที่มีรั้วและระบุภาษาชัดเจน
  - รวมข้อความคำอธิบาย 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. การแปลอัตโนมัติของไฟล์ markdown ภาษาอังกฤษทั้งหมด
3. การแปลรูปภาพตามความจำเป็น

### ไม่ต้องมีขั้นตอนการสร้าง

ที่เก็บนี้เน้นที่เอกสาร markdown เป็นหลัก ไม่มีขั้นตอนคอมไพล์หรือการสร้างสำหรับเนื้อหาหลักสูตรหลัก

### การปรับใช้โปรเจกต์ตัวอย่าง

โปรเจกต์ตัวอย่างแต่ละอันอาจมีคำแนะนำการปรับใช้:
- ดู `03-GettingStarted/09-deployment/` สำหรับคำแนะนำการปรับใช้เซิร์ฟเวอร์ MCP
- ตัวอย่างการปรับใช้ Azure Container Apps ใน `11-MCPServerHandsOnLabs/`

## แนวทางการมีส่วนร่วม

### กระบวนการ Pull Request

1. **Fork และ Clone**: Fork ที่เก็บและโคลน Fork ของคุณลงในเครื่อง
2. **สร้างสาขาใหม่**: ใช้ชื่อตามคำอธิบายที่ชัดเจน (เช่น `fix/typo-module-3`, `add/python-example`)
3. **แก้ไข**: แก้ไขไฟล์ markdown ภาษาอังกฤษเท่านั้น (ไม่แก้ไขการแปล)
4. **ทดสอบในเครื่อง**: ตรวจสอบว่า markdown แสดงผลถูกต้อง
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://modelcontextprotocol.io/specification/2026-07-28/
- **ชุมชน**: https://github.com/orgs/modelcontextprotocol/discussions
- **Discord**: เซิร์ฟเวอร์ Microsoft Foundry Discord
- **คอร์สที่เกี่ยวข้อง**: ดู README.md สำหรับเส้นทางการเรียนรู้ Microsoft อื่น ๆ

### การแก้ปัญหาที่พบบ่อย

**ถาม: PR ของฉันล้มเหลวในการตรวจสอบการแปล**
ตอบ: ตรวจสอบให้แน่ใจว่าแก้ไขไฟล์ markdown ภาษาอังกฤษในไดเรกทอรีโมดูลหลักเท่านั้น ไม่ใช่เวอร์ชันที่แปลแล้ว

**ถาม: ฉันจะเพิ่มภาษาใหม่ได้อย่างไร?**
ตอบ: การสนับสนุนภาษาได้รับการจัดการผ่านกระบวนการ co-op-translator เปิดปัญหาเพื่อหารือเกี่ยวกับการเพิ่มภาษาใหม่

**ถาม: ตัวอย่างโค้ดไม่ทำงาน**
ตอบ: ตรวจสอบว่าคุณได้ทำตามคำแนะนำการตั้งค่าใน README ของตัวอย่างนั้น ตรวจสอบว่าคุณมีเวอร์ชันของส่วนประกอบที่ถูกต้อง


**ถาม: รูปภาพไม่แสดงผล** 

A: ตรวจสอบให้แน่ใจว่าเส้นทางของรูปภาพเป็นแบบสัมพัทธ์และใช้สแลชไปข้างหน้า รูปภาพควรอยู่ในไดเรกทอรี `images/` หรือ `translated_images/` สำหรับเวอร์ชันที่แปล

### การพิจารณาด้านประสิทธิภาพ

- กระบวนการแปลอาจใช้เวลาหลายนาทีในการดำเนินการให้เสร็จสมบูรณ์
- รูปภาพขนาดใหญ่ควรได้รับการปรับให้เหมาะสมก่อนการคอมมิต
- รักษาไฟล์ markdown แต่ละไฟล์ให้มีโฟกัสและขนาดที่เหมาะสม
- ใช้ลิงก์สัมพัทธ์เพื่อความสะดวกในการพกพา

### การกำกับดูแลโครงการ

โครงการนี้ปฏิบัติตามแนวทางปฏิบัติซอร์สเปิดของ Microsoft:
- สัญญาอนุญาต MIT สำหรับโค้ดและเอกสาร
- หลักจรรยาบรรณโค้ดซอร์สเปิดของ Microsoft
- ต้องมี 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 -->