Vianmääritys

Useimmat asennusvirheet jakautuvat neljään ryhmään: API-avain ei saavuta palvelinta, @maguyva/mcp-silta ei käynnisty, repositoriota ei voida tunnistaa, tai asiakasohjelma ei saa yhteyttä lainkaan. Käy läpi osio, joka vastaa oiretta.

Jokainen pyyntö todennetaan API-avaimellasi, joka lähetetään Authorization: Bearer-otsikkona tai, jos asiakasohjelma ei osaa asettaa sitä, X-API-Key-otsikkona. Jos työkalukutsut hylätään:

• Varmista, että avaimesi alkaa mgv_-etuliitteellä.
• Tarkista, että korvasit konfiguraatioesimerkkien mgv_xxxx-paikkamerkin oikealla avaimellasi osoitteesta app.maguyva.ai.
• Jos konfiguraatiosi lukee avaimen muuttujasta MAGUYVA_API_KEY, varmista, että muuttuja on asetettu ympäristössä, josta asiakasohjelmasi oikeasti käynnistyy. Tiedostoihin ~/.zshrc tai ~/.bashrc lisätyt shell-exportit tulevat voimaan vasta shellin uudelleenlatauksen jälkeen — eivätkä GUI-sovellukset välttämättä peri niitä lainkaan. Jos olet epävarma, kirjoita avain suoraan konfiguraatioon: natiivin etäkonfiguraation Authorization-otsikkoon (Bearer ja sen perään avaimesi) tai @maguyva/mcp-siltaa käyttävän konfiguraation env-lohkoon.
• Varmista, ettei avain ole vanhentunut tai peruutettu.

Jos asiakasohjelmasi käyttää siltaa @maguyva/mcp, se käynnistää paikallisen prosessin, joka yhdistää Maguyva-palvelun etäpalvelimeen:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Jos palvelin ei koskaan näy asiakasohjelmassasi, tai näkyy ja katkeaa heti:

• Varmista, että npx on saatavilla PATH-muuttujassasi — silta tarvitsee toimivan Node.js-asennuksen. Aja npx -y @maguyva/mcp --help terminaalissa varmistaaksesi, että se voi käynnistyä.
• Tarkista asiakasohjelmasi MCP-konfiguraation syntaksi — virheellinen JSON-tiedosto epäonnistuu hiljaisesti joissakin asiakasohjelmissa.
• Monet asiakasohjelmat eivät tarvitse siltaa lainkaan. Claude Code käyttää Maguyva-liitännäistä (/plugin install maguyva@maguyva), ja Cursor, VS Code, Devin Desktop ja Zed yhdistävät etäpalvelimeen natiivisti Bearer-otsikolla (Zed context_servers:n kautta). Silta on tarkoitettu asiakasohjelmille, jotka eivät voi lähettää kyseistä otsikkoa konfiguraatiostaan, kuten Claude Desktop -sovellukselle, jonka claude_desktop_config.json käynnistää vain paikallisia palvelimia. Claude Desktop -sovelluksen mukautetut liittimet voivat lähettää authorization-pyyntöotsikon, mutta pyyntöotsikot ovat betavaiheessa rajatulle joukolle organisaatioita.

• Varmista, että repository on yhdistetty ja indeksoitu palvelussa app.maguyva.ai.
• Tarkista muoto: "owner/repo" kohdistuu oletushaaraan, "owner/repo:branch" tiettyyn haaraan (esim. "owner/repository:develop").
• Varmista, että tililläsi on pääsy repositoryyn.
• Tarkista komennolla repository_context(action="info", repository="..."), miten repositorio tunnistetaan; jätä repository-parametri pois vain, kun MCP-asiakas antaa pyyntökohtaisen oletuksen tai kun avaimella on pääsy täsmälleen yhteen repositoryyn.

• Testaa yhteyttä osoitteeseen https://maguyva.tools/mcp koneeltasi — yritysproxyt ja palomuurit ovat tavallisimmat syylliset.
• Tarkista, että API-tokenisi on voimassa eikä vanhentunut.
• Tarkista asiakasohjelmasi konfiguraatio uudelleen Asennusopas-oppaasta — konfiguraatiotiedoston sijainti ja muoto vaihtelevat asiakasohjelmittain.

Minkä tahansa muutoksen jälkeen kysy agentiltasi "Mitkä repositoriot minulla on yhdistettynä?" — se varmistaa yhteyden päästä päähän. Kysy sitten oikea kysymys repostasi; sinun pitäisi nähdä vastauksia tiedostopolkuineen ja rivinumeroineen yhdistetystä repositoriostasi.