Αντιμετώπιση προβλημάτων

Οι περισσότερες αποτυχίες ρύθμισης εμπίπτουν σε τέσσερις κατηγορίες: το κλειδί API δεν φτάνει στον διακομιστή, η γέφυρα @maguyva/mcp δεν ξεκινά, δεν είναι δυνατή η αντιστοίχιση του αποθετηρίου, ή ο πελάτης δεν μπορεί να συνδεθεί καθόλου. Δουλέψτε πάνω στην ενότητα που ταιριάζει με το σύμπτωμά σας.

Κάθε αίτημα αυθεντικοποιείται με το κλειδί API σας, το οποίο αποστέλλεται ως κεφαλίδα Authorization: Bearer ή, όταν ένας client δεν μπορεί να την ορίσει, ως κεφαλίδα X-API-Key. Αν οι κλήσεις εργαλείων απορρίπτονται:

• Επιβεβαιώστε ότι το κλειδί σας ξεκινά με το πρόθεμα mgv_.
• Ελέγξτε ότι αντικαταστήσατε το σύμβολο κράτησης θέσης mgv_xxxx από τα παραδείγματα ρύθμισης με το πραγματικό σας κλειδί από app.maguyva.ai.
• Αν η ρύθμισή σας διαβάζει το κλειδί από το MAGUYVA_API_KEY, επιβεβαιώστε ότι η μεταβλητή έχει οριστεί στο περιβάλλον από το οποίο εκκινεί πράγματι ο πελάτης σας. Οι εξαγωγές κελύφους που προστίθενται στο ~/.zshrc ή ~/.bashrc εφαρμόζονται μόνο μετά την επαναφόρτωση του κελύφους — και οι εφαρμογές GUI μπορεί να μην τις κληρονομούν καθόλου. Σε περίπτωση αμφιβολίας, γράψτε το κλειδί απευθείας στη ρύθμιση: στην κεφαλίδα Authorization μιας εγγενούς απομακρυσμένης ρύθμισης (Bearer και μετά το κλειδί σας) ή στην ενότητα env μιας ρύθμισης με τη γέφυρα @maguyva/mcp.
• Βεβαιωθείτε ότι το κλειδί δεν έχει λήξει ή ανακληθεί.

Αν ο πελάτης σας χρησιμοποιεί τη γέφυρα @maguyva/mcp, εκκινεί μια τοπική διεργασία που συνδέεται στον απομακρυσμένο διακομιστή του Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Αν ο διακομιστής δεν εμφανίζεται ποτέ στον πελάτη σας, ή εμφανίζεται και αποσυνδέεται αμέσως:

• Επιβεβαιώστε ότι το npx είναι διαθέσιμο στο PATH σας — η γέφυρα χρειάζεται μια λειτουργική εγκατάσταση Node.js. Εκτελέστε npx -y @maguyva/mcp --help σε ένα τερματικό για να επιβεβαιώσετε ότι μπορεί να ξεκινήσει.
• Ελέγξτε τη σύνταξη ρύθμισης MCP του πελάτη σας — ένα κακοσχηματισμένο αρχείο JSON αποτυγχάνει σιωπηλά σε ορισμένους πελάτες.
• Πολλοί πελάτες δεν χρειάζονται καθόλου τη γέφυρα. Το Claude Code χρησιμοποιεί το πρόσθετο Maguyva (/plugin install maguyva@maguyva), ενώ τα Cursor, VS Code, Devin Desktop και Zed συνδέονται στον απομακρυσμένο διακομιστή εγγενώς με κεφαλίδα Bearer (το Zed μέσω context_servers). Η γέφυρα προορίζεται για πελάτες που δεν μπορούν να στείλουν αυτή την κεφαλίδα από τη ρύθμισή τους, όπως το Claude Desktop, του οποίου το claude_desktop_config.json εκκινεί μόνο τοπικούς διακομιστές. Οι προσαρμοσμένοι σύνδεσμοι του Claude Desktop μπορούν να στείλουν κεφαλίδα αιτήματος authorization, αλλά οι κεφαλίδες αιτήματος είναι σε δοκιμαστική φάση για περιορισμένο αριθμό οργανισμών.

• Βεβαιωθείτε ότι το αποθετήριο είναι συνδεδεμένο και ευρετηριασμένο στο app.maguyva.ai.
• Ελέγξτε τη μορφή: Το "owner/repo" στοχεύει τον προεπιλεγμένο κλάδο, το "owner/repo:branch" στοχεύει έναν συγκεκριμένο κλάδο (π.χ. "owner/repository:develop").
• Βεβαιωθείτε ότι ο λογαριασμός σας έχει πρόσβαση στο αποθετήριο.
• Χρησιμοποιήστε το repository_context(action="info", repository="...") για να ελέγξετε πώς επιλύεται το αποθετήριο· παραλείψτε την παράμετρο repository μόνο όταν ο MCP client παρέχει προεπιλογή για το συγκεκριμένο αίτημα ή όταν το κλειδί έχει πρόσβαση σε ακριβώς ένα αποθετήριο.

• Δοκιμάστε τη συνδεσιμότητα με το https://maguyva.tools/mcp από το μηχάνημά σας — οι εταιρικοί διαμεσολαβητές και τα τείχη προστασίας είναι συνήθως οι ένοχοι.
• Ελέγξτε ότι το διακριτικό API σας είναι έγκυρο και δεν έχει λήξει.
• Επανελέγξτε τη ρύθμιση του πελάτη σε σχέση με τον Οδηγό Εγκατάστασης για τον πελάτη σας — η θέση και η μορφή του αρχείου ρύθμισης διαφέρουν ανά πελάτη.

Μετά από οποιαδήποτε αλλαγή, ρωτήστε τον πράκτορά σας "Ποια αποθετήρια έχω συνδεδεμένα;" — αυτό επιβεβαιώνει τη σύνδεση από άκρη σε άκρη. Στη συνέχεια κάντε μια πραγματική ερώτηση για το αποθετήριό σας· θα πρέπει να δείτε απαντήσεις με διαδρομές αρχείων και αριθμούς γραμμών από το συνδεδεμένο αποθετήριό σας.