# Πρακτικοί οδηγοί

Canonical source: https://maguyva.ai/el/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Πρακτικοί οδηγοί για καθημερινή εργασία με το Maguyva MCP. Κάθε οδηγός παρουσιάζει τα εργαλεία και τη σειρά χρήσης τους — δεν αποτελεί πλήρη αναφορά παραμέτρων. Για τις παραμέτρους των εργαλείων, χρησιμοποιήστε την [Αναφορά MCP API](https://maguyva.ai/docs/mcp-api). Για την πρώτη εγκατάσταση, χρησιμοποιήστε τη [Γρήγορη εκκίνηση](https://maguyva.ai/docs/quickstart).

### Επιλέξτε το σωστό εργαλείο

Οι περισσότερες ερωτήσεις ξεκινούν με μια κλήση. Κλιμακώστε μόνο όταν η πρώτη απάντηση είναι πολύ ευρεία ή ελλιπής.

- `intelligent_search` — ξεκινήστε εδώ για μια ερώτηση σε φυσική γλώσσα σχετικά με τη βάση κώδικα. Η προεπιλογή auto/balanced δρομολογεί ερωτήματα που αναγνωρίζονται με υψηλή βεβαιότητα ως αναζητήσεις ορισμών στη δομική αναζήτηση, ερωτήματα αναφορών ή επιπτώσεων στον γράφο και ερωτήματα ακριβούς αντιστοίχισης στην αναζήτηση κειμένου. Τα υπόλοιπα ερωτήματα χρησιμοποιούν τη σημασιολογική έννοια και το ευρετηριασμένο κείμενο. Χρησιμοποιήστε mode=hybrid ή auto με quality=thorough για να ζητήσετε και τις τέσσερις μεθόδους αναζήτησης. Η ρητά επιλεγμένη λειτουργία υπερισχύει της ρύθμισης quality.
- `find_symbol` — γνωρίζετε ήδη το όνομα της συνάρτησης, της κλάσης ή της μεταβλητής.
- `dependency_search` — ακτίνα επίδρασης: κώδικας που καλεί, εξαρτώμενα στοιχεία ή αντίκτυπος πριν και μετά από μια αλλαγή.
- `get_task_context` — άγνωστη περιοχή· ένα περιορισμένο σύνολο αρχείων, συμβόλων και εξαρτήσεων για μια περιγραφή εργασίας.
- `repository_context` — δείτε τα προσβάσιμα αποθετήρια ή εξετάστε πώς αντιστοιχίζεται το όνομα ενός αποθετηρίου.
- `ask_maguyva` με `operation="guidance"` — τοπική βοήθεια για την επιλογή εργαλείων και τη χρήση του Maguyva (χωρίς τροποποίηση του αποθετηρίου).

Τα μπλοκ JSON είναι είσοδοι για το MCP tools/call. Αντικαταστήστε το owner/repo, τον κλάδο και τα ονόματα συμβόλων με τιμές από το αποθετήριό σας.

### Εγκαταστήστε και επαληθεύστε έναν πελάτη

Αποκτήστε το Maguyva στον πελάτη MCP και επιβεβαιώστε τη σύνδεση με μια πραγματική λίστα αποθετηρίου.

1. Δημιουργήστε ένα κλειδί API στο [app.maguyva.ai](https://app.maguyva.ai) (τα κλειδιά ξεκινούν με `mgv_`).
2. Συνδέστε και δημιουργήστε ευρετήριο τουλάχιστον ενός αποθετηρίου GitHub που ήδη καταλαβαίνετε.
3. Συνδέστε τον πελάτη σας χρησιμοποιώντας τον [Οδηγό εγκατάστασης](https://maguyva.ai/docs/installation) (πρόσθετο Claude Code ή εγγενής απομακρυσμένη διαμόρφωση για Cursor, VS Code, Devin Desktop, Zed και άλλα).
4. Ρωτήστε τον πράκτορά σας "Τι αποθετήρια έχω συνδέσει;" — έτσι ελέγχονται από άκρη σε άκρη η αυθεντικοποίηση και το `repository_context`.
5. Κάντε μια πραγματική ερώτηση για αυτό το αποθετήριο, της οποίας την απάντηση μπορείτε να αξιολογήσετε. Θα πρέπει να δείτε διαδρομές αρχείων και αριθμούς γραμμών από το ευρετηριασμένο δέντρο.

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

Κολλήσατε σε κλειδιά, γέφυρες ή λείπουν αποθετήρια; [Αντιμετώπιση προβλημάτων](https://maguyva.ai/docs/troubleshooting).

### Ρωτήστε πριν επεξεργαστείτε

Χαρτογραφήστε τα σύμβολα και την ακτίνα επίδρασης πριν αλλάξετε κοινόχρηστο κώδικα. Τα εργαλεία Maguyva δεν τροποποιούν τα αποθετήριά σας — παρέχουν τις πληροφορίες στις οποίες βασίζεται η αλλαγή που εφαρμόζει τοπικά ο πελάτης σας.

1. Εάν γνωρίζετε το όνομα του συμβόλου, καλέστε το `find_symbol` για να βρείτε ορισμούς και χρήσεις.
2. Εάν διαθέτετε μόνο μια περιγραφή εργασίας ("προσθήκη SSO", "διορθώστε το webhook χρέωσης"), ξεκινήστε με `get_task_context` ή `intelligent_search`.
3. Πριν αλλάξετε ένα κοινόχρηστο σύμβολο, καλέστε το `dependency_search` για ανάλυση εξαρτώμενων στοιχείων ή επιπτώσεων (ή δώστε τις αλλαγμένες διαδρομές για ανάλυση επιπτώσεων τύπου PR), ώστε να δείτε την ακτίνα επίδρασης.
4. Ανοίξτε τα αναφερόμενα αρχεία (τοπική ανάγνωση για αρχεία στο δίσκο, `get_file` για διαδρομές σε απομακρυσμένα ή άλλα αποθετήρια) και επιβεβαιώστε το σχέδιο σε σχέση με τον πραγματικό κώδικα.
5. Μετά την αλλαγή, ελέγξτε ξανά τα ίδια σύμβολα με `dependency_search`, χρησιμοποιώντας verify_after_edit=true και targets ή changed_paths. Αυτό διαβάζει τον ευρετηριασμένο γράφο, όχι τοπικές αλλαγές χωρίς commit: ελέγξτε το indexed_commit_sha και την επικαιρότητα του ευρετηρίου πριν το θεωρήσετε τεκμήριο για τη νέα αναθεώρηση και εκτελέστε τοπικές δοκιμές.

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

Πλήρεις παράμετροι: [Αναφορά MCP API](https://maguyva.ai/docs/mcp-api).

### Ψάξε και μετά άλλαξε

Ο συνήθης κύκλος του πράκτορα: εξερεύνηση → εντοπισμός συγκεκριμένων συμβόλων → επεξεργασία με τεκμήρια.

1. Ξεκινήστε με το `intelligent_search` και ένα ερώτημα σε απλή γλώσσα ("πώς λειτουργεί η λήξη της περιόδου λειτουργίας", "πού είναι η λογική επανάληψης προσπαθειών").
2. Περιορίστε τα αποτελέσματα με φίλτρα γλώσσας ή διαδρομής όταν το πρώτο σύνολο περιέχει πολύ θόρυβο. Το language_filter παραλείπει τον γράφο από το auto/hybrid· ένα ερώτημα auto που είχε δρομολογηθεί μόνο στον γράφο επιστρέφει στη σημασιολογική αναζήτηση και στην αναζήτηση κειμένου. Η ρητή λειτουργία graph με language_filter απορρίπτεται. Εξετάστε το routing_decision.modalities_used για να δείτε το επιλεγμένο σχέδιο αναζήτησης· το warnings υπάρχει μόνο όταν ο διακομιστής έχει εκδώσει κάποια προειδοποίηση.
3. Διερευνήστε τα υποσχόμενα αποτελέσματα με `find_symbol` ή `dependency_search`, αντί να κάνετε ξανά την ίδια ασαφή ερώτηση.
4. Χρησιμοποιήστε το `get_file` μόνο όταν χρειάζεστε μια συγκεκριμένη διαδρομή με ευρετήριο που δεν βρίσκεται στο δίσκο.
5. Επεξεργαστείτε στα κανονικά εργαλεία πελάτη σας. Το Maguyva είναι για ανακάλυψη και επαλήθευση — δεν γράφει.

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

Γιατί λειτουργεί αυτός ο βρόχος: [Πώς λειτουργεί](https://maguyva.ai/docs/how-it-works).

### Κενά ή ελλιπή αποτελέσματα

Όταν τα εργαλεία δεν επιστρέφουν τίποτα χρήσιμο, διορθώστε την αντιστοίχιση αποθετηρίου και την ευρετηρίαση πριν ξαναγράφετε ασταμάτητα το ερώτημα.

1. Επιβεβαιώστε ότι το αποθετήριο είναι συνδεδεμένο και ολοκληρώθηκε η δημιουργία ευρετηρίου στο [app.maguyva.ai](https://app.maguyva.ai).
2. Ελέγξτε τη συμβολοσειρά του αποθετηρίου: Το `"owner/repo"` χρησιμοποιεί τον προεπιλεγμένο κλάδο. Το `"owner/repo:branch"` καρφιτσώνει έναν κλάδο. Η αντιστοίχιση είναι χωρίς διάκριση πεζών-κεφαλαίων, όχι ασαφής — τα τυπογραφικά λάθη δεν διορθώνονται αυτόματα.
3. Καλέστε το `repository_context` με το `action="info"` και επιθεωρήστε τα μεταδεδομένα αντιστοίχισης (για παράδειγμα `metadata.resolution_reason`).
4. Παραλείψτε το `repository` μόνο όταν ο πελάτης MCP παρέχει προεπιλεγμένο αποθετήριο για το συγκεκριμένο αίτημα ή το κλειδί έχει πρόσβαση σε ακριβώς ένα αποθετήριο· διαφορετικά, δώστε το ρητά.
5. Δοκιμάστε ξανά με ένα πιο συγκεκριμένο ερώτημα, ένα γνωστό όνομα συμβόλου μέσω `find_symbol` ή ένα φίλτρο γλώσσας/διαδρομής. Εάν η ίδια η σύνδεση είναι σπασμένη, χρησιμοποιήστε το [Αντιμετώπιση προβλημάτων](https://maguyva.ai/docs/troubleshooting).

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

Αποτυχίες εγκατάστασης: [Αντιμετώπιση προβλημάτων](https://maguyva.ai/docs/troubleshooting).

### Εργαστείτε σε πολλαπλά αποθετήρια

Στοχεύστε το σωστό αποθετήριο με ευρετήριο όταν ένα κλειδί μπορεί να δει περισσότερα από ένα.

1. Καλέστε το `repository_context` με το `action="list"` μία φορά για να μάθετε τα ακριβή αναγνωριστικά αποθετηρίων που μπορεί να αναζητήσει το κλειδί σας.
2. Περάστε ρητά το `repository` στην αναζήτηση και τα εργαλεία συμβόλων όταν χρειάζεστε ένα μη προεπιλεγμένο αποθετήριο (για παράδειγμα `"owner/other-repo"` ή `"owner/other-repo:develop"`).
3. Κρατήστε μία ερώτηση = ένα αποθετήριο, εκτός εάν συγκρίνετε σκόπιμα τα αποθετήρια σε ξεχωριστές κλήσεις.
4. Χρησιμοποιήστε το `get_file` όταν το αρχείο βρίσκεται σε ένα αποθετήριο με ευρετήριο που δεν είναι το τρέχον δέντρο εργασίας σας.
5. Θυμηθείτε: τα εργαλεία δεν γράφουν ποτέ πίσω στο GitHub — το περιβάλλον πολλαπλών αποθετηρίων είναι μόνο για ανάγνωση και σχεδιασμό.

Λεπτομέρειες μορφής αποθετηρίου: [Αναφορά MCP API](https://maguyva.ai/docs/mcp-api).

Κάνετε ρύθμιση για πρώτη φορά; Ξεκινήστε με τη [Γρήγορη εκκίνηση](https://maguyva.ai/docs/quickstart) και μετά χρησιμοποιήστε αυτές τις συνταγές για καθημερινές εργασίες.