Receitas

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. Para configuração inicial, use Início rápido.

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.

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

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

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

Preso em chaves, bridges ou repositórios ausentes? Solução de problemas.

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.

{
  "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.

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.

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

Por que esse loop funciona: Como funciona.

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

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

Falhas de configuração: Solução de problemas.

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.

• Início rápido — chave, indexação, conexão, primeira resposta verificada
• Guia de instalação — configuração MCP por cliente
• Referência da API MCP — cada ferramenta, parâmetro por parâmetro
• Solução de problemas — Falhas de chave de API, bridge e repositório