# Cookbook

Canonical source: https://maguyva.ai/fi/docs/cookbook

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

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](https://maguyva.ai/docs/mcp-api). Ensimmäiseen asennukseen: [Pikaopas](https://maguyva.ai/docs/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ä, 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).

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

### Asenna asiakasohjelma ja varmista yhteys

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

1. Luo API-avain osoitteessa [app.maguyva.ai](https://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](https://maguyva.ai/docs/installation) 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.

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

Oletko juuttunut avaimiin, siltoihin tai puuttuviin repoihin? [Vianmääritys](https://maguyva.ai/docs/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ö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.

```json
{
  "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](https://maguyva.ai/docs/mcp-api).

### Hae, sitten muuta

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.

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

Miksi tämä silmukka toimii: [Miten se toimii](https://maguyva.ai/docs/how-it-works).

### Tyhjiä tai puutteellisia tuloksia

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](https://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](https://maguyva.ai/docs/troubleshooting).

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

Asennusvirheet: [Vianmääritys](https://maguyva.ai/docs/troubleshooting).

### Työskentele useassa repositoriossa

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](https://maguyva.ai/docs/mcp-api).

Teetkö asetuksia ensimmäistä kertaa? Aloita kohdasta [Pikaopas](https://maguyva.ai/docs/quickstart) ja käytä sitten näitä ohjeita päivittäisiin tehtäviin.