Penyelesaian Masalah

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

Isu kunci API#

Setiap permintaan disahkan dengan kunci API anda, dihantar sebagai header Authorization: Bearer. Jika panggilan alat ditolak:

• Sahkan kunci anda bermula dengan awalan mgv_.
• Semak anda telah menggantikan ruang letak 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, letakkan kunci itu dalam blok env konfigurasi.
• Pastikan kunci itu belum luput tempoh atau dibatalkan.

Isu jambatan mcp-remote#

Kebanyakan konfigurasi klien yang didokumenkan melancarkan satu proses jambatan tempatan yang meneruskan trafik MCP stdio ke pelayan jauh:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

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 mcp-remote --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 pemalam Maguyva (/plugin install maguyva@maguyva), dan Cursor, VS Code, Windsurf, serta Zed menyambung ke pelayan jauh secara asli dengan header Bearer (Zed melalui context_servers). Jambatan ini hanya untuk klien yang tiada sokongan header-jauh asli, seperti penyambung OAuth-sahaja milik Claude Desktop.

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 diselesaikan; 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 apa yang saya ada 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.