Siirry sisältöön

Cookbook

Käytännöllisiä reseptejä jokapäiväiseen Maguyva MCP-työhön. Jokainen resepti nimeää työkalut ja järjestyksen – ei täydellistä parametriviittausta. Käytä työkaluparametreja MCP API-viite. Käytä ensimmäistä asennukseen Quickstart.

Valitse oikea työkalu#

Useimmat kysymykset alkavat yhdellä työkalukutsulla. Eskaloi vain, kun ensimmäinen vastaus on liian yleinen tai liian niukka.

  • intelligent_search — aloita tästä kaikki luonnollisen kielen koodipohjakysymykset; se reitittää semanttisen, symboli-, rakenne- ja riippuvuushaun.
  • find_symbol — tiedät jo funktion, luokan tai muuttujan nimen.
  • dependency_search — vaikutusalue: kutsujat, riippuvuudet tai vaikutus ennen muokkausta (ja sen jälkeen).
  • get_task_context — tuntematon alue; yksi rajattu nippu tiedostoja, symboleja ja riippuvuuksia tehtävän kuvaukselle.
  • repository_context — luettele käytettävissä olevat tietovarastot tai tarkista, kuinka arkiston nimi ratkeaa.
  • ask_maguyva ja operation="guidance" — paikallinen apu työkalujen valinnassa ja Maguyva-tuotteen käytössä (ei repositorion muokkaamista).

Asenna ja vahvista asiakas#

Hanki Maguyva MCP-asiakkaallesi ja vahvista yhteys todellisen arkistoluettelon avulla.

  1. Luo API-avain kenttään app.maguyva.ai (avaimet alkavat kirjaimella mgv_).
  2. Yhdistä ja indeksoi vähintään yksi GitHub-arkisto, jonka jo ymmärrät.
  3. Yhdistä asiakkaasi käyttämällä Asennusopas-laajennusta (Claude Code-laajennus tai alkuperäiset etäasetukset Cursor:lle, VS Code:lle, Windsurf:lle, Zed:lle ja muille).
  4. Kysy agentiltasi "Mitä arkistoja minulla on yhdistetty?" — joka harjoittaa todennusta ja repository_context päästä päähän.
  5. Esitä yksi todellinen kysymys reposta, jonka vastauksen voit arvostella. Sinun pitäisi nähdä tiedostopolut ja rivinumerot indeksoidusta puusta.

Oletko juuttunut avaimiin, siltoihin tai puuttuviin repoihin? Troubleshooting.

Kysy ennen muokkaamista#

Kartoita symbolit ja vaikutusalue ennen jaetun koodin muuttamista. Maguyva-työkalut eivät muokkaa repositorioitasi, vaan antavat pohjan asiakasohjelmasi paikallisesti tekemälle muutokselle.

  1. Jos tiedät symbolin nimen, kutsu find_symbol päästäksesi määritelmiin ja käyttöön.
  2. Jos sinulla on vain tehtävän kuvaus ("lisää SSO", "korjaa laskutuksen webhook"), aloita get_task_context tai intelligent_search.
  3. Ennen kuin muokkaat jaettua symbolia, kutsu dependency_search:lle riippuvuuksien ja vaikutusten analyysin avulla (tai anna muuttuneet polut PR-tyylistä vaikutusta varten), jotta näet vaikutusalueen.
  4. Avaa mainitut tiedostot (paikallinen luku levyllä oleville tiedostoille; get_file etä-/ristirepopoluille) ja vahvista suunnitelma oikealla koodilla.
  5. Tarkista muokkauksen jälkeen samat symbolit uudelleen dependency_search:lla (mukaan lukien muokkauksen jälkeinen vahvistus, kun asiakkaasi tukee vahvistuslippuja), jotta kutsujat löytyvät edelleen odotetusti.

Täydelliset parametrit: MCP API-viite.

Etsi ja vaihda sitten#

Oletusagenttisilmukka: tutki → paikanna symbolit → muokkaa todisteilla.

  1. Aloita intelligent_search:llä ja selväkielisellä kyselyllä ("miten istunnon vanheneminen toimii", "missä on uudelleenyrityslogiikka").
  2. Rajoita kieli- tai polkusuodattimilla, kun ensimmäinen ikkuna on meluisa.
  3. Mainosta lupaavia hittejä find_symbol:lle tai dependency_search:lle sen sijaan, että kysyisit uudelleen saman epämääräisen kysymyksen.
  4. Käytä get_file:tä vain, kun tarvitset tietyn indeksoidun polun, joka ei ole levyllä.
  5. Muokkaa tavallisilla asiakastyökaluillasi. Maguyva on tarkoitettu etsimiseen ja todentamiseen - ei kirjoittamiseen.

Miksi tämä silmukka toimii: Miten se toimii.

Tyhjiä tai puutteellisia tuloksia#

Kun työkalut eivät palauta mitään hyödyllistä, korjaa resoluutio ja indeksointi ennen kuin kirjoitat kyselyn ikuisesti.

  1. Varmista, että arkisto on yhdistetty ja että indeksointi on valmis app.maguyva.ai:ssä.
  2. Tarkista arkiston merkkijono: "owner/repo" käyttää oletushaaraa; "owner/repo:branch" kiinnittää haaran. Täsmäytys ei tee kirjainkoosta, ei sumeaa – kirjoitusvirheet eivät korjaa automaattisesti.
  3. Soita repository_context:lle action="info":lla ja tarkista resoluution metatiedot (esimerkiksi metadata.resolution_reason).
  4. Jätä repository pois vain silloin, kun MCP-asiakkaasi toimittaa pyynnön oletusarvon tai avain voi käyttää täsmälleen yhtä arkistoa; muuten välitä se nimenomaisesti.
  5. Yritä uudelleen tarkemmalla kyselyllä, tunnetulla symbolin nimellä find_symbol:n kautta tai kieli-/polkusuodattimella. Jos itse yhteys katkeaa, käytä Troubleshooting.

Asennusvirheet: Troubleshooting.

Työskentele useissa arkistoissa#

Kohdista oikeaan indeksoituun repoon, kun avain voi nähdä useamman kuin yhden.

  1. Kutsu repository_context action="list":n kanssa kerran saadaksesi selville tarkat repositoriotunnisteet, joita avaimesi voi etsiä.
  2. Anna repository nimenomaisesti haku- ja symbolityökaluissa, kun tarvitset ei-oletusrepon (esimerkiksi "owner/other-repo" tai "owner/other-repo:develop").
  3. Säilytä yksi kysymys = yksi tietovarasto, ellet vertaile tietovarastot erillisillä kutsuilla.
  4. Käytä get_file:tä, kun tiedosto on indeksoidussa repossa, joka ei ole nykyinen työpuusi.
  5. Muista: työkalut eivät koskaan kirjoita takaisin GitHub - usean repon konteksti on tarkoitettu vain lukemiseen ja suunnitteluun.

Tietovaraston muodon tiedot: MCP API-viite.

Onko Maguyva uusi käyttäjä? Kävele ensin Quickstart ja palaa sitten tänne myöhempiä työnkulkuja varten.

Seuraavat vaiheet#