Sorun Giderme

Çoğu kurulum hatası dört gruba ayrılır: API anahtarı sunucuya ulaşmıyor, @maguyva/mcp köprüsü başlamıyor, repo çözümlenemiyor ya da istemci hiç bağlanamıyor. Belirtinize uyan bölümü izleyin.

Her istek, Authorization: Bearer header'ı olarak ya da bir istemci bunu ayarlayamıyorsa X-API-Key header'ı olarak gönderilen API anahtarınızla kimlik doğrular. Araç çağrıları reddediliyorsa:

• Anahtarınızın mgv_ önekiyle başladığını doğrulayın.
• Yapılandırma örneklerindeki mgv_xxxx yer tutucusunu app.maguyva.ai adresinden aldığınız gerçek anahtarınızla değiştirdiğinizi kontrol edin.
• Yapılandırmanız anahtarı MAGUYVA_API_KEY değerinden okuyorsa, değişkenin istemcinizin gerçekten başlatıldığı ortamda ayarlandığını doğrulayın. ~/.zshrc veya ~/.bashrc dosyasına eklenen shell export'ları yalnızca shell yeniden yüklendikten sonra geçerli olur — ve GUI uygulamaları bunları hiç devralmayabilir. Şüphedeyseniz anahtarı doğrudan yapılandırmaya yazın: uzak sunucuya doğrudan bağlanan bir yapılandırmada Authorization header'ına (Bearer ve ardından anahtarınız), @maguyva/mcp köprüsünü kullanan bir yapılandırmada ise env bloğuna.
• Anahtarın süresinin dolmadığından ya da iptal edilmediğinden emin olun.

İstemciniz @maguyva/mcp köprüsünü kullanıyorsa Maguyva uzak sunucusuna bağlanan yerel bir işlem başlatır:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Sunucu istemcinizde hiç görünmüyorsa ya da görünüp hemen bağlantısı kesiliyorsa:

• npx komutunun PATH'inizde bulunduğunu doğrulayın — köprünün çalışan bir Node.js kurulumuna ihtiyacı var. Başlayıp başlamadığını doğrulamak için bir terminalde npx -y @maguyva/mcp --help çalıştırın.
• İstemcinizin MCP yapılandırma sözdizimini kontrol edin — biçimsiz bir JSON dosyası bazı istemcilerde sessizce başarısız olur.
• Birçok istemcinin köprüye hiç ihtiyacı yoktur. Claude Code, Maguyva eklentisini kullanır (/plugin install maguyva@maguyva) ve Cursor, VS Code, Devin Desktop ile Zed, uzak sunucuya bir Bearer header'ıyla doğrudan bağlanır (Zed, context_servers üzerinden). Köprü, bu header'ı yapılandırmasından gönderemeyen istemciler içindir; örneğin claude_desktop_config.json dosyası yalnızca yerel sunucuları başlatan Claude Desktop. Claude Desktop'ın özel connector'ları bir authorization istek header'ı gönderebilir, ancak istek header'ları sınırlı sayıda kuruluş için beta aşamasındadır.

• app.maguyva.ai içinde reponun bağlı ve dizinlenmiş olduğunu doğrulayın.
• Biçimi kontrol edin: "owner/repo" varsayılan dalı hedefler, "owner/repo:branch" belirli bir dalı hedefler (örn. "owner/repository:develop").
• Hesabınızın repoya erişimi olduğundan emin olun.
• Repo çözümlemesini incelemek için repository_context(action="info", repository="...") kullanın; repo parametresini yalnızca MCP istemciniz bir istek varsayılanı sağladığında veya anahtar tam olarak bir repoya erişebildiğinde atlayın.

• Makinenizden https://maguyva.tools/mcp adresine bağlantıyı test edin — kurumsal proxy'ler ve güvenlik duvarları genellikle asıl suçludur.
• API token'ınızın geçerli ve süresi dolmamış olduğunu kontrol edin.
• İstemciniz için istemci yapılandırmasını Kurulum Rehberi ile yeniden kontrol edin — yapılandırma dosyasının konumu ve biçimi istemciye göre değişir.

Herhangi bir değişiklikten sonra ajanınıza "Hangi repolar bağlı?" diye sorun — bu, bağlantıyı uçtan uca doğrular. Ardından reponuz hakkında gerçek bir soru sorun; bağlı reponuzdan dosya yolları ve satır numaralarıyla cevaplar görmelisiniz.