Penyelesaian Masalah

Kebanyakan kegagalan persediaan tergolong dalam empat kategori: kunci API tidak sampai ke pelayan, jambatan @maguyva/mcp tidak bermula, repositori tidak dapat dikenal pasti, atau klien langsung tidak dapat menyambung. Ikuti bahagian yang sepadan dengan gejala anda.

Setiap permintaan disahkan dengan kunci API anda, dihantar sebagai header Authorization: Bearer atau, jika sesebuah klien tidak dapat menetapkannya, sebagai header X-API-Key. Jika panggilan alat ditolak:

• Sahkan kunci anda bermula dengan awalan mgv_.
• Semak anda telah menggantikan pemegang tempat mgv_xxxx daripada contoh konfigurasi dengan kunci sebenar anda daripada app.maguyva.ai.
• Jika konfigurasi anda membaca kunci daripada MAGUYVA_API_KEY, pastikan pemboleh ubah itu ditetapkan dalam persekitaran tempat klien anda sebenarnya dilancarkan. Eksport shell yang ditambah ke ~/.zshrc atau ~/.bashrc hanya berkuat kuasa selepas shell dimuat semula — dan aplikasi GUI mungkin langsung tidak mewarisinya. Jika ragu-ragu, tulis kunci itu terus dalam konfigurasi: dalam header Authorization bagi konfigurasi jauh asli (Bearer diikuti kunci anda), atau dalam blok env bagi konfigurasi jambatan @maguyva/mcp.
• Pastikan kunci itu belum luput tempoh atau dibatalkan.

Jika klien anda menggunakan jambatan @maguyva/mcp, ia melancarkan proses setempat yang bersambung kepada pelayan jauh Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Jika pelayan langsung tidak muncul dalam klien anda, atau muncul lalu terus terputus:

• Sahkan npx tersedia dalam PATH anda — jambatan itu perlukan pemasangan Node.js yang berfungsi. Jalankan npx -y @maguyva/mcp --help dalam terminal untuk sahkan ia boleh bermula.
• Semak sintaks konfigurasi MCP klien anda — fail JSON yang salah format gagal secara senyap pada sesetengah klien.
• Kebanyakan klien langsung tidak memerlukan jambatan ini. Claude Code menggunakan plugin Maguyva (/plugin install maguyva@maguyva), dan Cursor, VS Code, Devin Desktop, serta Zed menyambung ke pelayan jauh secara asli dengan header Bearer (Zed melalui context_servers). Jambatan ini untuk klien yang tidak dapat menghantar header itu daripada konfigurasinya, seperti Claude Desktop, yang fail claude_desktop_config.json miliknya hanya memulakan pelayan tempatan. Penyambung tersuai Claude Desktop boleh menghantar header permintaan authorization, tetapi header permintaan masih dalam beta untuk bilangan organisasi yang terhad.

• Sahkan repositori disambungkan dan diindeks dalam app.maguyva.ai.
• Semak format: "owner/repo" menyasarkan cawangan lalai, "owner/repo:branch" menyasarkan cawangan tertentu (cth. "owner/repository:develop").
• Pastikan akaun anda mempunyai akses kepada repositori.
• Gunakan repository_context(action="info", repository="...") untuk memeriksa cara repositori dikenal pasti; abaikan parameter repository hanya apabila klien MCP anda memberikan lalai untuk permintaan tersebut atau apabila kunci boleh mengakses tepat satu repositori.

• Uji ketersambungan ke https://maguyva.tools/mcp daripada mesin anda — proksi korporat dan firewall biasanya punca masalah.
• Semak token API anda sah dan belum luput tempoh.
• Semak semula konfigurasi klien anda berbanding Panduan Pemasangan untuk klien anda — lokasi dan bentuk fail konfigurasi berbeza mengikut klien.

Selepas sebarang perubahan, tanya ejen anda "Repositori manakah yang telah saya sambungkan?" — itu mengesahkan sambungan hujung ke hujung. Kemudian tanya soalan sebenar tentang repo anda; anda sepatutnya nampak jawapan lengkap dengan laluan fail dan nombor baris daripada repositori yang disambungkan.