Cookbook

Käytännöllisiä ohjeita päivittäiseen Maguyva MCP -työhön. Jokainen ohje kertoo työkalut ja niiden käyttöjärjestyksen — ei kaikkia parametreja. Työkaluparametrit löydät täältä: MCP API-viite. Ensimmäiseen asennukseen: Pikaopas.

JSON-lohkot ovat MCP tools/call -kutsujen syötteitä. Korvaa owner/repo, haara ja symbolien nimet oman repositoriosi arvoilla.

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

• intelligent_search — aloita tästä, kun esität koodikantaa koskevan kysymyksen luonnollisella kielellä. Oletusarvoinen auto/balanced ohjaa suurella varmuudella määritelmien hauiksi tunnistetut kyselyt rakenteelliseen hakuun, viittaus- tai vaikutuskyselyt graafihakuun ja tarkkaa osumaa hakevat kyselyt tekstihakuun. Muut kyselyt käyttävät semanttista merkitystä ja indeksoitua tekstiä. Pyydä kaikkia neljää hakumenetelmää valinnalla mode=hybrid tai auto ja quality=thorough. Erikseen valittu tila on ensisijainen quality-asetukseen nähden.
• find_symbol — tiedät jo funktion, luokan tai muuttujan nimen.
• dependency_search — vaikutusalue: kutsuva koodi, riippuvaiset komponentit 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 repositoriot tai tarkista, miten repositorion tunniste tulkitaan.
• ask_maguyva ja operation="guidance" — paikallinen apu työkalujen valinnassa ja Maguyva-tuotteen käytössä (ei repositorion muokkaamista).

Yhdistä Maguyva MCP-asiakasohjelmaasi ja varmista yhteys hakemalla todellinen repositorioluettelo.

1. Luo API-avain osoitteessa app.maguyva.ai (avaimet alkavat etuliitteellä mgv_).
2. Yhdistä ja indeksoi vähintään yksi GitHub-repositorio, jonka jo tunnet.
3. Yhdistä asiakasohjelmasi oppaan Asennusopas avulla (Claude Code -liitännäinen tai natiivit etäasetukset asiakasohjelmille Cursor, VS Code, Devin Desktop, Zed ja muut).
4. Kysy agentiltasi "Mitkä repositoriot minulla on yhdistettynä?" — tämä testaa todennuksen ja repository_context-työkalun päästä päähän.
5. Esitä yksi todellinen kysymys reposta, jonka vastauksen voit arvioida. Sinun pitäisi nähdä tiedostopolut ja rivinumerot indeksoidusta puusta.

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

Oletko juuttunut avaimiin, siltoihin tai puuttuviin repoihin? Vianmääritys.

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ökohtiin.
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-työkalua dependents- tai impact-analyysillä (tai anna changed_paths PR-tyyppistä vaikutusanalyysiä 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 samat symbolit muutoksen jälkeen uudelleen työkalulla dependency_search käyttäen asetusta verify_after_edit=true sekä parametria targets tai changed_paths. Tämä lukee indeksoitua graafia, ei paikallisia muutoksia, joista ei ole tehty committia: tarkista indexed_commit_sha ja indeksin ajantasaisuus ennen kuin käytät tulosta uuden revision todisteena, ja suorita paikalliset testit.

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

Täydelliset parametrit: MCP API-viite.

Oletusagenttisilmukka: tutki → paikanna symbolit → muokkaa todisteilla.

1. Aloita intelligent_search:llä ja selväkielisellä kyselyllä ("miten istunnon vanheneminen toimii", "missä on uudelleenyrityslogiikka").
2. Rajaa kieli- tai polkusuodattimilla, jos ensimmäisessä tulosjoukossa on liikaa epärelevantteja osumia. language_filter jättää graafin pois auto/hybrid-haussa; pelkästään graafiin ohjattu auto-kysely siirtyy silloin semanttiseen hakuun ja tekstihakuun. Erikseen valittu graph-tila yhdessä language_filter-suodattimen kanssa hylätään. Valittu hakusuunnitelma näkyy kentässä routing_decision.modalities_used; warnings on mukana vain, kun palvelin on antanut varoituksen.
3. Tutki lupaavia hakutuloksia tarkemmin työkaluilla find_symbol tai dependency_search sen sijaan, että esittäisit saman epämääräisen kysymyksen uudelleen.
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.

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

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

Kun työkalut eivät palauta mitään hyödyllistä, korjaa repositorion tunnistus ja indeksointi ennen kuin muotoilet kyselyä loputtomasti uudelleen.

1. Varmista osoitteessa app.maguyva.ai, että repositorio on yhdistetty ja indeksointi valmis.
2. Tarkista repositorion tunniste: "owner/repo" käyttää oletushaaraa; "owner/repo:branch" määrittää haaran. Täsmäytys ei huomioi kirjainkokoa eikä käytä sumeaa hakua — kirjoitusvirheet eivät korjaannu automaattisesti.
3. Kutsu repository_context-työkalua toiminnolla action="info" ja tarkista tunnistuksen metatiedot (esimerkiksi metadata.resolution_reason).
4. Jätä repository pois vain, kun MCP-asiakasohjelmasi antaa pyyntökohtaisen oletuksen tai avaimella on pääsy täsmälleen yhteen repositorioon; muussa tapauksessa anna se erikseen.
5. Yritä uudelleen tarkemmalla kyselyllä, tunnetulla symbolin nimellä find_symbol:n kautta tai kieli-/polkusuodattimella. Jos itse yhteys katkeaa, käytä Vianmääritys.

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

Asennusvirheet: Vianmääritys.

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. Pidä yksi kysymys yhdessä repositoriossa, ellet vertaile repositorioita 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-palveluun - usean repon konteksti on tarkoitettu vain lukemiseen ja suunnitteluun.

Repositoriotunnisteen muoto: MCP API-viite.

• Pika-aloitus — avain, indeksi, yhteys, ensimmäinen arvioitu vastaus
• Asennusopas — asiakasohjelmakohtainen MCP-konfiguraatio
• MCP API-viite — jokainen työkalu parametri kerrallaan
• Vianetsintä — API-avain-, silta- ja repositorio-ongelmat