# Receitas

Canonical source: https://maguyva.ai/pt-br/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).

Receitas práticas para o trabalho diário do Maguyva MCP. Cada receita nomeia as ferramentas e a sequência — não uma referência completa dos parâmetros. Para parâmetros de ferramenta, use [Referência da API MCP](https://maguyva.ai/docs/mcp-api). Para configuração inicial, use [Início rápido](https://maguyva.ai/docs/quickstart).

### Escolha a ferramenta certa

A maioria das perguntas começa com uma chamada. Só aprofunde a busca quando a primeira resposta for muito ampla ou trouxer pouca informação.

- `intelligent_search` — comece aqui para fazer uma pergunta em linguagem natural sobre a base de código. Por padrão, auto/balanced direciona perguntas sobre definições cuja intenção identifica com confiança para a busca estrutural, perguntas sobre referências ou impacto para o grafo e perguntas de correspondência exata para o texto. As demais perguntas usam o significado semântico e o texto indexado. Use mode=hybrid ou auto com quality=thorough para solicitar as quatro modalidades de busca. Um mode explícito tem prioridade sobre quality.
- `find_symbol` — você já conhece o nome da função, classe ou variável.
- `dependency_search` — raio de impacto: código que faz chamadas, código dependente ou impacto antes (e depois) de uma edição.
- `get_task_context` — área desconhecida; um pacote limitado de arquivos, símbolos e dependências para uma descrição de tarefa.
- `repository_context` — liste repositórios acessíveis ou inspecione como o nome de um repositório é resolvido.
- `ask_maguyva` com `operation="guidance"` — ajuda local na seleção de ferramentas e uso de Maguyva (sem alterar o repositório).

Os blocos JSON são entradas para MCP tools/call. Substitua owner/repo e os nomes de branch e de símbolo pelos valores do seu repositório.

### Instalar e verificar um cliente

Conecte o Maguyva ao seu cliente MCP e confirme a conexão com uma lista real de repositórios.

1. Crie uma chave de API em [app.maguyva.ai](https://app.maguyva.ai) (as chaves começam com `mgv_`).
2. Conecte e indexe pelo menos um repositório GitHub que você já conhece.
3. Conecte seu cliente usando o [Guia de instalação](https://maguyva.ai/docs/installation) (plugin Claude Code ou configuração remota nativa para Cursor, VS Code, Devin Desktop, Zed e outros).
4. Pergunte ao seu agente "Quais repositórios eu conectei?" — isso testa a autenticação e `repository_context` de ponta a ponta.
5. Faça uma pergunta real sobre aquele repositório cuja resposta você pode avaliar. Você deverá ver os caminhos dos arquivos e os números das linhas da árvore indexada.

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

Preso em chaves, bridges ou repositórios ausentes? [Solução de problemas](https://maguyva.ai/docs/troubleshooting).

### Pergunte antes de editar

Mapeie símbolos e raio de impacto antes de alterar o código compartilhado. As ferramentas Maguyva não modificam seus repositórios — elas informam a edição que seu cliente aplica localmente.

1. Se você souber o nome do símbolo, chame `find_symbol` para obter definições e usos.
2. Se você tiver apenas uma descrição da tarefa ("adicionar SSO", "corrigir o webhook de cobrança"), comece com `get_task_context` ou `intelligent_search`.
3. Antes de editar um símbolo compartilhado, chame `dependency_search` com análise de dependentes/impacto (ou passe caminhos alterados para impacto no estilo PR) para ver o raio de impacto.
4. Abra os arquivos citados (leitura local para arquivos no disco; `get_file` para caminhos de repositórios remotos/cruzados) e confirme o plano com código real.
5. Após a edição, verifique novamente os mesmos símbolos com `dependency_search`, usando verify_after_edit=true e targets ou changed_paths. Isso lê o grafo indexado, não alterações locais ainda não commitadas: confira indexed_commit_sha e a atualização do índice antes de tratar o resultado como evidência da nova revisão, e execute os testes locais.

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

Parâmetros completos: [Referência da API MCP](https://maguyva.ai/docs/mcp-api).

### Pesquise e depois altere

Um loop de agente padrão: explorar → fixar símbolos → editar com evidências.

1. Comece com `intelligent_search` e uma consulta em linguagem simples ("como funciona a expiração da sessão", "onde está a lógica de nova tentativa").
2. Refine com filtros de linguagem ou caminho se os primeiros resultados tiverem muito ruído. language_filter exclui o grafo de auto/hybrid; uma consulta auto direcionada apenas ao grafo recorre à busca semântica e de texto. O modo de grafo explícito com language_filter é rejeitado. Confira routing_decision.modalities_used para ver o plano de busca selecionado; warnings só aparece quando o servidor emitiu algum aviso.
3. Promova resultados promissores para `find_symbol` ou `dependency_search` em vez de fazer novamente a mesma pergunta vaga.
4. Use `get_file` somente quando precisar de um caminho indexado específico que não esteja no disco.
5. Edite em suas ferramentas clientes normais. Maguyva é para descoberta e verificação – não para gravação.

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

Por que esse loop funciona: [Como funciona](https://maguyva.ai/docs/how-it-works).

### Resultados vazios ou insuficientes

Quando as ferramentas não retornam nada de útil, corrija a resolução e a indexação antes de reescrever a consulta para sempre.

1. Confirme se o repositório está conectado e terminou a indexação em [app.maguyva.ai](https://app.maguyva.ai).
2. Verifique a string do repositório: `"owner/repo"` usa o branch padrão; `"owner/repo:branch"` especifica um branch. A correspondência não diferencia maiúsculas de minúsculas e não usa aproximação (fuzzy) – erros de digitação não são corrigidos automaticamente.
3. Chame `repository_context` com `action="info"` e inspecione os metadados de resolução (por exemplo `metadata.resolution_reason`).
4. Omita `repository` somente quando seu cliente MCP fornecer um repositório padrão para a solicitação ou a chave puder acessar exatamente um repositório; caso contrário, passe-o explicitamente.
5. Tente novamente com uma consulta mais específica, um nome de símbolo conhecido via `find_symbol` ou um filtro de linguagem/caminho. Se a conexão for interrompida, use [Solução de problemas](https://maguyva.ai/docs/troubleshooting).

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

Falhas de configuração: [Solução de problemas](https://maguyva.ai/docs/troubleshooting).

### Trabalhe em vários repositórios

Escolha o repositório indexado correto quando uma chave puder acessar mais de um.

1. Chame `repository_context` com `action="list"` uma vez para saber os slugs exatos que sua chave pode pesquisar.
2. Passe `repository` explicitamente nas ferramentas de pesquisa e símbolos quando precisar de um repositório não padrão (por exemplo, `"owner/other-repo"` ou `"owner/other-repo:develop"`).
3. Mantenha uma pergunta = um repositório, a menos que você compare intencionalmente os repositórios em chamadas separadas.
4. Use `get_file` quando o arquivo estiver em um repositório indexado que não é sua árvore de trabalho atual.
5. Lembre-se: as ferramentas nunca escrevem de volta para GitHub – o contexto multi-repo é apenas para leitura e planejamento.

Detalhes do formato do repositório: [Referência da API MCP](https://maguyva.ai/docs/mcp-api).

Configurando pela primeira vez? Comece com [Início rápido](https://maguyva.ai/docs/quickstart) e depois use estas receitas nas tarefas do dia a dia.