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

Πρακτικοί οδηγοί για καθημερινή εργασία με το Maguyva MCP. Κάθε οδηγός παρουσιάζει τα εργαλεία και τη σειρά χρήσης τους — δεν αποτελεί πλήρη αναφορά παραμέτρων. Για τις παραμέτρους των εργαλείων, χρησιμοποιήστε την Αναφορά MCP API. Για την πρώτη εγκατάσταση, χρησιμοποιήστε τη Γρήγορη εκκίνηση.

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

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

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

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

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

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

Κολλήσατε σε κλειδιά, γέφυρες ή λείπουν αποθετήρια; Αντιμετώπιση προβλημάτων.

Χαρτογραφήστε τα σύμβολα και την ακτίνα επίδρασης πριν αλλάξετε κοινόχρηστο κώδικα. Τα εργαλεία 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 και την επικαιρότητα του ευρετηρίου πριν το θεωρήσετε τεκμήριο για τη νέα αναθεώρηση και εκτελέστε τοπικές δοκιμές.

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

Πλήρεις παράμετροι: Αναφορά 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 είναι για ανακάλυψη και επαλήθευση — δεν γράφει.

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

Γιατί λειτουργεί αυτός ο βρόχος: Πώς λειτουργεί.

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

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

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

Αποτυχίες εγκατάστασης: Αντιμετώπιση προβλημάτων.

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

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

Λεπτομέρειες μορφής αποθετηρίου: Αναφορά MCP API.

• Γρήγορη εκκίνηση — κλειδί, ευρετήριο, σύνδεση, πρώτη επαληθευμένη απάντηση
• Οδηγός εγκατάστασης — διαμόρφωση MCP ανά πελάτη
• Αναφορά MCP API — κάθε εργαλείο, παράμετρος προς παράμετρο
• Αντιμετώπιση προβλημάτων — Προβλήματα κλειδιού API, γέφυρας και αποθετηρίου