mcp-for-beginners / el

# 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
- **Πλατφόρμες Cloud**: Azure (Container Apps, OpenAI, Content Safety, Application Insights)
- **Εργαλεία Κατασκευής**: npm, Maven, pip, Cargo
- **Τεκμηρίωση**: Markdown με αυτοματοποιημένη μετάφραση σε πολλές γλώσσες (48+ γλώσσες)

### Αρχιτεκτονική

- **11 Βασικές Ενότητες (00-11)**: Ακολουθιακή διαδρομή εκμάθησης από τα βασικά έως προχωρημένα θέματα
- **Εργαστήρια Hands-on**: Πρακτικές ασκήσεις με πλήρη κώδικα λύσεων σε πολλές γλώσσες
- **Δείγματα Έργων**: Λειτουργικές υλοποιήσεις 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
```

## Ροή Εργασίας Ανάπτυξης

### Ετοιμότητα MCP 7-28

#### Λίστα ελέγχου ετοιμότητας αποθετηρίου

- [x] **Πληρότητα για νέους συνεισφέροντες**: Αυτό το αρχείο ορίζει τον σκοπό του αποθετηρίου,
  τη δομή, κανόνες συνεισφοράς και διαδρομές ρύθμισης δειγμάτων.
- [x] **Εντολές build/test/lint με ακριβείς σημαίες**:
  - Έλεγχος τεκμηρίωσης αποθετηρίου lint:
    `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`

- [x] **Ένα ρεαλιστικό workflow που μπορεί να γίνει εργαλείο MCP**:
  `validate_curriculum_change`
- [x] **Είσοδοι/έξοδοι είναι ρητές** (βλέπε προδιαγραφή παρακάτω).
- [x] **Τα δικαιώματα και οι τρόποι αποτυχίας είναι τεκμηριωμένοι** (βλέπε προδιαγραφή παρακάτω).
- [x] **Η δοκιμασιμότητα CI είναι ρητή** (καθοριστικές εντολές, ρητοί κωδικοί εξόδου και μηχανικά αναγνώσιμα αποτελέσματα).
  exit codes, and machine-readable outputs).

#### Υποψήφιο workflow εργαλείου MCP: `validate_curriculum_change`

##### Στόχος

Επικύρωση αλλαγών στην τεκμηρίωση προγράμματος σπουδών και υγείας αντιπροσωπευτικού δείγματος κώδικα πριν από τη συγχώνευση.
health before merge.

##### Είσοδοι

- `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/`.
  reports, test logs) only; no writes to `translations/` or
  `translated_images/`.
- Εκτέλεση τοπικών εντολών κελύφους.
- Προαιρετική πρόσβαση δικτύου μόνο για επαναφορά πακέτων (`npm ci`, `python -m pip install`, επίλυση εξαρτήσεων `mvn`).
  `python -m pip install`, `mvn` dependency resolution).
- Καμία άδεια για push, merge, ή τροποποίηση `translations/` ή `translated_images/`.
  `translated_images/`.

##### Τρόποι αποτυχίας

- `E_NO_INPUT_PATHS`: τα `changed_paths` είναι κενά.
- `E_INVALID_PATH`: η είσοδος διαδρομής ξεφεύγει από τη ρίζα του αποθετηρίου.
- `E_LINT_FAILED`: το lint markdown εξέρχεται με κωδικό διαφορετικό από το μηδέν.
- `E_LINK_AUDIT_FAILED`: η εντολή ελέγχου συνδέσμων εξέρχεται με κωδικό διαφορετικό από το μηδέν.
- `E_SAMPLE_TEST_FAILED`: η δοκιμή/κατασκευή δείγματος εξέρχεται με κωδικό διαφορετικό από το μηδέν.
- `E_TIMEOUT`: η εντολή ξεπέρασε το ρυθμισμένο χρονικό όριο.

##### Συνιστώμενο συμβόλαιο CI

Για αυτοματοποίηση της επικύρωσης, διαμορφώστε μια εργασία CI που:

- Ενεργοποιείται σε pull requests που αγγίζουν `*.md`, δείγματα κώδικα ή αυτό το αρχείο.
- Εκτελεί τις ακριβείς εντολές που παρατίθενται παραπάνω.
- Εξασφαλίζει την αποθήκευση των αρχείων καταγραφής ως τεχνουργήματα.
- Αποτυγχάνει η εργασία σε οποιονδήποτε μηδενικό κωδικό εξόδου.

#### Αν στείλετε έναν server MCP από αυτό το αποθετήριο

- [ ] Διαβάστε το τελικό αρχείο αλλαγών MCP `2026-07-28`:
  <https://modelcontextprotocol.io/specification/2026-07-28/changelog>
- [ ] Επαληθεύστε ότι η επιλεγμένη έκδοση SDK υποστηρίζει MCP `2026-07-28`:
  <https://modelcontextprotocol.io/docs/sdk>
- [ ] Αφαιρέστε υποθέσεις συνεδρίας και χειραψίας· θεωρήστε κάθε αίτημα ως αυτοτελές:
  self-contained:
  <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>
- [ ] Απομάκρυνση από το πειραματικό API `2025-11-25` Tasks:
  <https://modelcontextprotocol.io/extensions/tasks>
- [ ] Ανασκόπηση εξουσιοδότησης για ενίσχυση OAuth και OpenID Connect:
  <https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization>

### Δομή Τεκμηρίωσης

- **Ενότητες 00-11**: Κύριο περιεχόμενο μαθήματος με διαδοχική σειρά
- **translations/**: Έκδοσεις κατά γλώσσα (αυτόματα δημιουργημένες, μη επεξεργάζεστε απευθείας)
- **translated_images/**: Μεταφρασμένες εκδόσεις εικόνων (αυτόματα δημιουργημένες)
- **images/**: Πηγαίες εικόνες και διαγράμματα

### Πραγματοποίηση Αλλαγών στην Τεκμηρίωση

1. Επεξεργαστείτε μόνο τα αγγλικά αρχεία markdown στους ριζικούς φακέλους των ενοτήτων (00-11)
2. Ενημερώστε τις εικόνες στον φάκελο `images/` αν απαιτείται
3. Η ενέργεια co-op-translator στο GitHub δημιουργεί αυτόματα τις μεταφράσεις
4. Οι μεταφράσεις ανανεώνονται με κάθε ώθηση στον κεντρικό κλάδο

### Εργασία με Μεταφράσεις

- **Αυτόματη Μετάφραση**: Το workflow 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 (`#` σύνταξη)
  - Χρησιμοποιήστε fenced code blocks με αναγνωριστικά γλώσσας
  - Συμπεριλάβετε περιγραφικό alt κείμενο για τις εικόνες
  - Κρατήστε λογικό μήκος γραμμών (όχι αυστηρό όριο, αλλά να είστε συνετοί)

### Στυλ Δείγματος Κώδικα

#### TypeScript/JavaScript
- Χρησιμοποιήστε ES modules (`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 το αποθετήριο και κλωνοποιήστε το τοπικά
2. **Δημιουργήστε Branch**: Χρησιμοποιήστε περιγραφικά ονόματα κλάδων (π.χ., `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://modelcontextprotocol.io/specification/2026-07-28/
- **Κοινότητα**: https://github.com/orgs/modelcontextprotocol/discussions
- **Discord**: Microsoft Foundry Discord server
- **Σχετικά Μαθήματα**: Δείτε README.md για άλλα μονοπάτια εκμάθησης Microsoft

### Συνήθη Προβλήματα και Επίλυση

**Ε: Το PR μου αποτυγχάνει στον έλεγχο μετάφρασης**
Α: Βεβαιωθείτε ότι επεξεργαστήκατε μόνο αγγλικά αρχεία markdown στους ριζικούς φακέλους ενοτήτων και όχι μεταφρασμένα αρχεία.

**Ε: Πώς προσθέτω μια νέα γλώσσα;**
Α: Η υποστήριξη γλωσσών διαχειρίζεται μέσω του workflow co-op-translator. Ανοίξτε ένα θέμα για να συζητήσετε την προσθήκη νέων γλωσσών.

**Ε: Τα δείγματα κώδικα δεν λειτουργούν**
Α: Βεβαιωθείτε ότι ακολουθήσατε τις οδηγίες εγκατάστασης στο README του συγκεκριμένου δείγματος. Ελέγξτε ότι έχετε εγκαταστήσει τις σωστές εκδόσεις εξαρτήσεων.


**Ερώτηση: Οι εικόνες δεν εμφανίζονται**

Α: Επαληθεύστε ότι οι διαδρομές εικόνων είναι σχετικές και χρησιμοποιούν κάθετους προσανατολισμένους προς τα εμπρός. Οι εικόνες πρέπει να βρίσκονται στον φάκελο `images/` ή στο `translated_images/` για εντοπισμένες εκδόσεις.

### Παράγοντες Απόδοσης

- Η ροή εργασίας μετάφρασης μπορεί να διαρκέσει αρκετά λεπτά για να ολοκληρωθεί
- Οι μεγάλες εικόνες πρέπει να βελτιστοποιούνται πριν από το ανέβασμα
- Κρατήστε τα μεμονωμένα αρχεία markdown εστιασμένα και λογικά μεγέθους
- Χρησιμοποιήστε σχετικούς συνδέσμους για καλύτερη φορητότητα

### Διακυβέρνηση Έργου

Αυτό το έργο ακολουθεί τις πρακτικές ανοιχτού κώδικα της Microsoft:
- Άδεια MIT για κώδικα και τεκμηρίωση
- Κώδικας Δεοντολογίας Ανοικτού Κώδικα της Microsoft
- Απαιτείται 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 -->