# Penyelesaian Masalah

Canonical source: https://maguyva.ai/ms/docs/troubleshooting

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).

Betulkan kegagalan persediaan Maguyva yang biasa: masalah kunci API, isu jambatan @maguyva/mcp, carian repositori, dan ralat sambungan.

### Isu kunci API

- 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.

### Isu jambatan @maguyva/mcp

- 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.

### Repositori tidak ditemui

- 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.

### Isu sambungan MCP

- 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.

### Sahkan pembetulan

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.