Pular para o conteúdo

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

Escolha a ferramenta certa#

A maioria das perguntas começa com uma ligação. Escale apenas quando a primeira resposta for muito ampla ou muito limitada.

  • intelligent_search — comece aqui para qualquer questão de base de código em linguagem natural; ele roteia pesquisas semânticas, de símbolos, estruturais e de dependência.
  • find_symbol — você já conhece a função, classe ou nome da variável.
  • dependency_search — raio de impacto: chamadores, dependentes 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 mutação repo).

Instalar e verificar um cliente#

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

  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, Windsurf, Zed e outros).
  4. Pergunte ao seu agente "Quais repositórios eu conectei?" — que exerce autenticação e repository_context 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.

Preso em chaves, pontes ou repositórios ausentes? 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 (incluindo verificação pós-edição quando seu cliente oferece suporte aos sinalizadores de verificação) para que os chamadores ainda resolvam conforme o esperado.

Parâmetros completos: Referência da API MCP.

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. Limite com filtros de idioma ou caminho quando a primeira janela estiver barulhenta.
  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.

Por que esse loop funciona: Como funciona.

Resultados vazios ou finos#

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 a ramificação padrão; "owner/repo:branch" fixa uma ramificação. A correspondência não diferencia maiúsculas de minúsculas e não é confusa – 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 uma solicitação padrã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 idioma/caminho. Se a conexão for interrompida, use Troubleshooting.

Falhas de configuração: Troubleshooting.

Trabalhe em vários repositórios#

Direcione o repositório indexado correto quando uma chave puder ver mais de uma.

  1. Ligue para 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 reside 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.

Novo no Maguyva? Caminhe Quickstart primeiro e depois volte aqui para os loops do segundo dia.

Próximas etapas#